docs(billing): 固化计费闭环决策与迁移基础

新增 ADR-002、计费流程说明和 0069 增量迁移，建立独立计费状态、结算 Outbox、显式免费与钱包约束。历史成功未扣费任务仅进入人工复核，不执行追扣。\n\n验证：迁移安全验证与 tests/ci/migrations-test.sh 通过。
2026-07-20 23:09:18 +08:00
parent dcf5c4f340
commit 01a013c809
3 changed files with 314 additions and 0 deletions
@@ -0,0 +1,63 @@
+# 计费业务流程 v2
+
+## 正常流程
+
+```mermaid
+sequenceDiagram
+  participant UI as 前端
+  participant API as Gateway API
+  participant DB as PostgreSQL
+  participant UP as 上游模型
+  participant BW as 结算 Worker
+
+  UI->>API: 参数变化后的只读估价
+  API->>DB: 读取有效计价规则
+  API-->>UI: 首选预计费用 + 候选最大冻结额
+  UI->>API: 正式提交（可带 Idempotency-Key）
+  API->>DB: 重新计价、保存快照并冻结最大金额
+  API->>DB: 领取执行租约
+  API->>UP: 提交已预处理请求
+  UP-->>API: 成功结果与实际用量
+  API->>DB: 原子写 Attempt、任务成功、最终金额和 settle Outbox
+  API-->>UI: succeeded + billingStatus=pending
+  BW->>DB: SKIP LOCKED 领取 Outbox
+  BW->>DB: 原子扣费、释放冻结、完成 Outbox
+```
+
+## 失败与取消
+
+上游提交前失败、上游明确失败和用户取消均在任务终态事务内写入 `release` Outbox。Worker 使用冻结流水的幂等键释放资金。若上游请求已经进入 `submitting` 但没有可靠响应，系统不得再次提交；任务转人工复核并保留冻结。
+
+## 即时估价
+
+前端仅对影响计费的字段生成稳定签名，包括模型、生成模式、数量、质量、分辨率、时长、音频、参考素材和 Token 上限。签名变化后等待 350ms，取消旧请求，并用递增序号阻止乱序响应覆盖。
+
+界面必须区分：
+
+- 计算中；
+- 显式免费；
+- 正常预计费用与冻结上限；
+- 价格不可用；
+- 估价请求失败。
+
+价格不可用或估价失败时禁止生产生成；模拟模式仍允许执行并显示原因。
+
+## Worker 参数
+
+- 轮询间隔：1 秒。
+- 单批数量：50。
+- 处理锁过期：120 秒。
+- 最大自动尝试：20 次。
+- 退避上限：15 分钟。
+
+这些参数是安全默认值，可通过受控配置调整，但不得改变幂等键、快照和账务不变量。
+
+## 发布与回滚
+
+`BILLING_ENGINE_MODE` 支持：
+
+- `observe`：并行计算并记录差异，不改变旧路径账务结果。
+- `enforce`：启用 v2 缺价拒绝、冻结与结算闭环。
+- `hold`：在调用上游前拒绝新的生产任务，已有 Outbox 继续处理。
+
+发布先运行 24 小时 observe，补齐所有缺价和非法规则，再以 10% 流量启用 enforce，确认没有重复扣费、长期冻结和异常差额后扩大到 100%。回滚只切换到 hold，不回滚数据库增量，也不恢复隐式零价。