feat: establish production SaaS foundation

docs/refactor/import-worker-lease-verification.md

@@ -0,0 +1,42 @@
+# Import worker 持久 lease 验证报告
+
+更新时间：2026-07-12
+
+## 结论
+
+`content_import_jobs` 已具备多实例和进程重启所需的持久 lease 与 fencing 语义。验证只在专用测试库 `127.0.0.1:55432` 执行，没有连接生产环境。
+
+## 实现边界
+
+- migration `202607120016_content_import_job_leases.sql` 增加 `lease_token`、`lease_expires_at`、`last_heartbeat_at`、一致性约束和 pending/expired 部分索引。
+- claim 使用原子 `SKIP LOCKED`，可同时领取 ready pending job 和 lease 已过期的 importing job。
+- 每次 claim 只增加一次 `attempt_count` 并生成新 token；失败调度只写 `next_attempt_at`，不会重复增加 attempt。
+- worker 在执行期间续租；续租、完成、失败和重试都要求 token 匹配且 lease 未过期。
+- API executor 的业务写入和终态更新处于同一事务。fencing 校验失败会回滚题目、版本、集合绑定、item 和 audit 写入。
+- 最后一次 attempt 的 lease 过期后由 claim/reaper 路径直接标记 failed，避免第 `max_attempts + 1` 次执行。
+
+## 动态覆盖
+
+`scripts/import-worker-integration-test.js` 在 destructive-test database guard 后验证：
+
+1. 两个并发 worker 对三个 job 原子 claim，没有重复领取。
+2. 心跳推进 `last_heartbeat_at` 并延长 `lease_expires_at`。
+3. 模拟崩溃后，过期 job 被新 worker 接管，token 旋转且 attempt 从 1 变为 2。
+4. 旧 token 的执行在业务写入前被拒绝，旧 token 的失败提交也不能覆盖新 lease。
+5. 新 lease 可完成 job，终态清空 lease 字段并保持准确 attempt。
+6. retry 保持 pending、持久 `next_attempt_at`，再次 claim 才增加 attempt。
+7. 最后 attempt 过期后进入 failed，不再重新执行。
+
+## 验证命令
+
+```bash
+npm run check:worker
+npm run check:api
+npm run build:worker
+DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:55432/postgres \
+  node scripts/import-worker-integration-test.js \
+  --confirm=SMOKE_SEED_LOCAL_OR_CI_ONLY
+node scripts/production-readiness-check-test.js
+```
+
+完整 worker integration 会先跑 smoke seed；执行时必须明确指向允许 destructive tests 的本地/CI 数据库。