后续开发 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：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 上云测试前必须补齐

生产鉴权
- 已支持 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 只作为租户上下文，不能作为身份依据。
对象存储
- 已接阿里云 OSS、腾讯云 COS、Supabase Storage 的上传/下载签名 provider。
- 已补上传后对象确认接口、托管对象发布前 verified 校验、PDF/图片 inline 预览签名。
- 已补 assets worker 复检，异常托管对象会自动下架并记录审计。
- 继续补视频深度防盗链、动态水印、杀毒扫描、CDN 刷新和对象生命周期策略。
- content_assets 继续作为资源台账，不允许前端绕过台账直接访问私有资源。
真实导入 dry-run
- 从 PocketBase 导出现有用户、题库、单词、知识手册、分数线、订单、权益数据。
- 跑 scripts/import-pocketbase，生成迁移报告。
- 对题目 JSON、单词、知识手册、分数线、视频走后端 preview/import API 做二次验证。
部署配置
- 整理生产 .env 模板。
- 确认数据库迁移流程、备份恢复、日志、告警。
- 准备 API 容器部署和 Supabase 云端/自托管连接方案。

P1 商用功能完善

支付
- 已完成微信支付 JSAPI、支付宝 WAP/H5 的创建支付参数和 webhook 幂等开通权益。
- 已完成内部退款状态机、退款申请/审核/处理接口、微信/支付宝发起退款、微信/支付宝退款查询确认、微信/支付宝退款通知 webhook、部分/全额退款状态、全额退款权益撤销和审计事件。
- 已完成支付/退款补偿 worker，可兜底供应商漏通知、处理中退款和重复执行幂等。
- 继续补完整资金流水对账、账单下载比对和异常订单运营台。
- 租户自有商户收款和平台代收/服务商模式。
国内登录和短信
- 已完成阿里云短信、腾讯云短信 adapter 的后端实现和本地 fake endpoint 测试。
- 已完成微信小程序 code2Session 登录主链路。
- 继续补微信网页登录、QQ 登录、手机号绑定/换绑、真实生产账号联调。
- 旧 PocketBase 用户账号和新身份体系的映射/补绑。
导入体系扩展
- 已完成题目、单词、知识手册、分数线、视频的 CSV/Excel 到规范 JSON 解析适配。
- 继续补大批量导入异步 worker、重试、导入后校验。
- 继续补模板下载、字段映射 UI 和导入前抽样校验。
公共题库和租户授权
- 已完成平台公共题库/地区题库的基础授权、租户采纳和题目快照复制。
- 继续补按 SaaS 套餐限制地区数量、科目范围、题库范围的更细计费策略。
- 继续补公共题库版本同步 worker、租户自改冲突处理、同步失败重试和运营后台 UI。
视频会员控制
- 已完成视频 SVIP 权限、播放次数扣减、签名播放和播放日志。
- 继续补深度防盗链、动态水印、播放统计。
- 单题视频和通用知识视频混合推荐。
学习统计
- 已完成免费额度、练习访问事件、模考交卷评分报告、练习历史、正确率趋势、题型分布、错题复习计划。
- 已完成单词复习算法、每日计划和复习上报。
- 已完成排行榜主接口；继续补防刷、日/周榜预聚合和运营后台排名看板。
- 继续补断点续练和复盘体验。
订单和营销体验
- 已完成订单详情、订单状态轮询、激活码预检查、优惠券前台领取、下单抵扣计算和内部退款状态机。
- 已完成支付/退款补偿 worker；继续补完整资金流水对账、异常订单运营台、优惠券核销报表和复杂活动规则。
积分和反馈增强
- 已完成每日签到、积分流水、反馈提交、租户后台处理、奖励积分幂等。
- 已完成勋章后台维护、手动发放和学生端展示。
- 继续补积分兑换、活动任务、连续签到奖励配置、勋章自动发放、处理通知和反馈聚合统计。
数据看板
- 已完成首版实时聚合接口，覆盖收益、注册趋势、答题次数、收入趋势、题型分布、科目数量、题目总量、套餐销量、运营动态、24h 活跃度和激活码使用情况。
- 继续补日/周/月预聚合 worker、缓存策略、慢 SQL 监控和大租户性能压测。
- 分佣结算基础闭环已完成；继续补销售/代理转化、结算导出、真实打款、凭证和客资跟进效果看板。
销售/代理分佣

已完成租户默认分佣比例、成员分佣比例、激活码批次分佣比例。
已完成订单和激活码两类来源的佣金归因，且只统计客资绑定后的成交。
已完成结算单生成、重复结算拦截、审核、打款状态、已打款锁定、租户隔离和销售/代理本人范围权限。
继续补结算导出、真实打款 provider、发票/凭证、财务复核流、销售团队分佣看板和异常调整单。

学生运营管理

已完成学生列表、学生资料维护、班级分组、教师范围可见、学生批量导入、禁用/恢复、批量分班、学生备注和跟进任务。
继续补批量 CRM 推送、学习督导自动化、跟进效果统计和前端 UI。

AI 择校推荐

地区考试数据上下文。
学生输入 schema。
AI 返回 JSON schema。
报告渲染和 PDF 生成。

P2 运营体验和企业交付

自定义角色
- 已完成租户内角色模板、菜单可见、模块可见、字段级权限和权限变更审计基础 API。
- 已完成班级/教师/学生范围权限 API，教师只能查看自己负责班级的学生。
- 继续补租户后台可视化配置 UI。
- 继续补更细的数据范围 UI，例如地区、题库、销售团队、本人客资、班级学生组合规则。
主题系统
- 平台默认三套主题。
- 租户自定义主色、Logo、图标、启动图、小程序分享图。
- 主题预览和发布。
CRM worker
- 已完成 apps/worker CRM 队列消费、generic webhook、钉钉、飞书、企业微信机器人 adapter、签名、失败重试和日志。
- 继续补轮询/定向分配、富卡片模板、失败告警、死信运营后台和批量 CRM 推送。
运维
- 后台操作审计报表。
- 定时备份、恢复演练。
- 性能压测、慢 SQL、索引审查。

Taro 前端开发 TODO

架构目标

建议新建 apps/taro，不要继续在旧 React Web 上堆兼容。
H5 和小程序共用同一套业务 API client。
租户通过域名、小程序配置或启动参数解析。
页面主题、品牌、功能开关都从后端租户配置读取。

第一批页面

租户启动与首页
- 调 /api/tenant/resolve
- 读取品牌、主题、Banner、公告、功能开关
- 展示题库入口、背单词、知识手册、分数线、资料、会员
登录
- 迁移期可先接短信 mock 或临时登录
- 生产接微信小程序登录、短信登录、QQ/微信网页登录
题库
- content_entries/content_nodes
- question_collections/practice_blueprints
- 顺序刷题、随机刷题、全真模拟
- 答题、解析、错题、收藏、视频解析入口
背单词
- 单元列表、单词列表
- 学习状态、收藏、统计
- 每日新词、复习计划、认识/不认识上报
知识手册
- 手册入口、章节、小节、知识点阅读
- Markdown/公式/图片基础渲染
分数线
- 院校、专业、年份、动态字段筛选
- 趋势图
资料下载
- PDF 列表、权限提示、预览、下载
个人中心
- 会员权益、订单、激活码兑换
- 错题本、收藏夹、学习统计、排行榜、勋章

前端接入原则

不在前端实现最终权限判断，前端只做 UI 可见性控制。
不在前端直接拼接私有资源 URL，统一请求后端签名。
不把旧 PocketBase 字段当成长期模型，优先使用新 API 返回的 entryId/contentNodeId/collectionId/blueprintId。
小程序码、支付、登录等平台能力统一走 provider adapter，不在页面里硬编码租户密钥。

13 KiB Raw Blame History Unescape Escape

后续开发 TODO

当前后端基线

后端待补功能

P0 上云测试前必须补齐

P1 商用功能完善

P2 运营体验和企业交付

Taro 前端开发 TODO

架构目标

第一批页面

前端接入原则

推荐下一步顺序

13 KiB

Raw Blame History