test: harden pocketbase dry run readiness

docs/refactor/backend-capability-status.md

@@ -167,7 +167,7 @@
 | 能力 | 状态 | 说明 |
 | --- | --- | --- |
 | PocketBase schema/导出分析 | 可联调 | `scripts/import-pocketbase` 支持 schema summary/risk、`npm run pb:import:dry-run` 导出目录静态迁移报告 |
-| PocketBase JSON dry-run | 可联调 | 不写数据库，检查导出目录、JSON 形态、核心集合、旧 ID、敏感字段、schema relation、未映射集合和关键业务计数 |
+| PocketBase JSON dry-run | 可联调 | 不写数据库，检查导出目录、JSON 形态、核心集合、旧 ID、敏感字段、schema relation、未映射集合和关键业务计数；`--profile=production` 会额外检查生产迁移必需集合和关键字段覆盖率，正式切换建议配合 `--fail-on-warnings` |
 | 题目 JSON preview/import | 可联调 | 后端负责规范化、issue、幂等、审计 |
 | 公共题库采纳、手动同步和自动同步 | 可联调 | 平台授权后，租户可采纳公共题库并复制已发布题目快照；同步 API 和 `public-banks` worker 支持新增/更新题目、重新校验授权、跨租户拒绝、审计记录、租户内容通知和租户自改冲突保护；冲突处理 API 已支持单条/批量采纳平台版本和保留租户本地版本；已覆盖跨租户、重复采纳、采纳后组卷、同步新增题、通知隔离/已读/自动 resolved、冲突不覆盖、单条/批量冲突处理和 worker 自动同步测试 |
 | 单词 JSON preview/import | 可联调 | 兼容旧模板 |

docs/refactor/backend-handoff-roadmap.md

@@ -77,7 +77,7 @@
 
 - 生产鉴权：API 已支持 Supabase Auth JWT、HS256 本地测试和 JWKS/RS256 集成回归；`npm run test:rls` 已补本地运行时 RLS 深测；`npm run smoke:auth:remote` 已补真实云端 Auth/JWKS smoke 命令。继续在预生产/生产执行真实 token 回归和生产数据库 RLS 验收，并在生产关闭 `x-user-id` 与 `x-platform-admin-key` 兼容入口。生产配置 JWKS 时必须同时配置 `AUTH_JWT_ISSUER`。
 - 对象存储：上传/下载签名已接入阿里云 OSS、腾讯云 COS、Supabase Storage；上传确认、PDF/图片预览签名、动态水印上下文、assets worker 复检、内置安全扫描、外部 HTTP scanner 接入层和题库导出 PDF/Word/每日一练 ZIP worker 已完成，继续补视频播放防盗链、真实 AV/内容安全服务联调和转码/CDN 级水印。
-- 真实数据 dry-run：导出 PocketBase 用户、题库、单词、知识手册、分数线、订单、权益，先跑 `npm run pb:import:dry-run`，再跑迁移和校验报告。
+- 真实数据 dry-run：导出 PocketBase 用户、题库、单词、知识手册、分数线、订单、权益，先跑 `npm run pb:import:dry-run -- --profile=production --json --fail-on-warnings`，确认 `migrationReadiness` 的必需集合和关键字段覆盖率通过，再跑迁移和校验报告。
 - 生产环境配置：`.env.example` 和 `npm run readiness:production` / `npm run readiness:production:db` 已补；继续补数据库迁移流程、备份恢复、日志、告警和 API 容器部署说明。
 - Taro scaffold：`apps/taro` 地基已建立；学生端、租户后台、平台后台第一批 H5 页面已接真实 API，学生端已接地区选择、错题/收藏复习、阅读理解/案例分析多小题作答、题目反馈、视频解析、练习/模考报告、收银台、订单详情和售后入口第一版，平台后台关键写操作第一版已接入，租户工作台已接权限驱动模块入口，租户学生运营页已接学生创建/更新、禁用/恢复、批量导入、批量分班、备注和跟进任务第一版，租户内容页已接公共题库采纳/同步、冲突查看、单条/批量采纳平台或保留本地、导入问题、字段模板预览/下载、上传/粘贴预览、字段别名覆盖、同步/异步导入、异步轮询和复检详情第一版，租户设置页已接角色模板创建/编辑/停用、成员绑定模板和权限可见性配置第一版，租户营销中心已接 CRM 配置/队列和分佣结算操作台第一版；下一步补公式图片混排、更细数据范围 UI、平台后台审计增强和小程序兼容验证。
 
@@ -107,7 +107,7 @@
 - `npm run check:refactor` 在本地通过。
 - `npm run test:rls` 在本地通过，且新增租户表的 RLS 动态用例已补齐或有明确豁免说明。
 - `npm run smoke:auth:remote` 在预生产/生产 API 上通过，真实 Supabase JWT 能映射学生、租户管理员和平台管理员，坏 token/错租户上下文被拒绝。
-- 使用真实 PocketBase 导出数据完成一次 dry-run，产出问题清单和修复后的二次导入报告。
+- 使用真实 PocketBase 导出数据完成一次 production dry-run，产出问题清单和修复后的二次导入报告。
 - 核心学生链路 API 可以在 Taro H5 和小程序双端跑通：登录、首页、题库、练习、错题、收藏、单词、手册、会员、排行榜、个人中心。
 - 租户隔离、后台角色权限、资源访问权限、订单权益和内容导入至少有集成测试覆盖。
 

docs/refactor/next-development-todo.md

@@ -67,7 +67,7 @@
 
 3. 真实导入 dry-run
    - 从 PocketBase 导出现有用户、题库、单词、知识手册、分数线、订单、权益数据。
-   - 已补 `npm run pb:import:dry-run` 静态迁移报告工具、strict warning 门禁测试和真实数据迁移验收 runbook；拿到真实导出后先跑 strict dry-run，再跑 `pb:import:json`、`pb:import:validate` 和业务抽样。
+   - 已补 `npm run pb:import:dry-run` 静态迁移报告工具、`--profile=production` 生产迁移门禁、关键集合/关键字段覆盖率检查、strict warning 门禁测试和真实数据迁移验收 runbook；拿到真实导出后先跑 `npm run pb:import:dry-run -- --profile=production --json --fail-on-warnings`，再跑 `pb:import:json`、`pb:import:validate` 和业务抽样。
    - 对题目 JSON、单词、知识手册、分数线、视频走后端 preview/import API 做二次验证。
 
 4. 部署配置
@@ -237,6 +237,6 @@
 2. 继续补 Taro 学生端旧体验：地区选择、刷题答题卡、后端权威断点续练、本地进度恢复、模拟倒计时、主观题后端自评、阅读理解/案例分析多小题、视频播放、反馈、模考报告、逐题复盘、错题/收藏专题、个人中心学习报告、收银台、订单详情、售后入口、题干/解析/知识手册 RichContent 安全渲染、H5 KaTeX 公式渲染、私有资源 ID 题图短签名、背单词卡片学习/发音/收藏练习、资料短签名水印预览/下载确认已接第一版；继续补小程序公式真机验收、题图资源字段化、个人中心任务系统、背单词更细统计、小程序支付容器、分享场景和状态管理。
 3. 补平台后台增强：租户详情/编辑、平台审计报表、自动计费、账单批量操作和更细平台权限点。
 4. 云服务器部署 Supabase/PostgreSQL 和 API，配置对象存储生产环境变量，跑 `check:refactor` 的远程等价测试。
-5. 导出现有 PocketBase 数据，按 `docs/refactor/pocketbase-real-data-migration-runbook.md` 做完整 dry-run、导入演练、校验和抽样验收。
+5. 导出现有 PocketBase 数据，按 `docs/refactor/pocketbase-real-data-migration-runbook.md` 做 production dry-run、导入演练、校验和抽样验收。
 6. 并行补真实登录、真实生产账单格式验收、异常订单运营台、对象存储真实 AV/内容安全服务联调、转码/CDN 级水印/生命周期、题库导出模板精排/操作台、公共题库生产定时调度和失败告警。
 7. 前后端联调通过后，再做支付、权限、数据导入、资料下载、视频播放的商用验收。

docs/refactor/pocketbase-real-data-migration-runbook.md

@@ -84,7 +84,7 @@ npm run pb:import:dry-run
 
 ## 阶段 1：静态 Dry-Run
 
-先运行不写数据库的静态报告：
+先运行不写数据库的静态报告。默认是 `development` profile，适合开发环境快速发现 JSON 形态、关系和敏感字段问题：
 
 ```bash
 npm run pb:import:dry-run
@@ -96,12 +96,22 @@ npm run pb:import:dry-run
 npm run pb:import:dry-run -- --json > migration-dry-run-report.json
 ```
 
-严格模式会把 warning 也作为阻断条件，建议预生产验收和 CI 使用：
+预生产验收、最终切换和 CI 必须使用 `production` profile，并建议同时打开 warning 阻断：
 
 ```bash
-npm run pb:import:dry-run -- --json --fail-on-warnings
+npm run pb:import:dry-run -- --profile=production --json --fail-on-warnings
 ```
 
+也可以用环境变量指定 profile：
+
+```powershell
+$env:PB_DRY_RUN_PROFILE="production"
+npm run pb:import:dry-run -- --json --fail-on-warnings
+Remove-Item Env:\PB_DRY_RUN_PROFILE
+```
+
+`--profile` 只接受 `development` 或 `production`，拼写错误会 fail closed 并返回 blocker，避免正式迁移时误用开发模式。
+
 dry-run 会检查：
 
 - 导出目录是否存在。
@@ -112,12 +122,15 @@ dry-run 会检查：
 - 敏感字段是否出现在旧导出中。
 - 未映射集合是否需要补 mapper。
 - 用户、题目、订单、SVIP、激活码、单词、手册、分数线、视频等业务数量。
+- `production` profile 会额外检查生产迁移必需集合：`users`、`questions`、`subjects`、`categories`、`orders`、`svip_plans`、`codes`、`vocabulary_units`、`vocabulary`、`handbook_subjects`、`handbook_chapters`、`handbook_entries`。
+- `migrationReadiness.criticalFieldCoverage` 会统计关键字段覆盖率，例如 `users.phone`、`questions.subjectId/categoryId/content`、`orders.userId/planId/status`、`codes.code`、单词和手册的归属字段；生产模式下低于阈值会变成 blocker。
 
 准入标准：
 
 - `blockers = 0`。
 - 正式切换前建议 `warnings = 0`；如确有历史脏数据，需要记录处理结论、影响范围和接受人。
 - `businessCounts` 与旧后台统计口径差异必须能解释。
+- 生产切换前 `migrationProfile` 必须是 `production`，且 `migrationReadiness.requiredCollections` 不能有缺失或记录数不足。
 
 ## 阶段 2：正式导入演练
 
@@ -217,7 +230,7 @@ npm run dev:api
 1. 公告维护窗口。
 2. 旧 PocketBase 进入只读或暂停写入。
 3. 导出最终 JSON。
-4. 执行 strict dry-run。
+4. 执行 production strict dry-run。
 5. 重置目标生产库或清理目标租户迁移数据。
 6. 执行正式导入。
 7. 执行 `pb:import:validate` strict 模式。
@@ -240,11 +253,10 @@ npm run dev:api
 
 满足以下条件后，才建议进入生产切换：
 
-- `npm run pb:import:dry-run -- --json --fail-on-warnings` 通过，或全部 warning 有签字确认的处理结论。
+- `npm run pb:import:dry-run -- --profile=production --json --fail-on-warnings` 通过，或全部 warning 有签字确认的处理结论。
 - `npm run pb:import:validate` 无 FAIL；生产切换前 strict 模式无 WARN，或 WARN 已确认。
 - 核心业务抽样通过，尤其是题目答案解析、会员权益、订单支付、错题收藏、资料视频权限。
 - `npm run readiness:production` 和 `npm run readiness:production:db` 通过。
 - API/Taro 三端核心链路在迁移数据上跑通。
 - 对象存储、短信、OAuth、支付、CRM webhook 使用生产 provider 或明确标记为暂不开启。
 - 已准备数据库备份、旧系统快照、回滚步骤和负责人。
-