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
2026-04-11 23:38:43 +08:00
parent 339c740365
commit 4193b46b5f
8 changed files with 585 additions and 2 deletions
--- a/docs/team/FALSE_COMPLETION_PREVENTION.md
+++ b/docs/team/FALSE_COMPLETION_PREVENTION.md
@@ -0,0 +1,200 @@
+# 工程规则补充：虚假完成防范
+
+版本：1.0
+更新时间：2026-04-11
+
+本规则是 `QUALITY_STANDARD.md` 和 `PROJECT_EXPERIENCE_SUMMARY.md` 的补充，专门针对虚假完成的防范。
+
+---
+
+## 1. 虚假完成的定义
+
+虚假完成是指：
+- 声称"已修复"但实际未修复
+- 声称"已测试"但测试不运行或不验证真实行为
+- 声称"已完成"但遗漏关键部分（如缺少 swagger 注解、缺少边界条件测试）
+- 声称"已统一"但实际存在不一致
+
+---
+
+## 2. 必须逐项验证的检查点
+
+### 2.1 Swagger 注解完整性
+
+**每添加一个 handler 方法，必须同时添加完整的 swagger 注解。**
+
+验证方法：
+```bash
+# 统计方法数 vs @Summary 数
+for f in internal/api/handler/*_handler.go; do
+  methods=$(grep -E "^func \(h \*[A-Za-z]+.*\) [A-Z]" "$f" | wc -l)
+  annotations=$(grep -c "@Summary" "$f" || echo 0)
+  echo "$(basename $f): $methods methods, $annotations @Summary"
+done
+```
+
+**当前缺口（截至 2026-04-11）：**
+
+| Handler | 方法数 | @Summary 数 | 缺口 |
+|---------|--------|-----------|------|
+| password_reset_handler.go | 5 | 1 | 4 |
+| totp_handler.go | 5 | 1 | 4 |
+| log_handler.go | 5 | 3 | 2 |
+
+**每次提交前必须确保所有 handler 方法都有 @Summary。**
+
+### 2.2 响应格式统一性
+
+**所有 API 必须使用统一响应格式：**
+```go
+c.JSON(http.StatusOK, gin.H{
+    "code": 0,
+    "message": "success",
+    "data": <实际数据>,
+})
+```
+
+**例外情况**：
+- OAuth Token 端点（RFC 6749 要求直接返回 token）
+- 认证挑战响应（WWW-Authenticate）
+
+**当前缺口（截至 2026-04-11）：**
+- `sso_handler.go` 的 `Token` 端点 (line 213) 返回 `TokenResponse` 而非包装格式
+- `sso_handler.go` 的 `Introspect` 端点 (line 257, 261) 返回 `IntrospectResponse` 而非包装格式
+
+### 2.3 集成测试基础设施
+
+**IntegrationRedisSuite 类型必须在代码库中定义。**
+
+当前问题：多个 `*_integration_test.go` 文件引用 `IntegrationRedisSuite`，但该类型从未定义。
+
+验证方法：
+```bash
+# 检查 IntegrationRedisSuite 是否定义
+grep -r "type IntegrationRedisSuite" internal/repository/
+
+# 检查哪些文件依赖它
+grep -l "IntegrationRedisSuite" internal/repository/*_integration_test.go
+```
+
+**缺口（截至 2026-04-11）：**
+- `internal/repository/` 下 7 个 `*_integration_test.go` 文件依赖未定义的 `IntegrationRedisSuite`
+
+---
+
+## 3. 验证命令
+
+### 3.1 强制验证命令（在任何 PR 合并前）
+
+```bash
+# 1. Swagger 注解完整性检查
+for f in internal/api/handler/*_handler.go; do
+  methods=$(grep -E "^func \(h \*[A-Za-z]+.*\) [A-Z]" "$f" | wc -l)
+  annotations=$(grep -c "@Summary" "$f" || echo 0)
+  if [ "$methods" != "$annotations" ]; then
+    echo "FAIL: $(basename $f) - methods:$methods annotations:$annotations"
+  fi
+done
+
+# 2. 响应格式检查（排除白名单）
+grep -rn "c.JSON.*TokenResponse\|c.JSON.*IntrospectResponse" internal/api/handler/
+
+# 3. 集成测试类型检查
+grep -r "type IntegrationRedisSuite" internal/repository/
+```
+
+### 3.2 测试覆盖验证
+
+```bash
+# 运行测试并验证覆盖率
+go test ./internal/repository/... -cover -count=1
+
+# 验证覆盖率数字真实性
+# 81.1% 意味着运行 go test 时会打印 coverage 数字
+```
+
+### 3.3 E2E 验证
+
+```bash
+# 真实浏览器 E2E（涉及认证、导航、主流程时必须）
+cd frontend/admin && npm.cmd run e2e:full:win
+```
+
+---
+
+## 4. 常见虚假完成模式
+
+### 模式 1：部分 swagger 注解
+
+**错误做法**：只给部分方法添加 @Summary
+```go
+// ForgotPassword ✅
+func (h *PasswordResetHandler) ForgotPassword(c *gin.Context) { ... }
+
+// ValidateResetToken ❌ 没有 @Summary
+func (h *PasswordResetHandler) ValidateResetToken(c *gin.Context) { ... }
+```
+
+**正确做法**：每个方法都要注解
+```go
+// ForgotPassword 请求密码重置
+// @Summary 忘记密码
+// @Description ...
+func (h *PasswordResetHandler) ForgotPassword(c *gin.Context) { ... }
+```
+
+### 模式 2：响应格式不一致
+
+**错误做法**：
+```go
+// SSO Token 端点直接返回 TokenResponse
+c.JSON(http.StatusOK, TokenResponse{...})
+```
+
+**正确做法**：
+```go
+c.JSON(http.StatusOK, gin.H{"code": 0, "message": "success", "data": TokenResponse{...}})
+```
+
+### 模式 3：测试引用未定义类型
+
+**错误做法**：
+```go
+type UpdateCacheSuite struct {
+    IntegrationRedisSuite  // 未定义！
+    cache *updateCache
+}
+```
+
+**正确做法**：
+- 要么定义 `IntegrationRedisSuite`
+- 要么删除引用它的集成测试文件
+- 要么添加 `//go:build ignore` 标签并确保不编译
+
+---
+
+## 5. 防范承诺
+
+在提交任何 PR 之前，必须：
+
+1. **Swagger 注解**：确保每个 handler 方法都有 @Summary/@Description/@Param/@Success/@Router
+2. **响应格式**：确保使用统一的 `{"code": 0, "message": "success", "data": ...}` 格式
+3. **测试类型**：确保所有引用的类型都已定义
+4. **覆盖率数字**：确保声称的覆盖率数字是真实测试结果
+5. **文档同步**：确保文档中的声明与代码状态一致
+
+---
+
+## 6. 发现虚假完成时的处理
+
+当发现虚假完成时：
+
+1. **记录**：在发现问题的 PR 或 issue 中记录
+2. **修复**：立即修复虚假完成的部分
+3. **同步**：同步更新所有相关文档
+4. **防范**：将防範措施添加到本文件
+
+---
+
+**维护日期**: 2026-04-11
+**下次审查**: 每次 PR 合并前
--- a/docs/team/PROJECT_EXPERIENCE_SUMMARY.md
+++ b/docs/team/PROJECT_EXPERIENCE_SUMMARY.md
@@ -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 测试占比高但计入覆盖率
+
+防范措施：
+- 完整性检查必须逐项
+- 覆盖率必须验证真实测试运行
+- 类型引用必须验证定义存在
--- a/docs/team/QUALITY_STANDARD.md
+++ b/docs/team/QUALITY_STANDARD.md
@@ -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` 标签。
+