提交文件

2026-02-28 15:16:15 +08:00
parent 1a4e50e0a4
commit 44f250f58e
159 changed files with 61268 additions and 0 deletions
--- a/.qoder/repowiki/zh/content/API接口文档/认证接口.md
+++ b/.qoder/repowiki/zh/content/API接口文档/认证接口.md
@@ -0,0 +1,346 @@
+# 认证接口
+
+<cite>
+**本文引用的文件**
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py)
+- [backend/app/core/security.py](file://backend/app/core/security.py)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py)
+- [backend/app/models/models.py](file://backend/app/models/models.py)
+- [backend/app/core/config.py](file://backend/app/core/config.py)
+- [backend/app/core/database.py](file://backend/app/core/database.py)
+- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py)
+- [backend/app/main.py](file://backend/app/main.py)
+- [frontend/src/api/auth.js](file://frontend/src/api/auth.js)
+- [frontend/src/api/request.js](file://frontend/src/api/request.js)
+- [frontend/src/stores/user.js](file://frontend/src/stores/user.js)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构概览](#架构概览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考量](#性能考量)
+8. [故障排查指南](#故障排查指南)
+9. [结论](#结论)
+
+## 简介
+本文件为“用户认证接口”的完整API文档，覆盖以下三个核心接口：
+- 用户登录
+- 用户注册
+- 获取当前用户信息
+
+内容涵盖HTTP方法、URL路径、请求参数格式、响应数据结构、错误码、JWT令牌生成机制、密码验证流程、用户权限验证、OAuth2密码模式使用方法与安全注意事项、以及令牌过期处理与刷新机制的实现细节。同时提供成功与失败场景的请求/响应示例，并给出前后端集成要点。
+
+## 项目结构
+认证相关代码主要分布在后端的API层、安全模块、数据模型与配置模块；前端通过Axios封装统一请求，自动携带Authorization头。
+
+```mermaid
+graph TB
+subgraph "后端"
+A["API路由<br/>backend/app/api/v1/auth.py"]
+B["安全模块<br/>backend/app/core/security.py"]
+C["数据模型<br/>backend/app/models/models.py"]
+D["配置<br/>backend/app/core/config.py"]
+E["数据库连接<br/>backend/app/core/database.py"]
+F["主应用入口<br/>backend/app/main.py"]
+G["API聚合<br/>backend/app/api/v1/__init__.py"]
+end
+subgraph "前端"
+H["认证API封装<br/>frontend/src/api/auth.js"]
+I["请求拦截器<br/>frontend/src/api/request.js"]
+J["用户状态存储<br/>frontend/src/stores/user.js"]
+end
+H --> I
+I --> F
+F --> G
+G --> A
+A --> B
+A --> C
+B --> D
+B --> E
+J --> H
+```
+
+图表来源
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L1-L74)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L1-L110)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L244-L261)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L47)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L1-L39)
+- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py#L1-L17)
+- [backend/app/main.py](file://backend/app/main.py#L1-L92)
+- [frontend/src/api/auth.js](file://frontend/src/api/auth.js#L1-L22)
+- [frontend/src/api/request.js](file://frontend/src/api/request.js#L1-L66)
+- [frontend/src/stores/user.js](file://frontend/src/stores/user.js#L1-L49)
+
+章节来源
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L1-L74)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L1-L110)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L244-L261)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L47)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L1-L39)
+- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py#L1-L17)
+- [backend/app/main.py](file://backend/app/main.py#L1-L92)
+- [frontend/src/api/auth.js](file://frontend/src/api/auth.js#L1-L22)
+- [frontend/src/api/request.js](file://frontend/src/api/request.js#L1-L66)
+- [frontend/src/stores/user.js](file://frontend/src/stores/user.js#L1-L49)
+
+## 核心组件
+- 认证路由与控制器：定义登录、注册、获取当前用户三个接口，使用OAuth2密码模式进行认证。
+- 安全模块：负责密码哈希与校验、JWT令牌生成与解析、当前用户与权限校验。
+- 数据模型：User模型包含用户名、密码哈希、角色、激活状态等字段。
+- 配置模块：提供API前缀、JWT密钥、算法、过期时间等配置。
+- 数据库连接：异步SQLAlchemy会话管理。
+- 前端请求封装：统一添加Authorization头，处理401等错误并跳转登录。
+
+章节来源
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L17-L74)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L24-L110)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L244-L261)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L23-L26)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L28-L39)
+- [frontend/src/api/request.js](file://frontend/src/api/request.js#L15-L26)
+
+## 架构概览
+认证流程采用OAuth2密码模式，客户端向登录接口发送用户名/密码，服务端验证后签发JWT访问令牌；后续请求由前端在请求头中携带Authorization: Bearer <token>，后端通过依赖注入解析并校验令牌，获取当前用户。
+
+```mermaid
+sequenceDiagram
+participant FE as "前端应用"
+participant API as "认证接口<br/>/api/v1/auth"
+participant SEC as "安全模块<br/>JWT/密码"
+participant DB as "数据库<br/>User表"
+FE->>API : POST /api/v1/auth/login
+API->>DB : 查询用户(用户名)
+DB-->>API : 用户记录
+API->>SEC : 校验密码
+SEC-->>API : 校验结果
+API->>SEC : 生成访问令牌
+SEC-->>API : 返回JWT
+API-->>FE : {access_token, token_type}
+FE->>API : GET /api/v1/auth/me<br/>Authorization : Bearer <token>
+API->>SEC : 解析JWT并校验
+SEC->>DB : 查询用户(根据sub)
+DB-->>SEC : 用户记录
+SEC-->>API : 当前用户
+API-->>FE : 用户信息
+```
+
+图表来源
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L17-L74)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L34-L91)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L244-L261)
+- [frontend/src/api/auth.js](file://frontend/src/api/auth.js#L4-L21)
+- [frontend/src/api/request.js](file://frontend/src/api/request.js#L15-L26)
+
+## 详细组件分析
+
+### 接口定义与行为
+
+- 用户登录
+  - 方法与路径：POST /api/v1/auth/login
+  - 认证方式：OAuth2密码模式（form-data）
+  - 请求体字段：
+    - username: 字符串，最小长度3，最大长度50
+    - password: 字符串，最小长度6，最大长度100
+  - 成功响应：
+    - access_token: 字符串（JWT）
+    - token_type: 字符串，默认"bearer"
+  - 错误码：
+    - 401：用户名或密码错误
+    - 403：账户已禁用
+  - 处理逻辑：
+    - 根据用户名查询用户
+    - 使用bcrypt校验密码
+    - 校验用户是否激活
+    - 生成JWT访问令牌并返回
+
+- 用户注册
+  - 方法与路径：POST /api/v1/auth/register
+  - 请求体字段：
+    - username: 字符串，最小长度3，最大长度50
+    - password: 字符串，最小长度6，最大长度100
+    - staff_id: 可选整数
+    - role: 字符串，枚举(admin|manager|staff)，默认staff
+  - 成功响应：
+    - code: 整数，默认200
+    - message: 字符串，默认"注册成功"
+    - data.id: 新用户ID
+  - 错误码：
+    - 400：用户名已存在
+  - 处理逻辑：
+    - 检查用户名是否重复
+    - 生成密码哈希
+    - 创建用户记录并持久化
+
+- 获取当前用户信息
+  - 方法与路径：GET /api/v1/auth/me
+  - 认证方式：Bearer Token（Authorization头）
+  - 成功响应：
+    - id: 整数
+    - username: 字符串
+    - role: 字符串
+    - is_active: 布尔
+    - last_login: 可选时间戳
+    - created_at: 时间戳
+  - 错误码：
+    - 401：无法验证凭据（无效/过期令牌）
+    - 403：需要管理员权限（若使用管理员依赖）
+  - 处理逻辑：
+    - 通过OAuth2 Bearer Scheme获取令牌
+    - 解析JWT载荷(sub为用户ID)
+    - 查询用户并返回
+
+章节来源
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L17-L74)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L315-L345)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L24-L91)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L244-L261)
+
+### JWT令牌生成机制
+- 令牌内容：
+  - exp：过期时间（UTC）
+  - sub：用户ID（字符串）
+- 签发过程：
+  - 使用配置中的SECRET_KEY与ALGORITHM（如HS256）进行签名
+  - 默认过期时间为ACCESS_TOKEN_EXPIRE_MINUTES（8小时）
+- 解析过程：
+  - 从Authorization头提取Bearer Token
+  - 使用相同密钥与算法解码，获取payload
+  - 从payload取sub作为用户ID，查询用户是否存在且激活
+
+章节来源
+- [backend/app/core/security.py](file://backend/app/core/security.py#L34-L53)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L23-L26)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L55-L91)
+
+### 密码验证流程
+- 存储：密码以哈希形式保存（bcrypt）
+- 校验：接收明文密码与存储的哈希，使用bcrypt.checkpw进行比对
+- 注册：注册时对明文密码生成哈希再存入数据库
+
+章节来源
+- [backend/app/core/security.py](file://backend/app/core/security.py#L24-L31)
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L40-L65)
+
+### 用户权限验证
+- 当前用户：通过Bearer Token解析并查询用户
+- 激活状态：仅激活用户可访问受保护资源
+- 角色权限：提供管理员与经理权限校验依赖（用于特定接口）
+
+章节来源
+- [backend/app/core/security.py](file://backend/app/core/security.py#L85-L109)
+
+### OAuth2密码模式使用方法与安全考虑
+- 使用方法：
+  - 前端以application/x-www-form-urlencoded方式提交username与password到/login
+  - 服务端返回access_token
+  - 后续请求在Authorization头中携带Bearer <token>
+- 安全考虑：
+  - 必须通过HTTPS传输，避免令牌被窃听
+  - 令牌过期时间较短（默认8小时），建议实现刷新机制
+  - 前端仅本地存储令牌，避免泄露
+  - 服务端严格校验令牌与用户状态
+
+章节来源
+- [frontend/src/api/auth.js](file://frontend/src/api/auth.js#L4-L11)
+- [frontend/src/api/request.js](file://frontend/src/api/request.js#L15-L26)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L23-L26)
+
+### 令牌过期处理与刷新机制
+- 过期处理：
+  - 前端在401时提示“登录已过期”，清除本地令牌并跳转登录页
+- 刷新机制：
+  - 当前实现未提供refresh_token接口
+  - 建议新增刷新令牌接口，或延长ACCESS_TOKEN_EXPIRE_MINUTES并配合短期会话策略
+
+章节来源
+- [frontend/src/api/request.js](file://frontend/src/api/request.js#L39-L57)
+
+## 依赖关系分析
+
+```mermaid
+classDiagram
+class AuthRouter{
+POST /auth/login
+POST /auth/register
+GET /auth/me
+}
+class SecurityModule{
+verify_password()
+get_password_hash()
+create_access_token()
+decode_token()
+get_current_user()
+get_current_active_user()
+}
+class UserModel{
+id
+username
+password_hash
+role
+is_active
+}
+class Config{
+SECRET_KEY
+ALGORITHM
+ACCESS_TOKEN_EXPIRE_MINUTES
+API_PREFIX
+}
+class Database{
+get_db()
+}
+AuthRouter --> SecurityModule : "依赖"
+AuthRouter --> UserModel : "读写"
+SecurityModule --> Config : "读取"
+SecurityModule --> Database : "依赖"
+```
+
+图表来源
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L1-L74)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L1-L110)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L244-L261)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L23-L26)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L28-L39)
+
+章节来源
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L1-L74)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L1-L110)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L244-L261)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L23-L26)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L1-L39)
+
+## 性能考量
+- 密码哈希：bcrypt计算开销较高，建议在高并发场景下适当调整密钥迭代次数或使用更高效的硬件
+- JWT解析：每次受保护请求均需解码与用户查询，建议缓存活跃用户信息或使用Redis等缓存层
+- 数据库连接：使用异步连接池，合理设置池大小与超时，避免阻塞
+- 前端拦截器：统一处理401错误，减少重复逻辑
+
+[本节为通用指导，不直接分析具体文件]
+
+## 故障排查指南
+- 登录失败（401）：
+  - 检查用户名/密码是否正确
+  - 确认用户是否激活
+- 无法访问受保护接口（401）：
+  - 检查Authorization头是否正确携带Bearer Token
+  - 确认令牌未过期
+- 权限不足（403）：
+  - 确认用户角色是否满足接口要求
+- CORS问题：
+  - 检查CORS允许的源与预检请求
+- 前端401自动跳转：
+  - 确认本地存储的token是否被清理
+  - 检查请求拦截器是否正确添加Authorization头
+
+章节来源
+- [frontend/src/api/request.js](file://frontend/src/api/request.js#L39-L63)
+- [frontend/src/stores/user.js](file://frontend/src/stores/user.js#L34-L39)
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L30-L36)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L55-L91)
+
+## 结论
+该认证系统基于OAuth2密码模式与JWT实现，具备基本的用户登录、注册与当前用户信息获取能力。建议后续增强刷新令牌机制与更细粒度的权限控制，并在生产环境强化安全配置（如HTTPS、密钥轮换、令牌审计等）。