[提案] 设置页「用量和计费」:新增用量统计卡 + 分组排版优化
- Dominant language
- TypeScript
- Stars
- 2.7k
- Forks
- 401
- Avg merge
- 21h 48m
- Merged PRs (30d)
- 776
Description
# [提案] 设置页「用量和计费」:新增用量统计卡 + 分组排版优化
> 提案图先行,方向点头前不动代码(沿用 #1261 / #1316 的流程)。
> 与已合并的 #1300(额度卡)同一条体验线:这次是设置页里「钱」的一侧。
## 背景与动机
当前「用量和计费」页能查余额、管订阅、看订单,但回答不了用户最常问的一个问题:**「我最近花得多不多?」**——没有任何历史消耗视图。同时页面分组顺序(订阅 → 余额 → 明细 → 赠送 → 订单)与预付费用户的关注优先级(先看还剩多少钱)不完全一致,套餐关键信息(价格 / 含量 / 续订日)藏在一行顿号串里。
本提案只做两件事:
1. **新增「用量统计」卡**(唯一新功能):金额口径的消耗历史。
2. **分组排版优化**(零新机制):重排分组、套餐关键信息三栏化、余额一张卡收三池。
其余一切——checkout / 充值 / 订阅管理 / 订单 / 赠送明细 / 全部错误与降级状态——**零触碰**。
## 示意图(可交互原型截好的实图)
| 整页 · 浅色 | 整页 · 深色 |
|---|---|
|  |  |
**用量统计 · 悬停单日**(白卡气泡:日期 · 总额 · 各模型金额;高亮带跟随;图例悬停联动只亮该模型):

**边界状态**(按模型拆分不可用 / 新账号历史不足 / 获取失败,均有确定降级展示):

## 设计要点
**用量统计卡**:
- KPI 三格纯金额口径:今日 / 本月 / 近 30 天(今日与本月复用底栏 chip 已在用的网关数据);
- 分模型堆叠柱状图,时间范围 7 / 15 / 30 天(默认 15 天),悬停出白卡气泡(参照 Codex 后台的交互语言);
- **刻意不做**:导出 CSV(财务对账场景,非消费级需求)、Token 口径(第二套计量单位,回答不了任何决策问题)、精确 ETA(延续 #1307 的产品裁决)、百分比数字(堆叠形状即占比);
- 图表分模型着色用琥珀单一色系同族递淡(主力模型 = 既有 `--chart-money`),整套即 3 个 token,按 DESIGN.md §10 注册 `--chart-cat-*`——色值想换只动一行。
**排版优化**:
- 分组重排为:套餐 → 余额 → 用量统计 → 赠送明细 → 订单记录(预付费用户第一问题是「还剩多少钱」,余额前置);
- 套餐卡「月费 / 每月订阅额度 / 下次续订」三栏字段化(数据全部现成);
- 余额一张卡:可用余额大数字 + 三池行(订阅池带进度条与重置倒计时)收进同一张卡;
- **赠送明细、订单记录两组原组件零触碰**,仅位置随新排序;余额卡不内嵌明细入口。
**文案契约**:原 i18n 分支一字不动,新增文案只加不改;新术语走 glossary 提案流程。
## 数据边界
- 今日 / 本月 / 三池余额:全部现成(`claudeAccountUsage` + `getCreditUsage`);
- 逐日历史与按模型拆分:动手前先做网关按日活动端点的能力 spike(范围查询 / 按模型拆分),**按端点实际能力裁剪**——拆分拿不到就整柱单色、图例隐藏(示意图边界状态已画);
- 全部 renderer-only,不动 main 进程与 shared 契约。
## PR 拆分(一 PR 一问题)
1. **PR-A 排版整合**:分组重排 + 套餐三栏 + 余额一张卡。零新机制,现有 58 项 BillingPage 测试等强迁移;
2. **PR-B 用量统计卡**:数据源 spike 通过后按实际能力实现。
**后续(本提案不含)**:低余额 / 重置 / 到期通知族;余额条配速趋势行(待 #1307 落地后自然复用)。
## 想请维护者拍板的点
1. 方向是否认可(新增用量统计 + 排版重排);
2. 图表琥珀色系与新 token(`--chart-cat-*`)是否可注册,或您倾向别的色值;
3. 分组新顺序(余额前置)是否符合产品预期。
方向 OK 的话,我这边按上述拆分先提 PR-A。
Contributor guide
Research direction
Start with the BillingPage implementation and its existing 58 tests, then inspect claudeAccountUsage, getCreditUsage, and DESIGN.md §10. Confirm the gateway's daily-history and model-breakdown capabilities before scoping the usage card; the layout work is complete when the proposed section order, three-column plan details, and consolidated balance card pass the migrated tests without changing excluded billing components.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- frontend, payments
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100