# user-system 修复执行计划（按 P0 / P1 / P2 排序）

**计划日期**：2026-05-30  
**输入依据**：`docs/code-review/FULL_REVIEW_2026-05-30.md`  
**目标**：修复本轮 review 暴露出的安全、正确性、测试与文档一致性问题，并形成新的可审计验证证据。

---

## 一、执行原则

1. **先修协议与契约，再修测试与文档**
   - 先修 SSO / Swagger / 路由契约错误
   - 再收敛测试与静态检查
2. **每一类问题修完都必须立即验证**
3. **文档只能反映已验证事实，不能提前宣称完成**
4. **对外可见契约必须单点真实**
   - 路由
   - Swagger
   - 前端调用
   - 测试断言
   - 状态文档
5. **修复计划必须覆盖 review 报告中的全部问题**
   - 不能只修“代表性问题”
   - 必须处理系统性问题源头

---

## 二、P0 修复计划（必须最优先）

### P0-1：把空壳 Swagger 修成真实有效文档

#### 目标
让 `/swagger/*any` 对应的不是空 `paths`，而是真实可用 OpenAPI 文档。

#### 具体动作
1. 梳理 Swagger 生成入口与当前生成流程
2. 确认 `swag init` 或项目既定生成方式
3. 生成有效 `docs/swagger.go` / `docs/docs.go`
4. 校验 `paths` 非空
5. 校验至少以下路径存在：
   - `/api/v1/auth/login`
   - `/api/v1/auth/register`
   - `/api/v1/admin/users/export`
   - `/api/v1/users/{id}`

#### 验证
- 生成 Swagger
- 检查 `docs/swagger.go` 中 `paths` 非空
- 如可本地启动，验证 `/swagger/index.html` 与 `/swagger/doc.json` 可用

---

### P0-2：系统性修正 Swagger 注释与真实路由的漂移

> 这是对报告中“系统性契约漂移”的完整修复，不再只处理导入导出接口。

#### 目标
统一以下来源的 API 契约：

- `internal/api/router/router.go`
- `internal/api/handler/*.go` 中全部 `@Router`
- `docs/API.md`
- 前端调用与测试
- 生成后的 Swagger 文档

#### 具体动作
1. 全量审计并修复以下类别的 `@Router` 漂移：
   - export/import：admin 路径
   - refresh：`/refresh-token` → `/refresh`
   - email-code login：`/login-by-email-code` → `/login/email-code`
   - resend activation：`/resend-activation-email` → `/resend-activation`
   - TOTP：`/auth/totp/*` → `/auth/2fa/*`
   - captcha：`/captcha/*` → `/auth/captcha*`
   - password reset：`/auth/password/*` → `/forgot-password` / `/reset-password` / phone 变体
   - custom fields：`/fields/*` → `/custom-fields/*`
   - logs：`/users/me/*logs` → `/logs/*/me`
   - admins：`/users/admins` → `/admin/admins`
   - users/me 绑定类接口：bind-email / bind-phone / social accounts
2. 修复 HTTP method 漂移：
   - `AssignRoles`：`POST` → `PUT`
   - `AssignPermissions`：`POST` → `PUT`
   - `SetupTOTP`：注释 method 与真实 method 对齐
3. 对照 `router.go` 做一次全量注释-路由对账，直到关键差异清零
4. 更新 `docs/API.md` 中对应路径
5. 重新生成 Swagger 文档

#### 验证
- `go test ./internal/api/handler ./internal/api/router -count=1`
- 生成 Swagger 后检查关键路径与 method 全部正确
- 使用脚本或审查清单确认：关键业务路由不再存在注释/注册漂移

---

### P0-3：修复 SSO 授权码模式未绑定 `redirect_uri` 的问题

#### 目标
让 authorization code 与 client / redirect URI 形成强绑定。

#### 具体动作
1. 在 `internal/auth/sso.go` 的 `SSOSession` 中加入 `RedirectURI`
2. `GenerateAuthorizationCode(...)` 保存该字段
3. `Token(...)` 兑换令牌时校验：
   - `session.ClientID == req.ClientID`
   - `session.RedirectURI == req.RedirectURI`
4. 对不匹配场景返回明确错误
5. 为此补回归测试

#### 验证
- `go test ./internal/auth ./internal/api/handler -count=1`
- 增加测试覆盖：
  - 正确 client + redirect_uri 成功
  - 错误 redirect_uri 失败
  - 错误 client_id 失败

---

### P0-4：禁用 implicit flow

#### 目标
系统只支持更安全的授权码模式，不再通过 fragment 返回 access token。

#### 具体动作
1. 修改 `internal/api/handler/sso_handler.go`
2. 对 `response_type=token`：
   - 返回 `400 unsupported response_type`
   - 或仅允许 `code`
3. 清理相应的宽松测试
4. 同步文档说明只支持 code flow

#### 验证
- `response_type=token` 应明确失败
- `response_type=code` 正常工作

---

### P0-5：重构 SSO 路由分组与鉴权模型，使 `/token`、`/introspect`、`/revoke`、`/userinfo` 语义正确

> 这是第二轮新增问题；若不修，P0-3/P0-4 仍不完整。

#### 目标
让 SSO/OAuth 相关端点符合正确的访问控制模型，而不是错误复用平台用户 BearerAuth。

#### 具体动作
1. 将 SSO 路由按语义拆分，不再整体挂在 `protected` 下
2. 至少区分：
   - `/authorize`：需要当前平台登录用户完成授权
   - `/token`：客户端凭证 + 授权码模型，不依赖当前平台 BearerAuth
   - `/introspect`：客户端认证模型
   - `/revoke`：客户端认证模型或 token-owner 受控模型，必须明确
   - `/userinfo`：基于 SSO access token，而不是平台 JWT 上下文
3. 为 `/token`、`/introspect`、`/revoke` 设计明确的 client auth 机制
4. 修正 `UserInfo` 的 token 解析来源，不能继续直接读平台 auth middleware 的 `user_id`
5. 同步更新测试与文档

#### 验证
- `/token` 在无平台 BearerAuth、仅有正确 client/code 条件下可成功
- `/introspect` / `/revoke` 不接受任意平台登录用户代操作
- `/userinfo` 返回的是 SSO token subject，而不是平台当前 session user

---

## 三、P1 修复计划（紧随 P0）

### P1-1：修复 `go vet ./...` 失败并收口静态分析门禁

#### 目标
让项目重新具备诚实宣称 `go vet` 通过的资格。

#### 具体动作
1. 修复：
   - `internal/api/handler/avatar_handler_test.go`
   - `internal/api/handler/export_handler_test.go`
2. 所有 `resp` 使用前先检查 `err`
3. 扫描同类 helper/测试模式，避免只修报错行

#### 验证
- `go vet ./...`
- `go test ./... -count=1`

---

### P1-2：把宽松状态码测试改成严格契约测试

#### 目标
让测试真正约束行为，而不是“什么都算通过”。

#### 具体动作
1. 优先重写以下测试文件：
   - `internal/api/handler/export_handler_test.go`
   - `internal/api/handler/sso_handler_test.go`
2. 逐场景收紧断言：
   - 未认证 → 401
   - 未授权 → 403
   - 参数错误 → 400
   - 成功 → 200 / 302
3. 删除允许 `500` 的正常断言路径
4. 对有环境差异的场景，先修被测逻辑，再收紧测试
5. 针对 SSO 补充协议级回归测试：
   - `/token` 不再被平台 BearerAuth 门禁误拦
   - `/introspect` / `/revoke` 权限模型正确
   - `/userinfo` 基于 SSO token，而不是平台 session
6. 对关键契约类 handler 增加“路由/方法/状态码固定断言”

#### 验证
- 受影响包 `go test -count=1`
- 必须确保断言收紧后仍稳定通过

---

### P1-3：强化 JWT secret 治理为启动硬门禁

#### 目标
让 release 模式下的 JWT 配置符合项目自身文档标准。

#### 具体动作
1. 明确 `config.Load()` 下的正常启动规则
2. 在 release/standard 服务路径中强制：
   - secret 缺失 → fail fast
   - weak secret → fail fast
3. 保留 `LoadForBootstrap()` 仅用于初始化场景
4. 增加配置单元测试

#### 验证
- `go test ./internal/config -count=1`
- 缺失/弱 secret 场景必须失败

---

### P1-4：接通用户状态 / 权限变更后的缓存失效链路

#### 目标
避免密码、状态、角色、权限变更后继续使用陈旧缓存。

#### 具体动作
1. 梳理以下写路径：
   - `ChangePassword`
   - `UpdateStatus`
   - `BatchUpdateStatus`
   - `AssignRoles`
   - `DeleteAdmin`
   - `AssignPermissions`
2. 设计缓存失效注入方式
   - 推荐通过依赖注入引入失效能力
   - 不要让 service 直接依赖具体 middleware 实现细节
3. 在写路径完成后主动失效：
   - user_state
   - user_perms
   - 受影响角色下的用户权限缓存

#### 验证
- 增加回归测试：
  - 改密码后旧 token / 旧状态缓存失效
  - 改角色/权限后权限即时生效

---

### P1-5：清理拟真 secret 示例

#### 目标
恢复文档敏感边界清洁度。

#### 具体动作
1. 清理 `docs/archive/OAUTH_INTEGRATION.md` 中拟真值
2. 全仓搜索其它类似格式示例
3. 统一替换为显式占位符

#### 验证
- 搜索确认无拟真 secret 示例残留

---

## 四、P2 修复计划（在 P0/P1 收口后处理）

### P2-1：修复 `strconvAtoi` 吞错问题

#### 目标
非法 status 参数返回显式错误，而不是静默当作 0。

#### 动作
1. 修改 `internal/api/handler/export_handler.go` 中 `strconvAtoi`
2. 非数字输入返回 error
3. `ExportUsers` 中对非法 `status` 返回 400
4. 增加回归测试

#### 验证
- `status=abc` → 400

---

### P2-2：头像上传改为流式写盘

#### 目标
消除不必要的整块内存分配。

#### 动作
1. 用 `os.Create` + `io.Copy` 代替 `Read + WriteFile`
2. 保持现有 magic bytes 校验逻辑
3. 确保失败时清理半成品文件

#### 验证
- 头像上传相关测试通过
- 文件写入失败场景仍能回滚

---

### P2-3：头像上传响应改为明确 struct

#### 目标
让返回 schema 与注释一致。

#### 动作
1. 引入明确响应 struct
2. 更新 Swagger 注释 / handler 返回值
3. 同步前端类型

#### 验证
- 相关 handler test
- 前端编译通过

---

### P2-4：前端构建大 chunk 警告优化

#### 目标
降低主包体积，改善生产可维护性。

#### 动作
1. 识别大 chunk 页面
2. 做路由级动态拆分
3. 必要时拆分 antd 重型页面模块

#### 验证
- `npm run build`
- 观察 chunk 体积变化

---

## 五、修复计划完整性审核

本节用于确认：**计划是否覆盖 review 报告中的全部问题**。

| Review 问题 | 计划覆盖项 | 覆盖状态 |
|---|---|---|
| Swagger 空壳 | P0-1 | 已覆盖 |
| Swagger 注释与真实路由系统性漂移 | P0-2 | 已覆盖 |
| SSO code 未绑定 redirect_uri | P0-3 | 已覆盖 |
| SSO implicit flow | P0-4 | 已覆盖 |
| SSO `/token` `/introspect` `/revoke` `/userinfo` 鉴权模型错误 | P0-5 | 已覆盖 |
| 宽松状态码测试掩盖问题 | P1-2 | 已覆盖 |
| `go vet` 不通过 | P1-1 | 已覆盖 |
| JWT secret 硬门禁不足 | P1-3 | 已覆盖 |
| 状态 / 权限缓存失效未接入 | P1-4 | 已覆盖 |
| 拟真 secret 示例 | P1-5 | 已覆盖 |
| `strconvAtoi` 吞错 | P2-1 | 已覆盖 |
| 头像整块读入内存 | P2-2 | 已覆盖 |
| 头像响应 schema 漂移 | P2-3 | 已覆盖 |

### 审核结论

当前修复计划已经覆盖 review 报告中的**全部问题项**。  
其中最关键的改进是：

- 不再把“Swagger 路由错误”视为单点问题，而是按**系统性契约漂移**处理
- 新增 P0-5，明确修复 SSO route group / auth model 的结构性错误

这两点补齐后，计划才具备“能够完整修复 review 报告问题”的条件。

---

## 六、推荐执行顺序

### 阶段 1：协议与契约止血
1. P0-5 修 SSO route group / auth model
2. P0-3 修 SSO code / redirect_uri 绑定
3. P0-4 禁 implicit flow
4. P0-2 系统性修正 Swagger 注释与真实路由漂移
5. P0-1 生成有效 Swagger

### 阶段 2：质量门禁与测试收口
6. P1-1 修复 `go vet`
7. P1-2 收紧 export / sso / 契约类 handler 测试
8. P1-3 强化 JWT secret 启动门禁

### 阶段 3：一致性与边界治理
9. P1-4 接通缓存失效链路
10. P1-5 清理拟真 secret 示例

### 阶段 4：实现质量优化
11. P2-1 修 status 参数吞错
12. P2-2 头像流式写盘
13. P2-3 头像响应 struct 化
14. P2-4 前端 chunk 优化

---

## 七、每阶段完成后的最小验证矩阵

### P0 阶段后
```bash
go test ./internal/auth ./internal/api/handler ./internal/api/router -count=1
go build ./cmd/server
```
并检查 Swagger 生成结果。

### P1 阶段后
```bash
go vet ./...
go test ./... -count=1
go build ./cmd/server
cd frontend/admin && env -u NODE_ENV npm run test:run
cd frontend/admin && env -u NODE_ENV npm run build
```

### P2 阶段后
按受影响范围重跑：

```bash
go test ./internal/api/handler ./internal/service ./internal/repository -count=1
cd frontend/admin && env -u NODE_ENV npm run build
```

---

## 八、完成标准

只有同时满足以下条件，才能把本轮问题标记为“已收口”：

1. SSO code flow 绑定完整，implicit flow 已禁用
2. SSO `/token`、`/introspect`、`/revoke`、`/userinfo` 的访问控制模型正确
3. Swagger 文档非空且关键路径正确
4. 注释 / 路由 / 文档 / 前端 / 测试中的 API 契约一致
5. `go vet ./...` 通过
6. handler 关键测试不再接受互斥状态码混过
7. JWT secret 治理与项目文档标准一致
8. 缓存失效链路有真实接入与回归测试
9. 状态文档与 README 只保留已验证事实