forked from wangziqi/gongxue-base
117 lines
9.3 KiB
Markdown
117 lines
9.3 KiB
Markdown
# 后端进度同步与前端接入路线图
|
||
|
||
更新时间：2026-06-22
|
||
|
||
这份文档用于在进入 Taro 前端开发前，快速确认新 Supabase/PostgreSQL 后端已经做到哪里、还缺什么、前端应如何接入，以及后续继续开发的优先级。
|
||
|
||
## 当前结论
|
||
|
||
新项目已经不是简单的 PocketBase 字段平移，而是按多租户 SaaS 重新建立了后端边界：
|
||
|
||
- 平台侧可以管理租户、SaaS 套餐、订阅、账单、服务费和用量。
|
||
- 租户侧可以管理品牌、域名、支付账户、登录配置、私密密钥、活动、兑换码、优惠券、成员权限、审计日志、内容入口、分类树、题目集合、练习蓝图、题目、视频、分数线、单词、知识手册和资料资源。
|
||
- 学生侧已经有题库入口、分类树、题目集合、顺序/随机/全真模拟组卷、答题、错题、收藏、背单词进度、个人中心、排行榜、分数线、视频、订单详情/状态轮询、优惠券领取/抵扣、权益、激活码预检查/兑换和资料下载的基础 API。
|
||
- 销售/代理/CRM 已经有邀请码、扫码/分享事件、首绑客资保护、团队关系、统计、CRM 配置和入队能力。
|
||
- 旧题库 JSON、单词模板、知识手册嵌套模板已经进入后端 preview/import 管线，由后端负责规范化、校验、幂等、审计和租户隔离。
|
||
|
||
因此，后端现在已经具备进入 Taro 前端第一阶段联调的基础。需要注意的是，它还不是完整生产交付状态，真实鉴权、对象存储、支付、短信、微信/QQ 登录、异步 worker、真实数据 dry-run 迁移仍需要继续补齐。
|
||
|
||
## 后端模块进度
|
||
|
||
| 模块 | 当前状态 | 已经具备 | 上线前还要补 |
|
||
| --- | --- | --- | --- |
|
||
| 多租户底座 | 可联调 | 租户、域名、品牌、设置、RLS 基础、审计、Supabase JWT/API 身份映射 | 真实云端 Auth/JWKS 回归、生产 RLS 深测 |
|
||
| 平台后台 | 基础完成 | 租户、套餐、订阅、账单、服务费、用量、公共题库授权 | 自动计费、平台审计、公共题库版本同步 |
|
||
| 租户后台 | 可联调 | 品牌、域名、支付账户、登录配置、密钥掩码、活动、兑换码、优惠券、成员权限、角色模板、菜单/模块/字段权限配置 API | 前端权限 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` 为准。
|
||
|
||
前端第一阶段应该先做能跑完整学生链路的页面：
|
||
|
||
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 预览、视频播放签名、防盗链和水印。
|
||
- 真实数据 dry-run：导出 PocketBase 用户、题库、单词、知识手册、分数线、订单、权益，跑迁移和校验报告。
|
||
- 生产环境配置：补 `.env` 模板、数据库迁移流程、备份恢复、日志、告警和 API 容器部署说明。
|
||
- Taro scaffold：建立 `apps/taro`，先完成租户解析、首页、题库、背单词、知识手册、个人中心主链路。
|
||
|
||
### P1：商用收费和运营能力
|
||
|
||
- 退款通知 webhook、对账、支付补偿任务和异常订单自动处理。
|
||
- XPay 或其它实际支付网关 adapter。
|
||
- 阿里云/腾讯云短信、微信小程序登录、微信网页登录、QQ 登录。
|
||
- 公共题库/地区题库版本同步，租户按 SaaS 套餐购买地区、科目和题库范围的更细计费策略。
|
||
- Excel/CSV、分数线、视频批量导入。
|
||
- 视频会员播放次数、播放日志、防盗链、水印。
|
||
- 数据看板 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 推送、资源签名都有幂等和审计。
|
||
- 有生产环境变量模板、部署脚本、备份恢复方案、日志告警、错误追踪和基础压测报告。
|