new-api-key-usage/docs/design/topups表字段设计.md

topups 表字段设计

数据模型：充值入账事件——一行 = 一次「钱 → 账号额度」的入账。与 subscriptions（订阅权益）分表（见 payments建模评估.md，方案 B）。字段对齐上游实测 GET /api/user/topup/self（2026-10-09 样本）；无 quota_granted 列（派生），事件时刻只存一条（上游 complete_time，即平台列表展示的时间）。

项目	内容
状态	定稿（2026-10-12，作者认可实现）
关联	subscriptions表字段设计.md · payments建模评估.md · NewAPI-接口范围.md §4.5 · qpu_history表字段设计.md
范围	列结构 + 语义 + 写入时机
字段数	10 = 1 主键 + 8 上游/业务事实 + 1 登记时刻

---

1. 表定位

• 一行 = 一次充值入账（事件）；时间主轴 = paid_at（上游 complete_time，平台展示时刻）
• 与消耗的关系：钱包/账号余额池，无法逐笔对应模型日志（billing_source=wallet 无 subscription_id 是正常态）
• 不存 quota_granted 真值列（上游没有；见 §3）

2. 字段清单

列	类型	上游字段	说明
id	bigserial PK	—	本地主键
upstream_id	bigint?	id	上游充值单 ID（对账；手工补录可空）
amount	numeric	amount	平台计费金额（充值记账额，样本 1）——与实付 money 之间由管理员约定汇率换算；不标币种/单位
money	numeric	money	实付金额（样本 2.04）；同样不预设币种
trade_no	text?	trade_no	交易号
payment_method	text?	payment_method	如 alipay
payment_provider	text?	payment_provider	如 epay
status	text?	status	如 success；失败单一般不入账本
paid_at	timestamptz	complete_time	入账时刻（唯一事件时间）——平台列表展示的就是它；上游 create_time 不入库
billing_domain	text NULL	人工标注（登记 / 编辑）	账本域标签（如 carpool / office）；空 = 未标域，成员不可见（充值无逐笔日志连线，无法用日志证明「与我相关」）
remark	text	—	人工备注
created_at	timestamptz	—	本系统登记时刻（补录审计）

样本（2026-10-09）：amount: 1 · money: 2.04 · trade_no: "USR6NOLqTPGa1791534153" · alipay/epay · create_time/complete_time Unix 秒 · status: "success"。展示与筛选一律用 complete_time 落入的 paid_at。

3. 「换得额度」是派生

上游无 quota_granted：派生 amount × quota_per_unit（默认 QPU 500000）——amount 是平台计费侧充值额，与 quota 同域量纲。

• 只存事实：amount（平台计费）与 money（实付）两真值；汇率不入库（管理员社交约定，查询/展示可现算 money/amount）
• 不在库中固化派生额度

4. 时刻语义

时刻	含义
paid_at	入账（= 上游 complete_time）——筛选、排序、QPU 锚点
created_at	登记进本表（补录审计）

5. 写入与维护

时机	动作
辅助登录选用（与订阅选择器同模式）	控制台登录（密码不落库）→ 分页拉 /api/user/topup/self → 选用预填表单 → 确认入库
纯手工登记	抄充值页 / 账单；或粘贴 JSON 预填
编辑 / 删除	改错即修
后台定时同步	不做（辅助登录仅代拉一次、token 会话内用）

分页请求策略（接口仅 p / page_size，无时间过滤）：

1. 传统分页 UI：弹层底部「共 N 条 · 页码 / 上一页 / 下一页」；每次请求只取当前页（page_size=10）
2. 不设硬上限——用户可一直翻到 total 尽头（找旧账必须靠翻页）
3. 不提供时间范围筛选（上游收窄不了结果集；本地筛只会误导读不出的更早页）
4. 已登记去重：按 upstream_id 灰显，不可重复选用
5. 401：清会话 token → 重新登录；token 仅 sessionStorage

6. 对外边界

• 成员可见：amount、money、渠道、paid_at、备注、billing_domain；仅本人名下 key 所属账本域内；无逐笔与模型日志的连线；未标域默认不可见
• 纯用量模式可不登记

7. 迁移说明

• 原 payments.kind=topup：paid_at 语义本就落在入账日 → 直接迁入本表 paid_at
• 若曾手填 quota_granted：可反推 amount = quota_granted / qpu 填 amount，否则按实付与约定补记