fix: make Stripe invoice webhooks monotonic

docs/billing.md

@@ -100,6 +100,7 @@ RETURNING used_units;
 说明：
 - 批量任务的计量仍以“成功文件数”为准；失败文件（含 `QUOTA_EXCEEDED`）不计费。
 - 前端建议在上传前调用 `GET /billing/usage`（登录）或读取配额头（API）做本地提示/拦截。
+- 匿名批量任务先按文件数预留当日额度，终态结算只退还失败或未完成文件。未提供 `compression_rate` 属于正常压缩并计量；只有显式 `compression_rate=100`、同格式且无缩放的原样请求免计量。
 
 ---
 
@@ -142,6 +143,7 @@ RETURNING used_units;
 - **乱序容忍**：订阅对象按 `(event.created, 事件优先级)` 保存独立水位；`deleted` 即使先到也会保留 tombstone，旧 `created/updated` 不得恢复已取消订阅。
 - **同秒歧义**：两个不同事件具有相同 `(event.created, 事件优先级)` 时，不能用不透明的 Event ID 排序，必须从 Stripe 拉取当前订阅快照并以快照响应时间推进水位。
 - **迁移对账**：历史版本用本地 `subscriptions.updated_at` 播种的非终态水位会标记为待对账；API 后台任务持租约获取 Stripe 快照，成功后才清除标记。未映射 Customer 或 Price 的受管订阅事件返回失败并等待重试，不能标记为已处理。
+- **发票一致性**：`invoices(provider, provider_invoice_id)` 唯一，发票事件也使用对象水位；新 `invoice.paid` 不会被迟到的旧 `invoice.payment_failed` 回退。同秒同等级事件从 Stripe 获取权威发票快照，未映射 Customer 时返回失败重试。
 - **并发一致性**：`subscriptions(provider, provider_subscription_id)` 唯一，订阅业务写入与 `webhook_events=processed` 在同一事务提交。
 - **可重放**：保存原始 payload（脱敏）用于排查。
 

docs/database.md

@@ -315,7 +315,7 @@ Stripe 运行时还通过迁移维护三组一致性结构：
 - `provider_object_event_watermarks` 以 Stripe `event.created` 和事件等级保存对象水位；同秒同等级的不同事件标记为歧义并触发权威快照，不能按 Event ID 字典序决定先后。
 - `stripe_subscription_reconciliations` 保存历史非因果水位的租约化对账任务，允许多 API 实例用 `FOR UPDATE SKIP LOCKED` 安全消费。
 
-数据库唯一索引同时保证非空 `users.billing_customer_id` 全局唯一、`subscriptions(provider, provider_subscription_id)` 唯一，以及每用户最多一条未取消 Stripe 订阅。部署这些索引前必须先清理存量冲突，具体检查见 `docs/deployment.md`。
+数据库唯一索引同时保证非空 `users.billing_customer_id` 全局唯一、`subscriptions(provider, provider_subscription_id)` 唯一、非空 `invoices(provider, provider_invoice_id)` 唯一，以及每用户最多一条未取消 Stripe 订阅。部署这些索引前必须先清理存量冲突，具体检查见 `docs/deployment.md`。
 
 ### 4.8 tasks - 压缩任务
 ```sql

docs/deployment.md

@@ -55,9 +55,9 @@ curl --fail http://127.0.0.1:8080/metrics
 
 ### 更新与回滚
 
-更新代码后保留 `.env.production` 和命名卷。包含迁移 `017`、`018` 的版本不能直接让旧、新 Worker 并行滚动：先备份数据库并停止旧 Worker，再构建新镜像。
+更新代码后保留 `.env.production` 和命名卷。包含迁移 `017` 至 `019` 的版本不能直接让旧、新 Worker 并行滚动：先备份数据库并停止旧 Worker，再构建新镜像。
 
-迁移 `017` 会在发现重复 Customer 或同用户多条未取消 Stripe 订阅时主动失败。部署前先检查并人工对账，两个查询都必须返回 0 行：
+迁移 `017` 会在发现重复 Customer 或同用户多条未取消 Stripe 订阅时主动失败，迁移 `019` 会在发现同一 Stripe 发票对应多行时主动失败。部署前先检查并人工对账，三个查询都必须返回 0 行：
 
 ```sql
 SELECT billing_customer_id, COUNT(*)
@@ -71,6 +71,12 @@ FROM subscriptions
 WHERE provider = 'stripe' AND status <> 'canceled'
 GROUP BY user_id
 HAVING COUNT(*) > 1;
+
+SELECT provider, provider_invoice_id, COUNT(*)
+FROM invoices
+WHERE provider_invoice_id IS NOT NULL
+GROUP BY provider, provider_invoice_id
+HAVING COUNT(*) > 1;
 ```
 
 推荐顺序：