后续开发 TODO

更新时间：2026-06-29

当前后端基线

后端已经完成可本地验证的商用 SaaS 骨架：

Supabase/PostgreSQL 多租户 schema、RLS、索引、触发器。
Node.js API 分层：core/features。
学生端核心 API：题库、练习、答题、模考交卷报告、练习历史、学习统计、排行榜、错题复习计划、错题、收藏、背单词、知识手册、分数线、视频播放签名、资料、订单详情/状态轮询、优惠券领取/抵扣、激活码预检查/兑换、权益、个人中心、考试倒计时、签到积分、题目反馈、勋章。
租户后台 API：品牌、域名、设置、支付账户、登录 provider、私密密钥、活动、考试日期、题目反馈处理、激活码、优惠券、勋章管理/发放、成员权限、审计、内容管理、班级/教师/学生、学生批量导入、批量分班、学生备注、跟进任务。
租户主题系统：平台默认经典蓝、专注绿、高对比三套模板，租户可保存草稿、发布主题，公开租户解析只返回已发布主题，Taro 租户设置页已接第一版主题操作台。
平台后台 API：租户、SaaS 套餐、订阅、账单、服务费收款、用量。
销售/代理/CRM 增长链路：邀请码、扫码事件、首绑保护、团队、统计、CRM 配置/队列、CRM worker、分佣规则、成员比例、订单/激活码归因、结算生成、审核和打款状态；Taro 租户营销中心已接第一版操作台。
内容导航：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 预览、校验、导入、幂等、审计。
内容导出：题库 JSON、paper_json、打印 payload 导出基础已完成，支持集合/入口/分类范围、导出 job、审计、跨租户拒绝、答案/解析开关和复合题子题脱敏。
租户组织范围：班级、班级成员、教师/班主任/助教/学生分组，教师按负责班级查看学生，字段权限可脱敏学生手机号。
学生运营管理：学生批量 upsert、禁用/恢复、批量分班、备注、跟进任务已完成接口和集成测试；Taro 租户学生运营页已接学生创建/更新、状态切换、批量导入、批量分班、备注和跟进任务第一版；后续补批量 CRM 推送、自动学习督导和更细导入模板体验。
旧题库运营缺口已补一批：考试日期/倒计时、题目反馈/纠错处理、每日签到积分和积分流水、学习排行榜已完成接口和集成测试。
勋章管理已完成租户后台维护、手动发放、重复发放幂等、学生个人中心展示、权限点和集成测试；后续补自动发放规则和活动联动。
旧商城体验已补齐主链路：订单详情、订单状态轮询、激活码预检查、自用激活码拒绝、优惠券前台领取、下单抵扣、零元订单自动支付开通权益，且手工支付确认已限制为租户后台 tenant:payment:write 权限。
公共题库商业化基础闭环已完成：平台公共题库可由平台管理员按 SaaS 套餐/指定租户/全部活跃租户授权；租户内容管理员只能看到自己被授权的公共题库，并可采纳为本租户题库、内容入口、题目集合和题目快照，采纳后可直接进入练习 session；平台题库后续新增/更新题目可通过手动同步 API 或 public-banks worker 进入租户副本，并生成租户内容通知；租户自改题目会返回冲突并保留原内容，后台可查询最近一次冲突明细，并可单条或批量选择采纳平台版本/保留本地版本，冲突处理完成后通知自动 resolved。
租户后台数据看板已完成首版聚合 API：GET /api/tenant-admin/dashboard，支持租户/地区维度的收益、注册、学习、内容、激活码、反馈、趋势、24h 活跃、套餐销量和运营动态，前端可直接联调。
支付/退款补偿 worker 已完成：apps/worker --job commerce 可查询微信/支付宝支付和处理中退款，补偿漏通知订单，支付成功幂等开通权益，退款成功幂等更新退款/订单/支付并在全额退款时撤销订单权益。
资金对账和差错工单闭环已完成：commerce_reconciliation_batches/items 和 /api/commerce/reconciliation/* 支持手工/API 导入供应商账单行、预览差异、生成批次统计、查询异常、租户隔离、权限点 tenant:reconciliation:read/write 和审计日志；commerce_reconciliation_issues/events 支持异常明细创建工单、分配、开始处理、升级、解决、忽略、重开和事件留痕，且不直接修改订单/支付/退款/权益。
内容资源复检 worker 已完成：apps/worker --job assets 可复检 content_assets 中的托管对象元数据，正常资源写回复检证据，异常资源自动置为 failed + draft 并写入审计和安全标记。
题库导出 worker 已完成：apps/worker --job exports 可抢占 pdf/docx/daily_practice_zip 导出任务，渲染 PDF/Word、水印或每日一练图片素材包，写入对象存储或本地开发存储，创建 content_assets 并回填 assetId/hash/size；daily_practice 已支持每日一练九宫格 metadata、PDF/Word 基础版式、9 张 PNG/SVG 卡片和拼图 ZIP。
本地验证：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 复检，异常托管对象会自动下架并记录审计。
- 已补资源访问事件 content_asset_access_events，覆盖上传签名/确认、学生下载/预览、后台下载/预览的 granted/denied、短 TTL、签名模式、IP 和 UA。
- 已收紧锁定资源 CDN 边界：members/svip/private 外链默认拒绝，必须显式 provider-managed 才允许；视频绑定资源也复用该策略。
- 继续补动态水印、杀毒扫描、CDN 刷新和对象生命周期策略。
- content_assets 继续作为资源台账，不允许前端绕过台账直接访问私有资源。
真实导入 dry-run
- 从 PocketBase 导出现有用户、题库、单词、知识手册、分数线、订单、权益数据。
- 已补 npm run pb:import:dry-run 静态迁移报告工具；拿到真实导出后先跑 dry-run，再跑 pb:import:json 和 pb:import:validate。
- 对题目 JSON、单词、知识手册、分数线、视频走后端 preview/import API 做二次验证。
部署配置
- 生产 .env 模板和 npm run readiness:production / npm run readiness:production:db 已补，后续上云必须作为验收 gate。
- 确认数据库迁移流程、备份恢复、日志、告警。
- 准备 API 容器部署和 Supabase 云端/自托管连接方案。

P1 商用功能完善

支付
- 已完成微信支付 JSAPI、支付宝 WAP/H5 的创建支付参数和 webhook 幂等开通权益。
- 已完成内部退款状态机、退款申请/审核/处理接口、微信/支付宝发起退款、微信/支付宝退款查询确认、微信/支付宝退款通知 webhook、部分/全额退款状态、全额退款权益撤销和审计事件。
- 已完成支付/退款补偿 worker，可兜底供应商漏通知、处理中退款和重复执行幂等。
- 已完成资金对账手工/API 导入比对、批次/明细/异常查询、差错工单状态流和审计；继续补微信/支付宝官方账单自动下载、人工调整凭证附件、财务复核报表和异常订单运营台。
- 租户自有商户收款和平台代收/服务商模式。
国内登录和短信
- 已完成阿里云短信、腾讯云短信 adapter 的后端实现和本地 fake endpoint 测试。
- 已完成微信小程序 code2Session 登录主链路。
- 已完成手机号绑定/换绑、微信网页登录、QQ 登录基础 API；继续补真实生产账号、回调域名和开放平台联调。
- 旧 PocketBase 用户账号和新身份体系的映射/补绑。
导入体系扩展
- 已完成题目、单词、知识手册、分数线、视频的 CSV/Excel 到规范 JSON 解析适配。
- 已完成大批量异步导入 worker、重试、导入后复检和审计。
- 模板下载、字段映射 API、导入任务详情、导入后复检和 PocketBase JSON dry-run 报告工具已补；Taro 租户内容页已接 JSON/CSV/Excel 文件或粘贴内容、模板下载、后端 preview、字段别名覆盖、同步/异步执行、异步 job 轮询和复检结果详情第一版；后端已对字段映射目标做白名单和危险 key 拦截。
- 继续补真实数据执行验收、导入前抽样校验和导入性能压测。
题库导出增强
- 已完成服务端 JSON、paper_json、print_payload 基础导出和导出 job 台账。
- 已完成 PDF/Word 二进制生成 worker、页面水印、导出发布到 content_assets、后台资源签名下载/预览路径，以及每日一练九宫格 metadata、PDF/Word 基础版式和 ZIP 图片素材包。
- 继续补更精细的试卷模板、导出操作台和多模板排版。
公共题库和租户授权
- 已完成平台公共题库/地区题库的基础授权、租户采纳、题目快照复制和手动同步。
- 已完成 public-banks worker 自动同步、失败记录、审计、同步通知、冲突查询 API 和单条/批量冲突处理 API。
- 继续补按 SaaS 套餐限制地区数量、科目范围、题库范围的更细计费策略。
- 继续补生产定时调度、失败告警和更完整运营后台消息。
视频会员控制
- 已完成视频 SVIP 权限、播放次数扣减、签名播放和播放日志。
- 继续补深度防盗链、动态水印、播放统计。
- 单题视频和通用知识视频混合推荐。
学习统计
- 已完成免费额度、练习访问事件、模考交卷评分报告、练习历史、正确率趋势、题型分布、错题复习计划。
- 已完成单词复习算法、每日计划和复习上报。
- 已完成排行榜主接口；继续补防刷、日/周榜预聚合和运营后台排名看板。
- Taro 已有后端 session detail 续练、本地断点恢复、倒计时和阅读理解/案例分析多小题第一版；继续补复盘体验、长题干/公式图片混排和更细统计口径。
订单和营销体验
- 已完成订单详情、订单状态轮询、激活码预检查、优惠券前台领取、下单抵扣计算和内部退款状态机。
- 已完成支付/退款补偿 worker、资金对账导入比对和差错工单；继续补异常订单运营台、优惠券核销报表和复杂活动规则。
积分和反馈增强
- 已完成每日签到、积分流水、反馈提交、租户后台处理、奖励积分幂等。
- 已完成勋章后台维护、手动发放和学生端展示。
- 继续补积分兑换、活动任务、连续签到奖励配置、勋章自动发放、处理通知和反馈聚合统计。
数据看板

已完成首版实时聚合接口，覆盖收益、注册趋势、答题次数、收入趋势、题型分布、科目数量、题目总量、套餐销量、运营动态、24h 活跃度和激活码使用情况。
继续补日/周/月预聚合 worker、缓存策略、慢 SQL 监控和大租户性能压测。
分佣结算基础闭环已完成；继续补销售/代理转化、结算导出、真实打款、凭证和客资跟进效果看板。

销售/代理分佣

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

学生运营管理

已完成学生列表、学生资料维护、班级分组、教师范围可见、学生批量导入、禁用/恢复、批量分班、学生备注和跟进任务。
已完成 Taro 学生运营页第一版：学生创建/更新、状态禁用/恢复、批量导入、批量分班、备注、跟进任务和完成跟进。
继续补批量 CRM 推送、学习督导自动化、跟进效果统计和更细导入模板体验。

AI 择校推荐

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

P2 运营体验和企业交付

自定义角色
- 已完成租户内角色模板、菜单可见、模块可见、字段级权限和权限变更审计基础 API。
- 已完成班级/教师/学生范围权限 API，教师只能查看自己负责班级的学生。
- 已完成 Taro 租户设置页角色模板可视化配置第一版，支持创建、编辑、停用、权限点、菜单、模块、字段和基础数据范围配置。
- 已完成 Taro 成员绑定模板第一版，支持成员搜索/新建、绑定角色模板、成员状态和额外权限覆盖；工作台已按后端权限矩阵隐藏不可见模块。
- 继续补更细的数据范围 UI，例如地区、题库、销售团队、本人客资、班级学生组合规则，以及成员批量运营和完整后台菜单权限联动。
主题系统
- 已完成平台默认三套主题。
- 已完成租户自定义主色、强调色、Logo、图标集和分享图的草稿预览/发布 API。
- 已完成 Taro 租户设置页主题模板、草稿和发布第一版。
- 继续补素材库、启动图/小程序分享图上传到 content_assets 的后台体验、更多主题模板和更细组件级视觉 token。
CRM worker
- 已完成 apps/worker CRM 队列消费、generic webhook、钉钉、飞书、企业微信机器人 adapter、签名、失败重试和日志。
- 继续补轮询/定向分配、富卡片模板、失败告警、死信运营后台和批量 CRM 推送。
运维
- 后台操作审计报表。
- 定时备份、恢复演练。
- 性能压测、慢 SQL、索引审查。

Taro 前端开发 TODO

架构目标

已新建 apps/taro，不要继续在旧 React Web 上堆兼容。
H5 和小程序共用同一套业务 API client。
租户通过域名、小程序配置或启动参数解析。
页面主题、品牌、功能开关都从后端租户配置读取；学生端和后台只消费 /api/tenant/resolve 的已发布 branding.theme/publicAssets，租户后台草稿只通过 /api/tenant-admin/theme 查看。
当前已完成 H5 学生端、租户后台、平台后台三套构建入口和统一 API client；学生端、租户后台、平台后台都有第一批真实 API 页面；学生端已补地区选择、刷题答题卡、后端权威断点续练、本地进度恢复、模拟倒计时、主观题后端自评、阅读理解/案例分析多小题、错题/收藏复习、题目反馈、视频解析、练习/模考报告、会员收银台、订单详情和售后入口第一版；平台后台已接入创建租户、状态变更、订阅、账单、收款、用量和公共题库授权第一版写操作；租户后台已接权限驱动工作台、学生运营操作台、主题模板预览/发布、角色模板、成员绑定和 CRM/分佣操作台第一版；下一步补长题干/公式图片混排、状态管理、更细数据范围 UI、学生批量运营增强和小程序兼容验证。

第一批页面

租户启动与首页
- 调 /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，不在页面里硬编码租户密钥。

20 KiB Raw Blame History Unescape Escape

后续开发 TODO

当前后端基线

后端待补功能

P0 上云测试前必须补齐

P1 商用功能完善

P2 运营体验和企业交付

Taro 前端开发 TODO

架构目标

第一批页面

前端接入原则

推荐下一步顺序

20 KiB

Raw Blame History