fix: reconcile ambiguous Stripe event ordering

docs/billing.md

@@ -130,14 +130,18 @@ RETURNING used_units;
 - `payments.provider_payment_id` ↔ Stripe `payment_intent.id`（或 charge id，按实现选）
 
 ### 4.2 Checkout / Portal
-- Checkout：后端创建 Stripe Checkout Session，前端跳转 `checkout_url`。
+- Checkout：后端按用户行锁串行创建 Stripe Checkout Session，前端跳转 `checkout_url`。服务端使用稳定 Customer 幂等键和待支付记录 ID 对应的 Session 幂等键，不依赖客户端 `Idempotency-Key`。
+- 每个用户只能映射一个非空 Stripe Customer，同时只能存在一个未过期待支付记录和一个未取消 Stripe 订阅。并发请求复用同一 Session；Customer 映射未持久化时禁止返回或创建 Session。
+- 已有未取消 Stripe 订阅的用户不能再次进入订阅 Checkout，升级、降级、续费和取消统一走 Portal，避免多重周期扣费。
 - Portal：后端创建 Stripe Billing Portal Session，前端跳转管理支付方式/取消订阅。
 
 ### 4.3 Stripe Webhook（商用必须）
 要求：
 - **验签**：使用 `STRIPE_WEBHOOK_SECRET` 校验 `Stripe-Signature`。
 - **事件幂等**：按 `provider_event_id` 去重（落库 `webhook_events`）。
-- **乱序容忍**：订阅对象按 `(event.created, 事件优先级, event.id)` 保存独立水位；`deleted` 即使先到也会保留 tombstone，旧 `created/updated` 不得恢复已取消订阅。
+- **乱序容忍**：订阅对象按 `(event.created, 事件优先级)` 保存独立水位；`deleted` 即使先到也会保留 tombstone，旧 `created/updated` 不得恢复已取消订阅。
+- **同秒歧义**：两个不同事件具有相同 `(event.created, 事件优先级)` 时，不能用不透明的 Event ID 排序，必须从 Stripe 拉取当前订阅快照并以快照响应时间推进水位。
+- **迁移对账**：历史版本用本地 `subscriptions.updated_at` 播种的非终态水位会标记为待对账；API 后台任务持租约获取 Stripe 快照，成功后才清除标记。未映射 Customer 或 Price 的受管订阅事件返回失败并等待重试，不能标记为已处理。
 - **并发一致性**：`subscriptions(provider, provider_subscription_id)` 唯一，订阅业务写入与 `webhook_events=processed` 在同一事务提交。
 - **可重放**：保存原始 payload（脱敏）用于排查。
 

docs/database.md

@@ -310,6 +310,13 @@ CREATE UNIQUE INDEX idx_webhook_events_unique ON webhook_events(provider, provid
 CREATE INDEX idx_webhook_events_status ON webhook_events(status);
 ```
 
+Stripe 运行时还通过迁移维护三组一致性结构：
+- `billing_checkout_sessions` 持久化每用户唯一的待支付 Session 及处理租约，防止并发创建多个 Customer/Session。
+- `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`。
+
 ### 4.8 tasks - 压缩任务
 ```sql
 CREATE TABLE tasks (

docs/deployment.md

@@ -55,15 +55,48 @@ curl --fail http://127.0.0.1:8080/metrics
 
 ### 更新与回滚
 
-更新代码后保留 `.env.production` 和命名卷，重新构建并滚动重建：
+更新代码后保留 `.env.production` 和命名卷。包含迁移 `017`、`018` 的版本不能直接让旧、新 Worker 并行滚动：先备份数据库并停止旧 Worker，再构建新镜像。
+
+迁移 `017` 会在发现重复 Customer 或同用户多条未取消 Stripe 订阅时主动失败。部署前先检查并人工对账，两个查询都必须返回 0 行：
+
+```sql
+SELECT billing_customer_id, COUNT(*)
+FROM users
+WHERE billing_customer_id IS NOT NULL AND billing_customer_id <> ''
+GROUP BY billing_customer_id
+HAVING COUNT(*) > 1;
+
+SELECT user_id, COUNT(*)
+FROM subscriptions
+WHERE provider = 'stripe' AND status <> 'canceled'
+GROUP BY user_id
+HAVING COUNT(*) > 1;
+```
+
+推荐顺序：
 
 ```bash
 git pull --ff-only
+docker compose --env-file .env.production -f docker/docker-compose.prod.yml stop worker
 docker compose --env-file .env.production -f docker/docker-compose.prod.yml build api
-docker compose --env-file .env.production -f docker/docker-compose.prod.yml up -d
+docker compose --env-file .env.production -f docker/docker-compose.prod.yml up -d postgres redis api
+docker compose --env-file .env.production -f docker/docker-compose.prod.yml up -d worker
 ```
 
-生产镜像应使用不可变的 `IMAGEFORGE_TAG`。回滚时把该值改回上一镜像标签，然后再次运行 `up -d`。
+新 API 启动后会消费迁移 `018` 创建的 Stripe 对账队列。启动 Worker 前应确认 API 健康、`STRIPE_SECRET_KEY` 可用且服务器能访问 `STRIPE_API_BASE_URL`；对账可以后台继续，但必须监控失败项：
+
+```sql
+SELECT status, COUNT(*)
+FROM stripe_subscription_reconciliations
+GROUP BY status;
+
+SELECT provider_object_id, reconciliation_reason, updated_at
+FROM provider_object_event_watermarks
+WHERE provider = 'stripe' AND requires_reconciliation = true
+ORDER BY updated_at;
+```
+
+`failed` 会指数退避重试；持续失败通常表示 Stripe 凭据、网络、Customer/Price 映射不完整。上线验收要求 `pending/processing/failed` 最终归零，且 `requires_reconciliation=true` 为 0。生产镜像应使用不可变的 `IMAGEFORGE_TAG`。数据库迁移已应用后，不能只回滚旧二进制；应保留新 schema，并使用兼容该 schema 的修复镜像。
 
 ### 反向代理