# 头像卡片：用量与额度

## 用户可见范围

第一栏底部的会员标识位于头像上方。点击头像后的卡片依次为：头像昵称（右侧“我的世界”）、会员状态、四行用量摘要、数据管理、设置。卡片中的会员状态仍在头像昵称下方，不能与第一栏的标识位置混淆。

用量摘要显示月度 Token、云端存储、语音转文字、录音转写。前三行是“名称 / 已用进度条 / 总量”；悬停显示完整的已用、剩余及总量。第四行保留中性灰色占位轨，显示“暂未做限制”，明确提示用量统计待接入，不赋予 0% 等虚构进度。点击整块区域进入「设置 → 用量与额度」，该设置项紧跟「我的账户」，查看以下完整内容：

1. **AI 用量**：分别显示月度赠送 Token（已用 / 剩余）和额外充值的 AI 人民币余额（可用金额、非零任务预占）；不相加、不折算。余额旁提供现有充值入口。
2. **云端存储**：已用 / 总空间、剩余空间。沿用手机端的会员容量统计口径，不声称是云端所有文件的物理总大小。
3. **语音转文字**：已有 VOP 月度权益，显示本月已用、剩余及总时长；区别于录音板块文件转写。数据保留秒精度，展示为小时 / 分 / 秒。
4. **录音转写**：显示“暂未做限制”“用量统计待接入”。仅指录音板块的录音文件转写，不包含快记语音转写权益或 AI 总结。

## 数据与边界

- Token：`/api/v1/premium/get/q-token-limited-opt` 的 `used_token`、`able_token`。
- AI 余额：复用 `billing.quota` → `/api/v1/managed-ai/balance/query`。人民币纳元转金额；`reserved_nano_cny` 是进行中任务预占，不是累计消费。没有累计充值/消费字段，不估算。
- 存储用量：`/api/v1/premium/get/used-size`，优先 `used_file_size`，兼容 `size`，单位字节。
- 存储上限：`/api/v1/premium/get/member`，优先 `file_size` 字节，兼容 `file_size_mb × 1024 × 1024`；与 Flutter 一致。
- 语音转文字：`account.usage.voice` → `/api/v1/premium/get/vop-limited-opt`，`used_sec` 为本月已用秒数，`able_sec` 为剩余秒数，两者之和用于显示本月总量；不把 `able_sec` 误作总量，不写死会员档位时长。源码中的权益按中国时区自然月刷新。
- 不用 `/vop-limited-opt` 冒充录音文件转写用量；不把上传总时长当作成功转写时长。
- 不展示无来源的重置日期、已消费金额或“永久免费”承诺。
- 后端统一转写计量后，应补充权威的已用量、可用额度、周期、计量单位及限制状态，再替换第四项占位。没有限制时不绘制额度进度条。

## 交互与安全

### 存储与 Token 明细展开（2026-09-20）

入口只加在「设置 → 用量与额度」，头像快捷卡片的四行与高度不变。两个明细默认收起，采用页内展开，不叠加新弹窗。

- **空间构成**：复用 `used-size.breakdown`，按图片、视频、文件、背景音、通话录音、其他合并展示容量及占已用空间的比例；零条目不额外占行。分类之和必须等于权威已用字节数，否则仅提示分类明细暂不可用，保留有效汇总。文字、快记短语音、缩略图不计入此存储口径。
- **Token 明细**：展开后才读取 `/api/v1/llm-usage/me/summary`，使用浏览器当前时区和后端提供的可查询月份。显示该月已记录的实际模型用量，再通过 `/operations` 按操作分页（每页 20 条）；点击操作才调用 `/calls` 展开模型、时间、输入、输出、缓存命中/未命中等逐次明细。三者均为读取请求。
- 实际模型调用 Token、月度赠送额度扣减、人民币充值余额是三种不同口径，不相加、不替代，也不据此计算用户消费金额。字段不完整或接口失败时明确提示，不把未知数据填成 0。
- 切换月份、账号、关闭明细时取消在途请求并忽略迟到响应；账号范围由当前认证会话确认，不接受调用者指定其他用户。刷新保留所选月份并重读明细；分页失败保留已有结果，支持重试，防止重复游标循环。
- 参照手机端实际使用的 App Web 用户中心，复用其存储分类和智能后端明细契约；没有修改手机端、Web 用户中心或业务后端。

- 只在打开头像卡片或详情时读取，不轮询；重新打开或在详情中点击刷新会重新读取。
- Token、存储、语音和余额独立读取、独立显示失败，失败或字段不合法不回退为 0。余额只在详情打开后读取，快捷卡片不增加余额请求。
- 环境 + 用户组成账号作用域；切换账号后丢弃旧结果；关闭卡片取消前端请求。
- 剩余比例不高于 10% 时温和提醒，耗尽时明确提示，并提供查看对应会员权益入口。不自动下单、不承诺购买会员一定恢复额度。
- 会员付款沿用已有“桌面端支付开发中”占位流程；新详情的充值入口复用现有 managed-AI 商品与支付流程，不另造订单/扣费实现。打开充值只查询余额和商品；明确选择支付方式才创建订单。原生顶层弹窗保证充值不被详情遮住，关闭后返回详情并恢复充值按钮焦点；付款成功后的余额刷新沿用原逻辑。
- 明暗主题共用语义颜色；小高度窗口可滚动，不遮挡卡片底部设置入口。
- 快捷区 Token 总量用“万 / 亿”显示约数，完整数值放在悬停提示及详情中；低额度与耗尽改变进度条及总量颜色，悬停说明耗尽，不替换右侧总量、不额外增高。未知/失败用中性占位轨，没有 progressbar 数值。
- 详情复用 Harness 设置容器的关闭和导航行为，不再从头像卡片打开独立用量弹窗；充值和会员权益仍使用各自的原生 modal dialog。不会通过查看用量发送消息或主动提交消息已读。

## Token 口径核查（2026-09-20）

当前快捷卡片没有把两种资产合并：只读取 QToken 的 `used_token` / `able_token`。后端本地源码 `internal/premium/models.go` 按月度发放上限减本月消耗求剩余；`constants.go` 当前对免费 / VIP / SVIP 都配置为每自然月 5000 万，不能推断升级会员必然增加 Token。

单独购买的现有桌面通道是 managed-AI 充值余额，`/api/v1/managed-ai/balance/query` 返回人民币纳元，不是 Token。余额是可用 + 暂占，不能把暂占当作累计已消费，也不能折算后与 QToken 相加。经用户确认，“月度赠送 Token / AI 充值余额”已分项加入新详情，原设置入口保留。前端展示不代表后端已实现“月度 Token 耗尽后自动使用余额”，统一扣费策略仍需后端明确。

## 验证

覆盖合法/缺失/负数/不安全数值、字段兼容、零额度、超额存储、单项失败重试、跨用户和跨环境的迟到响应、刷新、会员入口和样式打包。真实付费与后端限额统一不在本次范围。

2026-09-20 本轮验证：7 个相关测试文件、106 项测试通过，类型检查及完整构建通过。固定 3098 独立 Web 预览已更新；使用已有登录账号读到了真实 Token 和存储数据，验证了手动刷新、明暗主题、600px 高度下卡片滚动及 Escape 关闭。录音转写统计仍为明确的待接入状态。未修改已安装 Arkme 客户端，未产生购买或扣费操作。

2026-09-20 精简版验证：7 个文件、110 项测试及完整构建通过。已登录浏览器测得快捷用量区高度 78px，头像卡片整体从初版 576px 降至 401.5px；三个数值均未截断，快捷区无进度条或说明文字。详情打开后关闭头像卡片，刷新、Escape、关闭按钮和头像焦点恢复正常；明暗主题及 500px 高窗口无横向溢出。只替换 3098 的前端资源，未重启预览服务，保留本轮前的登录状态及 Arkme 客户端。

2026-09-20 充值余额整合验证：11 个文件、151 项测试及完整构建通过。真实已登录预览读取了现有 AI 余额和三个充值套餐；打开充值只触发余额/商品查询，没有创建订单。充值弹窗处于原生顶层，Escape 返回详情并恢复充值按钮焦点；统一刷新、明暗详情和 500px 高窗口检查通过，无页面错误。头像快捷区仍为 78px，打开快捷区不查询余额。只更新 3098 的前端资源，服务进程、登录状态及已安装客户端不变。真实付款和月度额度/余额自动接续扣费未纳入验证或实现。

2026-09-20 四行进度版验证：11 个文件、165 项测试及完整构建通过。新增既有 VOP 接口的秒数校验、账号隔离及独立失败重试；快捷区四行、三个实测进度条，录音转写占位无虚构百分比。已登录 3098 实测四行各 16px，快捷区共 124px、头像卡片共 447.5px；总量均未截断，明暗主题、详情刷新、Escape/焦点恢复及 500px 高窗口正常，无页面错误。新增宿主读取能力仅重启独立 Web 预览，固定 3098 及原有 Arkme 账号保持不变；未修改已安装 Arkme 客户端，未创建订单或发起转写。

2026-09-20 明细展开验证：本轮 8 个相关文件、108 项测试和完整构建通过。固定 3098 已登录 Web 实测：返回 5 个非空存储分类，分类合计与权威已用空间一致；Token 月度汇总、操作记录、逐次模型调用成功，操作分页从 20 条增加至 40 条，切到上月重新加载并收起旧调用明细。中英文、明暗主题及 860×700 窗口无横向溢出，浏览器页面错误为 0。自动化验证阻断恢复、账户修改、下单、发送和上传，没有触发这些写入操作。仅更新并重启独立预览，未变更固定端口或已安装 Arkme 客户端。测试脚本和截图位于工作区外层 `.codex-artifacts/usage-details-dccCxx/`，不纳入产品包。