415 lines
12 KiB
Markdown
415 lines
12 KiB
Markdown
# Hermes Full Review — 2026-05-27
|
||
|
||
- 仓库：`/home/long/project/user-system`
|
||
- 分支：`main`
|
||
- 基线提交：`82109ec Merge branch 'fix/status-review-sync-20260409'`
|
||
- 审查方式：文档对齐 + 代码静态复核 + 本地构建/测试/审计实测 + 二次复核补查
|
||
- 结论：**❌ Not Ready / 当前不建议发布**
|
||
|
||
---
|
||
|
||
## 1. Executive Summary
|
||
|
||
当前仓库不是“完全不可运行”，但**不满足诚实发布条件**。阻断原因主要有三类：
|
||
|
||
1. **安全 / 权限 P0 问题**
|
||
- 普通登录用户可枚举全部用户并读取任意用户详情
|
||
- TOTP 二次验证被降级成可单独换取登录态的入口
|
||
- 多个“未配置”认证/绑定接口返回 `200 + code:0`，形成假成功
|
||
|
||
2. **后端 clean-state 基线不绿**
|
||
- `go build ./cmd/server`
|
||
- `go vet ./...`
|
||
- `go test ./... -count=1`
|
||
- 三者在当前提交态均失败，并提示 `go mod tidy`
|
||
|
||
3. **文档状态比代码现实更乐观**
|
||
- README / 状态文档存在“已闭环 / 已完成”表述
|
||
- 但实际仍有主链路契约漂移、假成功与 clean-state 基线不干净问题
|
||
|
||
---
|
||
|
||
## 2. 审查范围与方法
|
||
|
||
### 2.1 读取的关键文件
|
||
- `AGENTS.md`
|
||
- `README.md`
|
||
- `docs/PRD.md`
|
||
- `docs/status/REAL_PROJECT_STATUS.md`
|
||
- `go.mod`
|
||
- `frontend/admin/package.json`
|
||
|
||
### 2.2 执行的关键命令
|
||
|
||
后端：
|
||
- `go version`
|
||
- `go build ./cmd/server`
|
||
- `go vet ./...`
|
||
- `go test ./... -count=1`
|
||
- `go test -mod=mod ./internal/repository -count=1`
|
||
- `go test -mod=mod ./... -count=1`
|
||
- `go test ./... -coverprofile=/tmp/user-system-cover.out -count=1`
|
||
- `go tool cover -func=/tmp/user-system-cover.out`
|
||
|
||
前端：
|
||
- `npm ci`
|
||
- `env -u NODE_ENV npm ci`
|
||
- `env -u NODE_ENV npm run lint`
|
||
- `env -u NODE_ENV npm run build`
|
||
- `env -u NODE_ENV npm run test:run`
|
||
- `env -u NODE_ENV npm run test:coverage`
|
||
- `env -u NODE_ENV npm audit --omit=dev --json`
|
||
- `env -u NODE_ENV npm audit --json`
|
||
|
||
---
|
||
|
||
## 3. 验证快照
|
||
|
||
### 3.1 环境事实
|
||
- Go：`go1.26.3 linux/amd64`
|
||
- Node：`v22.22.0`
|
||
- npm：`10.9.4`
|
||
- 观察到默认 shell 存在：`NODE_ENV=production`
|
||
|
||
### 3.2 环境风险
|
||
默认 `NODE_ENV=production` 会导致第一次 `npm ci` 只安装生产依赖，进而出现：
|
||
- `eslint: not found`
|
||
- `tsc: not found`
|
||
- `@vitejs/plugin-react` not found
|
||
|
||
这说明 runbook / CI 若不显式控制环境变量，前端验证容易误判。
|
||
|
||
### 3.3 后端实测
|
||
|
||
#### 当前提交态 / clean-state
|
||
以下命令均失败：
|
||
- `go build ./cmd/server`
|
||
- `go vet ./...`
|
||
- `go test ./... -count=1`
|
||
|
||
统一报错：
|
||
```text
|
||
go: updates to go.mod needed; to update it:
|
||
go mod tidy
|
||
```
|
||
|
||
#### 探索性验证
|
||
为了区分“代码问题”与“模块清单漂移问题”，额外执行：
|
||
- `go test -mod=mod ./internal/repository -count=1` → **PASS**
|
||
- `go test -mod=mod ./... -count=1` → **PASS**
|
||
|
||
说明：核心代码不是全部跑不起来，但**提交态本身不干净**。
|
||
|
||
#### 覆盖率
|
||
- `go tool cover -func=/tmp/user-system-cover.out`
|
||
- 总覆盖率：**52.4%**
|
||
|
||
### 3.4 前端实测
|
||
在显式移除 `NODE_ENV=production` 影响后：
|
||
- `env -u NODE_ENV npm ci` → **PASS**
|
||
- `env -u NODE_ENV npm run lint` → **PASS**
|
||
- `env -u NODE_ENV npm run build` → **PASS**
|
||
- `env -u NODE_ENV npm run test:run` → **PASS**
|
||
- `82` 个 test files
|
||
- `518` 个 tests
|
||
- `env -u NODE_ENV npm run test:coverage` → **PASS**
|
||
|
||
前端 coverage：
|
||
- Statements: **89.83%**
|
||
- Branch: **80.38%**
|
||
- Funcs: **88.24%**
|
||
- Lines: **90.36%**
|
||
|
||
### 3.5 前端依赖审计
|
||
- `env -u NODE_ENV npm audit --omit=dev --json` → **0 漏洞**
|
||
- `env -u NODE_ENV npm audit --json` → **5 漏洞**
|
||
- 含 **1 个 high**：`vite 8.0.3`
|
||
|
||
---
|
||
|
||
## 4. Blockers（必须修复）
|
||
|
||
### P0-1 普通登录用户可枚举全部用户并读取任意用户详情
|
||
**证据**
|
||
- `internal/api/router/router.go:206-215`
|
||
- `internal/api/handler/user_handler.go:90-165`
|
||
|
||
**问题**
|
||
- `GET /api/v1/users`
|
||
- `GET /api/v1/users/:id`
|
||
|
||
当前仅挂在 `protected.Use(r.authMiddleware.Required())` 下，未加：
|
||
- `AdminOnly`
|
||
- `RequirePermission`
|
||
- 本人访问约束
|
||
|
||
**影响**
|
||
普通用户可读取其他用户列表 / 详情 / 邮箱等信息，属于明确数据越权。
|
||
|
||
---
|
||
|
||
### P0-2 TOTP 验证接口可单独换取登录态，二次验证被降级为单因子登录
|
||
**证据**
|
||
- `internal/api/handler/auth_handler.go:151-172`
|
||
- `internal/service/auth.go:811-831`
|
||
|
||
**问题**
|
||
`POST /api/v1/auth/login/totp-verify` 只依赖：
|
||
- `user_id`
|
||
- `code`
|
||
- `device_id`
|
||
|
||
没有要求：
|
||
- 已完成密码登录
|
||
- 临时 challenge ticket
|
||
- 短期 server-side login session
|
||
|
||
**影响**
|
||
拿到 TOTP / 恢复码即可直接换取完整 token，安全模型错误。
|
||
|
||
---
|
||
|
||
### P0-3 未实现的绑定 / OAuth 接口使用 `200 + code:0` 伪装成功
|
||
**证据**
|
||
- `internal/api/handler/auth_handler.go:316-355`
|
||
- `internal/api/handler/auth_handler.go:563-660`
|
||
- `frontend/admin/src/lib/http/client.ts:274-279`
|
||
- `frontend/admin/src/pages/admin/ProfileSecurityPage/ContactBindingsSection.tsx:141-216`
|
||
|
||
**问题**
|
||
后端在以下场景仍返回成功语义：
|
||
- OAuth not configured
|
||
- email bind not configured
|
||
- phone bind not configured
|
||
- social binding not configured
|
||
|
||
前端只要 `code===0` 就按成功处理。
|
||
|
||
**影响**
|
||
用户会看到“已绑定 / 已解绑 / 已发送验证码”等成功反馈，但实际无状态变化。
|
||
|
||
---
|
||
|
||
### P0-4 Bootstrap Admin 前后端契约冲突，首个管理员初始化默认不可用
|
||
**证据**
|
||
前端：
|
||
- `frontend/admin/src/pages/auth/BootstrapAdminPage/BootstrapAdminPage.tsx:24-30,68-76`
|
||
- `frontend/admin/src/services/auth.ts:61-63`
|
||
|
||
后端：
|
||
- `internal/api/handler/auth_handler.go:504-527`
|
||
|
||
**问题**
|
||
前端未满足后端强制契约：
|
||
- 缺少 `X-Bootstrap-Secret`
|
||
- `email` 前端可为空，但后端必填
|
||
|
||
**影响**
|
||
首次部署时最关键的 bootstrap 链路可能直接失败。
|
||
|
||
---
|
||
|
||
### P0-5 clean-state 后端构建基线不绿
|
||
**证据**
|
||
- `go build ./cmd/server` → fail
|
||
- `go vet ./...` → fail
|
||
- `go test ./... -count=1` → fail
|
||
- 统一要求 `go mod tidy`
|
||
|
||
**影响**
|
||
当前 `main` 不满足仓库 AGENTS 要求的最低验证矩阵，不能诚实宣称“始终可构建、可测试通过”。
|
||
|
||
---
|
||
|
||
## 5. High / Important Issues
|
||
|
||
### P1-1 Logout fail-open，token 失效失败也返回成功
|
||
**证据**
|
||
- `internal/service/auth.go:897-925`
|
||
- `internal/api/handler/auth_handler.go:185-209`
|
||
|
||
**问题**
|
||
黑名单写入错误被忽略，handler 仍返回 `200 logged out`。
|
||
|
||
---
|
||
|
||
### P1-2 多个 handler 的管理员判断读错 context key
|
||
**证据**
|
||
middleware 写入：
|
||
- `internal/api/middleware/auth.go:85-91`
|
||
- 写入 `role_codes`, `permission_codes`
|
||
|
||
handler 读取：
|
||
- `internal/api/handler/user_handler.go:188-200`
|
||
- `internal/api/handler/user_handler.go:374-383`
|
||
- `internal/api/handler/avatar_handler.go:72-85`
|
||
- 读取的是 `user_roles`
|
||
|
||
**影响**
|
||
管理员代操作逻辑可能失效，权限模型与实际行为漂移。
|
||
|
||
---
|
||
|
||
### P1-3 修改密码接口与注释声明不一致
|
||
**证据**
|
||
- `internal/api/router/router.go:211-213`
|
||
- `internal/api/handler/user_handler.go:275-297`
|
||
|
||
**问题**
|
||
注释写“仅管理员或本人”，但 handler 没有显式按该规则做校验。
|
||
|
||
---
|
||
|
||
### P1-4 密码历史记录异步写入，事务不完整
|
||
**证据**
|
||
- `internal/service/user_service.go:128-145`
|
||
|
||
**问题**
|
||
密码更新同步写库，但密码历史在 goroutine 中异步写入且错误吞掉。
|
||
|
||
---
|
||
|
||
### P1-5 Avatar token 随机源错误未 fail-closed
|
||
**证据**
|
||
- `internal/api/handler/avatar_handler.go:35-39`
|
||
|
||
**问题**
|
||
`rand.Read(bytes)` 错误被忽略。
|
||
|
||
---
|
||
|
||
## 6. 二次复核补充（第一次遗漏后补查）
|
||
|
||
### 6.1 前端测试绿，但没挡住真实 API 契约漂移
|
||
- 前端测试：`518 passed`
|
||
- 但 bootstrap-admin、contact bindings、OAuth 与真实后端契约仍不一致
|
||
|
||
**判断**
|
||
这是测试体系盲点，不是“测试通过即可放心”。
|
||
|
||
### 6.2 前端开发依赖存在 1 个 high 漏洞
|
||
- `vite 8.0.3` high
|
||
- 另有 moderate 级别依赖漏洞
|
||
|
||
### 6.3 `NODE_ENV=production` 造成验证误判风险
|
||
- 未显式控制环境变量时，devDependencies 可能缺失
|
||
- 容易把环境问题误判为代码问题
|
||
|
||
### 6.4 后端总覆盖率仅 52.4%
|
||
在当前已有多条认证 / 权限高风险链路下，后端覆盖率偏低会放大回归风险。
|
||
|
||
### 6.5 测试 warning 噪音较多
|
||
实测出现：
|
||
- `act(...)` warning
|
||
- React Router future flag warning
|
||
- `danger` 非布尔 attribute warning
|
||
- `addonAfter` deprecated warning
|
||
- React list key warning
|
||
|
||
虽然不阻断当前前端测试通过，但说明测试基线不够干净。
|
||
|
||
---
|
||
|
||
## 7. 文档真相审查
|
||
|
||
### 结论：❌ 未闭环
|
||
当前 README 与 `docs/status/REAL_PROJECT_STATUS.md` 存在“闭环 / 已完成 / 当前绿色”等偏乐观表述，但 live review 证明：
|
||
- 后端 clean-state 不绿
|
||
- bootstrap-admin 主链路漂移
|
||
- 绑定 / OAuth 存在假成功
|
||
- 权限模型存在 P0
|
||
|
||
建议文档至少降级为：
|
||
|
||
> 前端 lint/build/test 当前可通过；后端代码在 `-mod=mod` 探索性测试下大体可运行，但 clean-state 构建基线未绿；认证 / 权限 / 绑定链路仍有 P0 阻断，不可宣称发布闭环。
|
||
|
||
---
|
||
|
||
## 8. 四类闭环判断
|
||
|
||
### 8.1 实现闭环
|
||
**状态：❌**
|
||
- 权限越权未解决
|
||
- TOTP 流程模型错误
|
||
- bootstrap-admin 契约漂移
|
||
- binding / OAuth 实际未闭环
|
||
|
||
### 8.2 证据闭环
|
||
**状态：✅/⚠️ 部分成立**
|
||
- 前端构建 / 测试证据充分
|
||
- 后端 clean-state 失败证据明确
|
||
- 但这些事实尚未同步进主状态文档
|
||
|
||
### 8.3 文档真相闭环
|
||
**状态：❌**
|
||
- 当前对外状态文档比代码现实更乐观
|
||
|
||
### 8.4 防复发闭环
|
||
**状态：❌**
|
||
尚未看到系统性防线去约束：
|
||
- binding / OAuth 禁止 200 假成功
|
||
- bootstrap 前后端契约对齐校验
|
||
- `/users` 与 `/:id` 权限回归测试
|
||
- clean-state `go build/vet/test` gate
|
||
- 真实 API contract 联调验证
|
||
|
||
---
|
||
|
||
## 9. 最终评级
|
||
|
||
| 维度 | 评级 | 说明 |
|
||
|---|---|---|
|
||
| 需求 / 实现一致性 | C | 多条主链路契约漂移 |
|
||
| 安全基线 | D | 存在 P0 权限 / 认证问题 |
|
||
| 构建与测试基线 | C | 前端绿，后端 clean-state 红 |
|
||
| 可维护性 | B- | 结构尚可，但存在 context key 漂移 / fail-open / 异步事务问题 |
|
||
| 文档真相 | C- | 文档明显乐观于代码现实 |
|
||
| 发布就绪度 | D | 当前不建议发布 |
|
||
|
||
**综合评级：D / Not Ready**
|
||
|
||
---
|
||
|
||
## 10. 修复优先级建议
|
||
|
||
### P0（先修）
|
||
1. 修复 `/api/v1/users` 与 `/:id` 越权
|
||
2. 重构 `totp-verify`，必须绑定密码登录 challenge
|
||
3. 所有未实现的 binding / OAuth 接口改为 fail-closed，并同步前端处理
|
||
4. 修复 bootstrap-admin 前后端契约
|
||
5. 清理 `go.mod/go.sum` 漂移，恢复 clean-state build/vet/test 绿灯
|
||
|
||
### P1（紧随其后）
|
||
6. 修复 logout fail-open
|
||
7. 修复 `user_roles` / `role_codes` context key 漂移
|
||
8. 修复 password history 异步写入的事务缺口
|
||
9. 修复 avatar token 生成未检查错误
|
||
10. 升级前端 dev toolchain 漏洞（至少 vite）
|
||
|
||
### P2（收口）
|
||
11. 清理测试 warning 噪音
|
||
12. 补真实 API contract 集成测试
|
||
13. 更新 README / `docs/status/REAL_PROJECT_STATUS.md`
|
||
|
||
---
|
||
|
||
## 11. 本次二次 Review 的新增补充摘要
|
||
|
||
相较第一次结论，本次额外明确了以下问题：
|
||
1. 前端测试体系没有挡住真实 API 契约漂移
|
||
2. 前端 dev toolchain 存在 1 个 high 漏洞（Vite）
|
||
3. `NODE_ENV=production` 会导致 devDependencies 缺失，runbook / CI 易误判
|
||
4. 后端总覆盖率仅 52.4%
|
||
5. 测试输出 warning 噪音较多，质量门禁不够干净
|
||
|
||
---
|
||
|
||
## 12. 最终结论
|
||
|
||
**当前建议：不要发布；先修两个 high blocker 类问题，再推进剩余 P0 / P1。**
|
||
|
||
其中最先收口的方向应是：
|
||
- 认证 / 权限真安全
|
||
- clean-state 构建真绿色
|
||
- 文档真相与代码现实一致
|