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

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 {

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 {

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 {