feat: add pocketbase dry-run report

docs/refactor/backend-capability-status.md

@@ -158,7 +158,8 @@
 
 | 能力 | 状态 | 说明 |
 | --- | --- | --- |
-| PocketBase schema 分析 | 可联调 | `scripts/import-pocketbase` |
+| PocketBase schema/导出分析 | 可联调 | `scripts/import-pocketbase` 支持 schema summary/risk、`npm run pb:import:dry-run` 导出目录静态迁移报告 |
+| PocketBase JSON dry-run | 可联调 | 不写数据库，检查导出目录、JSON 形态、核心集合、旧 ID、敏感字段、schema relation、未映射集合和关键业务计数 |
 | 题目 JSON preview/import | 可联调 | 后端负责规范化、issue、幂等、审计 |
 | 公共题库采纳、手动同步和自动同步 | 可联调 | 平台授权后，租户可采纳公共题库并复制已发布题目快照；同步 API 和 `public-banks` worker 支持新增/更新题目、重新校验授权、跨租户拒绝、审计记录和租户自改冲突保护；已覆盖跨租户、重复采纳、采纳后组卷、同步新增题、冲突不覆盖和 worker 自动同步测试 |
 | 单词 JSON preview/import | 可联调 | 兼容旧模板 |
@@ -179,6 +180,7 @@ npx supabase db reset
 npm audit --audit-level=high
 npm run check:refactor
 npm run test:readiness
+npm run test:pb:dry-run
 npm run test:worker:imports
 npm run test:worker:crm
 npm run test:worker:commerce

docs/refactor/backend-handoff-roadmap.md

@@ -32,7 +32,7 @@
 | 会员与订单 | 可联调 | 下单、订单详情/状态轮询、优惠券领取/抵扣、零元订单自动开通、手工确认权限保护、激活码预检查/兑换、微信支付、支付宝、微信/支付宝发起退款、微信/支付宝退款查询确认、微信/支付宝退款通知 webhook、支付/退款补偿 worker、权益发放 | 完整资金流水对账、异常订单运营台 |
 | 登录认证 | 可联调 | 短信 mock、阿里云/腾讯云短信 adapter、迁移期 session、Supabase Auth JWT、微信小程序登录、微信网页登录、QQ 登录、手机号绑定/换绑、OAuth 配置表 | 真实生产账号和回调域名联调 |
 | 销售/代理/CRM | 基础完成 | 邀请码、首绑保护、团队关系、销售统计、CRM 入队 | 小程序码真实生成、分佣结算、钉钉/飞书/企微 worker |
-| 内容导入 | 可联调 | 题目、单词、知识手册、分数线、视频 JSON/CSV/Excel preview/import、issue、job、审计、幂等、`executionMode=async`、imports worker、导入后复检、模板下载和字段映射 API | 字段映射 UI、真实数据 dry-run 和导入性能压测 |
+| 内容导入 | 可联调 | 题目、单词、知识手册、分数线、视频 JSON/CSV/Excel preview/import、issue、job、审计、幂等、`executionMode=async`、imports worker、导入后复检、模板下载、字段映射 API、PocketBase JSON dry-run 报告 | 字段映射 UI、真实数据 dry-run 执行验收和导入性能压测 |
 | 数据看板 | 可联调 | 租户 dashboard 聚合接口，收益、注册、学习、内容、激活码、反馈、趋势、24h 活跃、套餐销量和运营动态 | 预聚合 worker、缓存、慢 SQL 监控和销售转化看板 |
 | AI 择校推荐 | 未开始 | 暂无 | 数据上下文、AI JSON schema、报告渲染、PDF 生成 |
 | Taro 前端 | 未开始 | 旧 Web 已有新 API 适配雏形 | `apps/taro`、跨端 API client、H5/小程序页面和端到端测试 |
@@ -77,7 +77,7 @@
 
 - 生产鉴权：API 已支持 Supabase Auth JWT；继续做真实云端 Auth/JWKS 回归、RLS 深测，并在生产关闭 `x-user-id` 与 `x-platform-admin-key` 兼容入口。
 - 对象存储：上传/下载签名已接入阿里云 OSS、腾讯云 COS、Supabase Storage；上传确认、PDF/图片预览签名和 assets worker 复检已完成，继续补 PDF 渲染、视频播放防盗链、杀毒扫描和水印。
-- 真实数据 dry-run：导出 PocketBase 用户、题库、单词、知识手册、分数线、订单、权益，跑迁移和校验报告。
+- 真实数据 dry-run：导出 PocketBase 用户、题库、单词、知识手册、分数线、订单、权益，先跑 `npm run pb:import:dry-run`，再跑迁移和校验报告。
 - 生产环境配置：`.env.example` 和 `npm run readiness:production` / `npm run readiness:production:db` 已补；继续补数据库迁移流程、备份恢复、日志、告警和 API 容器部署说明。
 - Taro scaffold：建立 `apps/taro`，先完成租户解析、首页、题库、背单词、知识手册、个人中心主链路。
 

docs/refactor/content-import-contract.md

@@ -378,6 +378,6 @@ GET /api/tenant-content/imports/post-check?jobId=<jobId>
 
 ## 下一步
 
-- 用真实 PocketBase 全量导出数据做多轮 dry-run，并把复检报告作为上线验收材料。
+- 已补 `npm run pb:import:dry-run` 静态报告工具；拿到真实 PocketBase 全量导出数据后做多轮 dry-run，并把 dry-run 报告、正式导入报告和复检报告作为上线验收材料。
 - 前端补可视化字段映射、模板下载按钮、导入 job 轮询、逐行 issue 展示和复检结果面板。
 - 后续按大租户数据量补导入任务分页预览、抽样校验和导入性能压测。

docs/refactor/implementation-status.md

@@ -15,7 +15,7 @@
 | 旧 PocketBase/React 项目 | `F:\project\参考\旧题库项目` | 保留作为功能参照和迁移来源 |
 | 新 Node API | `F:\project\apps\api` | 已按 `core/features` 分层重构 |
 | Supabase/PostgreSQL 迁移 | `F:\project\supabase\migrations` | 已建立多租户和业务域表 |
-| PocketBase 数据导入 | `F:\project\scripts\import-pocketbase` | 已支持多类旧数据归一化导入与校验 |
+| PocketBase 数据导入 | `F:\project\scripts\import-pocketbase` | 已支持多类旧数据归一化导入、dry-run 报告与校验 |
 | 共享包 | `F:\project\packages\config`、`F:\project\packages\db`、`F:\project\packages\domain` | 已建立基础共享层 |
 | 旧 Web 到新 API 适配 | `F:\project\参考\旧题库项目\src\services\supabaseApi.ts` | 仅作参考；后续应在 `apps/taro` 或共享包中建立新的跨端 API client |
 
@@ -39,7 +39,7 @@
 | 租户后台 | 已建品牌、域名、设置、支付账户、登录 provider、私密密钥表、成员、审计日志、资源台账、导入台账、内容导航台账 | 不适用 | 概览、品牌、设置、域名、支付账户、登录配置、密钥掩码、活动内容、兑换码/优惠券、成员管理、权限矩阵、审计查询、内容入口/分类树/题目集合/练习蓝图维护、资源管理、题目/单词/知识手册/分数线/视频 JSON/CSV/Excel 同步/异步导入已实现 | 核心 API 集成测试含角色/权限/租户隔离/密钥不泄露/导航/组卷/资源与导入断言 | 租户配置与运营闭环可用，前端权限 UI、字段映射操作台和导入复检结果面板待补 |
 | 平台后台 | 已建 SaaS 套餐、订阅、账单、服务费、用量 | 不适用 | 租户管理、账单、收款确认、用量记录、平台管理员 Supabase JWT 鉴权已实现 | API 集成测试 | 平台收费链路骨架可用，平台审计报表/自动计费待补 |
 | 登录认证 | 已建短信验证码、会话、OAuth provider 配置表，并支持 `auth_user_id` 映射 | 旧用户映射已预留 | 短信 mock 登录、迁移期 session、Supabase JWT 验签映射、微信小程序登录主链路、微信网页登录、QQ 登录、手机号绑定/换绑已实现 | API 集成测试 | H5 Supabase Auth 可联调；真实短信/OAuth 生产账号和回调域名联调待补 |
-| 数据导入 | 已建立 importer、risk report、validate | 已覆盖多类旧集合 | 命令行导入/校验 | `pb:import:validate` | 基础工具可用，需用真实完整数据做多轮 dry-run |
+| 数据导入 | 已建立 importer、risk report、dry-run report、validate | 已覆盖多类旧集合 | 命令行 dry-run/导入/校验 | `pb:import:dry-run`、`pb:import:validate` | 基础工具可用，需拿真实完整数据执行多轮 dry-run 和导入回归 |
 | 测试体系 | 不适用 | 不适用 | 不适用 | 已新增核心 API 集成测试、租户隔离测试、权限矩阵测试、资源/题目导入测试、导入校验 | 还不是完整覆盖，支付幂等、真实导入回归、前端端到端测试仍需补 |
 
 ## 已实现 API 范围
@@ -284,7 +284,7 @@ platform-admin:
 
 为了先把旧项目核心业务补齐，再进入支付/短信等商用关键模块，建议按下面顺序继续：
 
-1. 完善内容导入和文件上传：字段映射 UI、真实数据 dry-run、CDN 防盗链、杀毒扫描。
+1. 完善内容导入和文件上传：字段映射 UI、真实数据 dry-run 执行验收、CDN 防盗链、杀毒扫描。
 2. 补公共题库版本通知/冲突操作台、租户套餐地区/科目/题库范围限制、主题模板系统。
 3. 补学习统计增强：排行榜防刷/预聚合、断点续练、专项练习策略和更细题型分析。
 4. 补视频商用控制：深度防盗链、动态水印和播放统计。

docs/refactor/legacy-feature-gap-matrix.md

@@ -98,7 +98,7 @@
 1. 排行榜增强：刷题、模考、背单词、积分排行榜主接口已有；还需防刷、日/周榜预聚合、运营后台排名看板。
 2. 账号设置完整流：绑定/更换手机号基础 API 已完成；仍缺头像上传、微信/QQ 账号合并、密码/邮箱能力。
 3. 题库导出：服务端 JSON/试卷 payload 导出、权限审计和答案脱敏已补；仍缺 PDF/Word 二进制生成、水印、资料发布和后台导出操作台。
-4. 导入扩展：题目/单词/知识手册/分数线/视频已支持 JSON、CSV 和 Excel 预览导入，并可用 `executionMode=async` 进入 imports worker；导入后复检、模板下载和字段映射 API 已补，仍缺前端字段映射 UI 和真实数据 dry-run。
+4. 导入扩展：题目/单词/知识手册/分数线/视频已支持 JSON、CSV 和 Excel 预览导入，并可用 `executionMode=async` 进入 imports worker；导入后复检、模板下载、字段映射 API 和 PocketBase JSON dry-run 报告已补，仍缺前端字段映射 UI 和真实数据执行验收。
 5. 公共题库商业化：平台公共/地区题库授权、租户快照采纳、手动同步、自动同步 worker、冲突查询和租户自改冲突保护已完成基础闭环；还需版本通知、冲突处理操作台和运营后台 UI。
 6. CRM/销售结算：CRM worker、分佣规则、结算单、审核和打款状态基础闭环已完成；仍缺轮询/定向分配、打款导出、凭证和销售结算看板。
 7. 题目反馈增强：处理通知、消息提醒、问题聚合统计和内容修复闭环。
@@ -117,7 +117,7 @@
 
 1. 微信/支付宝支付和 webhook 幂等。
 2. 对象存储 PDF 预览、视频深度防盗链、动态水印。
-3. 字段映射 UI、真实数据 dry-run 和导入复检结果操作台。
+3. 字段映射 UI、真实数据 dry-run 执行验收和导入复检结果操作台。
 4. 数据看板预聚合 worker、销售/代理转化看板和分佣结算。
 5. 公共题库版本通知、冲突处理操作台和租户确认/跳过策略。
 

docs/refactor/local-supabase.md

@@ -109,10 +109,13 @@ PORT=8787
 把 PocketBase 导出的集合 JSON 放到仓库根目录的 `pb_export` 文件夹后执行：
 
 ```bash
+npm run pb:import:dry-run
 npm run pb:import:json
 npm run pb:import:validate
 ```
 
+`pb:import:dry-run` 不写数据库，会先检查 JSON 格式、核心集合、旧 ID、敏感字段、关系断裂和未映射集合。存在 blocker 时先处理问题，不要直接正式导入。
+
 导入真实密钥时必须明确打开开关，且只允许进入 `app_private.tenant_secrets`：
 
 ```bash

docs/refactor/next-development-todo.md

@@ -52,7 +52,7 @@
 
 3. 真实导入 dry-run
    - 从 PocketBase 导出现有用户、题库、单词、知识手册、分数线、订单、权益数据。
-   - 跑 `scripts/import-pocketbase`，生成迁移报告。
+   - 已补 `npm run pb:import:dry-run` 静态迁移报告工具；拿到真实导出后先跑 dry-run，再跑 `pb:import:json` 和 `pb:import:validate`。
    - 对题目 JSON、单词、知识手册、分数线、视频走后端 preview/import API 做二次验证。
 
 4. 部署配置
@@ -78,7 +78,7 @@
 3. 导入体系扩展
    - 已完成题目、单词、知识手册、分数线、视频的 CSV/Excel 到规范 JSON 解析适配。
    - 已完成大批量异步导入 worker、重试、导入后复检和审计。
-   - 模板下载、字段映射 API 和导入后复检已补；继续补字段映射 UI、真实数据 dry-run、导入前抽样校验和复检结果操作台。
+   - 模板下载、字段映射 API、导入后复检和 PocketBase JSON dry-run 报告工具已补；继续补字段映射 UI、真实数据执行验收、导入前抽样校验和复检结果操作台。
 
 4. 题库导出增强
    - 已完成服务端 JSON、`paper_json`、`print_payload` 基础导出和导出 job 台账。

docs/refactor/pocketbase-to-supabase-mapping.md

@@ -67,7 +67,30 @@ pb_export/
   questions.json
 ```
 
-执行导入：
+先执行不写数据库的 dry-run：
+
+```bash
+npm run import:dry-run
+```
+
+根目录也可以执行：
+
+```bash
+npm run pb:import:dry-run
+```
+
+dry-run 会检查：
+
+- 导出目录和 JSON 文件格式。
+- 核心集合是否缺失。
+- 旧记录 `id` 是否缺失或重复。
+- 旧 `pb_schema.json` 中的 relation 是否能在导出数据里找到目标记录。
+- `settings`、`crm_config`、用户资料等位置是否存在敏感字段。
+- 哪些集合当前已有规范化 mapper，哪些集合仍未映射。
+
+存在 `blocker` 时不要执行正式导入；先修导出、补 mapper 或记录业务处理结论。
+
+执行正式导入：
 
 ```bash
 npm run import:json
@@ -82,6 +105,7 @@ npm run import:validate
 根目录也可以执行：
 
 ```bash
+npm run pb:import:dry-run
 npm run pb:import:json
 npm run pb:import:validate
 ```