# 认证接口

<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、密钥轮换、令牌审计等）。