forked from wangziqi/gongxue-base
211 lines
14 KiB
Markdown
211 lines
14 KiB
Markdown
# 后续开发 TODO
|
||
|
||
更新时间：2026-06-29
|
||
|
||
## 当前后端基线
|
||
|
||
后端已经完成可本地验证的商用 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/CSV/Excel 预览、校验、导入、幂等、审计。
|
||
- 租户组织范围：班级、班级成员、教师/班主任/助教/学生分组，教师按负责班级查看学生，字段权限可脱敏学生手机号。
|
||
- 学生运营管理：学生批量 upsert、禁用/恢复、批量分班、备注、跟进任务已完成接口和集成测试；后续补批量 CRM 推送和自动学习督导。
|
||
- 旧题库运营缺口已补一批：考试日期/倒计时、题目反馈/纠错处理、每日签到积分和积分流水、学习排行榜已完成接口和集成测试。
|
||
- 勋章管理已完成租户后台维护、手动发放、重复发放幂等、学生个人中心展示、权限点和集成测试；后续补自动发放规则和活动联动。
|
||
- 旧商城体验已补齐主链路：订单详情、订单状态轮询、激活码预检查、自用激活码拒绝、优惠券前台领取、下单抵扣、零元订单自动支付开通权益，且手工支付确认已限制为租户后台 `tenant:payment:write` 权限。
|
||
- 公共题库商业化基础闭环已完成：平台公共题库可由平台管理员按 SaaS 套餐/指定租户/全部活跃租户授权；租户内容管理员只能看到自己被授权的公共题库，并可采纳为本租户题库、内容入口、题目集合和题目快照，采纳后可直接进入练习 session；平台题库后续新增/更新题目可通过手动同步 API 进入租户副本，租户自改题目会返回冲突并保留原内容。
|
||
- 租户后台数据看板已完成首版聚合 API：`GET /api/tenant-admin/dashboard`，支持租户/地区维度的收益、注册、学习、内容、激活码、反馈、趋势、24h 活跃、套餐销量和运营动态，前端可直接联调。
|
||
- 支付/退款补偿 worker 已完成：`apps/worker --job commerce` 可查询微信/支付宝支付和处理中退款，补偿漏通知订单，支付成功幂等开通权益，退款成功幂等更新退款/订单/支付并在全额退款时撤销订单权益。
|
||
- 内容资源复检 worker 已完成：`apps/worker --job assets` 可复检 `content_assets` 中的托管对象元数据，正常资源写回复检证据，异常资源自动置为 `failed + draft` 并写入审计和安全标记。
|
||
- 本地验证：`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 集成测试。
|
||
- 已补自定义角色模板、菜单/模块/字段级配置 API、班级/学生范围权限；继续补真实云端 Auth/JWKS 回归和 RLS 深测。
|
||
- 前端联调时禁止继续使用 `x-user-id`；`x-tenant-id` 只作为租户上下文，不能作为身份依据。
|
||
|
||
2. 对象存储
|
||
- 已接阿里云 OSS、腾讯云 COS、Supabase Storage 的上传/下载签名 provider。
|
||
- 已补上传后对象确认接口、托管对象发布前 verified 校验、PDF/图片 inline 预览签名。
|
||
- 已补 assets worker 复检，异常托管对象会自动下架并记录审计。
|
||
- 继续补视频深度防盗链、动态水印、杀毒扫描、CDN 刷新和对象生命周期策略。
|
||
- `content_assets` 继续作为资源台账，不允许前端绕过台账直接访问私有资源。
|
||
|
||
3. 真实导入 dry-run
|
||
- 从 PocketBase 导出现有用户、题库、单词、知识手册、分数线、订单、权益数据。
|
||
- 跑 `scripts/import-pocketbase`，生成迁移报告。
|
||
- 对题目 JSON、单词、知识手册、分数线、视频走后端 preview/import API 做二次验证。
|
||
|
||
4. 部署配置
|
||
- 整理生产 `.env` 模板。
|
||
- 确认数据库迁移流程、备份恢复、日志、告警。
|
||
- 准备 API 容器部署和 Supabase 云端/自托管连接方案。
|
||
|
||
### P1 商用功能完善
|
||
|
||
1. 支付
|
||
- 已完成微信支付 JSAPI、支付宝 WAP/H5 的创建支付参数和 webhook 幂等开通权益。
|
||
- 已完成内部退款状态机、退款申请/审核/处理接口、微信/支付宝发起退款、微信/支付宝退款查询确认、微信/支付宝退款通知 webhook、部分/全额退款状态、全额退款权益撤销和审计事件。
|
||
- 已完成支付/退款补偿 worker，可兜底供应商漏通知、处理中退款和重复执行幂等。
|
||
- 继续补完整资金流水对账、账单下载比对和异常订单运营台。
|
||
- 租户自有商户收款和平台代收/服务商模式。
|
||
|
||
2. 国内登录和短信
|
||
- 已完成阿里云短信、腾讯云短信 adapter 的后端实现和本地 fake endpoint 测试。
|
||
- 已完成微信小程序 `code2Session` 登录主链路。
|
||
- 继续补微信网页登录、QQ 登录、手机号绑定/换绑、真实生产账号联调。
|
||
- 旧 PocketBase 用户账号和新身份体系的映射/补绑。
|
||
|
||
3. 导入体系扩展
|
||
- 已完成题目、单词、知识手册、分数线、视频的 CSV/Excel 到规范 JSON 解析适配。
|
||
- 继续补大批量导入异步 worker、重试、导入后校验。
|
||
- 模板下载、字段映射 API 和导入后复检已补；继续补字段映射 UI、真实数据 dry-run、导入前抽样校验和复检结果操作台。
|
||
|
||
4. 公共题库和租户授权
|
||
- 已完成平台公共题库/地区题库的基础授权、租户采纳、题目快照复制和手动同步。
|
||
- 继续补按 SaaS 套餐限制地区数量、科目范围、题库范围的更细计费策略。
|
||
- 继续补公共题库自动同步 worker、同步失败重试、版本通知、冲突操作台和运营后台 UI。
|
||
|
||
5. 视频会员控制
|
||
- 已完成视频 SVIP 权限、播放次数扣减、签名播放和播放日志。
|
||
- 继续补深度防盗链、动态水印、播放统计。
|
||
- 单题视频和通用知识视频混合推荐。
|
||
|
||
6. 学习统计
|
||
- 已完成免费额度、练习访问事件、模考交卷评分报告、练习历史、正确率趋势、题型分布、错题复习计划。
|
||
- 已完成单词复习算法、每日计划和复习上报。
|
||
- 已完成排行榜主接口；继续补防刷、日/周榜预聚合和运营后台排名看板。
|
||
- 继续补断点续练和复盘体验。
|
||
|
||
7. 订单和营销体验
|
||
- 已完成订单详情、订单状态轮询、激活码预检查、优惠券前台领取、下单抵扣计算和内部退款状态机。
|
||
- 已完成支付/退款补偿 worker；继续补完整资金流水对账、异常订单运营台、优惠券核销报表和复杂活动规则。
|
||
|
||
8. 积分和反馈增强
|
||
- 已完成每日签到、积分流水、反馈提交、租户后台处理、奖励积分幂等。
|
||
- 已完成勋章后台维护、手动发放和学生端展示。
|
||
- 继续补积分兑换、活动任务、连续签到奖励配置、勋章自动发放、处理通知和反馈聚合统计。
|
||
|
||
9. 数据看板
|
||
- 已完成首版实时聚合接口，覆盖收益、注册趋势、答题次数、收入趋势、题型分布、科目数量、题目总量、套餐销量、运营动态、24h 活跃度和激活码使用情况。
|
||
- 继续补日/周/月预聚合 worker、缓存策略、慢 SQL 监控和大租户性能压测。
|
||
- 分佣结算基础闭环已完成；继续补销售/代理转化、结算导出、真实打款、凭证和客资跟进效果看板。
|
||
|
||
10. 销售/代理分佣
|
||
- 已完成租户默认分佣比例、成员分佣比例、激活码批次分佣比例。
|
||
- 已完成订单和激活码两类来源的佣金归因，且只统计客资绑定后的成交。
|
||
- 已完成结算单生成、重复结算拦截、审核、打款状态、已打款锁定、租户隔离和销售/代理本人范围权限。
|
||
- 继续补结算导出、真实打款 provider、发票/凭证、财务复核流、销售团队分佣看板和异常调整单。
|
||
|
||
11. 学生运营管理
|
||
- 已完成学生列表、学生资料维护、班级分组、教师范围可见、学生批量导入、禁用/恢复、批量分班、学生备注和跟进任务。
|
||
- 继续补批量 CRM 推送、学习督导自动化、跟进效果统计和前端 UI。
|
||
|
||
12. AI 择校推荐
|
||
- 地区考试数据上下文。
|
||
- 学生输入 schema。
|
||
- AI 返回 JSON schema。
|
||
- 报告渲染和 PDF 生成。
|
||
|
||
### P2 运营体验和企业交付
|
||
|
||
1. 自定义角色
|
||
- 已完成租户内角色模板、菜单可见、模块可见、字段级权限和权限变更审计基础 API。
|
||
- 已完成班级/教师/学生范围权限 API，教师只能查看自己负责班级的学生。
|
||
- 继续补租户后台可视化配置 UI。
|
||
- 继续补更细的数据范围 UI，例如地区、题库、销售团队、本人客资、班级学生组合规则。
|
||
|
||
2. 主题系统
|
||
- 平台默认三套主题。
|
||
- 租户自定义主色、Logo、图标、启动图、小程序分享图。
|
||
- 主题预览和发布。
|
||
|
||
3. CRM worker
|
||
- 已完成 `apps/worker` CRM 队列消费、generic webhook、钉钉、飞书、企业微信机器人 adapter、签名、失败重试和日志。
|
||
- 继续补轮询/定向分配、富卡片模板、失败告警、死信运营后台和批量 CRM 推送。
|
||
|
||
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. 并行补对象存储、真实登录、完整资金流水对账、题库导出和公共题库自动同步 worker/冲突操作台。
|
||
6. 前后端联调通过后，再做支付、权限、数据导入、资料下载、视频播放的商用验收。
|