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

237 lines
24 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 后续开发 TODO
更新时间2026-06-29
## 当前后端基线
后端已经完成可本地验证的商用 SaaS 骨架:
- Supabase/PostgreSQL 多租户 schema、RLS、索引、触发器。
- Node.js API 分层:`core/features`
- 学生端核心 API题库、练习、答题、模考交卷报告、练习历史、学习统计、排行榜、错题复习计划、错题、收藏、背单词、知识手册、分数线、视频播放签名、资料、订单详情/状态轮询、优惠券领取/抵扣、激活码预检查/兑换、权益、个人中心、考试倒计时、签到积分、题目反馈、勋章。
- 租户后台 API品牌、域名、设置、支付账户、登录 provider、私密密钥、活动、考试日期、题目反馈处理、激活码、优惠券、勋章管理/发放、成员权限、审计、内容管理、班级/教师/学生、学生批量导入、批量分班、学生备注、跟进任务。
- 租户主题系统平台默认经典蓝、专注绿、高对比三套模板租户可保存草稿、发布主题公开租户解析只返回已发布主题Taro 租户设置页已接第一版主题操作台。
- 平台后台 API租户、SaaS 套餐、订阅、账单、服务费收款、用量。
- 销售/代理/CRM 增长链路邀请码、扫码事件、首绑保护、团队、统计、CRM 配置/队列、`none/direct/round_robin/referrer` 跟进分配策略、CRM worker、分佣规则、成员比例、订单/激活码归因、结算生成、审核、打款状态、结算导出和凭证复核Taro 租户营销中心已接 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 预览、校验、导入、幂等、审计。
- 内容导出:题库 JSON、`paper_json`、打印 payload 导出基础已完成,支持集合/入口/分类范围、导出 job、审计、跨租户拒绝、答案/解析开关和复合题子题脱敏。
- 租户组织范围:班级、班级成员、教师/班主任/助教/学生分组,教师按负责班级查看学生,字段权限可脱敏学生手机号。
- 学生运营管理:学生批量 upsert、禁用/恢复、批量分班、备注、跟进任务已完成接口和集成测试Taro 租户学生运营页已接学生创建/更新、状态切换、批量导入、批量分班、备注和跟进任务第一版;后续补批量 CRM 推送、自动学习督导和更细导入模板体验。
- 旧题库运营缺口已补一批:考试日期/倒计时、题目反馈/纠错处理、每日签到积分和积分流水、学习排行榜已完成接口和集成测试。
- 勋章管理已完成租户后台维护、手动发放、重复发放幂等、学生个人中心展示、权限点和集成测试;后续补自动发放规则和活动联动。
- 旧商城体验已补齐主链路:订单详情、订单状态轮询、激活码预检查、自用激活码拒绝、优惠券前台领取、下单抵扣、零元订单自动支付开通权益,且手工支付确认已限制为租户后台 `tenant:payment:write` 权限。
- 优惠券商用规则已补齐后端和 Taro 租户后台第一版:租户后台可配置启停/归档、活动分组、最低金额、优惠封顶、单用户限次、首单限制、适用套餐/地区和 metadata学生领取/下单会由后端复核规则,后台可查核销明细和按活动/日期/券聚合的核销报表。
- 公共题库商业化基础闭环已完成:平台公共题库可由平台管理员按 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` 支持异常明细创建工单、分配、开始处理、升级、解决、忽略、重开和事件留痕,且不直接修改订单/支付/退款/权益。
- 微信/支付宝官方账单下载地基已完成:`commerce_bill_download_jobs``POST /api/commerce/reconciliation/provider-bills/request``GET /api/commerce/reconciliation/provider-bills/jobs``apps/worker --job provider-bills` 已接入worker 负责后端签名申请下载 URL、hash 校验、JSON/CSV/ZIP 账单解析、复用 `provider_download` 对账导入、任务状态回写和密钥脱敏。
- 异常订单运营台和人工调整凭证已完成后端第一版:`/api/commerce/operations/anomalies` 聚合未关闭对账工单、失败官方账单任务、支付事件错误、长时间 pending 支付/退款;`/api/commerce/adjustment-vouchers*` 支持凭证提交、审批、驳回、作废、事件轨迹和复核报表,使用 `tenant:reconciliation:review` 做独立复核权限,且审批凭证不会直接修改订单、支付、退款或权益。
- 内容资源复检与安全扫描 worker 已完成:`apps/worker --job assets` 可复检 `content_assets` 中的托管对象元数据,并执行内置 `metadata_rules` 和可选外部 HTTP scanner正常资源写回复检/扫描证据,异常资源自动置为 `failed/skipped + draft``security_scan_status=failed`,外部 scanner 不可用默认 fail-closed并写入审计、扫描事件和安全标记。
- 题库导出 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。
- 租户后台媒体运营报表已完成:`/api/tenant-content/media-analytics/summary``asset-events``video-events` 可按 7/30/90 天、资源、视频、用户和水印 traceId 查询资料访问、视频播放、拒绝访问、Top 资源/视频和日趋势;仅开放给 owner/admin/operator 或 `content:analytics:read` 权限角色,前端不会拿到签名 URL 或播放 token。
- 本地验证:`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 复检,异常托管对象会自动下架并记录审计。
- 已补内容资源安全扫描状态机:确认上传后进入 `securityScanStatus=pending`,扫描通过后才能发布、下载、预览或视频播放;后台可查 `/api/tenant-content/assets/security-scan-events`
- 已补资源访问事件 `content_asset_access_events`,覆盖上传签名/确认、学生下载/预览、后台下载/预览的 granted/denied、短 TTL、签名模式、IP、UA 和动态水印 traceId。
- 已补签名访问动态水印上下文:学生资料下载/预览、租户后台下载/预览和视频播放都会返回 `watermark`,并将 traceId 写入访问事件或播放事件。
- 已补租户后台媒体运营报表,支持资料/视频访问汇总、Top 资源/视频和 traceId 回查;大租户后续再把实时查询替换为日/周预聚合。
- 已收紧锁定资源 CDN 边界:`members/svip/private` 外链默认拒绝,必须显式 provider-managed 才允许;视频绑定资源也复用该策略。
- 已补外部 HTTP 杀毒/内容安全 scanner 接入层、失败关闭、生产 readiness 阻断和动态水印 traceId 审计;继续联调真实扫描服务、转码/CDN 级水印、CDN 刷新和对象生命周期策略。
- `content_assets` 继续作为资源台账,不允许前端绕过台账直接访问私有资源。
3. 真实导入 dry-run
- 从 PocketBase 导出现有用户、题库、单词、知识手册、分数线、订单、权益数据。
- 已补 `npm run pb:import:dry-run` 静态迁移报告工具;拿到真实导出后先跑 dry-run再跑 `pb:import:json``pb:import:validate`
- 对题目 JSON、单词、知识手册、分数线、视频走后端 preview/import API 做二次验证。
4. 部署配置
- 生产 `.env` 模板和 `npm run readiness:production` / `npm run readiness:production:db` 已补,后续上云必须作为验收 gate。
- 确认数据库迁移流程、备份恢复、日志、告警。
- 准备 API 容器部署和 Supabase 云端/自托管连接方案。
### P1 商用功能完善
1. 支付
- 已完成微信支付 JSAPI、支付宝 WAP/H5 的创建支付参数和 webhook 幂等开通权益。
- 已完成内部退款状态机、退款申请/审核/处理接口、微信/支付宝发起退款、微信/支付宝退款查询确认、微信/支付宝退款通知 webhook、部分/全额退款状态、全额退款权益撤销和审计事件。
- 已完成支付/退款补偿 worker可兜底供应商漏通知、处理中退款和重复执行幂等。
- 已完成资金对账手工/API 导入比对、微信/支付宝官方账单下载任务、批次/明细/异常查询、差错工单状态流、异常订单运营台、人工调整凭证和财务复核报表Taro 租户财务运营台第一版已接退款、官方账单任务、对账异常、差错工单和调整凭证;继续补真实生产账单格式抽样验收和更完整售后体验。
- 租户自有商户收款和平台代收/服务商模式。
2. 国内登录和短信
- 已完成阿里云短信、腾讯云短信 adapter 的后端实现和本地 fake endpoint 测试。
- 已完成微信小程序 `code2Session` 登录主链路。
- 已完成手机号绑定/换绑、微信网页登录、QQ 登录基础 API继续补真实生产账号、回调域名和开放平台联调。
- 旧 PocketBase 用户账号和新身份体系的映射/补绑。
3. 导入体系扩展
- 已完成题目、单词、知识手册、分数线、视频的 CSV/Excel 到规范 JSON 解析适配。
- 已完成大批量异步导入 worker、重试、导入后复检和审计。
- 模板下载、字段映射 API、导入任务详情、导入后复检和 PocketBase JSON dry-run 报告工具已补Taro 租户内容页已接 JSON/CSV/Excel 文件或粘贴内容、模板下载、后端 preview、字段别名覆盖、同步/异步执行、异步 job 轮询和复检结果详情第一版;后端已对字段映射目标做白名单和危险 key 拦截。
- 继续补真实数据执行验收、导入前抽样校验和导入性能压测。
4. 题库导出增强
- 已完成服务端 JSON、`paper_json``print_payload` 基础导出和导出 job 台账。
- 已完成 PDF/Word 二进制生成 worker、页面水印、导出发布到 `content_assets`、后台资源签名下载/预览路径,以及每日一练九宫格 metadata、PDF/Word 基础版式和 ZIP 图片素材包。
- 继续补更精细的试卷模板、导出操作台和多模板排版。
5. 公共题库和租户授权
- 已完成平台公共题库/地区题库的基础授权、租户采纳、题目快照复制和手动同步。
- 已完成 `public-banks` worker 自动同步、失败记录、审计、同步通知、冲突查询 API 和单条/批量冲突处理 API。
- 继续补按 SaaS 套餐限制地区数量、科目范围、题库范围的更细计费策略。
- 继续补生产定时调度、失败告警和更完整运营后台消息。
6. 视频会员控制
- 已完成视频 SVIP 权限、播放次数扣减、签名播放和播放日志。
- 已补播放签名动态水印上下文、traceId 事件、播放进度上报和租户后台播放事件查询;继续补深度防盗链、转码级水印和更细观看行为分析。
- 单题视频和通用知识视频混合推荐。
7. 学习统计
- 已完成免费额度、练习访问事件、模考交卷评分报告、练习历史、正确率趋势、题型分布、错题复习计划。
- 已完成单词复习算法、每日计划和复习上报。
- 已完成排行榜主接口;继续补防刷、日/周榜预聚合和运营后台排名看板。
- Taro 已有后端 session detail 续练、本地断点恢复、倒计时和阅读理解/案例分析多小题第一版;继续补复盘体验、长题干/公式图片混排和更细统计口径。
8. 订单和营销体验
- 已完成订单详情、订单状态轮询、激活码预检查、优惠券前台领取、下单抵扣计算、优惠券复杂规则、核销明细/报表和内部退款状态机。
- 已完成支付/退款补偿 worker、官方账单下载 worker、资金对账导入比对、差错工单、异常订单运营台和人工调整凭证复核Taro 财务运营台第一版已接入;继续补学生端售后入口深化、营销活动 UI、真实生产账单格式抽样验收和活动效果看板。
9. 积分和反馈增强
- 已完成每日签到、积分流水、反馈提交、租户后台处理、奖励积分幂等。
- 已完成勋章后台维护、手动发放和学生端展示。
- 继续补积分兑换、活动任务、连续签到奖励配置、勋章自动发放、处理通知和反馈聚合统计。
10. 数据看板
- 已完成首版实时聚合接口覆盖收益、注册趋势、答题次数、收入趋势、题型分布、科目数量、题目总量、套餐销量、运营动态、24h 活跃度和激活码使用情况。
- 继续补日/周/月预聚合 worker、缓存策略、慢 SQL 监控和大租户性能压测。
- 分佣结算基础闭环已完成;继续补销售/代理转化、真实打款 provider、发票、异常调整单和客资跟进效果看板。
11. 销售/代理分佣
- 已完成租户默认分佣比例、成员分佣比例、激活码批次分佣比例。
- 已完成订单和激活码两类来源的佣金归因,且只统计客资绑定后的成交。
- 已完成结算单生成、重复结算拦截、审核、打款状态、已打款锁定、CSV/JSON 导出、打款凭证登记、凭证复核、租户隔离和销售/代理本人范围权限。
- 继续补真实打款 provider、发票管理、批量凭证上传、销售团队分佣看板和异常调整单。
12. 学生运营管理
- 已完成学生列表、学生资料维护、班级分组、教师范围可见、学生批量导入、禁用/恢复、批量分班、学生备注和跟进任务。
- 已完成 Taro 学生运营页第一版:学生创建/更新、状态禁用/恢复、批量导入、批量分班、备注、跟进任务和完成跟进。
- 继续补批量 CRM 推送、学习督导自动化、跟进效果统计和更细导入模板体验。
13. AI 择校推荐
- 已完成 `ai_recommendation_reports` 报告台账、SVIP 门禁、学生输入 schema、地区/分数线上下文、`local_rules` 稳定 JSON 输出、报告列表/详情接口和 Taro 学生端基础页。
- 继续补真实 AI provider adapter、租户级 `app_private.tenant_secrets(secret_scope='ai')` 密钥联调、prompt 版本管理、运营后台配置、报告 PDF 渲染和人工复核流程。
### P2 运营体验和企业交付
1. 自定义角色
- 已完成租户内角色模板、菜单可见、模块可见、字段级权限和权限变更审计基础 API。
- 已完成班级/教师/学生范围权限 API教师只能查看自己负责班级的学生。
- 已完成 Taro 租户设置页角色模板可视化配置第一版,支持创建、编辑、停用、权限点、菜单、模块、字段和基础数据范围配置。
- 已完成 Taro 成员绑定模板第一版,支持成员搜索/新建、绑定角色模板、成员状态和额外权限覆盖;工作台已按后端权限矩阵隐藏不可见模块。
- 继续补更细的数据范围 UI例如地区、题库、销售团队、本人客资、班级学生组合规则以及成员批量运营和完整后台菜单权限联动。
2. 主题系统
- 已完成平台默认三套主题。
- 已完成租户自定义主色、强调色、Logo、图标集和分享图的草稿预览/发布 API。
- 已完成 Taro 租户设置页主题模板、草稿和发布第一版。
- 继续补素材库、启动图/小程序分享图上传到 `content_assets` 的后台体验、更多主题模板和更细组件级视觉 token。
3. CRM worker
- 已完成 `apps/worker` CRM 队列消费、generic webhook、钉钉、飞书、企业微信机器人 adapter、签名、失败重试和日志。
- 已完成 CRM 配置中的跟进分配策略:`none/direct/round_robin/referrer`,后端校验候选人必须是当前租户内 active 的销售/代理/运营/教师/管理员,首绑客资后写入 `assignedToUserId` 并把 assignee 放进 CRM 队列 payload。
- 继续补富卡片模板、失败告警、死信运营后台和批量 CRM 推送。
4. 运维
- 后台操作审计报表。
- 定时备份、恢复演练。
- 性能压测、慢 SQL、索引审查。
## Taro 前端开发 TODO
### 架构目标
- 已新建 `apps/taro`,不要继续在旧 React Web 上堆兼容。
- H5 和小程序共用同一套业务 API client。
- 租户通过域名、小程序配置或启动参数解析。
- 页面主题、品牌、功能开关都从后端租户配置读取;学生端和后台只消费 `/api/tenant/resolve` 的已发布 `branding.theme/publicAssets`,租户后台草稿只通过 `/api/tenant-admin/theme` 查看。
- 当前已完成 H5 学生端、租户后台、平台后台三套构建入口和统一 API client学生端、租户后台、平台后台都有第一批真实 API 页面;学生端已补地区选择、刷题答题卡、后端权威断点续练、本地进度恢复、模拟倒计时、主观题后端自评、阅读理解/案例分析多小题、错题/收藏复习、题目反馈、视频解析、练习/模考报告、会员收银台、订单详情、售后入口、题干/选项/解析/知识手册 RichContent 安全渲染、逐题复盘、背单词卡片学习/发音/收藏练习第一版;平台后台已接入创建租户、状态变更、订阅、账单、收款、用量和公共题库授权第一版写操作;租户后台已接权限驱动工作台、学生运营操作台、主题模板预览/发布、角色模板、成员绑定和 CRM/分佣操作台第一版;下一步补真正 KaTeX/小程序公式方案、私有题图签名资源映射、状态管理、更细数据范围 UI、学生批量运营增强和小程序兼容验证。
### 第一批页面
1. 租户启动与首页
-`/api/tenant/resolve`
- 读取品牌、主题、Banner、公告、功能开关
- 展示题库入口、背单词、知识手册、分数线、资料、会员
2. 登录
- 迁移期可先接短信 mock 或临时登录
- 生产接微信小程序登录、短信登录、QQ/微信网页登录真实账号
3. 题库
- `content_entries/content_nodes`
- `question_collections/practice_blueprints`
- 顺序刷题、随机刷题、全真模拟
- 答题、解析、错题、收藏、视频解析入口
4. 背单词
- 单元列表、单词列表
- 学习状态、收藏、统计
- 每日新词、复习计划、认识/不认识上报
- Taro 已接卡片翻转、发音、美/英音切换、收藏练习、单词跳转和本地位置恢复;后续补租户级发音源配置、收藏专项统计和小程序真机音频兼容验收
5. 知识手册
- 手册入口、章节、小节、知识点阅读
- RichContent 已支持 Markdown 图片、基础表格、代码、加粗、公式占位和安全过滤;后续补搜索、高亮、目录锚点、真正公式渲染和私有资源签名映射
6. 分数线
- 院校、专业、年份、动态字段筛选
- 趋势图
7. 资料下载
- PDF 列表、权限提示、预览、下载
8. 个人中心
- 会员权益、订单、激活码兑换
- 错题本、收藏夹、学习统计、排行榜、勋章
- 会员收银台、优惠券领取、下单、支付参数、订单详情、状态轮询和售后入口已接第一版
### 前端接入原则
- 不在前端实现最终权限判断,前端只做 UI 可见性控制。
- 不在前端直接拼接私有资源 URL统一请求后端签名。
- 不把旧 PocketBase 字段当成长期模型,优先使用新 API 返回的 `entryId/contentNodeId/collectionId/blueprintId`
- 小程序码、支付、登录等平台能力统一走 provider adapter不在页面里硬编码租户密钥。
## 推荐下一步顺序
1. 补租户后台写操作台:公共题库采纳/同步、冲突查看、单条/批量冲突采纳平台或保留本地、导入问题、模板预览/下载、上传/粘贴 preview/import、字段映射编辑、异步导入轮询、导入后复检详情、权限驱动工作台、学生创建/更新/批量导入/批量分班/备注/跟进、角色模板配置、成员绑定模板、CRM 配置/队列/跟进分配策略、分佣规则/成员比例/结算生成审核打款/导出/凭证复核已接第一版;继续补成员批量运营、更细数据范围 UI、真实打款 provider 和发票。
2. 继续补 Taro 学生端旧体验:地区选择、刷题答题卡、后端权威断点续练、本地进度恢复、模拟倒计时、主观题后端自评、阅读理解/案例分析多小题、视频播放、反馈、模考报告、逐题复盘、错题/收藏专题、收银台、订单详情、售后入口、题干/解析/知识手册 RichContent 安全渲染、背单词卡片学习/发音/收藏练习已接第一版;继续补真正 KaTeX/小程序公式方案、私有题图签名资源映射、背单词更细统计、小程序支付容器、分享场景和状态管理。
3. 补平台后台增强:租户详情/编辑、平台审计报表、自动计费、账单批量操作和更细平台权限点。
4. 云服务器部署 Supabase/PostgreSQL 和 API配置对象存储生产环境变量`check:refactor` 的远程等价测试。
5. 导出现有 PocketBase 数据,做完整 dry-run 迁移。
6. 并行补真实登录、真实生产账单格式验收、异常订单运营台、对象存储真实 AV/内容安全服务联调、转码/CDN 级水印/生命周期、题库导出模板精排/操作台、公共题库生产定时调度和失败告警。
7. 前后端联调通过后,再做支付、权限、数据导入、资料下载、视频播放的商用验收。