Sub2API v1.0 - AI API 网关（二开初始版本，基于上游 Wei-Shaw/sub2api）

backend/internal/handler/quotaview/helpers.go

@@ -0,0 +1,104 @@
+// Package quotaview provides shared quota response helpers for user and admin handlers.
+// Extracted to avoid import cycles between handler and handler/admin packages.
+package quotaview
+
+import (
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/pkg/timezone"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+)
+
+// LazyZeroQuotaForResponse 按 D14 规则把过期档位归零（不写 DB）。
+// includeWindowStart=true 时输出 *_window_start 字段（admin 视角调试用）
+func LazyZeroQuotaForResponse(r service.UserPlatformQuotaRecord, now time.Time, includeWindowStart bool) map[string]any {
+	daily := buildWindowSlice(r.DailyUsageUSD, r.DailyLimitUSD, r.DailyWindowStart, NeedsDailyReset(r.DailyWindowStart, now), nextDailyResetTime(now), includeWindowStart)
+	weekly := buildWindowSlice(r.WeeklyUsageUSD, r.WeeklyLimitUSD, r.WeeklyWindowStart, NeedsWeeklyReset(r.WeeklyWindowStart, now), nextWeeklyResetTime(now), includeWindowStart)
+	monthly := buildWindowSlice(r.MonthlyUsageUSD, r.MonthlyLimitUSD, r.MonthlyWindowStart, NeedsMonthlyReset(r.MonthlyWindowStart, now), NextMonthlyResetTimeFrom(r.MonthlyWindowStart, now), includeWindowStart)
+	out := map[string]any{
+		"platform":                 r.Platform,
+		"daily_usage_usd":          daily.usage,
+		"daily_limit_usd":          daily.limit,
+		"daily_window_resets_at":   daily.resetsAt,
+		"weekly_usage_usd":         weekly.usage,
+		"weekly_limit_usd":         weekly.limit,
+		"weekly_window_resets_at":  weekly.resetsAt,
+		"monthly_usage_usd":        monthly.usage,
+		"monthly_limit_usd":        monthly.limit,
+		"monthly_window_resets_at": monthly.resetsAt,
+	}
+	if includeWindowStart {
+		out["daily_window_start"] = daily.windowStart
+		out["weekly_window_start"] = weekly.windowStart
+		out["monthly_window_start"] = monthly.windowStart
+	}
+	return out
+}
+
+type windowSlice struct {
+	usage       float64
+	limit       *float64
+	resetsAt    *string
+	windowStart *string
+}
+
+func buildWindowSlice(usage float64, limit *float64, start *time.Time, expired bool, nextReset time.Time, includeStart bool) windowSlice {
+	out := windowSlice{usage: usage, limit: limit}
+	if expired {
+		out.usage = 0
+		out.resetsAt = nil
+	} else if start != nil {
+		s := nextReset.Format(time.RFC3339)
+		out.resetsAt = &s
+	}
+	if includeStart && start != nil {
+		s := start.Format(time.RFC3339)
+		out.windowStart = &s
+	}
+	return out
+}
+
+// NeedsDailyReset 判断日窗口是否已过期：start 早于「全局时区当天 0 点」即过期。
+// 时区跟随 timezone.Location()（全局服务器时区），与 billing / repo 写入的 window_start 同口径。
+func NeedsDailyReset(start *time.Time, now time.Time) bool {
+	if start == nil {
+		return false
+	}
+	return start.Before(timezone.StartOfDay(now))
+}
+
+func NeedsWeeklyReset(start *time.Time, now time.Time) bool {
+	if start == nil {
+		return false
+	}
+	return start.Before(timezone.StartOfWeek(now))
+}
+
+// NeedsMonthlyReset 30 天滚动窗口语义（与订阅模式 NeedsMonthlyReset 一致）。
+func NeedsMonthlyReset(start *time.Time, now time.Time) bool {
+	if start == nil {
+		return false
+	}
+	return now.Sub(*start) >= 30*24*time.Hour
+}
+
+func nextDailyResetTime(now time.Time) time.Time {
+	return timezone.StartOfDay(now).AddDate(0, 0, 1)
+}
+
+func nextWeeklyResetTime(now time.Time) time.Time {
+	return timezone.StartOfWeek(now).AddDate(0, 0, 7)
+}
+
+// NextMonthlyResetTimeFrom 计算 30 天滚动月度窗口的下次重置时间。
+// 语义：
+//   - start != nil → 返回 start + 30d（与 billing_cache_service.nextMonthlyResetFrom 一致）
+//   - start == nil → 退化为 now + 30d（保留旧行为，避免 nil 崩溃）
+//
+// 导出（首字母大写）以允许测试直接调用。
+func NextMonthlyResetTimeFrom(start *time.Time, now time.Time) time.Time {
+	if start == nil {
+		return now.Add(30 * 24 * time.Hour)
+	}
+	return start.Add(30 * 24 * time.Hour)
+}