后端进度同步与前端接入路线图

更新时间：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 权限校验、`local_dev`/阿里云 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 为准。

前端第一阶段应该先做能跑完整学生链路的页面：

租户启动
- 调 GET /api/tenant/resolve。
- 读取品牌、主题、功能开关、域名/小程序启动参数。
- 后续 H5 用域名解析，小程序用租户配置或启动参数解析。
首页与内容入口
- 调 GET /api/catalog/content-entries。
- 展示题库、背单词、知识手册、分数线、资料、会员入口。
- 前端不再依赖旧 PocketBase 树字段作为长期模型。
题库练习
- 调 GET /api/catalog/content-nodes、GET /api/catalog/question-collections、GET /api/catalog/practice-blueprints。
- 调 POST /api/learning/practice-sessions 生成顺序、随机、全真模拟题目快照。
- 调 POST /api/learning/answers、错题、收藏接口完成刷题闭环。
背单词和知识手册
- 背单词走 vocabulary units/words/progress/favorites。
- 知识手册走 handbook subjects/chapters/entries。
- 页面只做展示、搜索、筛选、学习状态提交，最终权限和数据范围以后端为准。
个人中心
- 调 GET /api/profile/me。
- 接会员权益、订单、激活码兑换、错题本、收藏夹、学习统计。
资料、视频和支付
- 资料下载、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 推送、资源签名都有幂等和审计。
有生产环境变量模板、部署脚本、备份恢复方案、日志告警、错误追踪和基础压测报告。

8.7 KiB Raw Blame History Unescape Escape