docs: sync backend handoff roadmap

docs/refactor/README.md

@@ -20,11 +20,12 @@
 - `docs/refactor/architecture.md`：新重构目录边界和工程规范。
 - `docs/refactor/content-import-contract.md`：题目、单词、知识手册导入契约，明确后端校验、旧格式转换和前端职责。
 - `docs/refactor/next-development-todo.md`：后端剩余缺口、Taro 前端接入顺序、上云测试前待办。
+- `docs/refactor/backend-handoff-roadmap.md`：进入 Taro 前端前的后端进度同步、缺口清单和接入路线图。
 
 下一步优先级：
 
-1. 导出 PocketBase 真实数据到 `pb_export/*.json`。
-2. 执行 `npm run pb:import:json` 和 `npm run pb:import:validate`。
-3. 按学生端页面逐步从 PocketBase SDK 切换到 `src/services/supabaseApi.ts`。
-4. 为分数线、视频、Excel/CSV 补齐批量导入，并复用 `content_import_jobs` 管线。
-5. 新建 Taro 学生端时复用同一套租户解析和业务 API，不另起一套后端。
+1. 先按 `docs/refactor/backend-handoff-roadmap.md` 的 P0 清单补齐上云测试和 Taro 主链路所需能力。
+2. 导出 PocketBase 真实数据到 `pb_export/*.json`，执行 `npm run pb:import:json` 和 `npm run pb:import:validate`。
+3. 新建 `apps/taro`，优先接租户解析、首页、题库练习、背单词、知识手册、个人中心。
+4. 为对象存储、分数线、视频、Excel/CSV 补齐 provider/导入能力，并复用 `content_import_jobs` 管线。
+5. 接真实短信、微信/QQ 登录、微信支付/支付宝和 CRM worker，进入商用验收。

docs/refactor/backend-handoff-roadmap.md

@@ -0,0 +1,116 @@
+# 后端进度同步与前端接入路线图
+
+更新时间：2026-06-22
+
+这份文档用于在进入 Taro 前端开发前，快速确认新 Supabase/PostgreSQL 后端已经做到哪里、还缺什么、前端应如何接入，以及后续继续开发的优先级。
+
+## 当前结论
+
+新项目已经不是简单的 PocketBase 字段平移，而是按多租户 SaaS 重新建立了后端边界：
+
+- 平台侧可以管理租户、SaaS 套餐、订阅、账单、服务费和用量。
+- 租户侧可以管理品牌、域名、支付账户、登录配置、私密密钥、活动、兑换码、优惠券、成员权限、审计日志、内容入口、分类树、题目集合、练习蓝图、题目、视频、分数线、单词、知识手册和资料资源。
+- 学生侧已经有题库入口、分类树、题目集合、顺序/随机/全真模拟组卷、答题、错题、收藏、背单词进度、个人中心、分数线、视频、订单、权益、激活码兑换和资料下载的基础 API。
+- 销售/代理/CRM 已经有邀请码、扫码/分享事件、首绑客资保护、团队关系、统计、CRM 配置和入队能力。
+- 旧题库 JSON、单词模板、知识手册嵌套模板已经进入后端 preview/import 管线，由后端负责规范化、校验、幂等、审计和租户隔离。
+
+因此，后端现在已经具备进入 Taro 前端第一阶段联调的基础。需要注意的是，它还不是完整生产交付状态，真实鉴权、对象存储、支付、短信、微信/QQ 登录、异步 worker、真实数据 dry-run 迁移仍需要继续补齐。
+
+## 后端模块进度
+
+| 模块 | 当前状态 | 已经具备 | 上线前还要补 |
+| --- | --- | --- | --- |
+| 多租户底座 | 基础完成 | 租户、域名、品牌、设置、RLS 基础、审计 | Supabase Auth/JWT 替换迁移期请求头，生产 RLS 回归 |
+| 平台后台 | 基础完成 | 租户、套餐、订阅、账单、服务费、用量 | 自动计费、平台审计、公共题库披露策略 |
+| 租户后台 | 基础完成 | 品牌、域名、支付账户、登录配置、密钥掩码、活动、兑换码、优惠券、成员权限 | 自定义角色模板、菜单/模块可见性 UI、字段级权限 |
+| 题库与练习 | 可联调 | 内容入口、任意深度分类、题目集合、顺序/随机/全真模拟蓝图、组卷快照、答题、错题、收藏 | 完整模考交卷报告、专项策略、公题库采纳/授权、Excel 导入 |
+| 背单词 | 可联调 | 单元、单词、进度、收藏、统计、JSON 导入 | 复习算法、每日计划、排行榜、Excel 导入 |
+| 知识手册 | 可联调 | 科目、章节、条目、Markdown 内容、嵌套 JSON 导入 | 富文本资源、版本管理、附件/PDF 关联 |
+| 分数线 | 可联调 | 院校、专业、动态字段、记录、年份、趋势、后台维护 | 批量导入、复杂筛选、AI 择校上下文 |
+| 视频解析 | 部分完成 | 单题视频、批量查询、后台视频绑定 | 会员播放权限、播放次数扣减、签名 URL、防盗链、水印 |
+| 资料下载 | 部分完成 | 资源台账、SVIP 权限校验、上传/下载签名占位 | 阿里云 OSS/腾讯 COS/Supabase Storage 真实签名、PDF 预览 |
+| 会员与订单 | 基础完成 | 下单、手动确认、激活码兑换、权益发放 | 微信支付、支付宝、退款、webhook 验签和幂等 |
+| 登录认证 | 迁移期可用 | 短信 mock、迁移期 session、OAuth 配置表 | 阿里云/腾讯云短信、微信小程序/网页登录、QQ 登录、Supabase Auth |
+| 销售/代理/CRM | 基础完成 | 邀请码、首绑保护、团队关系、销售统计、CRM 入队 | 小程序码真实生成、分佣结算、钉钉/飞书/企微 worker |
+| 内容导入 | 基础完成 | 题目、单词、知识手册 JSON preview/import、issue、job、审计、幂等 | Excel/CSV、分数线、视频导入，大批量异步 worker |
+| 数据看板 | 数据基础具备 | 日统计/收入统计表和部分旧脚本 | 新 API 聚合、24h 活跃、运营动态、题型/科目/套餐看板 |
+| AI 择校推荐 | 未开始 | 暂无 | 数据上下文、AI JSON schema、报告渲染、PDF 生成 |
+| Taro 前端 | 未开始 | 旧 Web 已有新 API 适配雏形 | `apps/taro`、跨端 API client、H5/小程序页面和端到端测试 |
+
+## 前端接入建议
+
+建议新建 `apps/taro`，不要在旧 React Web 上继续堆大量兼容。旧项目继续作为样式、页面和交互参照，真正的新业务调用以 `apps/api` 为准。
+
+前端第一阶段应该先做能跑完整学生链路的页面：
+
+1. 租户启动
+   - 调 `GET /api/tenant/resolve`。
+   - 读取品牌、主题、功能开关、域名/小程序启动参数。
+   - 后续 H5 用域名解析，小程序用租户配置或启动参数解析。
+
+2. 首页与内容入口
+   - 调 `GET /api/catalog/content-entries`。
+   - 展示题库、背单词、知识手册、分数线、资料、会员入口。
+   - 前端不再依赖旧 PocketBase 树字段作为长期模型。
+
+3. 题库练习
+   - 调 `GET /api/catalog/content-nodes`、`GET /api/catalog/question-collections`、`GET /api/catalog/practice-blueprints`。
+   - 调 `POST /api/learning/practice-sessions` 生成顺序、随机、全真模拟题目快照。
+   - 调 `POST /api/learning/answers`、错题、收藏接口完成刷题闭环。
+
+4. 背单词和知识手册
+   - 背单词走 vocabulary units/words/progress/favorites。
+   - 知识手册走 handbook subjects/chapters/entries。
+   - 页面只做展示、搜索、筛选、学习状态提交，最终权限和数据范围以后端为准。
+
+5. 个人中心
+   - 调 `GET /api/profile/me`。
+   - 接会员权益、订单、激活码兑换、错题本、收藏夹、学习统计。
+
+6. 资料、视频和支付
+   - 资料下载、PDF 预览、视频播放必须先请求后端签名或权限检查。
+   - 支付和登录在前端可以先接 mock/迁移期能力，生产再替换真实 provider。
+
+## 后续开发 TODO
+
+### P0：上云测试和前端主链路前必须处理
+
+- 生产鉴权：用 Supabase Auth/JWT 或服务端 session 替换 `x-tenant-id`、`x-user-id`、`x-platform-admin-key`。
+- 对象存储：接入阿里云 OSS、腾讯云 COS 或 Supabase Storage，完成上传、下载、PDF 预览、视频播放签名。
+- 真实数据 dry-run：导出 PocketBase 用户、题库、单词、知识手册、分数线、订单、权益，跑迁移和校验报告。
+- 生产环境配置：补 `.env` 模板、数据库迁移流程、备份恢复、日志、告警和 API 容器部署说明。
+- Taro scaffold：建立 `apps/taro`，先完成租户解析、首页、题库、背单词、知识手册、个人中心主链路。
+
+### P1：商用收费和运营能力
+
+- 微信支付、支付宝、XPay 或实际支付网关 adapter。
+- 支付 webhook 验签、幂等、退款、补偿任务。
+- 阿里云/腾讯云短信、微信小程序登录、微信网页登录、QQ 登录。
+- 公共题库/地区题库授权，租户按 SaaS 套餐购买地区、科目和题库范围。
+- Excel/CSV、分数线、视频批量导入。
+- 视频会员播放次数、播放日志、防盗链、水印。
+- 数据看板 API：收益、注册趋势、答题次数、收入趋势、题型分布、题目总量、套餐销量、24h 活跃。
+
+### P2：企业级体验和增长闭环
+
+- 租户自定义角色、菜单可见、模块可见、字段级权限和权限审计。
+- 三套默认主题、租户主题预览、Logo/图标/分享图配置。
+- CRM worker：钉钉、飞书、企微机器人，轮询/定向分配，失败重试。
+- 销售/代理分佣结算、销售团队看板、客资跟进效果。
+- AI 择校推荐：地区考试数据、学生输入 schema、AI JSON 输出、PDF 报告生成。
+- 性能压测、慢 SQL 审查、备份恢复演练、灰度发布和回滚预案。
+
+## 后端完成判定
+
+后端进入“可支撑前端全面联调”的最低标准：
+
+- `npm run check:refactor` 在本地通过。
+- 使用真实 PocketBase 导出数据完成一次 dry-run，产出问题清单和修复后的二次导入报告。
+- 核心学生链路 API 可以在 Taro H5 和小程序双端跑通：登录、首页、题库、练习、错题、收藏、单词、手册、会员、个人中心。
+- 租户隔离、后台角色权限、资源访问权限、订单权益和内容导入至少有集成测试覆盖。
+
+后端进入“商用生产交付”的最低标准：
+
+- JWT/RLS、短信、登录、支付、对象存储、CRM webhook 都使用真实 provider 或生产可用 adapter。
+- 支付 webhook、导入任务、CRM 推送、资源签名都有幂等和审计。
+- 有生产环境变量模板、部署脚本、备份恢复方案、日志告警、错误追踪和基础压测报告。

docs/refactor/next-development-todo.md

@@ -17,6 +17,10 @@
 - 内容导入：题目、单词、知识手册 JSON 预览、校验、导入、幂等、审计。
 - 本地验证：`npm run check:refactor` 已通过。
 
+当前更适合进入前端联调前阅读的总览文档：
+
+- `docs/refactor/backend-handoff-roadmap.md`
+
 ## 后端待补功能
 
 ### P0 上云测试前必须补齐