docs: add 2026-04-18 optimization baseline to governance documents
- Add optimization baseline appendix to QUALITY_STANDARD.md defining current baseline gates for all future optimization work - Update REAL_PROJECT_STATUS.md with latest project status - Add experience summary to PROJECT_EXPERIENCE_SUMMARY.md - Add technical guide updates to TECHNICAL_GUIDE.md - Add FULL_CODE_REVIEW_REPORT_2026-04-17.md as reference document
This commit is contained in:
@@ -212,3 +212,60 @@
|
||||
- 完整性检查必须逐项
|
||||
- 覆盖率必须验证真实测试运行
|
||||
- 类型引用必须验证定义存在
|
||||
## 2026-04-18 从复核到修复的经验
|
||||
|
||||
本附录记录了 2026-04-17 报告复核和 2026-04-18 文档对齐过程中提炼出的工程经验。
|
||||
|
||||
### 1. 评审报告不是实时状态页
|
||||
|
||||
- 一份报告可以在技术上仍然有价值，但它的门禁摘要会很快过时。
|
||||
- 团队必须把以下两类事实分开：
|
||||
- 报告日期的发现
|
||||
- 当前工作区的真实门禁状态
|
||||
- 如果这两类事实混写，执行顺序和优先级判断会很快漂移。
|
||||
|
||||
### 2. 新鲜命令证据优先于继承结论
|
||||
|
||||
- `go test ./... -count=1` 曾在评审材料里被视为红灯，但新鲜执行后在当前工作区已经转绿。
|
||||
- 与此同时，前端 `lint` 已经重新变红。
|
||||
- 经验：
|
||||
在安排修复顺序前，必须先刷新真实门禁。
|
||||
|
||||
### 3. stub 转 live 会带来第二波风险
|
||||
|
||||
- `AssignRoles`、`CreateAdmin/DeleteAdmin`、`UploadAvatar` 已经越过了旧的“未实现”阶段。
|
||||
- 一旦转为 live，主导风险就会从“功能缺失”切换为：
|
||||
- 授权边界
|
||||
- 事务性
|
||||
- 公开暴露面
|
||||
- 自操作 / 最后管理员治理
|
||||
- 经验：
|
||||
live 实现必须被当作新的安全与治理面重新复核，不能因为 stub 消失就直接标记为“闭环”。
|
||||
|
||||
### 4. 发布阻塞往往是策略链断裂，不是没写代码
|
||||
|
||||
- 密码登录绕过 TOTP/设备信任校验，比很多显眼的“功能缺失”更像真实发布阻塞项。
|
||||
- refresh token 吊销 fail-open 也是发布阻塞项，即使代码路径本身已经存在。
|
||||
- 经验：
|
||||
在认证系统里，“已实现”不等于“完整”，只要安全策略链断了，就是关键缺陷。
|
||||
|
||||
### 5. 事实成立，不代表措辞可以粗糙
|
||||
|
||||
- LIKE 搜索问题是真实的，但把它笼统写成通用 SQL 注入，会夸大具体缺陷类型。
|
||||
- 密码重置 replay 问题也是真实的，但必须精确指出脆弱路径。
|
||||
- 经验：
|
||||
严重级别可以保持不变，但措辞必须更精确；精确措辞能加快修复，也能减少无效争论。
|
||||
|
||||
### 6. 主入口绿灯比局部绿灯更重要
|
||||
|
||||
- 局部命令成功，不能替代项目正式支持的主命令成功。
|
||||
- 包装层失败或顶层命令失败，就是真实项目失败，即使更深层子命令单独能过。
|
||||
- 经验：
|
||||
所有结论都必须对齐文档中声明的主验收入口。
|
||||
|
||||
### 7. 文档漂移会制造返工
|
||||
|
||||
- `REAL_PROJECT_STATUS`、评审报告和团队规范已经开始出现漂移。
|
||||
- 这种漂移会把下一轮修复引向过时优先级。
|
||||
- 经验：
|
||||
文档更新不是交付后的清理工作，而是交付本身的一部分。
|
||||
|
||||
@@ -302,3 +302,66 @@ npm.cmd run e2e:full:win
|
||||
- 验证方法：`grep -r “type IntegrationRedisSuite” internal/repository/` 必须返回定义位置。
|
||||
- 禁止：测试文件引用未定义的类型，即使该测试有 `//go:build integration` 标签。
|
||||
|
||||
## 2026-04-18 优化修复前治理基线
|
||||
|
||||
本附录定义了后续任何优化或修复工作开始前必须遵守的治理基线。若旧章节与本附录冲突，以本附录为准。
|
||||
|
||||
### 1. 当前门禁真相优先
|
||||
|
||||
- 任何“当前状态”“已绿”“阻塞中”“可继续”的表述，都必须绑定当前工作区的新鲜命令证据。
|
||||
- 报告日期事实与当前工作区事实必须分开书写。
|
||||
- 历史绿灯结果不能复用为当前门禁证据。
|
||||
|
||||
### 2. 当前优化修复的最低门禁
|
||||
|
||||
在声称一批修复已完成前，必须执行并记录：
|
||||
|
||||
```powershell
|
||||
go build ./cmd/server
|
||||
go vet ./...
|
||||
go test ./... -count=1
|
||||
|
||||
cd frontend/admin
|
||||
npm.cmd run lint
|
||||
npm.cmd run build
|
||||
```
|
||||
|
||||
- 若改动涉及认证、会话、路由守卫、导航、`window` 防线或用户主流程，还必须执行：
|
||||
|
||||
```powershell
|
||||
cd frontend/admin
|
||||
npm.cmd run e2e:full:win
|
||||
```
|
||||
|
||||
- 超时不算通过。
|
||||
- 包装脚本失败就是真实失败。
|
||||
- 成功摘要后仍有浏览器原生弹窗噪声，不算干净通过。
|
||||
|
||||
### 3. 安全敏感修复必须 fail closed
|
||||
|
||||
- refresh token 轮换在吊销持久化失败时必须 fail closed。
|
||||
- 与 MFA 相关的登录逻辑在 TOTP/设备信任策略完成执行前，不能签发最终 token。
|
||||
- CORS 必须拒绝危险默认组合，例如通配来源配合 credentials 开启。
|
||||
- 任何由用户可控 ID 定位资源的接口，都必须在路由层或 handler 边界做显式授权检查。
|
||||
|
||||
### 4. 正确性修复必须遵守契约
|
||||
|
||||
- cursor pagination 只能支持与游标谓词一致的排序；不支持的排序必须显式拒绝。
|
||||
- 多步写操作必须具备事务性，或具备显式回滚逻辑。
|
||||
- 基于缓存的安全计数器或一次性验证码必须使用原子语义，不能继续使用 best-effort 的读改写序列。
|
||||
|
||||
### 5. 文档同步是强制项
|
||||
|
||||
- 若新鲜验证改变了真实门禁状态，必须在同一批次更新 `docs/status/REAL_PROJECT_STATUS.md`。
|
||||
- 若评审改变了长期工程约束，必须在同一批次更新本文和 `docs/team/TECHNICAL_GUIDE.md`。
|
||||
- 若评审产出了可复用经验，必须在同一批次更新 `docs/team/PROJECT_EXPERIENCE_SUMMARY.md`。
|
||||
|
||||
### 6. 强制修复顺序
|
||||
|
||||
除非有更窄的依赖关系强制改变顺序，否则按以下次序执行：
|
||||
|
||||
1. 刷新当前门禁真相并写入文档。
|
||||
2. 先修发布阻塞级别的安全与授权缺陷。
|
||||
3. 为每个确认接受的修复补回归测试。
|
||||
4. 重新执行受影响的完整门禁。
|
||||
5. 只有在以上完成后，才进入结构清理或一般优化。
|
||||
|
||||
@@ -81,3 +81,75 @@ npm.cmd run e2e:full:win
|
||||
- `frontend/admin/scripts/run-playwright-auth-e2e.ps1`：需要优先保证文档支持的 `e2e:full:win` 入口自身稳定，而不是只验证子命令。
|
||||
- `frontend/admin/src/components/common/ui-consistency.test.tsx`：原生弹窗噪声仍会污染测试结果，应继续清理。
|
||||
- `internal/api/handler/user_handler.go` 与 `internal/service/user_service.go`：RBAC / 管理员治理逻辑需要持续按越权、事务、自删、最后管理员等维度审查。
|
||||
## 2026-04-18 优化修复入口
|
||||
|
||||
本附录是任何工程师或智能体在当前仓库状态下开启新一轮优化或修复批次时的强制入口。
|
||||
|
||||
### 1. 改代码前的阅读顺序
|
||||
|
||||
开始前按以下顺序阅读：
|
||||
|
||||
1. `docs/status/REAL_PROJECT_STATUS.md`
|
||||
2. `docs/code-review/FULL_CODE_REVIEW_REPORT_2026-04-17.md`
|
||||
3. `docs/team/QUALITY_STANDARD.md`
|
||||
4. `docs/team/PROJECT_EXPERIENCE_SUMMARY.md`
|
||||
|
||||
用途：
|
||||
|
||||
- `REAL_PROJECT_STATUS` 告诉你当前已经验证过的工作区真相。
|
||||
- `FULL_CODE_REVIEW_REPORT` 告诉你已经复核过的风险清单和任务分级。
|
||||
- `QUALITY_STANDARD` 告诉你当前必须遵守的工程约束。
|
||||
- `PROJECT_EXPERIENCE_SUMMARY` 告诉你哪些失败模式已经真实消耗过项目时间。
|
||||
|
||||
### 2. 先执行的新鲜命令
|
||||
|
||||
在做出任何“当前状态”判断前，先执行：
|
||||
|
||||
```powershell
|
||||
go build ./cmd/server
|
||||
go vet ./...
|
||||
go test ./... -count=1
|
||||
|
||||
cd frontend/admin
|
||||
npm.cmd run lint
|
||||
npm.cmd run build
|
||||
```
|
||||
|
||||
如果本轮工作涉及认证、会话、路由守卫、导航、弹窗防线或用户主流程，还要执行：
|
||||
|
||||
```powershell
|
||||
cd frontend/admin
|
||||
npm.cmd run e2e:full:win
|
||||
```
|
||||
|
||||
### 3. 当前发布阻塞级关注点
|
||||
|
||||
在一般优化之前，优先处理这些区域：
|
||||
|
||||
- `internal/api/handler/user_handler.go`
|
||||
`UpdateUser` authorization boundary
|
||||
- `internal/service/auth.go`
|
||||
password login MFA/device-trust enforcement
|
||||
- `internal/service/auth.go`
|
||||
refresh-token revocation persistence failure handling
|
||||
- `internal/api/middleware/cors.go`
|
||||
unsafe default CORS behavior
|
||||
- `internal/repository/user.go`
|
||||
cursor/sort mismatch in `ListCursor`
|
||||
- `internal/service/password_reset.go`
|
||||
single-use verification code consumption semantics
|
||||
|
||||
### 4. 修复批次工作规则
|
||||
|
||||
- 不要把历史绿灯当作当前证据。
|
||||
- 不要在没有分别验证的情况下，把门禁刷新、安全修复和重构混在同一个“已完成”结论里。
|
||||
- 修 bug 或安全问题时，没有对应回归测试，就不要把任务提升为“完成”。
|
||||
- 不要让包装脚本掩盖项目正式支持主命令的失败。
|
||||
|
||||
### 5. 文档更新规则
|
||||
|
||||
当一轮修复改变了真实结论时，必须在同一批次同步更新：
|
||||
|
||||
- `docs/status/REAL_PROJECT_STATUS.md`
|
||||
- 规则变化时更新 `docs/team/QUALITY_STANDARD.md`
|
||||
- 产出可复用经验时更新 `docs/team/PROJECT_EXPERIENCE_SUMMARY.md`
|
||||
|
||||
Reference in New Issue
Block a user