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

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