fix: reconcile ambiguous Stripe event ordering

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 的修复镜像。
 
 ### 反向代理