feat: add vocabulary handbook import pipeline

2026-06-22 00:11:01 +08:00
parent c1159f8745
commit b458317a81
13 changed files with 2448 additions and 186 deletions
--- a/docs/refactor/README.md
+++ b/docs/refactor/README.md
@@ -18,11 +18,13 @@
 - `scripts/import-pocketbase`：PocketBase schema/数据导入工具。
 - `docker-compose.api.yml`、`apps/api/Dockerfile`：本地 Docker API 运行入口。
 - `docs/refactor/architecture.md`：新重构目录边界和工程规范。
+- `docs/refactor/content-import-contract.md`：题目、单词、知识手册导入契约，明确后端校验、旧格式转换和前端职责。
+- `docs/refactor/next-development-todo.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. 为订单、支付、权益开通补齐 API 写入流程和 webhook 幂等处理。
+4. 为分数线、视频、Excel/CSV 补齐批量导入，并复用 `content_import_jobs` 管线。
 5. 新建 Taro 学生端时复用同一套租户解析和业务 API，不另起一套后端。
--- a/docs/refactor/backend-progress.md
+++ b/docs/refactor/backend-progress.md
@@ -15,7 +15,7 @@
  - `referral`：销售/代理邀请码、首绑客资保护、销售统计、团队关系、CRM 队列。
  - `platform-admin`：平台方租户管理、SaaS 套餐、订阅、账单、服务费收款、使用量。
  - `tenant-admin`：租户资料、品牌、公开设置、域名、支付账户、登录 provider、私密密钥掩码、活动内容、激活码批次、优惠券、成员管理、权限矩阵、审计查询。
-  - `tenant-content`：租户后台内容入口、任意深度分类树、考试意向标记、题目集合、练习蓝图、题目、视频、分数线、单词、知识手册、资料资源、题目 JSON 导入维护。
+  - `tenant-content`：租户后台内容入口、任意深度分类树、考试意向标记、题目集合、练习蓝图、题目、视频、分数线、单词、知识手册、资料资源、题目/单词/知识手册 JSON 导入维护。
  - `tenant`：域名/租户解析。
 - `src/services/supabaseApi.ts` 已加入新 API 客户端方法，供旧 Web 逐步替换和后续 Taro 复用。
 - 已新增 `npm run db:smoke-seed`，用于 `supabase:reset` 后恢复最小烟测数据。
@@ -93,6 +93,10 @@ POST /api/tenant-content/assets/sign-upload
 POST /api/tenant-content/assets/sign-download
 POST /api/tenant-content/imports/preview/questions
 POST /api/tenant-content/imports/questions
+POST /api/tenant-content/imports/preview/vocabulary
+POST /api/tenant-content/imports/vocabulary
+POST /api/tenant-content/imports/preview/handbook
+POST /api/tenant-content/imports/handbook
 GET  /api/tenant-content/imports
 GET  /api/tenant-content/imports/issues
 PUT  /api/tenant-content/videos
@@ -173,11 +177,11 @@ GET  /api/tenant-admin/audit-logs
 - CRM 当前完成配置、密钥入私密表、客资入队和队列查询；真实 webhook 发送、重试、签名在后续 `apps/worker` 中实现。
 - 内容资源当前完成台账、租户后台维护、上传/下载签名占位和学生端 SVIP 下载权限；真实对象存储签名、PDF 预览渲染和防盗链在 provider/worker 中实现。
 - 题库内容导航当前以 `content_entries/content_nodes` 为主模型，可表达“入口 -> 多级分类 -> 院校/专业/学科/销售意向标记”；题目集合和练习方式由 `question_collections/practice_blueprints` 管理，练习 session 会保存当次题目 ID 快照。
- 题目批量导入当前支持 JSON 数组预览、逐行 issue、job/item 台账、执行导入、幂等跳过，并可落到新内容入口、分类节点和题目集合；Excel/CSV、单词/手册/分数线导入会复用同一套 `content_import_jobs` 管线。
+- 批量导入当前支持题目、单词、知识手册 JSON 预览、逐行 issue、job/item 台账、执行导入、幂等跳过，并可落到新内容入口和分类节点。旧单词模板的 `vocabulary_units_示例数据` / `vocabulary_示例数据`、知识手册的书籍/章节/小节/知识点嵌套结构都由后端规范化。Excel/CSV、分数线/视频导入会继续复用同一套 `content_import_jobs` 管线。

 ## 下一步

-1. 完善内容导入和文件上传：Excel/CSV、单词、手册、分数线、视频导入，真实 OSS/COS/Supabase Storage 签名。
+1. 完善内容导入和文件上传：Excel/CSV、分数线、视频导入，真实 OSS/COS/Supabase Storage 签名。
 2. 接入真实短信 provider：阿里云/腾讯云，密钥放 `app_private.tenant_secrets` 或生产 Vault。
 3. 接入真实 OAuth provider：微信网页、微信小程序、QQ，并处理旧 PocketBase 身份映射。
 4. 增加真实支付 provider：XPay、微信支付、支付宝，并完善 webhook 幂等。
--- a/docs/refactor/blueprint-coverage.md
+++ b/docs/refactor/blueprint-coverage.md
@@ -18,10 +18,10 @@
 | 平台超级管理员 | 部分完成 | 租户管理、SaaS 套餐、订阅、账单、服务费收款、用量记录 | 公共题库披露策略、地区/全国套餐权限、平台侧主题模板库、平台审计 |
 | 租户品牌和域名 | 基础完成 | 品牌、Logo、主题 JSON、公开资源、域名、租户公开配置 | 三套默认主题、主题可视化编辑、图标/图片上传 |
 | 租户成员权限 | 基础完成 | owner/admin/operator/teacher/sales/agent/student，权限矩阵，成员启停，审计查询 | 前端权限 UI、自定义角色模板、菜单级可见配置 |
-| 题库内容维护 | 基础完成 | 内容入口、任意深度分类树、院校/专业/学科/销售意向标记、题目集合、顺序/随机/全真模拟练习蓝图、题目录入/更新、题目 JSON 预览/导入、视频绑定、分数线、单词、知识手册后台 API | Excel/CSV 批量导入、公题库采纳/复制/授权、可视化拖拽排序前端 |
+| 题库内容维护 | 基础完成 | 内容入口、任意深度分类树、院校/专业/学科/销售意向标记、题目集合、顺序/随机/全真模拟练习蓝图、题目录入/更新、题目 JSON 预览/导入、视频绑定、分数线、单词、知识手册后台 API | Excel/CSV 批量导入、分数线/视频导入、公题库采纳/复制/授权、可视化拖拽排序前端 |
 | 学生刷题 | 基础完成 | 内容入口、分类树、题目集合、顺序刷题、随机刷题、全真模拟 session 题目快照、答题、错题本、收藏夹 | 完整模考交卷评分报告、专项练习策略、错题复习计划、题型统计深度分析 |
-| 背单词 | 基础完成 | 单词单元、单词、进度、收藏、统计 | 复习算法、每日计划、排行榜 |
-| 知识手册 | 基础完成 | 科目、章节、条目只读与后台维护 | 富文本资源、版本管理、附件/PDF 关联 |
+| 背单词 | 基础完成 | 单词单元、单词、进度、收藏、统计、旧模板/新模板 JSON 预览导入、内容导航绑定 | 复习算法、每日计划、排行榜、Excel 导入 |
+| 知识手册 | 基础完成 | 科目、章节、条目只读与后台维护、书籍/章节/小节/知识点嵌套 JSON 预览导入、内容导航绑定 | 富文本资源、版本管理、附件/PDF 关联、Excel/Markdown 批量解析 |
 | 分数线 | 基础完成 | 字段、院校、专业、记录、趋势、年份 | 复杂动态筛选、批量导入、AI 择校数据上下文 |
 | 视频解析会员 | 部分完成 | 题目视频、批量查询、后台绑定 | SVIP 权限、播放次数扣减、签名 URL、防盗链、水印、播放统计 |
 | 资料下载/PDF | 基础完成 | `content_assets` 资源台账、后台资源管理、上传/下载签名占位、学生端列表、SVIP 下载权限 | 真实 OSS/COS/Supabase Storage 签名、PDF 预览渲染、防盗链、资料前端管理页 |
@@ -36,7 +36,7 @@

 ## 接下来优先级

-1. 完善内容导入和对象存储：Excel/CSV、单词/手册/分数线/视频导入，真实 OSS/COS/Supabase Storage 签名。
+1. 完善内容导入和对象存储：Excel/CSV、分数线/视频导入，真实 OSS/COS/Supabase Storage 签名，JSON 导入异步化。
 2. 公共题库/地区题库授权：平台题库向租户披露、租户采纳、按 SaaS 套餐限制地区。
 3. 完整模考与学习统计：交卷、评分报告、练习历史、正确率趋势、错题复习计划。
 4. 视频会员控制：视频资源签名 URL、防盗链、水印、播放次数和会员权益。
--- a/docs/refactor/content-import-contract.md
+++ b/docs/refactor/content-import-contract.md
@@ -0,0 +1,158 @@
+# 内容导入契约
+
+更新时间：2026-06-21
+
+## 结论
+
+内容导入的最终规范化、校验、租户隔离、幂等和审计必须由后端负责。
+
+前端只负责：
+
+- 上传或粘贴 JSON/Excel/CSV。
+- 做轻量格式预检查，减少明显错误。
+- 展示后端 preview 返回的 `job/items/issues`。
+- 让运营人员修正数据后再确认导入。
+
+迁移脚本只负责：
+
+- 从 PocketBase 导出或旧 JSON 中抽取数据。
+- 转换成新架构推荐格式。
+- 调用后端 preview/import API。
+
+不建议迁移脚本直接绕过后端写业务表，除非是一次性内控迁移，并且必须额外跑导入后校验。
+
+## 已实现导入 API
+
+```text
+POST /api/tenant-content/imports/preview/questions
+POST /api/tenant-content/imports/questions
+
+POST /api/tenant-content/imports/preview/vocabulary
+POST /api/tenant-content/imports/vocabulary
+
+POST /api/tenant-content/imports/preview/handbook
+POST /api/tenant-content/imports/handbook
+
+GET  /api/tenant-content/imports
+GET  /api/tenant-content/imports/issues
+```
+
+所有导入都会写入：
+
+- `content_import_jobs`
+- `content_import_items`
+- `content_import_issues`
+- `audit_logs`
+
+## 单词导入
+
+推荐新格式：
+
+```json
+{
+  "regionId": "uuid",
+  "entryId": "uuid",
+  "contentNodeId": "uuid",
+  "units": [
+    {
+      "legacyId": "unit-1",
+      "name": "Unit 1 - 高频核心词",
+      "description": "专升本考试高频词汇",
+      "order": 1,
+      "words": [
+        {
+          "legacyId": "word-abandon",
+          "word": "abandon",
+          "phonetic": "/əˈbændən/",
+          "meaning": "v. 放弃，抛弃",
+          "example": "He had to abandon his car in the snow.",
+          "exampleTranslation": "他不得不把车丢弃在雪地里。",
+          "difficulty": 3,
+          "tags": ["高频词"],
+          "order": 1
+        }
+      ]
+    }
+  ]
+}
+```
+
+兼容旧模板：
+
+- `vocabulary_units_示例数据`
+- `vocabulary_示例数据`
+
+后端会把旧模板归一化为 `vocabulary_units/vocabulary_words`，并可自动挂到 `content_entries/content_nodes`。
+
+## 知识手册导入
+
+推荐新格式：
+
+```json
+{
+  "regionId": "uuid",
+  "entryId": "uuid",
+  "contentNodeId": "uuid",
+  "subjects": [
+    {
+      "legacyId": "handbook-chinese",
+      "name": "大学语文",
+      "type": "guide",
+      "chapters": [
+        {
+          "legacyId": "chapter-outline",
+          "name": "一、语文考纲",
+          "sections": [
+            {
+              "legacyId": "section-outline",
+              "name": "考纲解读",
+              "entries": [
+                {
+                  "legacyId": "entry-outline",
+                  "title": "2024年天津专升本语文考试大纲",
+                  "summary": "全面解读语文考试要求",
+                  "content": "Markdown 内容",
+                  "tags": ["考纲"]
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+映射规则：
+
+- 手册入口：`content_entries.entry_type = handbook`
+- 书籍/科目：`handbook_subjects`，并生成或绑定一个 `content_nodes`
+- 章节：`handbook_chapters`，并生成章节节点
+- 小节：默认进入 `content_nodes`，作为知识点的目录节点
+- 知识点：`handbook_entries`，通过 `content_node_id` 归属到小节或章节
+
+## 题目导入
+
+题目继续兼容旧题库 JSON 数组格式，并支持 Markdown、KaTeX、图片、表格、阅读理解子题等字段。导入时可以传：
+
+- `subjectId`
+- `categoryId`
+- `entryId`
+- `contentNodeId`
+- `collectionId`
+
+这样题目会同时落到旧兼容表和新内容导航/题目集合。
+
+## 幂等规则
+
+- 优先使用 `legacyId` 作为跨迁移稳定标识。
+- 没有 `legacyId` 时，后端按导入 job 和行号生成内部标识。
+- 相同 `legacyId` 再导入会更新。
+- 内容 hash 未变化时标记为 `skipped`。
+
+## 下一步
+
+- 增加 Excel/CSV 解析入口，但解析后仍进入同一套 preview/import 管线。
+- 增加分数线、视频导入。
+- 增加异步 worker，处理大批量导入、重试和导入后校验。
--- a/docs/refactor/implementation-status.md
+++ b/docs/refactor/implementation-status.md
@@ -4,7 +4,7 @@

 ## 当前结论

-当前重构已经完成了 Supabase/PostgreSQL 多租户底座、核心业务表、PocketBase 数据导入器雏形、学生端核心 API、租户后台 API、平台后台 SaaS 账务 API、内容资产/题目 JSON 批量导入基础闭环、题库入口/任意深度分类/题目集合/练习蓝图/组卷快照基础闭环，以及本地 Docker/API 构建验证。
+当前重构已经完成了 Supabase/PostgreSQL 多租户底座、核心业务表、PocketBase 数据导入器雏形、学生端核心 API、租户后台 API、平台后台 SaaS 账务 API、内容资产/题目/单词/知识手册 JSON 批量导入基础闭环、题库入口/任意深度分类/题目集合/练习蓝图/组卷快照基础闭环，以及本地 Docker/API 构建验证。

 但这还不是完整商用交付状态，也不能说旧项目核心功能已经全部重构完成。现在更准确的状态是：后端商用架构骨架已经立住，核心业务正在按模块补齐。部分功能已经有可调用 API，部分功能只有数据模型和导入映射，部分功能还没有前端/自动化测试闭环。

@@ -28,8 +28,8 @@
 | 错题本 | 已建 `wrong_questions` | 已支持旧错题归一化 | 错题列表、答题自动入错题、移出错题已实现 | 仅烟测 | 基础功能已实现，复习计划和统计未完成 |
 | 收藏夹 | 已建 `favorite_questions` | 已支持旧收藏归一化 | 收藏/取消收藏、收藏列表已实现 | 仅烟测 | 基础功能已实现 |
 | 用户订阅/题库会员/SVIP | 已建 `orders`、`payments`、`entitlements`、`svip_plans`、激活码 | 已映射旧 SVIP/会员权益 | 下单、手动支付确认、激活码兑换、权益查询已实现 | 仅烟测 | 业务骨架可跑，真实微信/支付宝支付和 webhook 未完成 |
-| 背单词 | 已建单词单元、单词、进度、收藏表 | 已支持内容和部分用户状态映射 | 单元/单词只读、进度、收藏、统计、租户后台单词维护 API 已实现 | 核心 API 集成测试 | 学生端基础学习状态和后台单词维护已实现，复习算法和后台统计待完善 |
-| 知识手册 | 已建手册科目、章节、条目 | 已支持内容导入 | 只读 API、租户后台手册科目/章节/条目维护 API 已实现 | 核心 API 集成测试 | 学生端阅读和后台维护基础可用，富文本资源/版本管理待补 |
+| 背单词 | 已建单词单元、单词、进度、收藏表，并可绑定 `content_entries/content_nodes` | 已支持内容和部分用户状态映射 | 单元/单词只读、进度、收藏、统计、租户后台单词维护 API、旧模板/新模板 JSON 预览导入已实现 | 核心 API 集成测试含导入断言 | 学生端基础学习状态、后台维护和批量 JSON 导入已实现，复习算法和后台统计待完善 |
+| 知识手册 | 已建手册科目、章节、条目，并可绑定 `content_entries/content_nodes` | 已支持内容导入 | 只读 API、租户后台手册科目/章节/条目维护 API、嵌套 JSON 预览导入已实现 | 核心 API 集成测试含导入断言 | 学生端阅读、后台维护和批量 JSON 导入基础可用，富文本资源/版本管理待补 |
 | 分数线 | 已建院校、专业、字段、记录表 | 已支持导入映射 | 字段、院校、专业、记录、趋势、年份、租户后台维护 API 已实现 | 核心 API 集成测试 | 查询和后台维护基础闭环已实现，复杂动态筛选/批量导入待补 |
 | 题目视频讲解 | 已建 `video_explanations`、`question_videos` | 已支持导入映射 | 单题视频、批量预加载、通用视频搜索、租户后台视频创建绑定 API 已实现 | 核心 API 集成测试 | 播放数据和后台绑定链路已实现，会员权限、签名 URL、播放统计待补 |
 | 资料下载/PDF | 已扩展 `content_assets`，新增资源台账和导入任务表 | 旧 `app_assets/images` 兼容导入 | 租户后台资源管理、上传/下载签名占位、学生端资料列表/下载权限已实现 | 核心 API 集成测试含 SVIP 资料下载 | 资料资源基础闭环可跑，真实 OSS/COS 签名、PDF 预览渲染、资料下载前端待补 |
@@ -134,6 +134,10 @@ tenant-content:
  POST  /api/tenant-content/assets/sign-download
  POST  /api/tenant-content/imports/preview/questions
  POST  /api/tenant-content/imports/questions
+  POST  /api/tenant-content/imports/preview/vocabulary
+  POST  /api/tenant-content/imports/vocabulary
+  POST  /api/tenant-content/imports/preview/handbook
+  POST  /api/tenant-content/imports/handbook
  GET   /api/tenant-content/imports
  GET   /api/tenant-content/imports/issues
  GET   /api/tenant-content/videos
@@ -237,7 +241,7 @@ platform-admin:
 1. 正式鉴权：迁移期 `x-tenant-id`、`x-user-id`、`x-platform-admin-key` 要替换为 Supabase Auth/JWT/服务端 session，并逐表验证 RLS。
 2. 国内能力接入：短信、微信登录、微信小程序登录、QQ 登录、微信支付、支付宝支付的租户级配置入口已具备，但真实 provider adapter、回调验签和 webhook 幂等仍需实现。
 3. 核心缺口 API：学生端个人中心、分数线、题目视频详情、背单词进度/收藏已补基础 API；下一步重点是后台维护、权限、统计和真实业务验收。
-4. 后台能力：题库录入、JSON 批量导入、资源台账、视频绑定、知识手册维护、分数线维护、品牌/商户/登录/活动/兑换码配置、销售客资、CRM 队列、成员权限、审计查询已补 API；Excel 导入、真实对象存储签名和前端操作台待补。
+4. 后台能力：题库录入、题目/单词/知识手册 JSON 批量导入、资源台账、视频绑定、知识手册维护、分数线维护、品牌/商户/登录/活动/兑换码配置、销售客资、CRM 队列、成员权限、审计查询已补 API；Excel 导入、分数线/视频导入、真实对象存储签名和前端操作台待补。
 5. 自动化测试：已建立核心 API、租户隔离、权限矩阵、后台维护、资源/导入集成测试；仍需真实数据导入回归、支付幂等、前端端到端测试。
 6. Taro 前端：建立 `apps/taro` 或等价跨端应用，把 H5 和小程序统一走同一套 API client。
 7. 运维交付：生产环境变量、备份恢复、日志监控、异常告警、数据库迁移流程、灰度发布、回滚预案。
@@ -246,7 +250,7 @@ platform-admin:

 为了先把旧项目核心业务补齐，再进入支付/短信等商用关键模块，建议按下面顺序继续：

-1. 完善内容导入和文件上传：Excel/CSV、单词、手册、分数线、视频导入，接真实 OSS/COS/Supabase Storage 签名。
+1. 完善内容导入和文件上传：Excel/CSV、分数线、视频导入，接真实 OSS/COS/Supabase Storage 签名，并把 JSON 导入扩展为异步 worker。
 2. 补地区/公共题库披露策略、租户套餐地区限制、主题模板系统。
 3. 补学习统计：练习历史、正确率趋势、错题复习计划、单词复习算法。
 4. 补视频商用控制：SVIP 权限、签名 URL、防盗链、水印、播放次数扣减。
--- a/docs/refactor/next-development-todo.md
+++ b/docs/refactor/next-development-todo.md
@@ -0,0 +1,170 @@
+# 后续开发 TODO
+
+更新时间：2026-06-22
+
+## 当前后端基线
+
+后端已经完成可本地验证的商用 SaaS 骨架：
+
+- Supabase/PostgreSQL 多租户 schema、RLS、索引、触发器。
+- Node.js API 分层：`core/features`。
+- 学生端核心 API：题库、练习、答题、错题、收藏、背单词、知识手册、分数线、视频、资料、订单、权益、个人中心。
+- 租户后台 API：品牌、域名、设置、支付账户、登录 provider、私密密钥、活动、激活码、优惠券、成员权限、审计、内容管理。
+- 平台后台 API：租户、SaaS 套餐、订阅、账单、服务费收款、用量。
+- 销售/代理/CRM 增长链路：邀请码、扫码事件、首绑保护、团队、统计、CRM 队列。
+- 内容导航：`content_entries/content_nodes` 支持任意深度入口和分类。
+- 练习组卷：`question_collections/practice_blueprints` 支持顺序、随机、全真模拟快照。
+- 内容导入：题目、单词、知识手册 JSON 预览、校验、导入、幂等、审计。
+- 本地验证：`npm run check:refactor` 已通过。
+
+## 后端待补功能
+
+### P0 上云测试前必须补齐
+
+1. 生产鉴权
+   - 用 Supabase Auth/JWT 或服务端 session 替换迁移期 `x-tenant-id`、`x-user-id`、`x-platform-admin-key`。
+   - 校验平台管理员、租户管理员、运营、教师、销售、代理、学生的访问边界。
+   - 做一轮真实 JWT + RLS 回归测试。
+
+2. 对象存储
+   - 接阿里云 OSS、腾讯云 COS 或 Supabase Storage。
+   - 完成上传签名、下载签名、PDF 预览地址、视频播放签名。
+   - `content_assets` 继续作为资源台账，不允许前端绕过台账直接访问私有资源。
+
+3. 真实导入 dry-run
+   - 从 PocketBase 导出现有用户、题库、单词、知识手册、分数线、订单、权益数据。
+   - 跑 `scripts/import-pocketbase`，生成迁移报告。
+   - 对题目 JSON、单词、知识手册走后端 preview/import API 做二次验证。
+
+4. 部署配置
+   - 整理生产 `.env` 模板。
+   - 确认数据库迁移流程、备份恢复、日志、告警。
+   - 准备 API 容器部署和 Supabase 云端/自托管连接方案。
+
+### P1 商用功能完善
+
+1. 支付
+   - 微信支付、支付宝、XPay 或实际使用的支付网关 adapter。
+   - webhook 验签、幂等、退款、支付补偿任务。
+   - 租户自有商户收款和平台代收/服务商模式。
+
+2. 国内登录和短信
+   - 阿里云短信、腾讯云短信 adapter。
+   - 微信小程序登录、微信网页登录、QQ 登录。
+   - 旧 PocketBase 用户账号和新身份体系的映射/补绑。
+
+3. 导入体系扩展
+   - Excel/CSV 导入。
+   - 分数线批量导入。
+   - 视频批量导入和题目视频批量绑定。
+   - 大批量导入异步 worker、重试、导入后校验。
+
+4. 公共题库和租户授权
+   - 平台公共题库/地区题库。
+   - 按 SaaS 套餐限制地区、科目、题库范围。
+   - 租户采纳、复制、授权、版本同步策略。
+
+5. 视频会员控制
+   - 视频 SVIP 权限、播放次数扣减。
+   - 防盗链、水印、播放日志、播放统计。
+   - 单题视频和通用知识视频混合推荐。
+
+6. 学习统计
+   - 练习历史、正确率趋势、题型分布、错题复习计划。
+   - 单词复习算法、每日计划、排行榜。
+   - 模考交卷、评分报告、错题解析汇总。
+
+7. 数据看板
+   - 收益、注册趋势、答题次数、收入趋势、题型分布、科目数量、题目总量。
+   - 套餐销量、运营动态、24h 活跃度、激活码使用情况。
+   - 销售/代理转化、分佣结算、客资跟进效果。
+
+8. AI 择校推荐
+   - 地区考试数据上下文。
+   - 学生输入 schema。
+   - AI 返回 JSON schema。
+   - 报告渲染和 PDF 生成。
+
+### P2 运营体验和企业交付
+
+1. 自定义角色
+   - 租户内角色模板。
+   - 菜单可见、模块可见、字段级权限。
+   - 权限变更审计。
+
+2. 主题系统
+   - 平台默认三套主题。
+   - 租户自定义主色、Logo、图标、启动图、小程序分享图。
+   - 主题预览和发布。
+
+3. CRM worker
+   - 钉钉、飞书、企业微信机器人 adapter。
+   - 轮询/定向分配。
+   - 推送失败重试和签名。
+
+4. 运维
+   - 后台操作审计报表。
+   - 定时备份、恢复演练。
+   - 性能压测、慢 SQL、索引审查。
+
+## Taro 前端开发 TODO
+
+### 架构目标
+
+- 建议新建 `apps/taro`，不要继续在旧 React Web 上堆兼容。
+- H5 和小程序共用同一套业务 API client。
+- 租户通过域名、小程序配置或启动参数解析。
+- 页面主题、品牌、功能开关都从后端租户配置读取。
+
+### 第一批页面
+
+1. 租户启动与首页
+   - 调 `/api/tenant/resolve`
+   - 读取品牌、主题、Banner、公告、功能开关
+   - 展示题库入口、背单词、知识手册、分数线、资料、会员
+
+2. 登录
+   - 迁移期可先接短信 mock 或临时登录
+   - 生产接微信小程序登录、短信登录、QQ/微信网页登录
+
+3. 题库
+   - `content_entries/content_nodes`
+   - `question_collections/practice_blueprints`
+   - 顺序刷题、随机刷题、全真模拟
+   - 答题、解析、错题、收藏、视频解析入口
+
+4. 背单词
+   - 单元列表、单词列表
+   - 学习状态、收藏、统计
+   - 后续补复习算法
+
+5. 知识手册
+   - 手册入口、章节、小节、知识点阅读
+   - Markdown/公式/图片基础渲染
+
+6. 分数线
+   - 院校、专业、年份、动态字段筛选
+   - 趋势图
+
+7. 资料下载
+   - PDF 列表、权限提示、预览、下载
+
+8. 个人中心
+   - 会员权益、订单、激活码兑换
+   - 错题本、收藏夹、学习统计
+
+### 前端接入原则
+
+- 不在前端实现最终权限判断，前端只做 UI 可见性控制。
+- 不在前端直接拼接私有资源 URL，统一请求后端签名。
+- 不把旧 PocketBase 字段当成长期模型，优先使用新 API 返回的 `entryId/contentNodeId/collectionId/blueprintId`。
+- 小程序码、支付、登录等平台能力统一走 provider adapter，不在页面里硬编码租户密钥。
+
+## 推荐下一步顺序
+
+1. 先把当前后端代码推到 Gitea。
+2. 云服务器部署 Supabase/PostgreSQL 和 API，跑 `check:refactor` 的远程等价测试。
+3. 导出现有 PocketBase 数据，做完整 dry-run 迁移。
+4. 开始 `apps/taro`，先接租户解析、首页、题库、背单词、知识手册。
+5. 并行补对象存储、真实登录、支付 adapter。
+6. 前后端联调通过后，再做支付、权限、数据导入、资料下载、视频播放的商用验收。