From 6a711c1fffe6f40129830a778d1f954a712cc789 Mon Sep 17 00:00:00 2001 From: wuxu Date: Sat, 22 Aug 2026 09:59:10 +0800 Subject: [PATCH] feat: show available reset credits --- README.md | 1 + backend/CONTRACT.md | 4 +- backend/internal/app/api.go | 37 ++++++++++++++++- backend/internal/app/runtime_test.go | 43 +++++++++++++++++--- backend/internal/app/types.go | 25 +++++++----- docs/backend/codex-integration-and-usage.md | 4 +- docs/frontend/application.md | 2 +- frontend/src/main.tsx | 18 +++++++++ frontend/src/styles.css | 45 +++++++++++++++++++++ frontend/src/types.test.ts | 16 ++++++++ frontend/src/types.ts | 16 ++++++++ frontend/tests/settings-layout.spec.ts | 11 +++++ 12 files changed, 201 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index c35e7d2..18e10f1 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,7 @@ - 支持在同一总览页查看多个 Codex 账号或工作区（包括同一邮箱的个人订阅与 Team 工作区） - 展示 Codex 账户、套餐、剩余额度和下次重置时间 - 展示当前重置周期 Token 合计、本周期单日峰值及每日 Token 趋势 +- 登录后有可用重置卡时展示卡片数量和到期时间 - 在本地 SQLite 中保留历史用量和限额快照 - 在限额重置前、重置后发送 Telegram 或邮件提醒 - 通过 Telegram 菜单查询当前用量、重置时间、历史概览和账户信息 diff --git a/backend/CONTRACT.md b/backend/CONTRACT.md index 3473cb8..b2e915b 100644 --- a/backend/CONTRACT.md +++ b/backend/CONTRACT.md @@ -33,6 +33,7 @@ usedPercent, windowDurationMinutes, resetsAt, planType:string|null}], currentCycle?:{limitId, windowType, windowDurationMinutes, startedAt, resetsAt, totalTokens}, + resetCredits?:{availableCount, expiresAt:[Unix seconds]}, summary:{lifetimeTokens?, peakDailyTokens?, longestRunningTurnSec?, currentStreakDays?, longestStreakDays?, callCount?, inputTokens?, outputTokens?}, usage:[{date,totalTokens,callCount?,inputTokens?,outputTokens?}], @@ -40,6 +41,7 @@ ``` 时间字段为 Unix 秒。`currentCycle` 是按当前仍有效的最长限额窗口计算的当前重置周期；`totalTokens` 由 `account/usage/read` 的每日 Token bucket 汇总，受每日粒度影响，无法精确切分周期起止日期内的单日数据。`summary.peakDailyTokens` 是同一当前重置周期内每日 Token bucket 的最大值，不再直接采用 app-server 未限定口径的峰值摘要；没有有效窗口或周期内没有每日数据时为 `null`。app-server 未提供的其他摘要字段可以是 `null`；列表应返回数组而非 `null`。 +`resetCredits` 仅在 app-server 返回可用重置卡且 `availableCount > 0` 时出现；`expiresAt` 是已返回卡片的去重到期时间列表，服务端未提供卡片详情时可以为空。匿名公开 Dashboard 不返回该字段。 ## 3. 系统、初始化与会话 @@ -64,7 +66,7 @@ | `POST /api/v1/accounts/{id}/login/device` | 启动并初始化 app-server，调用 `account/login/start` 的 `chatgptDeviceCode` 流程；返回含 `verificationUrl`、`userCode` 和 `loginId` 的结果。 | | `POST /api/v1/accounts/{id}/logout` | 调用 `account/logout` 并将连接状态置为 false；返回 `200 {ok:true}`。 | | `POST /api/v1/accounts/{id}/sync` | 同步指定账号；成功 `200 {ok:true}`，上游失败 502。 | -| `GET`/`HEAD /api/v1/dashboard?accountId={id}` | 初始化后匿名可读公开账号，返回内存中的 `Dashboard`；匿名访问未公开账号返回 404，匿名响应隐藏邮箱、认证方式和内部错误字段。登录后可读取全部账号。省略或无效的零值 ID 使用账号 1，前端使用 `GET`。 | +| `GET`/`HEAD /api/v1/dashboard?accountId={id}` | 初始化后匿名可读公开账号，返回内存中的 `Dashboard`；匿名访问未公开账号返回 404，匿名响应隐藏邮箱、认证方式、重置卡和内部错误字段。登录后可读取全部账号。省略或无效的零值 ID 使用账号 1，前端使用 `GET`。 | | `任意非读方法 /api/v1/dashboard?accountId={id}` | 要求 session；非 `GET`/`HEAD` 还需来源头。保持兼容的读取行为，省略或无效的零值 ID 使用账号 1。 | | `POST /api/v1/sync?accountId={id}` | 旧兼容入口，同步指定账号；省略或零值 ID 使用账号 1。 | diff --git a/backend/internal/app/api.go b/backend/internal/app/api.go index 5acc6a5..3e042f9 100644 --- a/backend/internal/app/api.go +++ b/backend/internal/app/api.go @@ -8,6 +8,7 @@ import ( "net/http" "os" "path/filepath" + "sort" "strconv" "strings" "time" @@ -229,6 +230,7 @@ func (a *App) dashboardAPI(w http.ResponseWriter, r *http.Request) { func publicDashboard(d Dashboard) Dashboard { d.Account.Email = nil d.Account.AuthMode = nil + d.ResetCredits = nil d.LastError = "" return d } @@ -489,10 +491,12 @@ func (a *App) syncAccount(ctx context.Context, id int64) error { d.Account.AuthMode = &ar.Account.Type } var lr struct { - RateLimits *rawLimit `json:"rateLimits"` - By map[string]rawLimit `json:"rateLimitsByLimitId"` + RateLimits *rawLimit `json:"rateLimits"` + By map[string]rawLimit `json:"rateLimitsByLimitId"` + ResetCredits *rawResetCredits `json:"rateLimitResetCredits"` } if e := rt.client.Call(ctx, "account/rateLimits/read", map[string]any{}, &lr); e == nil { + d.ResetCredits = normalizeResetCredits(lr.ResetCredits) if len(lr.By) > 0 { for _, x := range lr.By { d.Limits = append(d.Limits, flattenLimit(x)...) @@ -605,6 +609,35 @@ type rawLimit struct { Secondary *LimitWindow `json:"secondary"` } +type rawResetCredits struct { + AvailableCount int `json:"availableCount"` + Credits []rawResetCredit `json:"credits"` +} + +type rawResetCredit struct { + ExpiresAt *int64 `json:"expiresAt"` +} + +func normalizeResetCredits(raw *rawResetCredits) *ResetCreditsSummary { + if raw == nil || raw.AvailableCount <= 0 { + return nil + } + expiresAt := make([]int64, 0, len(raw.Credits)) + for _, credit := range raw.Credits { + if credit.ExpiresAt != nil && *credit.ExpiresAt > 0 { + expiresAt = append(expiresAt, *credit.ExpiresAt) + } + } + sort.Slice(expiresAt, func(i, j int) bool { return expiresAt[i] < expiresAt[j] }) + uniqueExpiresAt := expiresAt[:0] + for _, value := range expiresAt { + if len(uniqueExpiresAt) == 0 || uniqueExpiresAt[len(uniqueExpiresAt)-1] != value { + uniqueExpiresAt = append(uniqueExpiresAt, value) + } + } + return &ResetCreditsSummary{AvailableCount: raw.AvailableCount, ExpiresAt: uniqueExpiresAt} +} + func currentTokenCycle(limits []LimitBucket, usage []UsagePoint, fetchedAt int64) *TokenCycle { current := LimitBucket{} found := false diff --git a/backend/internal/app/runtime_test.go b/backend/internal/app/runtime_test.go index 2d6286a..eeddd73 100644 --- a/backend/internal/app/runtime_test.go +++ b/backend/internal/app/runtime_test.go @@ -6,6 +6,7 @@ import ( "errors" "net/http" "net/http/httptest" + "reflect" "strconv" "strings" "sync" @@ -93,12 +94,13 @@ func TestAnonymousOverviewIsReadOnly(t *testing.T) { } a.runtimes[1] = &accountRuntime{ dash: Dashboard{ - AccountID: 1, - DisplayName: "默认账号", - Account: AccountView{Email: &email, PlanType: &plan, Connected: true}, - Limits: []LimitBucket{}, - Usage: []UsagePoint{}, - FetchedAt: time.Now().Unix(), + AccountID: 1, + DisplayName: "默认账号", + Account: AccountView{Email: &email, PlanType: &plan, Connected: true}, + Limits: []LimitBucket{}, + Usage: []UsagePoint{}, + ResetCredits: &ResetCreditsSummary{AvailableCount: 2, ExpiresAt: []int64{1784246400}}, + FetchedAt: time.Now().Unix(), }, } @@ -132,6 +134,9 @@ func TestAnonymousOverviewIsReadOnly(t *testing.T) { if publicDashboardBody.Account.Email != nil || publicDashboardBody.Account.AuthMode != nil { t.Fatalf("anonymous dashboard account = %#v; identity fields were not redacted", publicDashboardBody.Account) } + if publicDashboardBody.ResetCredits != nil { + t.Fatalf("anonymous dashboard reset credits = %#v; entitlement data was not redacted", publicDashboardBody.ResetCredits) + } for _, path := range []string{"/api/v1/settings/general", "/api/v1/accounts", "/api/v1/accounts/1/sync"} { recorder := httptest.NewRecorder() @@ -163,6 +168,9 @@ func TestAnonymousOverviewIsReadOnly(t *testing.T) { if privateDashboardBody.Account.Email == nil || *privateDashboardBody.Account.Email != email { t.Fatalf("authenticated dashboard email = %v; want %q", privateDashboardBody.Account.Email, email) } + if privateDashboardBody.ResetCredits == nil || privateDashboardBody.ResetCredits.AvailableCount != 2 { + t.Fatalf("authenticated dashboard reset credits = %#v; want two credits", privateDashboardBody.ResetCredits) + } configRecorder := httptest.NewRecorder() configRequest := httptest.NewRequest(http.MethodPut, "/api/v1/settings/general", strings.NewReader(`{"timezone":"UTC","theme":"system","syncMinutes":5,"retentionDays":90,"beforeMinutes":30,"notifyBefore":true,"notifyAfter":true}`)) configRequest.AddCookie(&http.Cookie{Name: "session", Value: session}) @@ -320,6 +328,29 @@ func TestCurrentTokenCycleUsesLongestWindowAndFiltersDailyUsage(t *testing.T) { } } +func TestNormalizeResetCreditsKeepsAvailableCountAndUniqueExpiryTimes(t *testing.T) { + earlier := int64(1781654400) + later := int64(1784246400) + credits := normalizeResetCredits(&rawResetCredits{ + AvailableCount: 3, + Credits: []rawResetCredit{ + {ExpiresAt: &later}, + {ExpiresAt: nil}, + {ExpiresAt: &earlier}, + {ExpiresAt: &later}, + }, + }) + if credits == nil || credits.AvailableCount != 3 { + t.Fatalf("reset credits = %#v; want three available credits", credits) + } + if want := []int64{earlier, later}; !reflect.DeepEqual(credits.ExpiresAt, want) { + t.Fatalf("expiry times = %v; want %v", credits.ExpiresAt, want) + } + if normalizeResetCredits(&rawResetCredits{}) != nil { + t.Fatal("zero available credits should be hidden") + } +} + func TestCurrentTokenCycleRequiresAValidFutureResetWindow(t *testing.T) { cycle := currentTokenCycle( []LimitBucket{{WindowDurationMinutes: 0, ResetsAt: 1}}, diff --git a/backend/internal/app/types.go b/backend/internal/app/types.go index 9f6a8b6..fa5a112 100644 --- a/backend/internal/app/types.go +++ b/backend/internal/app/types.go @@ -81,17 +81,22 @@ type TokenCycle struct { ResetsAt int64 `json:"resetsAt"` TotalTokens int64 `json:"totalTokens"` } +type ResetCreditsSummary struct { + AvailableCount int `json:"availableCount"` + ExpiresAt []int64 `json:"expiresAt"` +} type Dashboard struct { - AccountID int64 `json:"accountId"` - DisplayName string `json:"displayName"` - Account AccountView `json:"account"` - Limits []LimitBucket `json:"limits"` - Summary UsageSummary `json:"summary"` - Usage []UsagePoint `json:"usage"` - CurrentCycle *TokenCycle `json:"currentCycle,omitempty"` - FetchedAt int64 `json:"fetchedAt"` - Stale bool `json:"stale"` - LastError string `json:"lastError,omitempty"` + AccountID int64 `json:"accountId"` + DisplayName string `json:"displayName"` + Account AccountView `json:"account"` + Limits []LimitBucket `json:"limits"` + Summary UsageSummary `json:"summary"` + Usage []UsagePoint `json:"usage"` + CurrentCycle *TokenCycle `json:"currentCycle,omitempty"` + ResetCredits *ResetCreditsSummary `json:"resetCredits,omitempty"` + FetchedAt int64 `json:"fetchedAt"` + Stale bool `json:"stale"` + LastError string `json:"lastError,omitempty"` } func defaults() GeneralSettings { diff --git a/docs/backend/codex-integration-and-usage.md b/docs/backend/codex-integration-and-usage.md index fcff75a..cd03514 100644 --- a/docs/backend/codex-integration-and-usage.md +++ b/docs/backend/codex-integration-and-usage.md @@ -23,13 +23,15 @@ account/login/start {type:"chatgptDeviceCode"} 一次同步依次读取 `account/read`、`account/rateLimits/read` 和 `account/usage/read`： - `account/read` 决定连接、邮箱、认证模式和套餐；读取失败会使整次同步失败。 -- 限额读取兼容 `rateLimitsByLimitId` 多 bucket 和旧 `rateLimits` 单 bucket，再把 primary/secondary 展平。失败时保留空限额而不令整次同步失败。 +- 限额读取兼容 `rateLimitsByLimitId` 多 bucket 和旧 `rateLimits` 单 bucket，再把 primary/secondary 展平；同时读取 `rateLimitResetCredits`，只在有可用卡时保留数量和到期时间。失败时保留空限额而不令整次同步失败。 - 套餐未知时，可从所有可分类且一致的限额 bucket 回填；冲突或未知时必须保持 unknown。 - 用量读取保存 summary 和每日 Token bucket；接口失败时使用空摘要和空历史，不令整次同步失败。同步成功后，以当前仍有效的最长限额窗口作为当前重置周期，按每日 bucket 汇总周期起点至当前日期的 Token，写入 Dashboard 的 `currentCycle`；周期外和未来日期不会计入。 - 每次限额同步写入快照、检测用量百分比显著回落，并更新账号元数据及内存 Dashboard。 `account/usage/read` 的 optional 指标和 daily buckets 可能暂未提供。仅 API Key 或 Bedrock 登录不能保证读取 ChatGPT 用量；不得在缺失数据时合成调用次数、输入/输出 Token、价格或账单日期。 +重置卡来自 `account/rateLimits/read` 的 `rateLimitResetCredits`。该信息只保存在内存 Dashboard 中，下一次同步会重新读取；没有可用卡时不返回到 Dashboard。当前项目只展示数量和到期时间，不执行消耗操作。 + `currentCycle` 的周期长度和重置时间来自 `account/rateLimits/read`，不硬编码为七天；通常会选择 secondary 周窗口。由于 daily bucket 只有日期没有每次请求时间，周期边界所在日期按整日汇总，因此该值是当前周期的日级统计，不是 Credits 或美元估值。 ## 套餐类型 diff --git a/docs/frontend/application.md b/docs/frontend/application.md index fb6bf6e..eb9ace3 100644 --- a/docs/frontend/application.md +++ b/docs/frontend/application.md @@ -18,7 +18,7 @@ API 类型精确区分后端 `null` 与 optional，并为秘密设置拆分读 ## 总览与设置 -总览显示账户连接、套餐、每个限额窗口的剩余百分比和重置时间、当前重置周期 Token 合计、本周期单日峰值、其他摘要及每日 Token 图。当前周期 Token 与本周期单日峰值都由后端按 app-server 的有效最长限额窗口和每日 bucket 汇总，不包含周期外或未来日期；详情会显示周期起止时间和“按每日数据汇总”提示。`usedPercent` 展示前限制到 0–100，但原始数据语义不得在 API 类型层改写。缺失摘要显示“暂无”，缺失限额显示明确空状态。 +总览显示账户连接、套餐、每个限额窗口的剩余百分比和重置时间、当前重置周期 Token 合计、本周期单日峰值、其他摘要及每日 Token 图；登录后账号有可用重置卡时，详情额外显示卡片数量和到期时间。当前周期 Token 与本周期单日峰值都由后端按 app-server 的有效最长限额窗口和每日 bucket 汇总，不包含周期外或未来日期；详情会显示周期起止时间和“按每日数据汇总”提示。`usedPercent` 展示前限制到 0–100，但原始数据语义不得在 API 类型层改写。缺失摘要显示“暂无”，缺失限额显示明确空状态。匿名公开 Dashboard 不显示重置卡信息。 设置页四个 tab 全部保持挂载，以保留未提交表单状态；非活动 panel 使用 `aria-hidden` 和 `inert` 隔离。tab 支持方向键、Home 和 End，程序化切换不得改变页面滚动和布局。账号删除必须保留不可撤销确认，并清理正在显示的设备码和本地账号选择。 diff --git a/frontend/src/main.tsx b/frontend/src/main.tsx index 969befd..f440735 100644 --- a/frontend/src/main.tsx +++ b/frontend/src/main.tsx @@ -24,6 +24,7 @@ import { MoreHorizontal, Settings, Sun, + Ticket, Trash2, TrendingUp, Zap, @@ -714,6 +715,21 @@ function AccountDashboardDetails({ value={dashboard.stale ? "数据可能已过期" : "数据已更新"} /> + {!publicView && + dashboard.resetCredits && + dashboard.resetCredits.availableCount > 0 && ( +
+ +
+ 重置卡 + 可用 {dashboard.resetCredits.availableCount} 张 +
+
+ 到期时间 + {formatResetCreditExpiry(dashboard.resetCredits.expiresAt)} +
+
+ )}
{dashboard.limits.map((limit, index) => ( }).format(v); const cycleTimestamp = (value: number) => new Date(value * 1000).toLocaleString(); +const formatResetCreditExpiry = (values: number[]) => + values.length ? values.map(cycleTimestamp).join("、") : "服务端未提供"; const cycleDuration = (minutes: number) => minutes % (24 * 60) === 0 ? `${minutes / (24 * 60)} 天窗口` diff --git a/frontend/src/styles.css b/frontend/src/styles.css index e3e3a6d..83c3e49 100644 --- a/frontend/src/styles.css +++ b/frontend/src/styles.css @@ -499,6 +499,44 @@ header p { white-space: nowrap; font-size: 13px; } +.reset-credits { + display: flex; + align-items: center; + gap: 12px; + margin-top: 14px; + padding: 12px 14px; + border: 1px solid color-mix(in srgb, var(--accent2) 30%, var(--border)); + border-radius: 12px; + background: color-mix(in srgb, var(--accent2) 7%, var(--panel)); +} +.reset-credits > svg { + flex: none; + width: 20px; + color: var(--accent2); +} +.reset-credits-main, +.reset-credits-expiry { + display: flex; + min-width: 0; + flex-direction: column; + gap: 4px; +} +.reset-credits-main small, +.reset-credits-expiry small { + color: var(--muted); + font-size: 12px; +} +.reset-credits-main b, +.reset-credits-expiry b { + font-size: 13px; +} +.reset-credits-expiry { + margin-left: auto; + text-align: right; +} +.reset-credits-expiry b { + overflow-wrap: anywhere; +} .account-detail-state { display: flex; min-height: 170px; @@ -1041,6 +1079,13 @@ a { .account-info-grid { grid-template-columns: 1fr 1fr; } + .reset-credits { + align-items: flex-start; + } + .reset-credits-expiry { + margin-left: 0; + text-align: left; + } .account { display: grid; grid-template-columns: auto minmax(0, 1fr) auto; diff --git a/frontend/src/types.test.ts b/frontend/src/types.test.ts index abb6970..9f3243b 100644 --- a/frontend/src/types.test.ts +++ b/frontend/src/types.test.ts @@ -47,6 +47,22 @@ describe("API decoders", () => { expect(value.currentCycle?.totalTokens).toBe(123_456); }); + it("解码可用重置卡及到期时间", () => { + const value = decodeDashboard({ + accountId: 1, + displayName: "个人账号", + account: { email: null, planType: "plus", connected: true }, + limits: [], + resetCredits: { availableCount: 2, expiresAt: [1_784_246_400] }, + summary: {}, + usage: [], + fetchedAt: 1_900_000_000, + stale: false, + }); + expect(value.resetCredits?.availableCount).toBe(2); + expect(value.resetCredits?.expiresAt).toEqual([1_784_246_400]); + }); + it("拒绝未知主题", () => { expect(() => decodeGeneral({ diff --git a/frontend/src/types.ts b/frontend/src/types.ts index a172813..0e332a1 100644 --- a/frontend/src/types.ts +++ b/frontend/src/types.ts @@ -57,6 +57,10 @@ export interface TokenCycle { resetsAt: number; totalTokens: number; } +export interface ResetCreditsSummary { + availableCount: number; + expiresAt: number[]; +} export interface Dashboard { accountId: number; displayName: string; @@ -76,6 +80,7 @@ export interface Dashboard { usage: Point[]; fetchedAt: number; stale: boolean; + resetCredits?: ResetCreditsSummary; lastError?: string; } export interface GeneralSettings { @@ -178,6 +183,14 @@ const decodeTokenCycle: Decoder = (value) => { totalTokens: number(x.totalTokens, "totalTokens"), }; }; +const decodeResetCredits: Decoder = (value) => { + const x = record(value, "resetCredits"); + if (!Array.isArray(x.expiresAt)) throw new Error("expiresAt格式无效"); + return { + availableCount: number(x.availableCount, "availableCount"), + expiresAt: x.expiresAt.map((v, index) => number(v, `expiresAt[${index}]`)), + }; +}; export const decodeDashboard: Decoder = (value) => { const x = record(value, "Dashboard"), account = record(x.account, "account"), @@ -209,6 +222,9 @@ export const decodeDashboard: Decoder = (value) => { ...(x.currentCycle == null ? {} : { currentCycle: decodeTokenCycle(x.currentCycle) }), + ...(x.resetCredits == null + ? {} + : { resetCredits: decodeResetCredits(x.resetCredits) }), summary: { lifetimeTokens: optionalNumber(summary.lifetimeTokens, "lifetimeTokens"), peakDailyTokens: optionalNumber( diff --git a/frontend/tests/settings-layout.spec.ts b/frontend/tests/settings-layout.spec.ts index f5559a2..4dcea09 100644 --- a/frontend/tests/settings-layout.spec.ts +++ b/frontend/tests/settings-layout.spec.ts @@ -106,6 +106,10 @@ test("shows every account as a collapsible summary on the overview", async ({ currentStreakDays: 4, longestRunningTurnSec: 80, }, + resetCredits: { + availableCount: 2, + expiresAt: [1_784_246_400], + }, usage: [{ date: "2026-08-13", totalTokens: 3_000 }], fetchedAt: 1_900_000_000, stale: false, @@ -175,6 +179,9 @@ test("shows every account as a collapsible summary on the overview", async ({ ).toBeVisible(); await expect(first.getByText("本周期 Tokens")).toBeVisible(); await expect(first.getByText("本周期单日峰值")).toBeVisible(); + await expect(first.getByTestId("reset-credits")).toContainText("重置卡"); + await expect(first.getByTestId("reset-credits")).toContainText("可用 2 张"); + await expect(first.getByTestId("reset-credits")).toContainText("到期时间"); await expect(first.getByText("连续使用", { exact: true })).toHaveCount(0); await expect(first.getByText("最长任务时长", { exact: true })).toHaveCount(0); await expect(first.getByText("123.5K", { exact: true })).toBeVisible(); @@ -183,6 +190,10 @@ test("shows every account as a collapsible summary on the overview", async ({ await first.getByRole("button", { name: "收起个人账号详情" }).click(); await expect(page.locator(".account-detail")).toHaveCount(0); + + const second = page.locator('[data-account-id="2"]'); + await second.getByRole("button", { name: "展开Team 工作区详情" }).click(); + await expect(second.getByTestId("reset-credits")).toHaveCount(0); }); test("shows a read-only overview before login", async ({ page }) => {