完善掉线诊断并优化二维码加载

backend/internal/middleware/auth.go

@@ -2,9 +2,11 @@ package middleware
 
 import (
 	"context"
+	"errors"
 	"net/http"
 	"strings"
 
+	"hfb_sys/backend/internal/logging"
 	"hfb_sys/backend/internal/modules/auth"
 	"hfb_sys/backend/pkg/response"
 
@@ -17,6 +19,10 @@ const (
 	ContextAdminID            = "admin_id"
 	ContextUsername           = "username"
 	ContextPasswordMustChange = "password_must_change"
+	ContextAuthFailureReason  = "auth_failure_reason"
+	ContextAuthTokenSource    = "auth_token_source"
+	ContextAuthTokenVersion   = "auth_token_version"
+	ContextAuthCurrentVersion = "auth_current_token_version"
 	AdminAccessCookieName     = "hfb_admin_access"
 )
 
@@ -68,12 +74,15 @@ func Auth(jwtManager *auth.JWTManager) gin.HandlerFunc {
 func AdminAuth(jwtManager *auth.JWTManager, validate AdminTokenValidatorFunc) gin.HandlerFunc {
 	return func(c *gin.Context) {
 		tokenText := extractBearerToken(c)
+		tokenSource := "bearer"
 		if tokenText == "" {
 			if cookieToken, err := c.Cookie(AdminAccessCookieName); err == nil {
 				tokenText = strings.TrimSpace(cookieToken)
+				tokenSource = "cookie"
 			}
 		}
 		if tokenText == "" {
+			RecordAdminAuthFailure(c, "missing", "none", 0, 0)
 			response.Unauthorized(c, "缺少后台访问令牌")
 			c.Abort()
 			return
@@ -81,15 +90,20 @@ func AdminAuth(jwtManager *auth.JWTManager, validate AdminTokenValidatorFunc) gi
 
 		claims, err := jwtManager.ParseSubject(tokenText, "access", "admin")
 		if err != nil {
+			RecordAdminAuthFailure(c, auth.TokenFailureReason(err), tokenSource, 0, 0)
 			response.Unauthorized(c, "后台访问令牌无效或已过期")
 			c.Abort()
 			return
 		}
+		c.Set(ContextAdminID, claims.UserID)
+		c.Request = c.Request.WithContext(logging.WithAdminID(c.Request.Context(), claims.UserID))
 		username := claims.Phone
 		passwordMustChange := false
 		if validate != nil {
 			tokenContext, err := validate(c.Request.Context(), claims.UserID, claims.TokenVersion)
 			if err != nil {
+				reason, tokenVersion, currentVersion := AdminValidationFailure(err)
+				RecordAdminAuthFailure(c, reason, tokenSource, tokenVersion, currentVersion)
 				response.Unauthorized(c, "后台访问令牌无效或已过期")
 				c.Abort()
 				return
@@ -98,13 +112,45 @@ func AdminAuth(jwtManager *auth.JWTManager, validate AdminTokenValidatorFunc) gi
 			passwordMustChange = tokenContext.PasswordMustChange
 		}
 
-		c.Set(ContextAdminID, claims.UserID)
 		c.Set(ContextUsername, username)
 		c.Set(ContextPasswordMustChange, passwordMustChange)
 		c.Next()
 	}
 }
 
+type authFailureReasonCarrier interface {
+	AuthFailureReason() string
+}
+
+type authFailureVersionCarrier interface {
+	AuthFailureVersions() (int64, int64)
+}
+
+// AdminValidationFailure 将认证包内部错误转换为安全、可观测的失败类别。
+func AdminValidationFailure(err error) (string, int64, int64) {
+	reason := "admin_validation_failed"
+	var reasonCarrier authFailureReasonCarrier
+	if errors.As(err, &reasonCarrier) && reasonCarrier.AuthFailureReason() != "" {
+		reason = reasonCarrier.AuthFailureReason()
+	}
+	var versionCarrier authFailureVersionCarrier
+	if errors.As(err, &versionCarrier) {
+		tokenVersion, currentVersion := versionCarrier.AuthFailureVersions()
+		return reason, tokenVersion, currentVersion
+	}
+	return reason, 0, 0
+}
+
+// RecordAdminAuthFailure 把认证失败诊断字段写入请求上下文，供访问日志统一输出。
+func RecordAdminAuthFailure(c *gin.Context, reason, source string, tokenVersion, currentVersion int64) {
+	c.Set(ContextAuthFailureReason, reason)
+	c.Set(ContextAuthTokenSource, source)
+	if tokenVersion != 0 || currentVersion != 0 {
+		c.Set(ContextAuthTokenVersion, tokenVersion)
+		c.Set(ContextAuthCurrentVersion, currentVersion)
+	}
+}
+
 func RequireAdminPasswordChanged() gin.HandlerFunc {
 	allowed := map[string]bool{
 		"/api/admin/me":                      true,