docs: add false completion prevention rules and fix swagger gaps
Changes: - Add FALSE_COMPLETION_PREVENTION.md documenting false completion patterns - Add integrity check script (scripts/check-integrity.sh) for automated verification - Fix swagger annotation gaps in 3 handlers (+10 annotations): - password_reset_handler.go: +4 annotations - totp_handler.go: +4 annotations - log_handler.go: +2 annotations - Define IntegrationRedisSuite type for Redis integration tests - Update QUALITY_STANDARD.md with swagger completeness and response format requirements - Update PROJECT_EXPERIENCE_SUMMARY.md with new learnings on false completion Integrity check now validates: - Swagger annotation completeness per handler - Response format uniformity (with OAuth whitelist) - Test infrastructure type definitions - Repository test coverage
This commit is contained in:
@@ -181,3 +181,34 @@
|
||||
- 经验教训:
|
||||
- review 一旦改变了真实结论,当轮就要同步文档。
|
||||
- 文档不是收尾材料,而是下一轮决策的输入。
|
||||
|
||||
## 21. 部分完成等于未完成
|
||||
|
||||
- 项目中发现:声称"已添加 swagger 注解"但只添加了部分方法的注解。
|
||||
- 项目中发现:声称"已统一响应格式"但 SSO handler 仍有 3 个端点未统一。
|
||||
- 项目中发现:声称"已定义测试基础设施"但 IntegrationRedisSuite 类型从未定义。
|
||||
- 经验教训:
|
||||
- "80% 完成"在质量语境下等于"未完成"。
|
||||
- 验证必须逐项,不能只看整体数字。
|
||||
- 每次提交前必须运行完整性检查。
|
||||
|
||||
## 22. 完整性检查必须是自动化的
|
||||
|
||||
- 手动检查容易被跳过或遗漏。
|
||||
- 经验教训:
|
||||
- 必须有自动化检查脚本验证 swagger 注解完整性。
|
||||
- 必须在 CI 中集成完整性检查。
|
||||
- 必须在 PR 检查清单中明确列出完整性验证命令。
|
||||
|
||||
## 23. 声称 vs 实际的差距来源
|
||||
|
||||
虚假完成通常来自:
|
||||
1. **部分完成就说完成**:swagger 注解 80% 完整就声称"已完成"
|
||||
2. **格式不统一**:大部分统一但有例外就声称"已统一"
|
||||
3. **类型未定义**:引用未定义的类型但测试没运行就声称"测试通过"
|
||||
4. **覆盖率数字失真**:mock 测试占比高但计入覆盖率
|
||||
|
||||
防范措施:
|
||||
- 完整性检查必须逐项
|
||||
- 覆盖率必须验证真实测试运行
|
||||
- 类型引用必须验证定义存在
|
||||
|
||||
Reference in New Issue
Block a user