gongxue-base/docs/refactor/next-development-todo.md

后续开发 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 支持顺序、随机、全真模拟快照。
• 模考报告与学习统计：practice_session_reports/practice_session_report_sections 支持交卷、评分、题型/小节统计、错题解析汇总和历史查询；/api/learning/stats、trend、practice-sessions/history、wrong-questions/review-plan 可支撑个人中心和学习报告基础页。
• 练习访问控制：practice_daily_usage/practice_access_events 支持免费每日额度、SVIP 范围校验、SVIP-only 内容拦截和答题 session 快照保护。
• 内容导入：题目、单词、知识手册 JSON 预览、校验、导入、幂等、审计。
• 本地验证：npm run check:refactor 已通过。

当前更适合进入前端联调前阅读的总览文档：

• docs/refactor/backend-handoff-roadmap.md

后端待补功能

P0 上云测试前必须补齐

1. 生产鉴权

   • 已支持 Supabase Auth JWT 和迁移期 tk_ session 双入口；JWT 通过 auth.users.id -> platform_users.auth_user_id -> tenant_memberships 映射业务身份。
   • 已覆盖学生、租户管理员、平台管理员、错租户、坏签名、禁用 legacy header 的 API 集成测试。
   • 继续补真实云端 Auth/JWKS 回归、RLS 深测、自定义角色模板和菜单/模块/字段级权限。
   • 前端联调时禁止继续使用 x-user-id；x-tenant-id 只作为租户上下文，不能作为身份依据。

2. 对象存储

   • 已接阿里云 OSS、腾讯云 COS、Supabase Storage 的上传/下载签名 provider。
   • 继续补上传后对象存在性校验、PDF 预览地址、视频深度防盗链、动态水印和 worker 校验。
   • content_assets 继续作为资源台账，不允许前端绕过台账直接访问私有资源。

3. 真实导入 dry-run

   • 从 PocketBase 导出现有用户、题库、单词、知识手册、分数线、订单、权益数据。
   • 跑 scripts/import-pocketbase，生成迁移报告。
   • 对题目 JSON、单词、知识手册走后端 preview/import API 做二次验证。

4. 部署配置

   • 整理生产 .env 模板。
   • 确认数据库迁移流程、备份恢复、日志、告警。
   • 准备 API 容器部署和 Supabase 云端/自托管连接方案。

P1 商用功能完善

1. 支付

   • 已完成微信支付 JSAPI、支付宝 WAP/H5 的创建支付参数和 webhook 幂等开通权益。
   • 继续补退款、支付补偿任务、对账、异常订单处理。
   • 租户自有商户收款和平台代收/服务商模式。

2. 国内登录和短信

   • 已完成阿里云短信、腾讯云短信 adapter 的后端实现和本地 fake endpoint 测试。
   • 已完成微信小程序 code2Session 登录主链路。
   • 继续补微信网页登录、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. 前后端联调通过后，再做支付、权限、数据导入、资料下载、视频播放的商用验收。