skycurtain/new-api-key-usage
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 账本域 billing_domain 与成员支付可见性收紧

Browse Source 
三表增加账本域标签，成员支付参数改为同域透明、跨域隔离、未标域默认藏；管理面登记/筛选/行内编辑与文档中心同步对齐。
This commit is contained in:
skycurtain
2026-10-13 20:42:26 +08:00
parent 843ab4433a
commit b0e9ea750b
31 changed files with 1463 additions and 53 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/design/API契约-成员视图.md
+4 -4
View File
@@ -48,13 +48,13 @@
"subscriptions": [
{ "id": 3, "subscription_id": 44, "period_start": "2026-09-01T00:00:00Z",
"period_end": "2026-10-01T00:00:00Z", "quota_granted": 12500000, "quota_usd": "25.00",
"paid_amount": 170, "paid_at": "2026-08-28T10:00:00Z", "remark": "九月拼车",
"paid_amount": 170, "paid_at": "2026-08-28T10:00:00Z", "billing_domain": "carpool", "remark": "九月拼车",
"created_at": "2026-09-02T12:00:00Z" }
],
"topups": [
{ "id": 1, "upstream_id": 17, "amount": 1, "money": 2.04,
"trade_no": "USR6…", "payment_method": "alipay", "payment_provider": "epay",
"status": "success", "paid_at": "…",
"status": "success", "paid_at": "…", "billing_domain": "carpool",
"quota_derived": 500000, "quota_usd": "1.00",
"remark": "", "created_at": "…" }
]
@@ -62,7 +62,7 @@
```
- `usage`：该时段总用量（总览摘要条）；`by_source`：订阅 / 充值分解（分段条）；`keys`：我的 Key 表（`log_synced_at` 支撑停滞标注）
- `subscriptions` / `topups`：**支付参数页 + 订阅徽章弹窗 + 「本订阅期间」快捷项**的数据源，判定见 §5 裁定 2；对成员**全字段可见**（含 `remark`）；两集皆空 = 纯用量模式中性空态
- `subscriptions` / `topups`：**支付参数页 + 订阅徽章弹窗 + 「本订阅期间」快捷项**的数据源，判定见 §5 裁定 2；对成员**同账本域内全字段可见**（含 `remark`）；两集皆空 = 纯用量模式中性空态
- 订阅徽章弹窗仅限「订阅 #N」（查 `subscriptions`）：「充值」不弹窗（余额池无逐笔）、「未关联」不可点；降级「该订阅无登记信息」
## 4. 日志明细
@@ -92,7 +92,7 @@
## 5. 本稿裁定项（请作者重点审）
1. **成员视图明细默认全类型**（消费 + 错误）——对齐「事实可查」；聚合仍仅 `type = 2`（用量口径不变）；`type` 可筛 2 / `error`；
2. **「该时段涉及」登记的判定**：订阅 = 该时段日志（`type = 2`）出现过的 `subscription_id` 对应 `subscriptions` 行 **∪ 进行中的订阅**（`period_end` 为空或未来——支撑「本订阅期间」快捷项）；充值 = `paid_at ∈ [from, to)`（入账事件按付费时刻锚定）；补录审计看各表 `created_at`（不进本判定）；
2. **「该时段涉及」登记的判定**（账本域隔离）：成员的**我的域** = 名下 key 的 `billing_domain` 非空并集。订阅 = 该时段日志（`type = 2`）出现过的 `subscription_id` 对应 `subscriptions` 行（**事实直连**，含未标域） **∪**（进行中 **∧** `billing_domain ∈ 我的域`）——未标域进行中订阅不放行；充值 = **`billing_domain ∈ 我的域`** ∧ `paid_at ∈ [from, to)`——未标域充值不放行。管理面不受此限；
3. **明细行 DTO 与管理面同构**：同一 `LogItem` 类型，成员端经归属与 `type` 恒定过滤；
4. **「充值」徽章不弹窗**——余额池扣款与具体充值记录无逐笔关联，弹窗回答不了「这笔花在哪」（《交互设计-成员视图》§4.2：订阅徽章才开支付参数弹窗，「充值」为纯标识；行展开只放模型调用详情）。
docs/design/API契约-管理面.md
+8 -5
View File
@@ -119,12 +119,13 @@
### GET `/api/admin/keys` → 200 `[key]`
全量直返（基数 10–25，不分页——§10 裁定 3）。筛选参数：`member_id`（id 或 `unassigned`）、`status`、`recent_failed=true`（引擎最近轮次失败）。排序默认数据截止降序（前端事）。
全量直返（基数 10–25，不分页——§10 裁定 3）。筛选参数：`member_id`（id 或 `unassigned`）、`status`、`billing_domain`（值或 `none` = 未标注）、`recent_failed=true`（引擎最近轮次失败）。排序默认数据截止降序（前端事）。
```json
{
"id": 5, "token_name": "小张-01", "status": "active",
"member_id": 1, "member_name": "小张",
"billing_domain": "carpool",
"registered_at": "2026-09-20T10:00:00Z",
"log_synced_at": "2026-10-02T08:00:00Z", "usage_synced_at": "2026-10-02T08:00:00Z",
"total_used": 600000, "total_available": 940000, "total_granted": 1540000,
@@ -136,7 +137,7 @@
### POST `/api/admin/keys` → 201 `key`
`{ "sk_key": "sk-…", "member_id": null }`——登记四态：
`{ "sk_key": "sk-…", "member_id": null, "billing_domain": null }`——登记四态：
| 结果 | 响应 |
|------|------|
@@ -147,7 +148,7 @@
### PATCH `/api/admin/keys/:id` → 200 `key`
`{ "status": "disabled" }`（启用 / 停用）或 `{ "member_id": 3 }`（归属变更；`null` = 归还未归属）——部分更新，单字段或并存均可，审计按实际变更字段各落一行（§9 枚举）。非法值 `422`；key 不存在 `404`；`member_id` 引用不存在成员 `422`（`fields`）。
`{ "status": "disabled" }`（启用 / 停用）· `{ "member_id": 3 }`（归属变更；`null` = 归还未归属）或 `{ "billing_domain": "office" }`（账本域变更；`null` = 未标域）——部分更新，单字段或并存均可，审计按实际变更字段各落一行（§9 枚举）。非法值 `422`；key 不存在 `404`；`member_id` 引用不存在成员 `422`（`fields`）。
## 6. 日志明细（管理面下钻）
@@ -184,6 +185,7 @@
"period_start": "2026-09-01T00:00:00Z", "period_end": "2026-10-01T00:00:00Z",
"quota_granted": 12500000, "quota_usd": "25.00",
"paid_amount": 170, "paid_at": "2026-08-28T10:00:00Z",
"billing_domain": "carpool",
"remark": "九月拼车", "created_at": "2026-09-02T12:00:00Z"
}
```
@@ -193,7 +195,7 @@
### POST `/api/admin/subscriptions` → 201 `subscription`
必填：`subscription_id` · `period_start` · `quota_granted`；可空：`period_end`（=进行中）· `paid_amount` · `paid_at` · `remark`。美元双输入为前端换算，落库恒原始 quota。
必填：`subscription_id` · `period_start` · `quota_granted`；可空：`period_end`（=进行中）· `paid_amount` · `paid_at` · `billing_domain` · `remark`。美元双输入为前端换算，落库恒原始 quota。列表筛选支持 `billing_domain`（值或 `none`）。
### PUT `/api/admin/subscriptions/:id` / DELETE → 204
@@ -209,6 +211,7 @@
"payment_method": "alipay", "payment_provider": "epay",
"status": "success",
"paid_at": "2026-10-09T12:22:56Z",
"billing_domain": "carpool",
"quota_derived": 500000, "quota_usd": "1.00",
"remark": "", "created_at": "2026-10-09T13:00:00Z"
}
@@ -218,7 +221,7 @@
### POST `/api/admin/topups` → 201 `topup`
必填：`paid_at` · `amount` · `money`；可空：`upstream_id` · `trade_no` · `payment_method` · `payment_provider` · `status` · `remark`。
必填：`paid_at` · `amount` · `money`；可空：`upstream_id` · `trade_no` · `payment_method` · `payment_provider` · `status` · `billing_domain` · `remark`。列表筛选支持 `billing_domain`（值或 `none`）。
### PUT `/api/admin/topups/:id` / DELETE → 204
docs/design/api_keys表字段设计.md
+1
View File
@@ -32,6 +32,7 @@
| `key_ciphertext` | bytea | 登记时 AES-256-GCM（管理员粘贴输入），nonce + 密文 + tag 打包 | 调上游时解密原文（唯一用途） |
| `status` | text | 管理面启停（引擎只读） | `active` / `disabled`；轮询清单 = active；disabled 数据保留、仅移出轮询 |
| `member_id` | bigint FK NULL | 归属登记（管理通道） | → `members.id`；成员视图与按成员统计的锚点；空 = 未归属 |
| `billing_domain` | text NULL | 人工标注（登记 / 行内编辑） | **账本域标签**（如 `carpool` / `office`）——区分用途的自由文本，非身份、非权限；空 = 未标域；成员可见性与支付记录的 `billing_domain` 对齐 |
| `registered_at` | timestamptz | 登记时写入 | 空态文案「数据自该 key 登记起累积」 |
| `log_synced_at` | timestamptz NULL | 日志同步成功时写入 | **「数据截止 HH:mm」的唯一来源**；同步失败的显形信号（停滞） |
| `usage_synced_at` | timestamptz NULL | 额度采集成功时写入 | 额度信息的新鲜度（UI 若做）、排查 |
docs/design/subscriptions表字段设计.md
+2 -1
View File
@@ -29,6 +29,7 @@
| `quota_granted` | bigint | 人工录入（钱包页 `amount_total`） | 套餐总额度——**原始 quota 整数**（与日志 `quota` 同域；充值侧无此列，额度由 `amount × qpu` 派生） |
| `paid_amount` | numeric? | 人工录入（支付凭证） | 该套餐实付金额；币种无关纯数值；未知可空 |
| `paid_at` | timestamptz? | 人工录入（支付凭证） | **钱出手时刻**（非登记时刻）；未知可空 |
| `billing_domain` | text NULL | 人工标注（登记 / 编辑） | **账本域标签**（如 `carpool` / `office`）；空 = 未标域，成员不可见（涉及该订阅 `subscription_id` 的日志事实直连除外） |
| `remark` | text | 人工填写 | 备注 |
| `created_at` | timestamptz | 系统 | **登记入库时刻**（补录审计） |
@@ -60,5 +61,5 @@
## 6. 对外边界
- 参数对成员**完全公开透明**（含 `remark` / 金额）——访问主体模型裁决
- 参数对成员**同账本域内可见**（含 `remark` / 金额）——同域透明、跨域隔离；未标域默认对成员隐藏，例外：该订阅 `subscription_id` 出现在本人名下 key 的 `type = 2` 日志中（事实直连）
- 无「应付」、无分摊字段
docs/design/topups表字段设计.md
+2 -1
View File
@@ -30,6 +30,7 @@
| `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 | — | 本系统登记时刻（补录审计） |
@@ -68,7 +69,7 @@
## 6. 对外边界
- 成员可见：`amount`、`money`、渠道、`paid_at`、备注；无逐笔与模型日志的连线
- 成员可见：`amount`、`money`、渠道、`paid_at`、备注、`billing_domain`；**仅本人名下 key 所属账本域内**；无逐笔与模型日志的连线；未标域默认不可见
- 纯用量模式可不登记
## 7. 迁移说明
docs/design/交互设计-key管理.md
+6 -3
View File
@@ -16,6 +16,7 @@
|----|------|------|
| 名称 | `token_name`（上游同步） | 展示名以它为准（上游改名随轮询更新） |
| 归属 | 成员名徽章 / 「未归属」 | 行内下拉可直接改归属（见 §4） |
| 账本域 | `billing_domain` / 「—」 | 行内可编辑（联想输入，防抖落盘）；列表可按域筛，含「未标注」 |
| 状态 | `active` / `disabled` 徽章 | disabled 灰态 |
| 数据截止 | `log_synced_at` | **停滞预警**：落后 > 2 小时 → 该单元格黄色标注「停滞」+ hover 提示「检查引擎日志；若持续 401 请停用」 |
| 累计已用 / 剩余 | `total_used` / `total_available` + `unlimited_quota` 分支 | 「剩余：不限」分支 |
@@ -30,6 +31,7 @@
1. **sk-key 粘贴框**（大号单行，paste 友好）——页脚安全注记：「粘贴后立即加密存储，界面不再回显明文」
2. 归属成员下拉（默认「未归属」，可后改；下拉旁附「+ 新建成员」快捷入口——缝合「开户 → 发令牌 → 开 key」的跨页流程断点，见《交互设计-成员管理》）
2b. 账本域输入（可空，已有值联想；与支付记录的 `billing_domain` 同语义）
3. 提交 → 服务端上游验证，四态反馈：
| 结果 | 反馈 |
@@ -45,10 +47,11 @@
- **启用**：行操作 → 「已启用——下一轮同步（≤5 分钟）将自动验证，结果见数据截止」（无人工预验证环节，引擎即验证器）
- **死亡处置推荐流**（对持续 401 的 key）：数据截止停滞 → 你查看引擎日志确认 → 停用 → 找运营方 → 修复后启用。界面在停滞标注的 hover 中给出这条指引文案（把「引擎记录不决策」的操作闭环写进提示里）
## 4. 归属变更
## 4. 归属 / 账本域变更
- 清单行内下拉直接切换（含「未归属」选项）——即时生效，无确认弹窗（低风险、可逆）
- 变更后统计自动按新归属呈现（行级联查当前归属——表设计 3.8 语义）
- 归属：清单行内下拉直接切换（含「未归属」选项）——即时生效，无确认弹窗（低风险、可逆）
- 账本域：行内联想输入，防抖保存（失焦落盘）；可清空为未标域
- 变更后统计自动按新归属呈现（行级联查当前归属——表设计 3.8 语义）；账本域影响成员支付参数可见性
## 5. 空态
docs/design/交互设计-成员视图.md
+7 -7
View File
@@ -1,12 +1,12 @@
# 交互设计 · 成员视图
> 成员世界——**布局与信息结构对齐管理端**（侧边栏壳 + 页内区块 + 表格优先），内容仍是「我的用量」：名下 key 的调用日志、用量聚合、完全公开透明的支付参数。**R12 的交互落点**（日志行携带所属订阅/充值信息：徽章弹窗 + 行展开调用详情）。页面无任何「应付」概念（分摊哲学裁决）。
> 成员世界——**布局与信息结构对齐管理端**（侧边栏壳 + 页内区块 + 表格优先），内容仍是「我的用量」：名下 key 的调用日志、用量聚合、同账本域内可见的支付参数。**R12 的交互落点**（日志行携带所属订阅/充值信息：徽章弹窗 + 行展开调用详情）。页面无任何「应付」概念（分摊哲学裁决）。
| 项目 | 内容 |
|------|------|
| 状态 | 定稿（2026-10-09，作者认可布局重写） |
| 关联 | 《交互设计-总览与共性》（数值呈现、时间选择器、响应式）·《交互设计-调用日志》（明细表列语义同构参照）· R12（裁决记录）· `members表字段设计.md`（令牌）· `usage_logs表字段设计.md`（来源提列）· `subscriptions` / `topups` 表字段设计（参数数据源）·《API契约-成员视图》 |
| 数据 | 名下 key 的 `usage_logs` 聚合与明细 · 相关 `subscriptions` / `topups`（完全可见） |
| 数据 | 名下 key 的 `usage_logs` 聚合与明细 · 相关 `subscriptions` / `topups`（同账本域内可见） |
| 前置 | 经登录壳（令牌）进入；**侧边栏布局**（与管理端同构，菜单与数据不同） |
---
@@ -32,11 +32,11 @@
|------|------|-----------|-----------|
| 总览 | 成员总览 | 该时段用量与名下 key 全景 | **是** |
| 调用日志 | 调用明细 | 名下 key 的模型请求流水 | |
| 支付参数 | 支付参数 | 订阅 / 充值登记参数（完全公开） | |
| 支付参数 | 支付参数 | 订阅 / 充值登记参数（同账本域内可见） | |
顺序逻辑：先看汇总 → 查事实（流水）→ 对参数（支付）——与管理端「总览 → 对象 → 事实」同型，体量收成三项。
**时间范围全局共享**：三页共用同一对账窗口——切页保留当前范围（菜单带 `from/to`），任一页改范围即全局生效；URL 可深链。支付参数页的「该时段涉及」：订阅看期间重叠 ∪ 进行中，充值看 `paid_at`。
**时间范围全局共享**：三页共用同一对账窗口——切页保留当前范围（菜单带 `from/to`），任一页改范围即全局生效；URL 可深链。支付参数页的「该时段涉及」：订阅 = 涉及我日志的 `subscription_id` ∪ 我域内进行中；充值 = 我域内且 `paid_at` 落在窗口内。
**数据刷新心智**：**仅总览**作看板自动刷新（约 60s）；调用日志 / 支付参数为查询台，**不主动轮询**（改条件或手动重试才拉）；相对时间窗在选定后定格，避免每分钟打穿缓存。
@@ -113,11 +113,11 @@
## 5. 支付参数页
完全公开透明的落点——**订阅权益 + 充值入账**两组清单（Tab 或上下两节），参数原貌成表。
同账本域内可见的落点——**订阅权益 + 充值入账**两组清单（Tab 或上下两节），参数原貌成表。
### 5.1 页头
`PageHeader`「支付参数」+ 副文案「订阅与充值的登记参数 · 对成员完全公开」；右侧时间范围（全局共享窗口）。
`PageHeader`「支付参数」+ 副文案「订阅与充值的登记参数 · 同账本域内可见」；右侧时间范围（全局共享窗口）。
### 5.2 订阅表
@@ -139,7 +139,7 @@
| 派生额度 | `amount × qpu` + $（展示） |
| 备注 | `remark` |
- 脚注：「支付参数对成员完全公开；币种由成员与作者约定」——透明裁决的界面声明
- 脚注：「支付参数在你所属账本域内公开；币种由成员与作者约定」——透明裁决的界面声明（同域透明、跨域隔离）
- **不出现**任何派生金额：无「折合人民币」、无「占比 × 金额」、无「应付」
- 空态（纯用量模式）：中性文案「暂无支付记录信息」——**不设行动引导**
docs/design/交互设计-支付记录.md
+3 -2
View File
@@ -50,13 +50,14 @@
| 交易号 / 渠道 | `trade_no` · `payment_method` / `payment_provider` |
| 派生额度 | `amount × qpu` + $（展示，不入库） |
| 备注 / 登记 | `remark` · `created_at` |
| 账本域 | `billing_domain`（可空；列表可按域筛，含「未标注」） |
| 操作 | 编辑 / 删除 |
## 4. 登记表单（分 Tab，不再 `kind` 切换）
**订阅**：订阅 ID · 期间起止（结束可空）· 额度（quota / 美元双输入）· 付款金额（可空）· 付款时间（可空）· 备注 · **「从平台选用」**（辅助登录 → 订阅列表）
**订阅**：订阅 ID · 期间起止（结束可空）· 额度（quota / 美元双输入）· 付款金额（可空）· 付款时间（可空）· 账本域（可空，已有值联想）· 备注 · **「从平台选用」**（辅助登录 → 订阅列表）
**充值**：时间 `paid_at`（必填）· `amount`（必填）· `money`（必填）· 交易号 / 渠道（可空）· 备注 · **「从平台选用」**（辅助登录 → 充值单分页列表）；**无「换得额度」输入框**（派生）
**充值**：时间 `paid_at`（必填）· `amount`（必填）· `money`（必填）· 交易号 / 渠道（可空）· 账本域（可空，已有值联想）· 备注 · **「从平台选用」**（辅助登录 → 充值单分页列表）；**无「换得额度」输入框**（派生）
### 4.1 选用弹层（订阅 / 充值同规则）
docs/design/需求清单.md
+2 -2
View File
@@ -56,7 +56,7 @@
| # | 需求 | 说明 | 状态 |
|---|------|------|------|
| R11 | 平台身份体系与鉴权 | 访问主体 = 作者 + 成员（运营方完全信任，不设身份）。**成员身份与管理面鉴权均已裁决**（2026-09-29，见裁决记录） | **已裁决**（2026-09-29） |
| R12 | 成员自助视图 | 令牌进成员视图：**名下 key 的模型调用日志**——每条记录额外携带所属订阅/充值的信息（具体携带形态待核查后设计）+ 用量聚合（quota / 美元，按来源分解）；**完全公开透明**（订阅与支付参数对成员可见）；无「应付」概念（分摊是社交层问题）；登录壳交互（输令牌 → sessionStorage，关标签失效） | **已裁决**（2026-09-29） |
| R12 | 成员自助视图 | 令牌进成员视图：**名下 key 的模型调用日志**——每条记录额外携带所属订阅/充值的信息（具体携带形态待核查后设计）+ 用量聚合（quota / 美元，按来源分解）；支付参数**同账本域内可见**（同域透明、跨域隔离；未标域默认藏，详见各表 `billing_domain` 与《API契约-成员视图》§5）；无「应付」概念（分摊是社交层问题）；登录壳交互（输令牌 → sessionStorage，关标签失效） | **已裁决**（2026-09-29；2026-10-13 补账本域可见性） |
| R16 | 成员档案维护与空壳删除 | **修改**：开户后可改 `name` / `remark`（误建、挂 key 前改名等真实场景）；`status` 走启停、令牌走重发，不并入档案编辑。**删除**：仅当**当前无任何 key 归属**（`key_count = 0`）才允许硬删——清理空壳，不触碰账本事实；名下有 key 只能停用（软删除语义不变） | **已裁决**（2026-10-10） |
## 5. 交付域（已裁决）
@@ -137,7 +137,7 @@
- **支付记录**（订阅与充值同构）：支付金额 ↔ 额度的**比率关系**——**币种无关**（系统不预设人民币或其他币种，币种是使用者之间的约定）；订阅与充值两类支付事件统一建模（表结构与命名随 R15）
- **计费来源标注为一等维度**：`billing_source`（订阅 / 充值）随日志解析存储；按来源 / 成员 / key / 模型的任意时段多维聚合
- **充值登记**（R7 重定义）：与订阅同构——不做充值用量的金额分摊（原「池子加权平均」方案裁撤）
- **成员视角（R12 形态修正）**：名下 key 的模型调用日志，**每条记录额外携带所属订阅/充值的信息**（具体携带形态待核查后设计）、**完全公开透明**（订阅与支付参数对成员可见）、无「应付」概念
- **成员视角（R12 形态修正）**：名下 key 的模型调用日志，**每条记录额外携带所属订阅/充值的信息**（具体携带形态待核查后设计）、支付参数**同账本域内可见**、无「应付」概念
### 2026-10-01 · R15 审阅定稿