xiongyuxing/gongxue-base
1
0
Fork 0
forked from wangziqi/gongxue-base
Code Pull Requests Activity
Files
db86fa37059e9fdd879074bb0fb57a442fb6582c
gongxue-base/docs/refactor/next-development-todo.md

25 KiB
Raw Blame History

后续开发 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 写入访问事件或播放事件。
    • 已补 Taro 学生资料页水印容器第一版：预览/下载都先请求后端短签名，展示过期时间、签名模式和 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、发票、异常调整单和客资跟进效果看板。
  1. 销售/代理分佣
  • 已完成租户默认分佣比例、成员分佣比例、激活码批次分佣比例。
  • 已完成订单和激活码两类来源的佣金归因，且只统计客资绑定后的成交。
  • 已完成结算单生成、重复结算拦截、审核、打款状态、已打款锁定、CSV/JSON 导出、打款凭证登记、凭证复核、租户隔离和销售/代理本人范围权限。
  • 继续补真实打款 provider、发票管理、批量凭证上传、销售团队分佣看板和异常调整单。
  1. 学生运营管理
  • 已完成学生列表、学生资料维护、班级分组、教师范围可见、学生批量导入、禁用/恢复、批量分班、学生备注和跟进任务。
  • 已完成 Taro 学生运营页第一版：学生创建/更新、状态禁用/恢复、批量导入、批量分班、备注、跟进任务和完成跟进。
  • 继续补批量 CRM 推送、学习督导自动化、跟进效果统计和更细导入模板体验。
  1. 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 安全渲染、H5 KaTeX 公式渲染、私有资源 ID 题图短签名渲染、逐题复盘、背单词卡片学习/发音/收藏练习第一版；平台后台已接入创建租户、状态变更、订阅、账单、收款、用量和公共题库授权第一版写操作；租户后台已接权限驱动工作台、学生运营操作台、主题模板预览/发布、角色模板、成员绑定和 CRM/分佣操作台第一版；下一步补小程序公式真机验收、题图资源字段化、个人中心任务系统、状态管理、更细数据范围 UI、学生批量运营增强和小程序兼容验证。

第一批页面

  1. 租户启动与首页

    • 调 /api/tenant/resolve
    • 读取品牌、主题、Banner、公告、功能开关
    • 展示题库入口、背单词、知识手册、分数线、资料、会员

  2. 登录

    • 迁移期可先接短信 mock 或临时登录
    • 生产接微信小程序登录、短信登录、QQ/微信网页登录真实账号

  3. 题库

    • content_entries/content_nodes
    • question_collections/practice_blueprints
    • 顺序刷题、随机刷题、全真模拟
    • 答题、解析、错题、收藏、视频解析入口

  4. 背单词

    • 单元列表、单词列表
    • 学习状态、收藏、统计
    • 每日新词、复习计划、认识/不认识上报
    • Taro 已接卡片翻转、发音、美/英音切换、收藏练习、单词跳转和本地位置恢复；后续补租户级发音源配置、收藏专项统计和小程序真机音频兼容验收

  5. 知识手册

    • 手册入口、章节、小节、知识点阅读
    • RichContent 已支持 Markdown 图片、基础表格、代码、加粗、H5 KaTeX 公式渲染、私有资源 ID 短签名和安全过滤；后续补搜索、高亮、目录锚点、小程序公式真机验收和题图资源字段化

  6. 分数线

    • 院校、专业、年份、动态字段筛选
    • 趋势图

  7. 资料下载

    • PDF 列表、权限提示、短签名预览、下载确认和动态水印 traceId 展示已接第一版

  8. 个人中心

    • 会员权益、订单、激活码兑换
    • 错题本、收藏夹、学习统计、排行榜、勋章
    • Taro 已接学习报告、14 天趋势、题型表现、最近练习和 7 日答题榜当前排名第一版
    • 会员收银台、优惠券领取、下单、支付参数、订单详情、状态轮询和售后入口已接第一版

前端接入原则

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

推荐下一步顺序

  1. 补租户后台写操作台：公共题库采纳/同步、冲突查看、单条/批量冲突采纳平台或保留本地、导入问题、模板预览/下载、上传/粘贴 preview/import、字段映射编辑、异步导入轮询、导入后复检详情、权限驱动工作台、学生创建/更新/批量导入/批量分班/备注/跟进、角色模板配置、成员绑定模板、CRM 配置/队列/跟进分配策略、分佣规则/成员比例/结算生成审核打款/导出/凭证复核已接第一版；继续补成员批量运营、更细数据范围 UI、真实打款 provider 和发票。
  2. 继续补 Taro 学生端旧体验：地区选择、刷题答题卡、后端权威断点续练、本地进度恢复、模拟倒计时、主观题后端自评、阅读理解/案例分析多小题、视频播放、反馈、模考报告、逐题复盘、错题/收藏专题、个人中心学习报告、收银台、订单详情、售后入口、题干/解析/知识手册 RichContent 安全渲染、H5 KaTeX 公式渲染、私有资源 ID 题图短签名、背单词卡片学习/发音/收藏练习、资料短签名水印预览/下载确认已接第一版；继续补小程序公式真机验收、题图资源字段化、个人中心任务系统、背单词更细统计、小程序支付容器、分享场景和状态管理。
  3. 补平台后台增强：租户详情/编辑、平台审计报表、自动计费、账单批量操作和更细平台权限点。
  4. 云服务器部署 Supabase/PostgreSQL 和 API，配置对象存储生产环境变量，跑 check:refactor 的远程等价测试。
  5. 导出现有 PocketBase 数据，做完整 dry-run 迁移。
  6. 并行补真实登录、真实生产账单格式验收、异常订单运营台、对象存储真实 AV/内容安全服务联调、转码/CDN 级水印/生命周期、题库导出模板精排/操作台、公共题库生产定时调度和失败告警。
  7. 前后端联调通过后，再做支付、权限、数据导入、资料下载、视频播放的商用验收。