docs: add phase 2 billing review

2026-07-02 16:33:31 +08:00
parent 826f5f685b
commit 3afa5284c7
11 changed files with 151 additions and 24 deletions
@@ -160,7 +160,7 @@ CREATE TABLE exchange_rate (
 );
 ```

-T-102 已实现 `AiModel` / `ModelAlias` 的 Django models、admin、迁移与别名解析。T-103 已补 `AiConfigAuditLog`，admin 里保存/删除模型配置或能力别名时自动写审计日志。T-202 已实现 `PricingRule` / `ExchangeRate` 与 `apps.billing.pricing` 计算函数：定价按 `operation_type + alias + resolution` 查 active 规则，优先 exact resolution，再回退到空 resolution 默认价；缺规则抛 `NoPricingRuleError(code="no_pricing_rule")`。默认别名唯一性由 model validation、admin 与导入器保证；MySQL 不支持通用 partial unique index，后续若要强制数据库层约束可在 T-401 评估触发器或约束表。
+T-102 已实现 `AiModel` / `ModelAlias` 的 Django models、admin、迁移与别名解析。T-103 已补 `AiConfigAuditLog`，admin 里保存/删除模型配置或能力别名时自动写审计日志。T-202 已实现 `PricingRule` / `ExchangeRate` 与 `apps.billing.pricing` 计算函数：定价按 `operation_type + alias + resolution` 查 active 规则，优先 exact resolution，再回退到空 resolution 默认价；缺规则抛 `NoPricingRuleError(code="no_pricing_rule")`。T-203 已实现 `apps.billing.services`：`precharge_call()` 锁 `UserWallet` 行预扣并写 pending 调用与 consume 流水；`mark_call_success()` 确认成功不再改余额；`refund_call_points()` 锁调用记录并幂等退点，写 refund 流水。默认别名唯一性由 model validation、admin 与导入器保证；MySQL 不支持通用 partial unique index，后续若要强制数据库层约束可在 T-401 评估触发器或约束表。

 > 可选增强（接口预留、MVP 不实现）：`account_alias_permission`（按账号授权可用别名，防止调用方点用未授权/昂贵模型）；别名按比例分流到多个模型（灰度/AB/故障转移）。适配器接口需为此留口子。

@@ -260,7 +260,7 @@ CREATE TABLE call_record (
 - `payment_user_id`、`payment_txn_no` 为对账预留，字段先建。
 - `recharge_order.exchange_rate` 与 `points_granted` 在下单时写入，状态为 `pending` 时也必须有值；支付回调金额必须与订单金额一致，入账时不得按新的汇率重算。
 - `call_record.status` 状态机为 `pending -> success / failed`。上游失败退点后仍保持 `failed`，退款流水通过 `points_ledger(change_type=refund, ref_call_id=call_record.id)` 关联，不单独增加 `refunded` 状态，避免调用结果与账务动作混在一个字段里。
- T-201 已落地 `UserWallet` / `ApiKey` 于 `apps.users`，`PointsLedger` / `CallRecord` 于 `apps.billing`；`ref_order_id` 在充值订单模型落地前保持索引化数值引用。
+- T-201 已落地 `UserWallet` / `ApiKey` 于 `apps.users`，`PointsLedger` / `CallRecord` 于 `apps.billing`；T-203 已落地扣点/退点服务；`ref_order_id` 在充值订单模型落地前保持索引化数值引用。

 ## 四、计费时序（核心，务必照此实现）

@@ -350,7 +350,7 @@ CREATE TABLE call_record (

 1. Django + DRF 骨架可运行，django-admin 可登录（Phase 0）。
 2. 移植并跑通一次 AI 调用（标题 / 图片）原型（Phase 1）。
-3. 计费：点数扣减（并发安全）+ 计费规则 + 调用记录（Phase 2）。
+3. 计费：点数扣减（并发安全）+ 计费规则 + 调用记录（Phase 2，T-201~T-203 已完成）。
 4. 对外 API 鉴权 + 余额查询 + 充值回调（验签、幂等）入账（Phase 3）。
 5. 运营后台完善、完整验收、部署（Phase 4）。