forked from wangziqi/gongxue-base
117 lines
12 KiB
Markdown
117 lines
12 KiB
Markdown
# 后端进度同步与前端接入路线图
|
||
|
||
更新时间：2026-06-29
|
||
|
||
这份文档用于在进入 Taro 前端开发前，快速确认新 Supabase/PostgreSQL 后端已经做到哪里、还缺什么、前端应如何接入，以及后续继续开发的优先级。
|
||
|
||
## 当前结论
|
||
|
||
新项目已经不是简单的 PocketBase 字段平移，而是按多租户 SaaS 重新建立了后端边界：
|
||
|
||
- 平台侧可以管理租户、SaaS 套餐、订阅、账单、服务费和用量。
|
||
- 租户侧可以管理品牌、域名、支付账户、登录配置、私密密钥、活动、兑换码、优惠券、成员权限、审计日志、内容入口、分类树、题目集合、练习蓝图、题目、视频、分数线、单词、知识手册、资料资源和题库导出任务。
|
||
- 学生侧已经有题库入口、分类树、题目集合、顺序/随机/全真模拟组卷、答题、错题、收藏、背单词进度、个人中心、勋章、排行榜、分数线、视频、订单详情/状态轮询、优惠券领取/抵扣、权益、激活码预检查/兑换和资料下载的基础 API。
|
||
- 销售/代理/CRM 已经有邀请码、扫码/分享事件、首绑客资保护、团队关系、统计、CRM 配置和入队能力。
|
||
- 旧题库 JSON、单词模板、知识手册嵌套模板、分数线 JSON 和视频绑定 JSON 已经进入后端 preview/import 管线，由后端负责规范化、校验、幂等、审计和租户隔离。
|
||
|
||
因此，后端现在已经具备进入 Taro 前端第一阶段联调的基础。需要注意的是，它还不是完整生产交付状态，真实云端鉴权、对象存储生产安全、支付/短信/OAuth 生产账号、真实数据 dry-run 迁移仍需要继续补齐或联调；导入后复检、模板下载和字段映射 API 已可联调，前端操作台待接。
|
||
|
||
## 后端模块进度
|
||
|
||
| 模块 | 当前状态 | 已经具备 | 上线前还要补 |
|
||
| --- | --- | --- | --- |
|
||
| 多租户底座 | 可联调 | 租户、域名、品牌、设置、RLS 基础、审计、Supabase JWT/API 身份映射 | 真实云端 Auth/JWKS 回归、生产 RLS 深测 |
|
||
| 平台后台 | 基础完成 | 租户、套餐、订阅、账单、服务费、用量、公共题库授权、公共题库自动同步 worker | 自动计费、平台审计、公共题库版本通知和冲突处理运营台 |
|
||
| 租户后台 | 可联调 | 品牌、域名、支付账户、登录配置、密钥掩码、活动、兑换码、优惠券、勋章管理/发放、成员权限、角色模板、菜单/模块/字段权限配置 API、班级/教师/学生范围权限 | 前端权限 UI、更细的数据范围组合 |
|
||
| 题库与练习 | 可联调 | 内容入口、任意深度分类、题目集合、顺序/随机/全真模拟蓝图、组卷快照、答题、错题、收藏、模考报告、排行榜、公共题库采纳快照、手动同步、自动同步 worker、冲突查询 API、JSON/试卷 payload 导出 | 专项策略、PDF/Word 导出 worker、公共题库版本通知和冲突操作台、排行榜防刷/预聚合 |
|
||
| 背单词 | 可联调 | 单元、单词、进度、收藏、统计、每日计划、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 渲染、CDN 防盗链、杀毒扫描、视频水印 |
|
||
| 会员与订单 | 可联调 | 下单、订单详情/状态轮询、优惠券领取/抵扣、零元订单自动开通、手工确认权限保护、激活码预检查/兑换、微信支付、支付宝、微信/支付宝发起退款、微信/支付宝退款查询确认、微信/支付宝退款通知 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、PocketBase JSON dry-run 报告 | 字段映射 UI、真实数据 dry-run 执行验收和导入性能压测 |
|
||
| 数据看板 | 可联调 | 租户 dashboard 聚合接口，收益、注册、学习、内容、激活码、反馈、趋势、24h 活跃、套餐销量和运营动态 | 预聚合 worker、缓存、慢 SQL 监控和销售转化看板 |
|
||
| AI 择校推荐 | 未开始 | 暂无 | 数据上下文、AI JSON schema、报告渲染、PDF 生成 |
|
||
| Taro 前端 | 地基已建 | `apps/taro` 已有 Taro 4 React 工程、H5 三入口、租户解析、统一 API client、Supabase Auth client 初始化；学生端、租户后台和平台后台均已有第一批真实 API 页面；学生端已接地区选择、错题/收藏复习、题目反馈、视频解析和练习/模考报告第一版；平台后台已接关键写操作第一版，租户内容页已接公共题库采纳/同步、导入问题、字段模板和复检第一版 | 学生端收银台/订单详情/售后入口和刷题细节 UI、租户后台导入上传/字段映射编辑/冲突处理详情、平台后台审计/详情增强、小程序兼容验证和端到端测试 |
|
||
|
||
## 前端接入建议
|
||
|
||
建议新建 `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：上云测试和前端主链路前必须处理
|
||
|
||
- 生产鉴权：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 用户、题库、单词、知识手册、分数线、订单、权益，先跑 `npm run pb:import:dry-run`，再跑迁移和校验报告。
|
||
- 生产环境配置：`.env.example` 和 `npm run readiness:production` / `npm run readiness:production:db` 已补；继续补数据库迁移流程、备份恢复、日志、告警和 API 容器部署说明。
|
||
- Taro scaffold：`apps/taro` 地基已建立；学生端、租户后台、平台后台第一批 H5 页面已接真实 API，学生端已接地区选择、错题/收藏复习、题目反馈、视频解析和练习/模考报告第一版，平台后台关键写操作第一版已接入，租户内容页已接公共题库采纳/同步、导入问题、字段模板和复检第一版；下一步补学生端收银台/订单详情/售后入口和刷题细节 UI、租户后台导入上传/字段映射编辑/冲突处理详情、平台后台审计增强和小程序兼容验证。
|
||
|
||
### P1：商用收费和运营能力
|
||
|
||
- 完整资金流水对账、账单下载比对和异常订单运营台。
|
||
- XPay 或其它实际支付网关 adapter。
|
||
- 阿里云/腾讯云短信、微信小程序登录、微信网页登录、QQ 登录真实账号联调。
|
||
- 公共题库/地区题库自动同步 worker 已具备单批执行能力；继续补版本通知、冲突操作台，以及租户按 SaaS 套餐购买地区、科目和题库范围的更细计费策略。
|
||
- 导入模板、字段映射和复检 API 已可用；前端继续补模板下载按钮、字段映射 UI、job 状态轮询和复检结果面板。
|
||
- 视频深度防盗链、动态水印和播放统计。
|
||
- 数据看板 API：收益、注册趋势、答题次数、收入趋势、题型分布、题目总量、套餐销量、24h 活跃。
|
||
|
||
### P2：企业级体验和增长闭环
|
||
|
||
- 租户自定义角色模板基础 API 已完成；继续补权限配置 UI、班级/教师/学生范围权限和平台级审计报表。
|
||
- 三套默认主题、租户主题预览、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 推送、资源签名都有幂等和审计。
|
||
- 有生产环境变量模板、生产就绪检查脚本、部署脚本、备份恢复方案、日志告警、错误追踪和基础压测报告。
|