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

@@ -279,4 +279,26 @@ npm.cmd run e2e:full:win
### 11.4 文档同步要求
- review 结论改变后,必须同步更新状态文档、门槛文档、技术指引和经验文档,禁止让旧结论继续充当协作依据。
- 文档中的已闭环”可上线”已收口”表述,必须对应实际执行过的命令结果和当前支持的主验收入口。
- 文档中的已闭环”可上线”已收口”表述,必须对应实际执行过的命令结果和当前支持的主验收入口。
### 11.5 Swagger 注解完整性要求
- **每个 handler 方法必须有完整的 swagger 注解**,包括 `@Summary``@Description``@Tags``@Param``@Success``@Router`
- 验证方法:每个新增方法必须通过 `grep -E “^func \(h \*[A-Za-z]+.*\) [A-Z]” <handler>.go | wc -l``grep -c “@Summary” <handler>.go` 比对。
- 禁止:只给部分方法添加注解就声称”已完成 swagger 文档”。
### 11.6 响应格式统一性要求
- **所有 API 必须使用统一响应格式**`gin.H{“code”: 0, “message”: “success”, “data”: ...}`
- **白名单例外**RFC 标准要求直接返回):
- OAuth Token 端点(`/oauth/token`
- OpenID Connect UserInfo 端点
- **禁止**:在声称”已统一响应格式”后,仍有 handler 直接返回自定义结构体。
- 验证方法:`grep -rn “c.JSON.*TokenResponse\|c.JSON.*IntrospectResponse” internal/api/handler/`
### 11.7 测试基础设施完整性要求
- 所有测试引用的类型必须在代码库中定义。
- 验证方法:`grep -r “type IntegrationRedisSuite” internal/repository/` 必须返回定义位置。
- 禁止:测试文件引用未定义的类型,即使该测试有 `//go:build integration` 标签。