refactor: 重构 api_key_auth 中间件，用 skipBilling 替代 7 处散落的 isUsageQuery

将中间件职责拆分为鉴权（Authentication）和计费执行（Billing Enforcement）两层：
- 鉴权层（disabled/IP/用户状态）始终执行
- 计费层（过期/配额/订阅/余额）用单一 skipBilling 守卫整块控制

/v1/usage 端点只需鉴权不需计费，skipBilling 仅出现 2 处（订阅加载错误处理 + 计费块守卫），
取代了之前 isUsageQuery 散布在 7 个 if 分支中的控制流。

backend/internal/server/middleware/api_key_auth.go

@@ -19,8 +19,16 @@ func NewAPIKeyAuthMiddleware(apiKeyService *service.APIKeyService, subscriptionS
 }
 
 // apiKeyAuthWithSubscription API Key认证中间件（支持订阅验证）
+//
+// 中间件职责分为两层：
+//   - 鉴权（Authentication）：验证 Key 有效性、用户状态、IP 限制 —— 始终执行
+//   - 计费执行（Billing Enforcement）：过期/配额/订阅/余额检查 —— skipBilling 时整块跳过
+//
+// /v1/usage 端点只需鉴权，不需要计费执行（允许过期/配额耗尽的 Key 查询自身用量）。
 func apiKeyAuthWithSubscription(apiKeyService *service.APIKeyService, subscriptionService *service.SubscriptionService, cfg *config.Config) gin.HandlerFunc {
 	return func(c *gin.Context) {
+		// ── 1. 提取 API Key ──────────────────────────────────────────
+
 		queryKey := strings.TrimSpace(c.Query("key"))
 		queryApiKey := strings.TrimSpace(c.Query("api_key"))
 		if queryKey != "" || queryApiKey != "" {
@@ -56,7 +64,8 @@ func apiKeyAuthWithSubscription(apiKeyService *service.APIKeyService, subscripti
 			return
 		}
 
-		// 从数据库验证API key
+		// ── 2. 验证 Key 存在 ─────────────────────────────────────────
+
 		apiKey, err := apiKeyService.GetByKey(c.Request.Context(), apiKeyString)
 		if err != nil {
 			if errors.Is(err, service.ErrAPIKeyNotFound) {
@@ -67,29 +76,13 @@ func apiKeyAuthWithSubscription(apiKeyService *service.APIKeyService, subscripti
 			return
 		}
 
-		// 检查API key是否激活
-		if !apiKey.IsActive() {
-			// Provide more specific error message based on status
-			switch apiKey.Status {
-			case service.StatusAPIKeyQuotaExhausted:
-				AbortWithError(c, 429, "API_KEY_QUOTA_EXHAUSTED", "API key 额度已用完")
-			case service.StatusAPIKeyExpired:
-				AbortWithError(c, 403, "API_KEY_EXPIRED", "API key 已过期")
-			default:
+		// ── 3. 基础鉴权（始终执行） ─────────────────────────────────
+
+		// disabled / 未知状态 → 无条件拦截（expired 和 quota_exhausted 留给计费阶段）
+		if !apiKey.IsActive() &&
+			apiKey.Status != service.StatusAPIKeyExpired &&
+			apiKey.Status != service.StatusAPIKeyQuotaExhausted {
 			AbortWithError(c, 401, "API_KEY_DISABLED", "API key is disabled")
-			}
-			return
-		}
-
-		// 检查API Key是否过期（即使状态是active，也要检查时间）
-		if apiKey.IsExpired() {
-			AbortWithError(c, 403, "API_KEY_EXPIRED", "API key 已过期")
-			return
-		}
-
-		// 检查API Key配额是否耗尽
-		if apiKey.IsQuotaExhausted() {
-			AbortWithError(c, 429, "API_KEY_QUOTA_EXHAUSTED", "API key 额度已用完")
 			return
 		}
 
@@ -116,8 +109,9 @@ func apiKeyAuthWithSubscription(apiKeyService *service.APIKeyService, subscripti
 			return
 		}
 
+		// ── 4. SimpleMode → early return ─────────────────────────────
+
 		if cfg.RunMode == config.RunModeSimple {
-			// 简易模式：跳过余额和订阅检查，但仍需设置必要的上下文
 			c.Set(string(ContextKeyAPIKey), apiKey)
 			c.Set(string(ContextKeyUser), AuthSubject{
 				UserID:      apiKey.User.ID,
@@ -130,54 +124,89 @@ func apiKeyAuthWithSubscription(apiKeyService *service.APIKeyService, subscripti
 			return
 		}
 
-		// 判断计费方式：订阅模式 vs 余额模式
+		// ── 5. 加载订阅（订阅模式时始终加载） ───────────────────────
+
+		// skipBilling: /v1/usage 只需鉴权，跳过所有计费执行
+		skipBilling := c.Request.URL.Path == "/v1/usage"
+
+		var subscription *service.UserSubscription
 		isSubscriptionType := apiKey.Group != nil && apiKey.Group.IsSubscriptionType()
 
 		if isSubscriptionType && subscriptionService != nil {
-			// 订阅模式：获取订阅（L1 缓存 + singleflight）
-			subscription, err := subscriptionService.GetActiveSubscription(
+			sub, subErr := subscriptionService.GetActiveSubscription(
 				c.Request.Context(),
 				apiKey.User.ID,
 				apiKey.Group.ID,
 			)
-			if err != nil {
+			if subErr != nil {
+				if !skipBilling {
 					AbortWithError(c, 403, "SUBSCRIPTION_NOT_FOUND", "No active subscription found for this group")
 					return
 				}
-
-			// 合并验证 + 限额检查（纯内存操作）
-			needsMaintenance, err := subscriptionService.ValidateAndCheckLimits(subscription, apiKey.Group)
-			if err != nil {
-				code := "SUBSCRIPTION_INVALID"
-				status := 403
-				if errors.Is(err, service.ErrDailyLimitExceeded) ||
-					errors.Is(err, service.ErrWeeklyLimitExceeded) ||
-					errors.Is(err, service.ErrMonthlyLimitExceeded) {
-					code = "USAGE_LIMIT_EXCEEDED"
-					status = 429
+				// skipBilling: 订阅不存在也放行，handler 会返回可用的数据
+			} else {
+				subscription = sub
 			}
-				AbortWithError(c, status, code, err.Error())
+		}
+
+		// ── 6. 计费执行（skipBilling 时整块跳过） ────────────────────
+
+		if !skipBilling {
+			// Key 状态检查
+			switch apiKey.Status {
+			case service.StatusAPIKeyQuotaExhausted:
+				AbortWithError(c, 429, "API_KEY_QUOTA_EXHAUSTED", "API key 额度已用完")
+				return
+			case service.StatusAPIKeyExpired:
+				AbortWithError(c, 403, "API_KEY_EXPIRED", "API key 已过期")
 				return
 			}
 
-			// 将订阅信息存入上下文
-			c.Set(string(ContextKeySubscription), subscription)
+			// 运行时过期/配额检查（即使状态是 active，也要检查时间和用量）
+			if apiKey.IsExpired() {
+				AbortWithError(c, 403, "API_KEY_EXPIRED", "API key 已过期")
+				return
+			}
+			if apiKey.IsQuotaExhausted() {
+				AbortWithError(c, 429, "API_KEY_QUOTA_EXHAUSTED", "API key 额度已用完")
+				return
+			}
+
+			// 订阅模式：验证订阅限额
+			if subscription != nil {
+				needsMaintenance, validateErr := subscriptionService.ValidateAndCheckLimits(subscription, apiKey.Group)
+				if validateErr != nil {
+					code := "SUBSCRIPTION_INVALID"
+					status := 403
+					if errors.Is(validateErr, service.ErrDailyLimitExceeded) ||
+						errors.Is(validateErr, service.ErrWeeklyLimitExceeded) ||
+						errors.Is(validateErr, service.ErrMonthlyLimitExceeded) {
+						code = "USAGE_LIMIT_EXCEEDED"
+						status = 429
+					}
+					AbortWithError(c, status, code, validateErr.Error())
+					return
+				}
 
 				// 窗口维护异步化（不阻塞请求）
-			// 传递独立拷贝，避免与 handler 读取 context 中的 subscription 产生 data race
 				if needsMaintenance {
 					maintenanceCopy := *subscription
 					subscriptionService.DoWindowMaintenance(&maintenanceCopy)
 				}
 			} else {
-			// 余额模式：检查用户余额
+				// 非订阅模式 或 订阅模式但 subscriptionService 未注入：回退到余额检查
 				if apiKey.User.Balance <= 0 {
 					AbortWithError(c, 403, "INSUFFICIENT_BALANCE", "Insufficient account balance")
 					return
 				}
 			}
+		}
 
-		// 将API key和用户信息存入上下文
+		// ── 7. 设置上下文 → Next ─────────────────────────────────────
+
+		if subscription != nil {
+			c.Set(string(ContextKeySubscription), subscription)
+		}
 		c.Set(string(ContextKeyAPIKey), apiKey)
 		c.Set(string(ContextKeyUser), AuthSubject{
 			UserID:      apiKey.User.ID,