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:
2026-04-11 23:38:43 +08:00
parent 339c740365
commit 4193b46b5f
8 changed files with 585 additions and 2 deletions

View File

@@ -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 测试占比高但计入覆盖率
防范措施:
- 完整性检查必须逐项
- 覆盖率必须验证真实测试运行
- 类型引用必须验证定义存在