docs: add multi-round review learnings to team quality docs
- 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
This commit is contained in:
@@ -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 实现,已补充负向权限测试、边界条件测试、失败回滚测试。
|
||||
|
||||
@@ -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 一旦改变了真实结论,当轮就要同步文档。
|
||||
- 文档不是收尾材料,而是下一轮决策的输入。
|
||||
|
||||
@@ -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 结论改变后,必须同步更新状态文档、门槛文档、技术指引和经验文档,禁止让旧结论继续充当协作依据。
|
||||
- 文档中的“已闭环”“可上线”“已收口”表述,必须对应实际执行过的命令结果和当前支持的主验收入口。
|
||||
|
||||
@@ -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 / 管理员治理逻辑需要持续按越权、事务、自删、最后管理员等维度审查。
|
||||
|
||||
Reference in New Issue
Block a user