2026-05-12

training/context/03-功能模块/01-认证模块.md

@@ -0,0 +1,110 @@
+# 认证模块（auth）
+
+> 证据来源：[SRC-FEAT-01] [SRC-API-01] [SRC-CODE-01：module/auth/]
+
+---
+
+## 1. 模块定位
+
+- **模块目标**：负责用户身份验证（企业微信OAuth + 账号密码备选）和 JWT Token 的签发、校验，为所有其他模块提供鉴权基础。
+- **解决问题**：500人规模的企业内部系统，需要统一身份验证入口，并将身份与角色绑定，为下游数据隔离提供 `userId + role + departmentId` 上下文。
+
+---
+
+## 2. 功能清单
+
+[SRC-API-01：四、API 接口设计 / SRC-CODE-01：module/auth/]
+
+| 功能名称 | 功能描述 | 输入 | 输出 | 依赖模块 |
+|---------|---------|------|------|---------|
+| 企业微信 OAuth 登录 | 通过企业微信授权 code 换取用户身份，查找系统用户，签发 JWT | wx_code | JWT Token + 用户信息（LoginResponse） | system（查sys_user） |
+| 账号密码登录（备选） | 用用户名+密码登录，BCrypt 验证密码 | username, password | JWT Token + 用户信息 | system（查sys_user） |
+| 获取当前用户信息 | 解析 Token 返回用户基本信息 | Authorization Header | UserInfoResponse | - |
+| 微信小程序登录（预留） | 通过小程序 code 获取用户信息 | WechatLoginRequest | JWT Token | system |
+| Token 携带与拦截 | AuthInterceptor 拦截所有受保护请求，提取 Token 注入 UserContext | Authorization: Bearer {token} | UserContext（ThreadLocal） | - |
+
+---
+
+## 3. 核心逻辑
+
+### 3.1 业务规则
+
+- 企业微信登录路径：前端传 code → 后端调 weixin-java-cp SDK 换 `access_token` → 获取 `wx_userid` → 查 `sys_user.wx_userid` 匹配 → 用户不存在则返回错误（不自动注册）[SRC-FEAT-01]
+- JWT Payload 包含：userId、role、departmentId，有效期由配置决定
+- 密码存储：BCrypt 加密（Spring Security 6.x），初始管理员密码 `admin123` 已预置 [SRC-SQL-01：5.4]
+
+### 3.2 校验逻辑
+
+| 校验项 | 规则 | 失败响应 |
+|-------|------|---------|
+| wx_userid 是否存在于 sys_user | 必须已由管理员录入 | 返回错误：用户未录入，请联系管理员 |
+| sys_user.status | 必须为 0（启用） | 返回错误：账号已禁用 |
+| Token 有效性 | 未过期、签名正确 | 返回 401 |
+| 受保护接口 Token 缺失 | 无 Authorization Header | 返回 401 |
+
+### 3.3 状态流转
+
+```mermaid
+stateDiagram-v2
+    [*] --> 未认证
+    未认证 --> 已认证 : 登录成功（JWT签发）
+    已认证 --> 未认证 : Token过期 / 主动登出
+    已认证 --> 已认证 : Token续期（如有配置）
+```
+
+---
+
+## 4. 数据结构
+
+### 4.1 涉及数据表
+
+**sys_user**（读取，不由本模块创建）[SRC-SQL-01]
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | BIGINT | 用户主键 |
+| wx_userid | VARCHAR(100) | 企业微信用户ID（唯一索引 uk_wx_userid） |
+| username | VARCHAR(50) | 账号密码登录用账号（唯一索引 uk_username） |
+| password | VARCHAR(100) | BCrypt加密密码 |
+| role | TINYINT | 0-管理员 / 1-讲师 / 2-学员 |
+| department_id | BIGINT | 所属部门ID（会注入 JWT Payload） |
+| status | TINYINT | 0-启用 / 1-禁用 |
+
+### 4.2 DTO/VO 定义
+
+[SRC-CODE-01：module/auth/dto/]
+
+| 类名 | 方向 | 关键字段 |
+|------|------|---------|
+| LoginRequest | 入参 | username, password |
+| WechatLoginRequest | 入参 | code（企业微信授权码） |
+| LoginResponse | 出参 | token, userId, realName, role, departmentId |
+| UserInfoResponse | 出参 | 同 LoginResponse（从 Token 解析） |
+
+---
+
+## 5. 对外接口
+
+[SRC-API-01]
+
+| API 名称 | 方法 | 路径 | 权限 |
+|---------|------|------|------|
+| 企业微信登录 | POST | /api/auth/wechat/login | 公开 |
+| 账号密码登录 | POST | /api/auth/login | 公开 |
+| 获取当前用户 | GET | /api/auth/me | 需 Token |
+
+**事件机制**：登录成功后，UserContext（ThreadLocal）持有用户信息，供同请求链路的所有 Service 使用，请求结束后清除。[SRC-CODE-01：common/context/UserContextHolder.java]
+
+---
+
+## 6. 异常与边界处理
+
+| 场景 | 处理方式 |
+|------|---------|
+| 企业微信 API 调用超时/失败 | 返回 503，提示"企业微信服务暂时不可用，请稍后重试" |
+| 企业微信 code 已使用（重放） | 企业微信 SDK 返回错误，转化为 400 |
+| 用户 wx_userid 存在但账号被禁用（status=1） | 返回 403，提示"账号已禁用，请联系管理员" |
+| sys_user 中无对应 wx_userid | 返回 403，提示"用户未录入系统，请联系管理员" |
+| Token 格式错误（非JWT） | AuthInterceptor 捕获，返回 401 |
+| Token 过期 | AuthInterceptor 捕获，返回 401，前端跳转登录页 |
+| 并发登录（同一账号多端） | 当前设计无限制，多端独立 Token 有效 |