user-system/docs/team/FALSE_COMPLETION_PREVENTION.md

工程规则补充：虚假完成防范

版本：1.0 更新时间：2026-04-11

本规则是 QUALITY_STANDARD.md 和 PROJECT_EXPERIENCE_SUMMARY.md 的补充，专门针对虚假完成的防范。

---

1. 虚假完成的定义

虚假完成是指：

• 声称"已修复"但实际未修复
• 声称"已测试"但测试不运行或不验证真实行为
• 声称"已完成"但遗漏关键部分（如缺少 swagger 注解、缺少边界条件测试）
• 声称"已统一"但实际存在不一致

---

2. 必须逐项验证的检查点

2.1 Swagger 注解完整性

每添加一个 handler 方法，必须同时添加完整的 swagger 注解。

验证方法：

# 统计方法数 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 必须使用统一响应格式：

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，但该类型从未定义。

验证方法：

# 检查 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 合并前）

# 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 测试覆盖验证

# 运行测试并验证覆盖率
go test ./internal/repository/... -cover -count=1

# 验证覆盖率数字真实性
# 81.1% 意味着运行 go test 时会打印 coverage 数字

3.3 E2E 验证

# 真实浏览器 E2E（涉及认证、导航、主流程时必须）
cd frontend/admin && npm.cmd run e2e:full:win

---

4. 常见虚假完成模式

模式 1：部分 swagger 注解

错误做法：只给部分方法添加 @Summary

// ForgotPassword ✅
func (h *PasswordResetHandler) ForgotPassword(c *gin.Context) { ... }

// ValidateResetToken ❌ 没有 @Summary
func (h *PasswordResetHandler) ValidateResetToken(c *gin.Context) { ... }

正确做法：每个方法都要注解

// ForgotPassword 请求密码重置
// @Summary 忘记密码
// @Description ...
func (h *PasswordResetHandler) ForgotPassword(c *gin.Context) { ... }

模式 2：响应格式不一致

错误做法：

// SSO Token 端点直接返回 TokenResponse
c.JSON(http.StatusOK, TokenResponse{...})

正确做法：

c.JSON(http.StatusOK, gin.H{"code": 0, "message": "success", "data": TokenResponse{...}})

模式 3：测试引用未定义类型

错误做法：

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 合并前