makecindy / makecindy/cindy

[提案] 设置页「用量和计费」:新增用量统计卡 + 分组排版优化

Open
#2,020 2 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
2.7k
Forks
401
Avg merge
21h 48m
Merged PRs (30d)
776

Description

# [提案] 设置页「用量和计费」:新增用量统计卡 + 分组排版优化

> 提案图先行,方向点头前不动代码(沿用 #1261 / #1316 的流程)。
> 与已合并的 #1300(额度卡)同一条体验线:这次是设置页里「钱」的一侧。

## 背景与动机

当前「用量和计费」页能查余额、管订阅、看订单,但回答不了用户最常问的一个问题:**「我最近花得多不多?」**——没有任何历史消耗视图。同时页面分组顺序(订阅 → 余额 → 明细 → 赠送 → 订单)与预付费用户的关注优先级(先看还剩多少钱)不完全一致,套餐关键信息(价格 / 含量 / 续订日)藏在一行顿号串里。

本提案只做两件事:

1. **新增「用量统计」卡**(唯一新功能):金额口径的消耗历史。
2. **分组排版优化**(零新机制):重排分组、套餐关键信息三栏化、余额一张卡收三池。

其余一切——checkout / 充值 / 订阅管理 / 订单 / 赠送明细 / 全部错误与降级状态——**零触碰**。

## 示意图(可交互原型截好的实图)

| 整页 · 浅色 | 整页 · 深色 |
|---|---|
| ![浅色](https://raw.githubusercontent.com/0xmariowu/cindy/6d682b390cb765b91741a751531b6dc8ed6d1db3/billing-light.png) | ![深色](https://raw.githubusercontent.com/0xmariowu/cindy/6d682b390cb765b91741a751531b6dc8ed6d1db3/billing-dark.png) |

**用量统计 · 悬停单日**(白卡气泡:日期 · 总额 · 各模型金额;高亮带跟随;图例悬停联动只亮该模型):

![悬停](https://raw.githubusercontent.com/0xmariowu/cindy/6d682b390cb765b91741a751531b6dc8ed6d1db3/usage-hover.png)

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

![边界](https://raw.githubusercontent.com/0xmariowu/cindy/6d682b390cb765b91741a751531b6dc8ed6d1db3/usage-edge-cases.png)

## 设计要点

**用量统计卡**:
- 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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.