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

更新时间：2026-06-29

这份文档用于在进入 Taro 前端开发前，快速确认新 Supabase/PostgreSQL 后端已经做到哪里、还缺什么、前端应如何接入，以及后续继续开发的优先级。

当前结论

新项目已经不是简单的 PocketBase 字段平移，而是按多租户 SaaS 重新建立了后端边界：

平台侧可以管理租户、SaaS 套餐、订阅、账单、服务费和用量。
租户侧可以管理品牌、域名、支付账户、登录配置、私密密钥、活动、兑换码、优惠券、成员权限、审计日志、内容入口、分类树、题目集合、练习蓝图、题目、视频、分数线、单词、知识手册、资料资源和题库导出任务。
学生侧已经有题库入口、分类树、题目集合、顺序/随机/全真模拟组卷、答题、错题、收藏、背单词进度、个人中心、勋章、排行榜、分数线、视频、订单详情/状态轮询、优惠券领取/抵扣、权益、激活码预检查/兑换和资料下载的基础 API。
销售/代理/CRM 已经有邀请码、扫码/分享事件、首绑客资保护、团队关系、统计、CRM 配置、入队、worker 推送和分佣结算基础闭环。
旧题库 JSON、单词模板、知识手册嵌套模板、分数线 JSON 和视频绑定 JSON 已经进入后端 preview/import 管线，由后端负责规范化、校验、幂等、审计和租户隔离。

因此，后端现在已经具备进入 Taro 前端第一阶段联调的基础。需要注意的是，它还不是完整生产交付状态，真实云端鉴权、对象存储生产安全、支付/短信/OAuth 生产账号、真实数据 dry-run 迁移仍需要继续补齐或联调；导入后复检、模板下载、字段映射 API 和导入任务详情已可联调，Taro 租户内容页已接入上传/粘贴预览、字段别名覆盖、同步/异步执行、异步轮询和复检详情第一版，租户营销中心已接入 CRM 配置/队列和分佣结算操作台第一版。

后端模块进度

模块	当前状态	已经具备	上线前还要补
多租户底座	可联调	租户、域名、品牌、设置、RLS 基础、审计、Supabase JWT/API 身份映射	真实云端 Auth/JWKS 回归、生产 RLS 深测
平台后台	基础完成	租户、套餐、订阅、账单、服务费、用量、公共题库授权、公共题库自动同步 worker、公共题库冲突单条/批量处理 API、公共题库同步通知第一版	自动计费、平台审计、更完整运营消息
租户后台	可联调	品牌、域名、支付账户、登录配置、密钥掩码、活动、兑换码、优惠券、勋章管理/发放、成员权限、角色模板、菜单/模块/字段权限配置 API、班级/教师/学生范围权限；Taro 工作台已接权限驱动模块入口，学生运营页已接学生创建/更新、禁用/恢复、批量导入、批量分班、备注和跟进任务第一版，租户设置页已接角色模板和成员绑定操作台第一版，营销中心已接 CRM 配置/队列和分佣结算操作台第一版	更细的数据范围组合、成员批量运营、真实打款/导出/凭证和完整权限菜单
题库与练习	可联调	内容入口、任意深度分类、题目集合、顺序/随机/全真模拟蓝图、组卷快照、客观题后端判分、主观题 `selfJudgedCorrect` 自评、阅读理解/案例分析 `subAnswers` 多小题判分、答题、错题、收藏、模考报告、排行榜、公共题库采纳快照、手动同步、自动同步 worker、冲突查询/单条和批量处理 API、公共题库同步通知、JSON/试卷 payload 导出、PDF/Word 异步导出 worker、水印和资料发布路径、每日一练九宫格 metadata、PDF/Word 运营版式和 ZIP 图片素材包	长题干/公式图片混排体验、导出模板精排、导出操作台、排行榜防刷/预聚合
背单词	可联调	单元、单词、进度、收藏、统计、每日计划、JSON/CSV/Excel 导入、排行榜	更细复习参数
知识手册	可联调	科目、章节、条目、Markdown 内容、嵌套 JSON/CSV/Excel 导入	富文本资源、版本管理、附件/PDF 关联
分数线	可联调	院校、专业、动态字段、记录、年份、趋势、后台维护、JSON/CSV/Excel 导入	复杂筛选、AI 择校上下文
视频解析	可联调	单题视频、批量查询、后台视频绑定、JSON/CSV/Excel 导入、会员播放权限、播放次数扣减、签名 URL 和播放日志	深度防盗链、动态水印、播放统计
资料下载	部分完成	资源台账、SVIP 权限校验、`local_dev`/阿里云 OSS/腾讯 COS/Supabase Storage 上传下载签名、上传确认、PDF/图片预览签名、assets worker 复检异常下架、题库导出 PDF/Word/每日一练 ZIP 可生成 `content_assets` 并走签名下载/预览	CDN 防盗链、杀毒扫描、视频水印、资料前端操作体验
会员与订单	可联调	下单、订单详情/状态轮询、优惠券领取/抵扣、零元订单自动开通、手工确认权限保护、激活码预检查/兑换、微信支付、支付宝、微信/支付宝发起退款、微信/支付宝退款查询确认、微信/支付宝退款通知 webhook、支付/退款补偿 worker、权益发放	完整资金流水对账、异常订单运营台
登录认证	可联调	短信 mock、阿里云/腾讯云短信 adapter、迁移期 session、Supabase Auth JWT、微信小程序登录、微信网页登录、QQ 登录、手机号绑定/换绑、OAuth 配置表	真实生产账号和回调域名联调
销售/代理/CRM	可联调	邀请码、首绑保护、团队关系、销售统计、CRM 配置/队列、钉钉/飞书/企微 worker、分佣规则、成员分佣比例、订单/激活码归因、结算生成、审核和打款状态；Taro 营销中心已接第一版操作台	小程序码真实生成、CRM 分配策略、结算导出、真实打款、凭证、财务复核和销售转化看板
内容导入	可联调	题目、单词、知识手册、分数线、视频 JSON/CSV/Excel preview/import、issue、job/detail、审计、幂等、`executionMode=async`、imports worker、导入后复检、模板下载、字段映射 API、字段映射覆盖白名单校验、PocketBase JSON dry-run 报告；Taro 租户内容页已接上传/粘贴预览、模板文件下载、字段别名编辑、同步/异步执行、异步轮询和复检详情第一版	真实数据 dry-run 执行验收、抽样校验和导入性能压测
数据看板	可联调	租户 dashboard 聚合接口，收益、注册、学习、内容、激活码、反馈、趋势、24h 活跃、套餐销量和运营动态	预聚合 worker、缓存、慢 SQL 监控和销售转化看板
AI 择校推荐	未开始	暂无	数据上下文、AI JSON schema、报告渲染、PDF 生成
Taro 前端	地基已建	`apps/taro` 已有 Taro 4 React 工程、H5 三入口、租户解析、统一 API client、Supabase Auth client 初始化；学生端、租户后台和平台后台均已有第一批真实 API 页面；学生端已接地区选择、刷题答题卡、后端权威断点续练、本地进度恢复、模拟倒计时、主观题后端自评、阅读理解/案例分析多小题作答、错题/收藏复习、题目反馈、视频解析、练习/模考报告、收银台、订单详情和售后入口第一版；平台后台已接关键写操作第一版，租户工作台已接权限驱动模块入口，租户学生运营页已接创建/更新、禁用/恢复、批量导入、批量分班、备注和跟进任务第一版，租户内容页已接公共题库采纳/同步、冲突查看、单条/批量采纳平台或保留本地、导入问题、字段模板预览/下载、上传/粘贴预览、字段别名覆盖、同步/异步导入、异步轮询和复检详情第一版；租户设置页已接角色模板和成员绑定操作台第一版；租户营销中心已接 CRM 配置保存、队列筛选、分佣规则、成员比例、订单明细、结算生成/审核/标记线下打款第一版	长题干/公式图片混排体验、更细数据范围 UI、平台后台审计/详情增强、小程序兼容验证和端到端测试

前端接入建议

建议新建 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、错题、收藏接口完成刷题闭环；主观题自评传 selfJudgedCorrect，客观题仍以后端答案判分为准。
背单词和知识手册
- 背单词走 vocabulary units/words/progress/favorites。
- 知识手册走 handbook subjects/chapters/entries。
- 页面只做展示、搜索、筛选、学习状态提交，最终权限和数据范围以后端为准。
个人中心
- 调 GET /api/profile/me。
- 接会员权益、订单详情/状态轮询、优惠券、激活码预检查/兑换、错题本、收藏夹、学习统计、排行榜和勋章。
资料、视频和支付
- 资料下载、PDF 预览、视频播放必须先请求后端签名或权限检查。
- 支付和登录在前端可以先接 mock/迁移期能力，生产再替换真实 provider。

后续开发 TODO

P0：上云测试和前端主链路前必须处理

生产鉴权：API 已支持 Supabase Auth JWT；继续做真实云端 Auth/JWKS 回归、RLS 深测，并在生产关闭 x-user-id 与 x-platform-admin-key 兼容入口。
对象存储：上传/下载签名已接入阿里云 OSS、腾讯云 COS、Supabase Storage；上传确认、PDF/图片预览签名、assets worker 复检和题库导出 PDF/Word/每日一练 ZIP worker 已完成，继续补视频播放防盗链、杀毒扫描和动态水印。
真实数据 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 地基已建立；学生端、租户后台、平台后台第一批 H5 页面已接真实 API，学生端已接地区选择、错题/收藏复习、阅读理解/案例分析多小题作答、题目反馈、视频解析、练习/模考报告、收银台、订单详情和售后入口第一版，平台后台关键写操作第一版已接入，租户工作台已接权限驱动模块入口，租户学生运营页已接学生创建/更新、禁用/恢复、批量导入、批量分班、备注和跟进任务第一版，租户内容页已接公共题库采纳/同步、冲突查看、单条/批量采纳平台或保留本地、导入问题、字段模板预览/下载、上传/粘贴预览、字段别名覆盖、同步/异步导入、异步轮询和复检详情第一版，租户设置页已接角色模板创建/编辑/停用、成员绑定模板和权限可见性配置第一版，租户营销中心已接 CRM 配置/队列和分佣结算操作台第一版；下一步补公式图片混排、更细数据范围 UI、平台后台审计增强和小程序兼容验证。

P1：商用收费和运营能力

完整资金流水对账、账单下载比对和异常订单运营台。
XPay 或其它实际支付网关 adapter。
阿里云/腾讯云短信、微信小程序登录、微信网页登录、QQ 登录真实账号联调。
公共题库/地区题库自动同步 worker 已具备单批执行能力，租户后台已有同步通知、单条/批量冲突采纳平台或保留本地操作；继续补生产定时调度、失败告警，以及租户按 SaaS 套餐购买地区、科目和题库范围的更细计费策略。
导入模板、字段映射、导入任务详情和复检 API 已可用；Taro 租户内容页已接模板下载、字段别名覆盖、导入执行、异步 job 轮询和复检结果面板第一版。前端继续补真实导入目标选择体验和大数据量导入验收。
视频深度防盗链、动态水印和播放统计。
数据看板 API：收益、注册趋势、答题次数、收入趋势、题型分布、题目总量、套餐销量、24h 活跃。

P2：企业级体验和增长闭环

租户自定义角色模板基础 API、Taro 权限配置 UI、成员绑定模板和工作台权限驱动入口第一版已完成；继续补班级/教师/学生组合范围 UI、成员批量运营和平台级审计报表。
三套默认主题、租户主题预览、Logo/图标/分享图配置。
CRM worker：钉钉、飞书、企微机器人发送、签名、失败重试已落地；Taro 营销中心已能配置 CRM 和查看队列；继续补轮询/定向分配、富卡片、失败告警和死信运营台。
销售/代理分佣基础闭环已接 Taro 第一版；继续补销售团队看板、客资跟进效果、结算导出、真实打款、凭证和财务复核。
AI 择校推荐：地区考试数据、学生输入 schema、AI JSON 输出、PDF 报告生成。
性能压测、慢 SQL 审查、备份恢复演练、灰度发布和回滚预案。

后端完成判定

后端进入“可支撑前端全面联调”的最低标准：

npm run check:refactor 在本地通过。
使用真实 PocketBase 导出数据完成一次 dry-run，产出问题清单和修复后的二次导入报告。
核心学生链路 API 可以在 Taro H5 和小程序双端跑通：登录、首页、题库、练习、错题、收藏、单词、手册、会员、排行榜、个人中心。
租户隔离、后台角色权限、资源访问权限、订单权益和内容导入至少有集成测试覆盖。

后端进入“商用生产交付”的最低标准：

JWT/RLS、短信、登录、支付、对象存储、CRM webhook 都使用真实 provider 或生产可用 adapter。
支付 webhook、导入任务、CRM 推送、资源签名都有幂等和审计。
有生产环境变量模板、生产就绪检查脚本、部署脚本、备份恢复方案、日志告警、错误追踪和基础压测报告。

15 KiB Raw Blame History Unescape Escape