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/internal/api/handler/log_handler.go
+++ b/internal/api/handler/log_handler.go
@@ -156,6 +156,20 @@ func (h *LogHandler) GetLoginLogs(c *gin.Context) {
 	})
 }

+// GetOperationLogs 获取操作日志列表
+// @Summary 获取操作日志列表
+// @Description 获取所有操作日志（仅管理员），支持游标分页和偏移分页
+// @Tags 日志
+// @Produce json
+// @Security BearerAuth
+// @Param cursor query string false "游标分页游标"
+// @Param size query int false "每页数量（游标模式）"
+// @Param page query int false "页码"
+// @Param page_size query int false "每页数量"
+// @Success 200 {object} Response{data=OperationLogListResponse} "操作日志列表"
+// @Failure 403 {object} Response "无权限"
+// @Failure 500 {object} Response "服务器错误"
+// @Router /api/v1/admin/logs/operation [get]
 func (h *LogHandler) GetOperationLogs(c *gin.Context) {
 	var req service.ListOperationLogRequest
 	if err := c.ShouldBindQuery(&req); err != nil {
@@ -197,6 +211,19 @@ func (h *LogHandler) GetOperationLogs(c *gin.Context) {
 	})
 }

+// ExportLoginLogs 导出登录日志
+// @Summary 导出登录日志
+// @Description 导出登录日志为 CSV 文件
+// @Tags 日志
+// @Produce json
+// @Security BearerAuth
+// @Param start_time query string false "开始时间"
+// @Param end_time query string false "结束时间"
+// @Param user_id query int64 false "用户ID"
+// @Success 200 {file} file "CSV文件"
+// @Failure 403 {object} Response "无权限"
+// @Failure 500 {object} Response "服务器错误"
+// @Router /api/v1/admin/logs/login/export [get]
 func (h *LogHandler) ExportLoginLogs(c *gin.Context) {
 	var req service.ExportLoginLogRequest
 	if err := c.ShouldBindQuery(&req); err != nil {
--- a/internal/api/handler/password_reset_handler.go
+++ b/internal/api/handler/password_reset_handler.go
@@ -55,6 +55,15 @@ func (h *PasswordResetHandler) ForgotPassword(c *gin.Context) {
 	c.JSON(http.StatusOK, gin.H{"code": 0, "message": "password reset email sent"})
 }

+// ValidateResetToken 验证密码重置 Token
+// @Summary 验证密码重置 Token
+// @Description 验证密码重置链接中的 Token 是否有效
+// @Tags 密码重置
+// @Produce json
+// @Param token query string true "重置 Token"
+// @Success 200 {object} Response{data=ValidateTokenResponse} "Token验证结果"
+// @Failure 400 {object} Response "请求参数错误"
+// @Router /api/v1/auth/password/validate [get]
 func (h *PasswordResetHandler) ValidateResetToken(c *gin.Context) {
 	token := c.Query("token")
 	if token == "" {
@@ -71,6 +80,16 @@ func (h *PasswordResetHandler) ValidateResetToken(c *gin.Context) {
 	c.JSON(http.StatusOK, gin.H{"code": 0, "message": "success", "data": gin.H{"valid": valid}})
 }

+// ResetPassword 重置密码
+// @Summary 重置密码
+// @Description 使用 Token 重置密码
+// @Tags 密码重置
+// @Accept json
+// @Produce json
+// @Param request body ResetPasswordRequest true "重置请求"
+// @Success 200 {object} Response "密码重置成功"
+// @Failure 400 {object} Response "请求参数错误"
+// @Router /api/v1/auth/password/reset [post]
 func (h *PasswordResetHandler) ResetPassword(c *gin.Context) {
 	var req struct {
 		Token       string `json:"token" binding:"required"`
@@ -95,7 +114,17 @@ type ForgotPasswordByPhoneRequest struct {
 	Phone string `json:"phone" binding:"required"`
 }

-// ForgotPasswordByPhone 发送短信验证码
+// ForgotPasswordByPhone 发送短信验证码（忘记密码）
+// @Summary 发送短信验证码（忘记密码）
+// @Description 向绑定的手机号发送短信验证码用于重置密码
+// @Tags 密码重置
+// @Accept json
+// @Produce json
+// @Param request body ForgotPasswordByPhoneRequest true "手机号"
+// @Success 200 {object} Response "验证码发送成功"
+// @Failure 400 {object} Response "请求参数错误"
+// @Failure 503 {object} Response "短信服务未配置"
+// @Router /api/v1/auth/password/sms/forgot [post]
 func (h *PasswordResetHandler) ForgotPasswordByPhone(c *gin.Context) {
 	if h.smsService == nil {
 		c.JSON(http.StatusServiceUnavailable, gin.H{"code": 503, "message": "SMS service not configured"})
@@ -142,6 +171,17 @@ type ResetPasswordByPhoneRequest struct {
 }

 // ResetPasswordByPhone 通过短信验证码重置密码
+// @Summary 通过短信验证码重置密码
+// @Description 使用短信验证码重置登录密码
+// @Tags 密码重置
+// @Accept json
+// @Produce json
+// @Param request body ResetPasswordByPhoneRequest true "重置请求"
+// @Success 200 {object} Response "密码重置成功"
+// @Failure 400 {object} Response "请求参数错误"
+// @Failure 401 {object} Response "验证码错误"
+// @Failure 503 {object} Response "短信服务未配置"
+// @Router /api/v1/auth/password/sms/reset [post]
 func (h *PasswordResetHandler) ResetPasswordByPhone(c *gin.Context) {
 	var req ResetPasswordByPhoneRequest
 	if err := c.ShouldBindJSON(&req); err != nil {
--- a/internal/api/handler/totp_handler.go
+++ b/internal/api/handler/totp_handler.go
@@ -47,6 +47,17 @@ func (h *TOTPHandler) GetTOTPStatus(c *gin.Context) {
 	c.JSON(http.StatusOK, gin.H{"code": 0, "message": "success", "data": gin.H{"enabled": enabled}})
 }

+// SetupTOTP 设置 TOTP
+// @Summary 设置 TOTP 两步验证
+// @Description 为当前用户设置 TOTP 两步验证，返回密钥和二维码
+// @Tags 两步验证
+// @Accept json
+// @Produce json
+// @Security BearerAuth
+// @Success 200 {object} Response{data=TOTPSetupResponse} "TOTP设置信息"
+// @Failure 401 {object} Response "未认证"
+// @Failure 500 {object} Response "服务器错误"
+// @Router /api/v1/auth/totp/setup [post]
 func (h *TOTPHandler) SetupTOTP(c *gin.Context) {
 	userID, ok := getUserIDFromContext(c)
 	if !ok {
@@ -71,6 +82,19 @@ func (h *TOTPHandler) SetupTOTP(c *gin.Context) {
 	})
 }

+// EnableTOTP 启用 TOTP
+// @Summary 启用 TOTP 两步验证
+// @Description 输入验证码启用 TOTP 两步验证
+// @Tags 两步验证
+// @Accept json
+// @Produce json
+// @Security BearerAuth
+// @Param request body EnableTOTPRequest true "验证码"
+// @Success 200 {object} Response "启用成功"
+// @Failure 400 {object} Response "请求参数错误"
+// @Failure 401 {object} Response "未认证或验证码错误"
+// @Failure 500 {object} Response "服务器错误"
+// @Router /api/v1/auth/totp/enable [post]
 func (h *TOTPHandler) EnableTOTP(c *gin.Context) {
 	userID, ok := getUserIDFromContext(c)
 	if !ok {
@@ -95,6 +119,19 @@ func (h *TOTPHandler) EnableTOTP(c *gin.Context) {
 	c.JSON(http.StatusOK, gin.H{"code": 0, "message": "success"})
 }

+// DisableTOTP 禁用 TOTP
+// @Summary 禁用 TOTP 两步验证
+// @Description 输入验证码禁用 TOTP 两步验证
+// @Tags 两步验证
+// @Accept json
+// @Produce json
+// @Security BearerAuth
+// @Param request body DisableTOTPRequest true "验证码"
+// @Success 200 {object} Response "禁用成功"
+// @Failure 400 {object} Response "请求参数错误"
+// @Failure 401 {object} Response "未认证或验证码错误"
+// @Failure 500 {object} Response "服务器错误"
+// @Router /api/v1/auth/totp/disable [post]
 func (h *TOTPHandler) DisableTOTP(c *gin.Context) {
 	userID, ok := getUserIDFromContext(c)
 	if !ok {
@@ -119,6 +156,19 @@ func (h *TOTPHandler) DisableTOTP(c *gin.Context) {
 	c.JSON(http.StatusOK, gin.H{"code": 0, "message": "success"})
 }

+// VerifyTOTP 验证 TOTP
+// @Summary 验证 TOTP 验证码
+// @Description 在登录或其他敏感操作时验证 TOTP 验证码
+// @Tags 两步验证
+// @Accept json
+// @Produce json
+// @Security BearerAuth
+// @Param request body VerifyTOTPRequest true "验证码"
+// @Success 200 {object} Response{data=VerifyTOTPResponse} "验证结果"
+// @Failure 400 {object} Response "请求参数错误"
+// @Failure 401 {object} Response "未认证或验证码错误"
+// @Failure 500 {object} Response "服务器错误"
+// @Router /api/v1/auth/totp/verify [post]
 func (h *TOTPHandler) VerifyTOTP(c *gin.Context) {
 	userID, ok := getUserIDFromContext(c)
 	if !ok {
--- a/internal/repository/integration_redis_suite.go
+++ b/internal/repository/integration_redis_suite.go
@@ -0,0 +1,61 @@
+//go:build integration
+
+package repository
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"github.com/redis/go-redis/v9"
+	"github.com/stretchr/testify/suite"
+)
+
+// IntegrationRedisSuite Redis 集成测试基础套件
+// 所有 Redis 集成测试应嵌入此套件
+type IntegrationRedisSuite struct {
+	suite.Suite
+	rdb  *redis.Client
+	ctx  context.Context
+	host string
+	port string
+}
+
+// SetupSuite 连接 Redis
+func (s *IntegrationRedisSuite) SetupSuite() {
+	s.ctx = context.Background()
+	s.host = "localhost"
+	s.port = "6379"
+
+	s.rdb = redis.NewClient(&redis.Options{
+		Addr:         s.host + ":" + s.port,
+		DialTimeout:  5 * time.Second,
+		ReadTimeout:  3 * time.Second,
+		WriteTimeout: 3 * time.Second,
+		PoolSize:     10,
+	})
+}
+
+// SetupTest 每个测试前清空数据库
+func (s *IntegrationRedisSuite) SetupTest() {
+	if s.rdb == nil {
+		s.T().Skip("Redis not available, skipping integration test")
+	}
+	s.rdb.FlushDB(s.ctx)
+}
+
+// TearDownSuite 关闭连接
+func (s *IntegrationRedisSuite) TearDownSuite() {
+	if s.rdb != nil {
+		s.rdb.Close()
+	}
+}
+
+// Redis 返回的辅助方法
+func (s *IntegrationRedisSuite) Redis() *redis.Client {
+	return s.rdb
+}
+
+func (s *IntegrationRedisSuite) Context() context.Context {
+	return s.ctx
+}