From 2cd76b28352f4d332f1587c20176982d87fe470f Mon Sep 17 00:00:00 2001 From: long-agent Date: Sat, 11 Apr 2026 10:41:08 +0800 Subject: [PATCH] docs: add multi-round review learnings to team quality docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - PRODUCTION_CHECKLIST: add RBAC/admin governance checklist section - PROJECT_EXPERIENCE_SUMMARY: add lessons from 2026-04-10 reviews (live ≠ done, main-entry green > local green, test noise = quality issue, docs lag = rework) - QUALITY_STANDARD: add stub→live review threshold rules --- docs/team/PRODUCTION_CHECKLIST.md | 16 +++++++++++++ docs/team/PROJECT_EXPERIENCE_SUMMARY.md | 30 +++++++++++++++++++++++++ docs/team/QUALITY_STANDARD.md | 26 +++++++++++++++++++++ docs/team/TECHNICAL_GUIDE.md | 22 ++++++++++++++++++ 4 files changed, 94 insertions(+) diff --git a/docs/team/PRODUCTION_CHECKLIST.md b/docs/team/PRODUCTION_CHECKLIST.md index d2b61c4..dea449c 100644 --- a/docs/team/PRODUCTION_CHECKLIST.md +++ b/docs/team/PRODUCTION_CHECKLIST.md @@ -109,3 +109,19 @@ npm.cmd run e2e:full:win - `GET /health` - `GET /health/live` - `GET /health/ready` + +## 6. 2026-04-10 多轮 Review 补充检查项 + +### 6.1 RBAC / 管理员治理改动 + +- [ ] 涉及 `GetUserRoles`、`AssignRoles`、`CreateAdmin`、`DeleteAdmin`、角色表单或管理员页的改动时，已验证越权读取失败、越权修改失败。 +- [ ] 已验证不可自删管理员、不可删除最后一个管理员、不可把系统带入无管理员状态。 +- [ ] 已验证角色赋权、管理员创建、管理员删除具备事务性；若失败，数据库状态可回滚到操作前。 +- [ ] 已验证未引入绕过 bootstrap 或 service 校验链路的硬编码角色 ID 或默认角色假设。 + +### 6.2 主入口与测试洁净度 + +- [ ] 文档声明的主入口命令本身已跑通：`go test ./... -count=1`、`cd frontend/admin && npm.cmd run e2e:full:win`。 +- [ ] 若包装脚本、临时缓存、工作目录切换或环境注入失败，已按真实失败处理，而不是拿局部命令绿灯代替。 +- [ ] `cd frontend/admin && npm.cmd run test:run` 与 `cd frontend/admin && npm.cmd run test:coverage` 运行后，无 `window.alert`、`window.confirm`、`window.prompt`、`window.open` 调用和 jsdom `Not implemented` 噪声。 +- [ ] 如本轮改动把 stub、`not implemented` 或 mock 接口切换为 live 实现，已补充负向权限测试、边界条件测试、失败回滚测试。 diff --git a/docs/team/PROJECT_EXPERIENCE_SUMMARY.md b/docs/team/PROJECT_EXPERIENCE_SUMMARY.md index 8d6389c..8277cd8 100644 --- a/docs/team/PROJECT_EXPERIENCE_SUMMARY.md +++ b/docs/team/PROJECT_EXPERIENCE_SUMMARY.md @@ -151,3 +151,33 @@ - 补充 Playwright 未覆盖的交互场景 - 增加复杂业务流程的端到端验证 - 提供更灵活的用户操作模拟能力 + +## 17. 2026-04-10 多轮 Review 的新增经验 + +- 2026-04-08、2026-04-09、2026-04-10 的连续 review 证明：真正难的不是把 stub 改成 live，而是把 live 链路补到可治理、可回滚、可验证。 +- `GetUserRoles`、`AssignRoles`、`CreateAdmin`、`DeleteAdmin` 从 stub 变成 live 后，问题从“功能没实现”升级成“权限边界、事务一致性、管理员治理是否成立”。 +- 经验教训： + - “功能通了”不是结束，live 后第一轮就应该补越权读取、越权修改、自删管理员、最后管理员、失败回滚等负向验证。 + - 高风险治理面不能靠默认假设，必须用显式规则和测试守住。 + +## 18. 主入口绿灯比局部绿灯更重要 + +- 连续 review 反复说明：`go vet ./...`、`go build ./cmd/server`、`go test ./... -short -count=1` 的绿灯，不能代替全量 `go test ./... -count=1` 与 `npm.cmd run e2e:full:win`。 +- 2026-04-10 的 review 里，`LL_001` 仍让全量后端测试失败，`e2e:full:win` 仍卡在包装入口；这说明“单步可过”与“主入口可过”是两件不同的事。 +- 经验教训： + - 发布判断必须跟着文档支持的主入口走。 + - 任何脚本包装层失败都算真实失败，不应被下层局部绿灯掩盖。 + +## 19. 测试噪声也是质量问题 + +- 前端 `test:run` 与 `test:coverage` 即使最终返回成功，只要仍输出 `window.alert` 的 jsdom `Not implemented` 噪声，就说明代码库里还保留着会破坏真实交互的缺陷信号。 +- 经验教训： + - “success summary 之后还有噪声”不算干净通过。 + - 原生弹窗与 popup 应继续按缺陷治理，而不是按低优先级美观问题处理。 + +## 20. 文档如果慢于代码，会制造第二轮返工 + +- 多轮 review 的另一个稳定结论是：状态文档、质量规范、发布清单、技术指引如果不跟着真实结论更新，很快就会反向误导后续协作。 +- 经验教训： + - review 一旦改变了真实结论，当轮就要同步文档。 + - 文档不是收尾材料，而是下一轮决策的输入。 diff --git a/docs/team/QUALITY_STANDARD.md b/docs/team/QUALITY_STANDARD.md index 5255898..3a930c7 100644 --- a/docs/team/QUALITY_STANDARD.md +++ b/docs/team/QUALITY_STANDARD.md @@ -254,3 +254,29 @@ npm.cmd run e2e:full:win - 禁止"用 mock 响应替代真实 API 调用进行 E2E 验证"。 - 禁止"在测试中硬编码预期结果而不走真实业务链路"。 - 禁止"跳过认证、权限校验等安全环节直接断言页面状态"。 + +## 11. 2026-04-10 多轮 Review 新增质量规则 + +### 11.1 stub 转 live 的复核门槛 + +- 任何从 stub、mock、`not implemented` 切换为 live 的接口，都必须重新做权限边界审查，不能沿用“之前只是占位实现”的风险判断。 +- 这类改动至少补齐：正向用例、负向权限用例、边界条件用例、失败回滚用例。 +- 若 live 化后暴露新治理风险，结论应以新风险为准，禁止因为“功能终于通了”而降低审查标准。 + +### 11.2 RBAC / 管理员治理规则 + +- `GetUserRoles`、`AssignRoles`、`CreateAdmin`、`DeleteAdmin` 这类能力必须有显式权限控制，不能默认任何已登录用户可读写他人角色数据。 +- 管理员治理必须包含 `self-action` 与 `last-admin` 防护：禁止自删管理员、禁止删除最后一个管理员、禁止把系统带入无管理员状态。 +- 角色赋权、管理员创建、管理员删除这类多步写操作必须具备事务性；若底层不支持事务，必须提供显式回滚并有对应测试。 +- 禁止在已有可靠角色解析或引导链路之外，再引入硬编码角色 ID 作为生产逻辑捷径。 + +### 11.3 干净通过的定义 + +- `go test ./... -count=1` 与 `cd frontend/admin && npm.cmd run e2e:full:win` 是当前项目的真实发布门槛；局部命令绿灯、单步 build 绿灯、`-short` 绿灯都不能替代。 +- 文档支持的主入口命令本身必须可复现；脚本包装器、临时缓存路径、工作目录切换等任一层失败，都应按真实失败处理。 +- 测试完成后若仍输出 `window.alert`、`window.confirm`、`window.prompt`、`window.open` 或对应的 jsdom `Not implemented` 噪声，不算干净通过，必须继续治理。 + +### 11.4 文档同步要求 + +- review 结论改变后，必须同步更新状态文档、门槛文档、技术指引和经验文档，禁止让旧结论继续充当协作依据。 +- 文档中的“已闭环”“可上线”“已收口”表述，必须对应实际执行过的命令结果和当前支持的主验收入口。 diff --git a/docs/team/TECHNICAL_GUIDE.md b/docs/team/TECHNICAL_GUIDE.md index 6fe0b16..64a8c4c 100644 --- a/docs/team/TECHNICAL_GUIDE.md +++ b/docs/team/TECHNICAL_GUIDE.md @@ -59,3 +59,25 @@ npm.cmd run e2e:full:win - 规则变更：更新 `docs/team/QUALITY_STANDARD.md` - 发布门槛变更：更新 `docs/team/PRODUCTION_CHECKLIST.md` - 阶段性经验：更新 `docs/team/PROJECT_EXPERIENCE_SUMMARY.md` + +## 6. 2026-04-10 多轮 Review 实操指引 + +### 6.1 如何判断“是否闭环” + +- 结论优先级：文档支持的主入口 > repo 内单步命令 > 局部 smoke、单个用例、`-short` 结果。 +- 只要 `go test ./... -count=1` 仍被 `LL_001` 卡住，或 `npm.cmd run e2e:full:win` 仍未跑通，就不能把项目表述为“全量验证通过”。 +- `go build ./cmd/server` 通过，只能证明 repo 内该命令通过；不能自动推出包装脚本里的 build 路径也稳定。 + +### 6.2 如何审查 stub 转 live 的高风险改动 + +- 先看权限边界：调用者是否真的具备读取或修改目标资源的资格。 +- 再看治理边界：是否存在 `self-action`、`last-admin`、越权枚举、越权提升等问题。 +- 再看一致性：多步写操作是否在事务内；失败时是否有显式回滚。 +- 最后看文档与测试：是否补了负向测试、边界测试、回滚测试，以及状态文档与规范文档。 + +### 6.3 当前需要持续关注的热点 + +- `internal/service/scale_test.go`：`LL_001` 仍是全量 `go test ./... -count=1` 的门槛。 +- `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 / 管理员治理逻辑需要持续按越权、事务、自删、最后管理员等维度审查。