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

backend/internal/modules/adminauth/handler.go

@@ -124,9 +124,11 @@ func (h *Handler) Refresh(c *gin.Context) {
 		}
 	}
 	refreshToken := strings.TrimSpace(req.RefreshToken)
+	refreshTokenSource := "body"
 	if refreshToken == "" {
 		if cookieValue, err := c.Cookie(adminRefreshCookieName); err == nil {
 			refreshToken = strings.TrimSpace(cookieValue)
+			refreshTokenSource = "cookie"
 		}
 	}
 	if refreshToken == "" {
@@ -135,6 +137,8 @@ func (h *Handler) Refresh(c *gin.Context) {
 	}
 	tokens, err := h.service.Refresh(c.Request.Context(), refreshToken)
 	if err != nil {
+		reason, tokenVersion, currentVersion := middleware.AdminValidationFailure(err)
+		middleware.RecordAdminAuthFailure(c, reason, refreshTokenSource, tokenVersion, currentVersion)
 		writeAdminAuthError(c, err)
 		return
 	}

backend/internal/modules/adminauth/repository.go

@@ -8,7 +8,9 @@ import (
 	"strings"
 	"time"
 
+	"hfb_sys/backend/internal/auditlog"
 	"hfb_sys/backend/internal/captcha"
+	"hfb_sys/backend/internal/logging"
 	"hfb_sys/backend/internal/model"
 	"hfb_sys/backend/internal/modules/auth"
 
@@ -92,21 +94,45 @@ func (r *Repository) Login(ctx context.Context, username string, password string
 func (r *Repository) FindActiveForToken(ctx context.Context, id uint64, tokenVersion int64) (*model.AdminUser, error) {
 	var admin model.AdminUser
 	if err := r.db.WithContext(ctx).First(&admin, id).Error; err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return nil, newTokenValidationError("admin_not_found", ErrAdminNotFound)
+		}
 		return nil, err
 	}
 	if admin.Status != "active" {
-		return nil, ErrAdminDisabled
+		return nil, newTokenValidationError("admin_disabled", ErrAdminDisabled)
 	}
 	if admin.TokenVersion <= 0 || admin.TokenVersion != tokenVersion {
-		return nil, ErrInvalidRefreshToken
+		return nil, newTokenVersionMismatchError(tokenVersion, admin.TokenVersion)
 	}
 	return &admin, nil
 }
 
 func (r *Repository) RevokeTokens(ctx context.Context, adminID uint64) error {
-	return r.db.WithContext(ctx).Model(&model.AdminUser{}).
-		Where("id = ?", adminID).
-		UpdateColumn("token_version", gorm.Expr("token_version + 1")).Error
+	return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		if err := tx.Model(&model.AdminUser{}).
+			Where("id = ?", adminID).
+			UpdateColumn("token_version", gorm.Expr("token_version + 1")).Error; err != nil {
+			return err
+		}
+		return appendTokenVersionAudit(tx, ctx, adminID, "logout")
+	})
+}
+
+func appendTokenVersionAudit(tx *gorm.DB, ctx context.Context, adminID uint64, reason string) error {
+	bizID := adminID
+	return auditlog.Append(tx, auditlog.Entry{
+		ActorType: "admin",
+		ActorID:   logging.AdminIDFromContext(ctx),
+		Action:    "auth.token_version.bump",
+		BizType:   "admin_user",
+		BizID:     &bizID,
+		Meta:      auditlog.Meta{RequestID: logging.RequestIDFromContext(ctx)},
+		Detail: map[string]any{
+			"target_admin_id": adminID,
+			"reason":          reason,
+		},
+	})
 }
 
 func (r *Repository) verifyCaptcha(ctx context.Context, captchaID string, captchaCode string) error {

backend/internal/modules/adminauth/service.go

@@ -14,8 +14,49 @@ var (
 	ErrAdminDisabled         = errors.New("admin disabled")
 	ErrInvalidRefreshToken   = errors.New("invalid refresh token")
 	ErrLoginLocked           = errors.New("login locked")
+	ErrAdminNotFound         = errors.New("admin not found")
+	ErrTokenVersionMismatch  = errors.New("admin token version mismatch")
 )
 
+// TokenValidationError 为后台会话失败保留安全的诊断类别，响应仍使用统一文案。
+type TokenValidationError struct {
+	Reason         string
+	TokenVersion   int64
+	CurrentVersion int64
+	err            error
+}
+
+func (e *TokenValidationError) Error() string {
+	return "admin token validation failed: " + e.Reason
+}
+
+func (e *TokenValidationError) Unwrap() error {
+	return e.err
+}
+
+// AuthFailureReason 供中间件读取失败类别并写入结构化日志。
+func (e *TokenValidationError) AuthFailureReason() string {
+	return e.Reason
+}
+
+// AuthFailureVersions 返回令牌声明版本和数据库当前版本；非版本不匹配时均为 0。
+func (e *TokenValidationError) AuthFailureVersions() (int64, int64) {
+	return e.TokenVersion, e.CurrentVersion
+}
+
+func newTokenValidationError(reason string, err error) error {
+	return &TokenValidationError{Reason: reason, err: err}
+}
+
+func newTokenVersionMismatchError(tokenVersion, currentVersion int64) error {
+	return &TokenValidationError{
+		Reason:         "token_version_mismatch",
+		TokenVersion:   tokenVersion,
+		CurrentVersion: currentVersion,
+		err:            ErrTokenVersionMismatch,
+	}
+}
+
 type Service struct {
 	repo *Repository
 	jwt  *auth.JWTManager
@@ -31,7 +72,7 @@ func (s *Service) Refresh(ctx context.Context, refreshToken string) (*auth.Token
 	}
 	claims, err := s.jwt.ParseSubject(refreshToken, "refresh", "admin")
 	if err != nil {
-		return nil, ErrInvalidRefreshToken
+		return nil, newTokenValidationError(auth.TokenFailureReason(err), ErrInvalidRefreshToken)
 	}
 	if s.repo == nil {
 		return nil, ErrDependencyUnavailable
@@ -41,7 +82,7 @@ func (s *Service) Refresh(ctx context.Context, refreshToken string) (*auth.Token
 		if errors.Is(err, ErrAdminDisabled) {
 			return nil, ErrAdminDisabled
 		}
-		return nil, ErrInvalidRefreshToken
+		return nil, invalidRefreshTokenError(err)
 	}
 	pair, err := s.jwt.GenerateSubjectPairWithVersion(admin.ID, admin.Username, "admin", admin.TokenVersion)
 	if err != nil {
@@ -50,6 +91,21 @@ func (s *Service) Refresh(ctx context.Context, refreshToken string) (*auth.Token
 	return &pair, nil
 }
 
+func invalidRefreshTokenError(err error) error {
+	reason := "invalid"
+	var tokenErr *TokenValidationError
+	if errors.As(err, &tokenErr) {
+		reason = tokenErr.Reason
+		return &TokenValidationError{
+			Reason:         reason,
+			TokenVersion:   tokenErr.TokenVersion,
+			CurrentVersion: tokenErr.CurrentVersion,
+			err:            ErrInvalidRefreshToken,
+		}
+	}
+	return newTokenValidationError(reason, ErrInvalidRefreshToken)
+}
+
 func (s *Service) Captcha(ctx context.Context) (*CaptchaDTO, error) {
 	if s.repo == nil {
 		return nil, ErrDependencyUnavailable