修复数据库波动导致后台掉线

backend/internal/middleware/auth.go

@@ -23,6 +23,7 @@ const (
 	ContextAuthTokenSource    = "auth_token_source"
 	ContextAuthTokenVersion   = "auth_token_version"
 	ContextAuthCurrentVersion = "auth_current_token_version"
+	ContextAuthFailureDetail  = "auth_failure_detail"
 	AdminAccessCookieName     = "hfb_admin_access"
 )
 
@@ -103,7 +104,12 @@ func AdminAuth(jwtManager *auth.JWTManager, validate AdminTokenValidatorFunc) gi
 			tokenContext, err := validate(c.Request.Context(), claims.UserID, claims.TokenVersion)
 			if err != nil {
 				reason, tokenVersion, currentVersion := AdminValidationFailure(err)
-				RecordAdminAuthFailure(c, reason, tokenSource, tokenVersion, currentVersion)
+				RecordAdminAuthFailure(c, reason, tokenSource, tokenVersion, currentVersion, AdminValidationFailureDetail(err))
+				if AdminValidationUnavailable(err) {
+					response.ServiceUnavailable(c, "后台认证服务暂时不可用")
+					c.Abort()
+					return
+				}
 				response.Unauthorized(c, "后台访问令牌无效或已过期")
 				c.Abort()
 				return
@@ -126,6 +132,14 @@ type authFailureVersionCarrier interface {
 	AuthFailureVersions() (int64, int64)
 }
 
+type authFailureDetailCarrier interface {
+	AuthFailureDetail() string
+}
+
+type authFailureUnavailableCarrier interface {
+	AuthFailureUnavailable() bool
+}
+
 // AdminValidationFailure 将认证包内部错误转换为安全、可观测的失败类别。
 func AdminValidationFailure(err error) (string, int64, int64) {
 	reason := "admin_validation_failed"
@@ -141,14 +155,32 @@ func AdminValidationFailure(err error) (string, int64, int64) {
 	return reason, 0, 0
 }
 
+// AdminValidationFailureDetail 返回仅供服务端日志记录的安全错误摘要。
+func AdminValidationFailureDetail(err error) string {
+	var detailCarrier authFailureDetailCarrier
+	if errors.As(err, &detailCarrier) {
+		return detailCarrier.AuthFailureDetail()
+	}
+	return ""
+}
+
+// AdminValidationUnavailable 判断失败是否由临时依赖故障引起。
+func AdminValidationUnavailable(err error) bool {
+	var unavailableCarrier authFailureUnavailableCarrier
+	return errors.As(err, &unavailableCarrier) && unavailableCarrier.AuthFailureUnavailable()
+}
+
 // RecordAdminAuthFailure 把认证失败诊断字段写入请求上下文，供访问日志统一输出。
-func RecordAdminAuthFailure(c *gin.Context, reason, source string, tokenVersion, currentVersion int64) {
+func RecordAdminAuthFailure(c *gin.Context, reason, source string, tokenVersion, currentVersion int64, detail ...string) {
 	c.Set(ContextAuthFailureReason, reason)
 	c.Set(ContextAuthTokenSource, source)
 	if tokenVersion != 0 || currentVersion != 0 {
 		c.Set(ContextAuthTokenVersion, tokenVersion)
 		c.Set(ContextAuthCurrentVersion, currentVersion)
 	}
+	if len(detail) > 0 && detail[0] != "" {
+		c.Set(ContextAuthFailureDetail, detail[0])
+	}
 }
 
 func RequireAdminPasswordChanged() gin.HandlerFunc {