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)
+}

backend/internal/handler/quotaview/helpers_test.go

@@ -0,0 +1,133 @@
+package quotaview
+
+import (
+	"testing"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/pkg/timezone"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+)
+
+// TestNextMonthlyResetTimeFrom_FromStart 验证：start 已知时返回 start+30d，不随 now 漂移。
+func TestNextMonthlyResetTimeFrom_FromStart(t *testing.T) {
+	t0 := time.Date(2024, 1, 1, 0, 0, 0, 0, time.UTC)
+	now := t0.Add(15 * 24 * time.Hour)  // t0 + 15d
+	want := t0.Add(30 * 24 * time.Hour) // t0 + 30d
+
+	got := NextMonthlyResetTimeFrom(&t0, now)
+	if !got.Equal(want) {
+		t.Errorf("NextMonthlyResetTimeFrom: want %v, got %v", want, got)
+	}
+}
+
+// TestNextMonthlyResetTimeFrom_NilStart 验证：start=nil 时退化为 now+30d（不 panic）。
+func TestNextMonthlyResetTimeFrom_NilStart(t *testing.T) {
+	now := time.Date(2024, 3, 15, 12, 0, 0, 0, time.UTC)
+	want := now.Add(30 * 24 * time.Hour)
+
+	got := NextMonthlyResetTimeFrom(nil, now)
+	if !got.Equal(want) {
+		t.Errorf("NextMonthlyResetTimeFrom(nil): want %v, got %v", want, got)
+	}
+}
+
+// TestLazyZeroQuotaForResponse_MonthlyResetsAt_NotDrifting 验证：
+// 连续两次以不同 now 调用、但 MonthlyWindowStart 相同的 record，
+// monthly_window_resets_at 始终等于 windowStart+30d，不随 now 漂移。
+func TestLazyZeroQuotaForResponse_MonthlyResetsAt_NotDrifting(t *testing.T) {
+	windowStart := time.Date(2024, 1, 1, 0, 0, 0, 0, time.UTC)
+	wantResetsAt := windowStart.Add(30 * 24 * time.Hour).Format(time.RFC3339)
+
+	r := service.UserPlatformQuotaRecord{
+		Platform:           "openai",
+		MonthlyUsageUSD:    5.0,
+		MonthlyWindowStart: &windowStart,
+	}
+
+	// 第一次调用：now = windowStart + 5d
+	now1 := windowStart.Add(5 * 24 * time.Hour)
+	out1 := LazyZeroQuotaForResponse(r, now1, false)
+	resetsAt1, ok1 := out1["monthly_window_resets_at"]
+	if !ok1 || resetsAt1 == nil {
+		t.Fatal("first call: monthly_window_resets_at should be set for active window")
+	}
+	s1, ok := resetsAt1.(*string)
+	if !ok || s1 == nil {
+		t.Fatalf("first call: monthly_window_resets_at should be *string, got %T", resetsAt1)
+	}
+	if *s1 != wantResetsAt {
+		t.Errorf("first call: want %s, got %s", wantResetsAt, *s1)
+	}
+
+	// 第二次调用：now = windowStart + 10d（不同 now，但 resetsAt 应不变）
+	now2 := windowStart.Add(10 * 24 * time.Hour)
+	out2 := LazyZeroQuotaForResponse(r, now2, false)
+	resetsAt2, ok2 := out2["monthly_window_resets_at"]
+	if !ok2 || resetsAt2 == nil {
+		t.Fatal("second call: monthly_window_resets_at should be set for active window")
+	}
+	s2, ok := resetsAt2.(*string)
+	if !ok || s2 == nil {
+		t.Fatalf("second call: monthly_window_resets_at should be *string, got %T", resetsAt2)
+	}
+	if *s2 != wantResetsAt {
+		t.Errorf("second call: want %s, got %s", wantResetsAt, *s2)
+	}
+
+	// 两次结果必须相等
+	if *s1 != *s2 {
+		t.Errorf("resetsAt drifted between calls: %s vs %s", *s1, *s2)
+	}
+}
+
+// TestNeedsDailyReset_FollowsServerTimezone 验证日窗口过期判断按全局时区（北京 0 点）而非 UTC。
+func TestNeedsDailyReset_FollowsServerTimezone(t *testing.T) {
+	if err := timezone.Init("Asia/Shanghai"); err != nil {
+		t.Fatalf("Init: %v", err)
+	}
+	t.Cleanup(func() { _ = timezone.Init("UTC") })
+
+	// now = 2026-05-25 23:00 UTC = 2026-05-26 07:00 +08（北京 5/26）
+	now := time.Date(2026, 5, 25, 23, 0, 0, 0, time.UTC)
+
+	// start = 2026-05-25 10:00 UTC = 2026-05-25 18:00 +08（北京 5/25）→ 应判定为过期
+	startPrevBeijingDay := time.Date(2026, 5, 25, 10, 0, 0, 0, time.UTC)
+	if !NeedsDailyReset(&startPrevBeijingDay, now) {
+		t.Error("上一个北京日的窗口应判定为过期")
+	}
+
+	// start = 2026-05-25 20:00 UTC = 2026-05-26 04:00 +08（北京 5/26 同日）→ 不应过期
+	startSameBeijingDay := time.Date(2026, 5, 25, 20, 0, 0, 0, time.UTC)
+	if NeedsDailyReset(&startSameBeijingDay, now) {
+		t.Error("同一北京日的窗口不应判定为过期")
+	}
+}
+
+// TestNextDailyResetTime_FollowsServerTimezone 验证下次日重置 = 次日北京 0 点。
+func TestNextDailyResetTime_FollowsServerTimezone(t *testing.T) {
+	if err := timezone.Init("Asia/Shanghai"); err != nil {
+		t.Fatalf("Init: %v", err)
+	}
+	t.Cleanup(func() { _ = timezone.Init("UTC") })
+
+	now := time.Date(2026, 5, 25, 23, 0, 0, 0, time.UTC)            // 北京 5/26 07:00
+	want := time.Date(2026, 5, 27, 0, 0, 0, 0, timezone.Location()) // 北京 5/27 00:00
+	if got := nextDailyResetTime(now); !got.Equal(want) {
+		t.Errorf("nextDailyResetTime = %v, want %v", got, want)
+	}
+}
+
+// TestNextWeeklyResetTime_FollowsServerTimezone 验证下次周重置 = 下周一北京 0 点。
+func TestNextWeeklyResetTime_FollowsServerTimezone(t *testing.T) {
+	if err := timezone.Init("Asia/Shanghai"); err != nil {
+		t.Fatalf("Init: %v", err)
+	}
+	t.Cleanup(func() { _ = timezone.Init("UTC") })
+
+	// 北京 2026-05-26（周二）→ 下周一是 2026-06-01
+	now := time.Date(2026, 5, 25, 23, 0, 0, 0, time.UTC) // 北京 5/26 07:00 周二
+	want := time.Date(2026, 6, 1, 0, 0, 0, 0, timezone.Location())
+	if got := nextWeeklyResetTime(now); !got.Equal(want) {
+		t.Errorf("nextWeeklyResetTime = %v, want %v", got, want)
+	}
+}