docs(billing): 固化计费闭环决策与迁移基础
新增 ADR-002、计费流程说明和 0069 增量迁移，建立独立计费状态、结算 Outbox、显式免费与钱包约束。历史成功未扣费任务仅进入人工复核，不执行追扣。\n\n验证：迁移安全验证与 tests/ci/migrations-test.sh 通过。
This commit is contained in:
@@ -0,0 +1,165 @@
|
||||
ALTER TABLE gateway_tasks
|
||||
ADD COLUMN IF NOT EXISTS billing_version text NOT NULL DEFAULT 'effective-pricing-v2',
|
||||
ADD COLUMN IF NOT EXISTS billing_status text NOT NULL DEFAULT 'not_started',
|
||||
ADD COLUMN IF NOT EXISTS billing_currency text NOT NULL DEFAULT 'resource',
|
||||
ADD COLUMN IF NOT EXISTS pricing_snapshot jsonb NOT NULL DEFAULT '{}'::jsonb,
|
||||
ADD COLUMN IF NOT EXISTS request_fingerprint text,
|
||||
ADD COLUMN IF NOT EXISTS idempotency_key_hash text,
|
||||
ADD COLUMN IF NOT EXISTS reservation_amount numeric(38, 9) NOT NULL DEFAULT 0,
|
||||
ADD COLUMN IF NOT EXISTS execution_token uuid,
|
||||
ADD COLUMN IF NOT EXISTS execution_lease_expires_at timestamptz,
|
||||
ADD COLUMN IF NOT EXISTS billing_updated_at timestamptz,
|
||||
ADD COLUMN IF NOT EXISTS billing_settled_at timestamptz;
|
||||
|
||||
ALTER TABLE gateway_tasks
|
||||
ADD CONSTRAINT gateway_tasks_billing_status_v2_check CHECK (
|
||||
billing_status IN (
|
||||
'not_started', 'pending', 'processing', 'settled', 'released',
|
||||
'retryable_failed', 'manual_review', 'not_required'
|
||||
)
|
||||
) NOT VALID,
|
||||
ADD CONSTRAINT gateway_tasks_reservation_amount_v2_check CHECK (reservation_amount >= 0) NOT VALID;
|
||||
|
||||
CREATE UNIQUE INDEX IF NOT EXISTS uniq_gateway_tasks_idempotency_hash_v2
|
||||
ON gateway_tasks(user_id, idempotency_key_hash)
|
||||
WHERE idempotency_key_hash IS NOT NULL;
|
||||
|
||||
CREATE INDEX IF NOT EXISTS idx_gateway_tasks_execution_lease_v2
|
||||
ON gateway_tasks(status, execution_lease_expires_at)
|
||||
WHERE status = 'running';
|
||||
|
||||
CREATE INDEX IF NOT EXISTS idx_gateway_tasks_billing_status_v2
|
||||
ON gateway_tasks(billing_status, billing_updated_at, created_at);
|
||||
|
||||
ALTER TABLE gateway_task_attempts
|
||||
ADD COLUMN IF NOT EXISTS pricing_snapshot jsonb NOT NULL DEFAULT '{}'::jsonb,
|
||||
ADD COLUMN IF NOT EXISTS request_fingerprint text,
|
||||
ADD COLUMN IF NOT EXISTS upstream_submission_status text NOT NULL DEFAULT 'not_submitted',
|
||||
ADD COLUMN IF NOT EXISTS upstream_submission_updated_at timestamptz;
|
||||
|
||||
ALTER TABLE gateway_task_attempts
|
||||
ADD CONSTRAINT gateway_task_attempts_submission_v2_check CHECK (
|
||||
upstream_submission_status IN ('not_submitted', 'submitting', 'response_received')
|
||||
) NOT VALID;
|
||||
|
||||
ALTER TABLE settlement_outbox
|
||||
ADD COLUMN IF NOT EXISTS action text NOT NULL DEFAULT 'settle',
|
||||
ADD COLUMN IF NOT EXISTS amount numeric(38, 9) NOT NULL DEFAULT 0,
|
||||
ADD COLUMN IF NOT EXISTS currency text NOT NULL DEFAULT 'resource',
|
||||
ADD COLUMN IF NOT EXISTS pricing_snapshot jsonb NOT NULL DEFAULT '{}'::jsonb,
|
||||
ADD COLUMN IF NOT EXISTS locked_by text,
|
||||
ADD COLUMN IF NOT EXISTS lock_token uuid,
|
||||
ADD COLUMN IF NOT EXISTS locked_at timestamptz,
|
||||
ADD COLUMN IF NOT EXISTS last_error_code text,
|
||||
ADD COLUMN IF NOT EXISTS last_error_message text,
|
||||
ADD COLUMN IF NOT EXISTS completed_at timestamptz,
|
||||
ADD COLUMN IF NOT EXISTS manual_review_reason text;
|
||||
|
||||
ALTER TABLE settlement_outbox
|
||||
ADD CONSTRAINT settlement_outbox_action_v2_check CHECK (action IN ('settle', 'release')) NOT VALID,
|
||||
ADD CONSTRAINT settlement_outbox_status_v2_check CHECK (
|
||||
status IN ('pending', 'processing', 'retryable_failed', 'completed', 'manual_review')
|
||||
) NOT VALID,
|
||||
ADD CONSTRAINT settlement_outbox_amount_v2_check CHECK (amount >= 0) NOT VALID;
|
||||
|
||||
CREATE INDEX IF NOT EXISTS idx_settlement_outbox_claim_v2
|
||||
ON settlement_outbox(status, next_attempt_at, created_at)
|
||||
WHERE status IN ('pending', 'retryable_failed');
|
||||
|
||||
CREATE INDEX IF NOT EXISTS idx_settlement_outbox_stale_v2
|
||||
ON settlement_outbox(status, locked_at)
|
||||
WHERE status = 'processing';
|
||||
|
||||
ALTER TABLE model_pricing_rules
|
||||
ADD COLUMN IF NOT EXISTS is_free boolean NOT NULL DEFAULT false;
|
||||
|
||||
ALTER TABLE model_pricing_rules
|
||||
ADD CONSTRAINT model_pricing_rules_explicit_free_v2_check CHECK (
|
||||
base_price > 0 OR (base_price = 0 AND is_free)
|
||||
) NOT VALID;
|
||||
|
||||
ALTER TABLE gateway_wallet_accounts
|
||||
ADD CONSTRAINT gateway_wallet_nonnegative_frozen_v2_check CHECK (frozen_balance >= 0) NOT VALID,
|
||||
ADD CONSTRAINT gateway_wallet_balance_covers_frozen_v2_check CHECK (balance >= frozen_balance) NOT VALID;
|
||||
|
||||
ALTER TABLE gateway_wallet_transactions
|
||||
ADD CONSTRAINT gateway_wallet_transactions_account_restrict_v2
|
||||
FOREIGN KEY (account_id) REFERENCES gateway_wallet_accounts(id) ON DELETE RESTRICT NOT VALID;
|
||||
|
||||
UPDATE gateway_tasks task
|
||||
SET billing_status = 'not_required',
|
||||
billing_updated_at = now()
|
||||
WHERE task.run_mode <> 'production'
|
||||
OR task.gateway_user_id IS NULL;
|
||||
|
||||
UPDATE gateway_tasks task
|
||||
SET billing_status = 'settled',
|
||||
billing_currency = COALESCE(NULLIF(task.billing_summary->>'currency', ''), 'resource'),
|
||||
billing_updated_at = now(),
|
||||
billing_settled_at = COALESCE(task.finished_at, task.updated_at)
|
||||
WHERE task.status = 'succeeded'
|
||||
AND EXISTS (
|
||||
SELECT 1
|
||||
FROM gateway_wallet_transactions transaction
|
||||
WHERE transaction.reference_type = 'gateway_task'
|
||||
AND transaction.reference_id = task.id::text
|
||||
AND transaction.transaction_type = 'task_billing'
|
||||
);
|
||||
|
||||
UPDATE gateway_tasks task
|
||||
SET billing_status = 'manual_review',
|
||||
billing_currency = COALESCE(NULLIF(task.billing_summary->>'currency', ''), 'resource'),
|
||||
billing_updated_at = now()
|
||||
WHERE task.status = 'succeeded'
|
||||
AND task.run_mode = 'production'
|
||||
AND task.gateway_user_id IS NOT NULL
|
||||
AND NOT EXISTS (
|
||||
SELECT 1
|
||||
FROM gateway_wallet_transactions transaction
|
||||
WHERE transaction.reference_type = 'gateway_task'
|
||||
AND transaction.reference_id = task.id::text
|
||||
AND transaction.transaction_type = 'task_billing'
|
||||
);
|
||||
|
||||
INSERT INTO settlement_outbox (
|
||||
task_id, event_type, action, amount, currency, payload, status, next_attempt_at
|
||||
)
|
||||
SELECT task.id,
|
||||
'task.billing.release',
|
||||
'release',
|
||||
transaction.amount,
|
||||
account.currency,
|
||||
jsonb_build_object(
|
||||
'taskId', task.id,
|
||||
'reservationIdempotencyKey', transaction.idempotency_key,
|
||||
'classification', 'historical_terminal_reservation'
|
||||
),
|
||||
'pending',
|
||||
now()
|
||||
FROM gateway_tasks task
|
||||
JOIN gateway_wallet_transactions transaction
|
||||
ON transaction.reference_type = 'gateway_task'
|
||||
AND transaction.reference_id = task.id::text
|
||||
AND transaction.transaction_type = 'reserve'
|
||||
JOIN gateway_wallet_accounts account ON account.id = transaction.account_id
|
||||
WHERE task.status IN ('failed', 'cancelled')
|
||||
AND COALESCE(transaction.idempotency_key, '') <> ''
|
||||
AND NOT EXISTS (
|
||||
SELECT 1
|
||||
FROM gateway_wallet_transactions release
|
||||
WHERE release.account_id = transaction.account_id
|
||||
AND release.transaction_type = 'release'
|
||||
AND release.idempotency_key = transaction.idempotency_key || ':release'
|
||||
)
|
||||
ON CONFLICT (task_id, event_type) DO NOTHING;
|
||||
|
||||
UPDATE gateway_tasks task
|
||||
SET billing_status = 'pending',
|
||||
billing_updated_at = now()
|
||||
WHERE EXISTS (
|
||||
SELECT 1
|
||||
FROM settlement_outbox outbox
|
||||
WHERE outbox.task_id = task.id
|
||||
AND outbox.action = 'release'
|
||||
AND outbox.status IN ('pending', 'processing', 'retryable_failed')
|
||||
);
|
||||
@@ -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，不回滚数据库增量，也不恢复隐式零价。
|
||||
@@ -0,0 +1,86 @@
|
||||
# ADR-002：计费正确性闭环与即时估价
|
||||
|
||||
## 状态
|
||||
|
||||
Accepted
|
||||
|
||||
## 日期
|
||||
|
||||
2026-07-20
|
||||
|
||||
## 背景
|
||||
|
||||
Gateway 已具备 PostgreSQL 本地钱包、任务冻结、任务扣费和钱包流水，但任务终态与钱包结算分属不同事务。进程在任务成功写入后、扣费前或释放前退出时，可能留下成功未扣费或永久冻结。现有估价只计算首选候选，缺价会退化为普通零价，且文本输出上限和精度规则与正式结算并不完全一致。
|
||||
|
||||
Comfy 的业务流程证明了三项做法有参考价值：任务状态与计费状态分离；计费操作使用独立令牌和过期接管；参数变化后立即生成只读估价。Gateway 不采用 Comfy 的三十分钟虚拟预占、结算时刷新最新价格、公开估价接口和负余额策略，因为这些做法会削弱本地钱包作为唯一账务事实源的约束。
|
||||
|
||||
## 决策
|
||||
|
||||
### 账务事实源与状态
|
||||
|
||||
Gateway PostgreSQL 本地钱包是唯一账务事实源，不与 Comfy 或其他系统双写。任务状态与计费状态独立：生成成功可以处于 `succeeded + pending`，结算失败不得篡改生成结果。
|
||||
|
||||
计费状态为：
|
||||
|
||||
- `not_started`：尚未产生账务动作。
|
||||
- `pending`：结算或释放已进入 Outbox。
|
||||
- `processing`：Worker 已领取账务动作。
|
||||
- `settled`：已幂等扣费并释放冻结。
|
||||
- `released`：失败或取消任务的冻结已释放。
|
||||
- `retryable_failed`：可自动重试。
|
||||
- `manual_review`：上游结果不明或连续失败，需要人工处理。
|
||||
- `not_required`：模拟任务、无本地钱包用户或其他明确无需计费的任务。
|
||||
|
||||
### 统一计价
|
||||
|
||||
估价、提交冻结和最终账单统一使用 `effective-pricing-v2`。规则优先级为平台模型、平台、基准模型；只接受处于生效期内、状态有效、币种为 `resource` 且计算器受支持的规则。普通零价、缺价或失效规则返回 `503 pricing_unavailable`；只有 `isFree=true` 的显式免费规则允许零费用。
|
||||
|
||||
金额决策使用 9 位十进制定点数。文本费用按实际 Token 比例计算，不按千 Token 向上取整；视频以五秒为一个单位向上取整。估价对所有有效候选计算并以最大值作为冻结上限，首选候选费用继续作为 `totalAmount`。
|
||||
|
||||
前端估价是只读提示，不构成价格承诺。正式提交必须重新计价、冻结，并保存不可变计价快照。
|
||||
|
||||
### 结算闭环
|
||||
|
||||
成功 Attempt、任务成功结果、最终金额、计价快照和 `settle` Outbox 在同一个数据库事务写入；失败和取消任务原子写入 `release` Outbox。Worker 使用 `FOR UPDATE SKIP LOCKED` 批量领取，锁超时后允许其他实例接管，并在钱包行锁事务中完成幂等扣费或释放、任务计费状态和 Outbox 完成状态。
|
||||
|
||||
上游提交状态分为 `not_submitted`、`submitting` 和 `response_received`。处于 `submitting` 且结果不明的任务保留冻结并进入人工复核，不自动重试上游。
|
||||
|
||||
### 请求幂等与执行租约
|
||||
|
||||
生成接口可选接受单值 `Idempotency-Key`。数据库只保存键摘要以及规范化请求摘要；同键同请求按协议重放，同键不同请求返回 `409 idempotency_key_reused`，流式重复返回 `409 idempotency_stream_replay_unsupported`。日志和审计记录不得包含原始键或完整请求正文。
|
||||
|
||||
任务由带随机 `execution_token` 的五分钟租约领取，每三十秒续约。运行态更新和终态提交必须匹配令牌，旧 Worker 不得覆盖接管后的新结果。
|
||||
|
||||
## 账务不变量
|
||||
|
||||
1. `balance >= frozen_balance >= 0`。
|
||||
2. 同一任务和币种最多存在一笔有效扣费。
|
||||
3. 一个冻结必须最终被结算消费或释放，不能同时发生两者。
|
||||
4. 正式任务缺价时不得调用上游。
|
||||
5. 最终扣费只能使用提交时保存的计价快照，不能读取更新后的价格。
|
||||
6. 估价不得创建任务、冻结余额或写钱包流水。
|
||||
7. 历史成功未扣费任务只标记人工复核，不自动追扣。
|
||||
|
||||
## 异常矩阵
|
||||
|
||||
| 发生点 | 任务状态 | 计费状态 | 自动动作 |
|
||||
| --- | --- | --- | --- |
|
||||
| 计价失败 | 未创建或失败 | `not_started` | 返回 `pricing_unavailable`，不调用上游 |
|
||||
| 冻结失败 | 已创建 | `not_started` | 返回余额不足，不调用上游 |
|
||||
| 上游提交前失败 | 失败 | `pending` | Outbox 释放冻结 |
|
||||
| 上游提交结果不明 | 运行中或失败 | `manual_review` | 保留冻结，禁止自动重试上游 |
|
||||
| 上游明确失败 | 失败 | `pending` | Outbox 释放冻结 |
|
||||
| 生成成功、结算待执行 | 成功 | `pending` | 返回成功结果，Worker 异步结算 |
|
||||
| 结算暂时失败 | 成功 | `retryable_failed` | 指数退避重试 |
|
||||
| 结算连续失败 | 成功 | `manual_review` | 管理员审计化重试 |
|
||||
|
||||
## 历史数据策略
|
||||
|
||||
迁移只分类，不产生历史补扣：已有任务扣费流水的成功任务标记 `settled`；失败或取消任务的遗留冻结进入释放队列；成功但无扣费流水的生产任务进入 `manual_review`。
|
||||
|
||||
## 后果
|
||||
|
||||
- 成功结果和账务暂时失败可以独立呈现，调用方必须读取 `billingStatus`。
|
||||
- 计价规则编辑器必须要求显式免费，并在规则不可用时阻止生产生成。
|
||||
- 结算具有最终一致性，因此需要积压、延迟、重试和人工复核监控。
|
||||
- 数据库增量在回滚时保留；应用切换到 `hold` 后拒绝新的生产任务，同时继续运行结算 Worker。
|
||||
Reference in New Issue
Block a user