user-system/docs/review-fix-closure-2026-05-28.md

# user-system review 修复收口（2026-05-28）

## 结论
本轮已完成 review 报告相关最高优先级前端/E2E blocker 修复，并完成后端、前端、E2E 三层验证。

当前状态：
- 最高优先级 blocker：已修复
- Go 全量测试：通过
- 前端全量测试：通过（82 files, 522 tests）
- Playwright CDP 全链路 E2E：通过

## 本轮修复项

### 1. 会话恢复 / refresh 竞态
- 问题：`AuthProvider` 初始恢复会话与 HTTP client 401 重试路径会并发触发 `/auth/refresh`，在 refresh token 轮换模型下导致 `401`。
- 修复：前端改为共享 single-flight refresh。
- 涉及文件：
  - `frontend/admin/src/lib/http/client.ts`
  - `frontend/admin/src/services/auth.ts`
  - `frontend/admin/src/services/auth.test.ts`

### 2. 用户列表响应结构漂移
- 问题：后端 `/users` 返回 `{ users, total, limit, offset }`，前端只按 `items` 读取，导致页面空表。
- 修复：增加 users 列表 normalize，兼容 `items/users` 和 `page_size/limit/offset`。
- 涉及文件：
  - `frontend/admin/src/services/users.ts`
  - `frontend/admin/src/services/users.test.ts`

### 3. Webhooks 列表响应结构漂移
- 问题：Webhooks 页加载时报 `Cannot read properties of undefined (reading 'map')`。
- 修复：兼容 `data/items/webhooks` 多种列表包裹形状。
- 涉及文件：
  - `frontend/admin/src/services/webhooks.ts`
  - `frontend/admin/src/services/webhooks.test.ts`

### 4. Social accounts 响应结构漂移
- 问题：ProfileSecurityPage 报 `socialAccounts.map is not a function`。
- 修复：兼容 `array/items/accounts/social_accounts` 形状。
- 涉及文件：
  - `frontend/admin/src/services/social-accounts.ts`
  - `frontend/admin/src/services/social-accounts.test.ts`

### 5. Playwright CDP E2E harness 漂移
- 修复点包括：
  - refresh token 断言从可读 cookie 改为 HttpOnly cookie / session presence 真相
  - `创建用员` 文案 typo
  - responsive 场景后 viewport 未恢复
  - drawer 选择器 strict mode 冲突
  - delete confirm 由 modal 漂移为 popconfirm
  - 菜单分组/路由漂移：设备、审计日志、Webhooks、profile/security
  - 多处页面断言从宽文本改为更稳定选择器
- 涉及文件：
  - `frontend/admin/scripts/run-playwright-cdp-e2e.mjs`
  - `frontend/admin/scripts/run-playwright-auth-e2e.sh`

### 6. E2E 限流误伤
- 问题：测试流量触发 API rate limit，导致后续场景误报。
- 修复：为 E2E backend 增加 `DISABLE_RATE_LIMIT=1` 开关，仅用于测试启动脚本。
- 涉及文件：
  - `internal/api/middleware/ratelimit.go`
  - `frontend/admin/scripts/run-playwright-auth-e2e.sh`

### 7. 内存限流器全局误伤与条目泄漏风险
- 问题：`internal/api/middleware/ratelimit.go` 之前按 endpoint 只创建单一 limiter，导致同一接口上的所有用户共享一个桶；同时缺少空闲条目清理策略，无法对历史 client key 做收敛。
- 修复：改为按 `endpoint + user_id/IP` 分桶，并在访问路径上按 TTL 清理长期空闲的 limiter 条目。
- 回归测试：
  - 不同 IP 的登录限流相互独立
  - 共享 IP 下不同 `user_id` 的 API 限流相互独立
  - 空闲 limiter 会被清理，不再无限累积
- 涉及文件：
  - `internal/api/middleware/ratelimit.go`
  - `internal/api/middleware/ratelimit_test.go`

### 8. handler context 类型断言补强
- 问题：`SSOHandler` 与 `WebhookHandler` 仍存在 `user_id.(int64)` / `username.(string)` 直接断言，若 middleware 注入异常类型会触发 panic。
- 修复：统一复用 `getUserIDFromContext` / `getUsernameFromContext`，类型不匹配时返回 `401 unauthorized`，避免 handler panic。
- 回归测试：
  - `SSOHandler.Authorize` 非法 context 类型返回 `401`
  - `SSOHandler.UserInfo` 非法 context 类型返回 `401`
  - `WebhookHandler.CreateWebhook/ListWebhooks` 非法 context 类型返回 `401`
- 涉及文件：
  - `internal/api/handler/auth_handler.go`
  - `internal/api/handler/sso_handler.go`
  - `internal/api/handler/webhook_handler.go`
  - `internal/api/handler/context_guard_test.go`

### 9. 密码强度 + 静默错误补强
- 问题：review 报告中指出两类尾部问题：
  - 默认密码校验对刚好达到最小长度的短密码过于宽松
  - TOTP / 操作日志链路存在 `_ = err`、`_ = json.Unmarshal(...)`、`_ = repo.Create(...)` 这类静默吞错
- 修复：
  - `validatePasswordStrength` 改为对“刚好达到最小长度”的密码要求至少 3 种字符类型；较长密码仍保留 2 种类型可过的兼容行为
  - `TOTPService` 对恢复码摘要、JSON 编解码、`UpdateTOTP` 持久化失败全部显式返回错误，不再静默忽略
  - `OperationLogMiddleware` 对 nil repo fail-safe 返回；异步落库失败改为写日志，不再无声吞错
- 回归测试：
  - 8 位两类字符密码被拒绝，8 位三类字符密码通过，较长两类字符密码仍通过
  - 损坏的恢复码 JSON 会返回解析错误
  - 恢复码消费后持久化失败会显式返回更新错误
  - operation log 在 nil repo 情况下不会 panic，参数脱敏/非 JSON fallback 继续受测
- 涉及文件：
  - `internal/service/auth.go`
  - `internal/service/auth_service_test.go`
  - `internal/service/auth_password_internal_test.go`
  - `internal/service/totp.go`
  - `internal/service/totp_internal_test.go`
  - `internal/api/middleware/operation_log.go`
  - `internal/api/middleware/operation_log_test.go`

### 10. review 报告真相校准 + avatar 路径硬化
- 真相校准：`PROJECT_REVIEW_REPORT.md` 中一批条目已不再代表当前仓库真相，至少包括：
  - `uploadAvatar` 字段名错误：前后端当前都使用 `avatar`，该条为陈旧误报
  - `StateManager` 无法停止、`L1Cache` 无容量限制、密码强度过宽松、操作日志未转义、Webhooks 客户端全量分页、`ContactBindingsSection` 未复用：均已在后续提交中关闭
- 仍值得继续跟踪、但已不构成功能 blocker 的尾项：
  - `social_account_repo.go` 仍是原生 SQL 实现
  - `AuthProvider` 仍保留 React state + session store 双轨状态管理
  - `ApiResponse.data` 空值建模仍偏乐观（`T` 而非 `T | null`）
- 本轮额外修复：
  - 将头像上传目录从运行时相对路径解析改为绝对路径归一化，避免 cwd 漂移导致文件落盘位置不稳定
  - 扩展名校验统一转小写，避免 `.JPG/.PNG` 这类常见文件名被误拒
- 回归测试：
  - `resolveAvatarUploadDir("")` 返回绝对路径且收敛到 `/uploads/avatars`
  - 自定义根目录会被保留并归一化到 `<root>/avatars`
- 涉及文件：
  - `internal/api/handler/avatar_handler.go`
  - `internal/api/handler/avatar_handler_path_test.go`

## 验证结果

### 后端
- 命令：`go test ./...`
- 结果：通过

### 前端
- 命令：`npm test -- --runInBand`
- 结果：通过
- 统计：`82 passed`, `522 passed`

### E2E
- 命令：`npm run e2e:full`
- 结果：通过
- 结论：`Playwright CDP E2E completed successfully`

## 闭环判断

### 实现闭环
已完成。本轮识别出的真实 blocker 均已修复。

### 证据闭环
已完成。Go 全量测试、前端全量测试、CDP E2E 全部通过。

### 文档真相闭环
已完成。本文件记录了问题、修复、验证与当前结论。

### 防复发闭环
已部分完成：
- 已为 users/webhooks/social-accounts 响应结构漂移补 service-level normalize + tests
- 已把 refresh 单飞与 E2E harness 漂移修复固化
- 后续建议：把 E2E 页面导航/断言进一步抽象为页面对象或稳定 helper，减少文案/菜单变动带来的连锁断言漂移