gongxue-base/docs/refactor/legacy-feature-gap-matrix.md

旧题库功能差距矩阵

更新时间：2026-06-29

旧项目位于 F:\project\参考\旧题库项目，只作为功能、样式、交互和迁移参考。新项目不再复刻 PocketBase/SQLite 的数据结构，而是以新多租户 SaaS 模型为准。

状态说明：

• 已覆盖：新后端已有对应模型和接口。
• 部分覆盖：已有主干，但商用体验或边界还要补。
• 本地待推：本地代码已实现并通过过验证，但尚未提交/推送到 Gitea。
• 未覆盖：需要新增后端能力。
• 前端为主：后端已有基础，主要由 Taro/H5 实现展示和交互。

学生端功能

旧功能/页面	旧项目参考	新后端状态	待补齐
登录/注册	pages/Login.tsx	部分覆盖	短信、Supabase JWT、微信小程序登录主链路、微信网页登录、QQ OAuth、手机号绑定/换绑已有；生产账号、回调域名和真实开放平台联调待补
选地区	pages/RegionSelector.tsx	已覆盖	需要前端按租户套餐和权益展示可选地区
首页/学生看板	pages/StudentDashboardNew.tsx	部分覆盖	品牌、Banner、公告、FAQ、时间线、考试倒计时、入口、个人统计有基础；缺完整运营动态和学习任务聚合
题库入口	pages/SubjectSelector.tsx、RegionArchitectureEditor.tsx	已覆盖	前端应改接 content_entries/content_nodes
多级分类树	旧 module/subject/category 树	已覆盖	新后端支持任意深度和 marker_type；前端不要写死层级
顺序刷题	pages/Quiz.tsx	已覆盖	免费额度/SVIP 校验、session 快照、练习历史、趋势统计和题目反馈已由后端强制；继续补断点续练
随机刷题	pages/Quiz.tsx	已覆盖	已有 blueprint/session 快照、访问控制和历史统计，前端需按 mode 调用
全真模拟	components/AdminMockexam、MockExamConfigModal.tsx	部分覆盖	blueprint、session 快照、交卷评分、分段统计和错题解析汇总已覆盖；后续补排行榜/排名、断点续练、复盘体验
错题本	用户 stats/错题逻辑	已覆盖	错题列表、移出错题、复习计划和 wrong_review 后端组卷已覆盖；后续补更细的间隔复习算法
收藏夹	WordFavoritesPage.tsx、题目收藏	已覆盖	题目和单词收藏已有
题目视频	VideoPlayer.tsx	部分覆盖	题目视频查询、播放签名、SVIP/次数扣减、播放日志已有；缺深度防盗链、动态水印、播放统计报表
背单词	VocabularyPage.tsx、VocabularyQuiz.tsx	部分覆盖	单词列表、进度、收藏、统计、每日计划和后端复习调度已覆盖；后续补收藏练习体验、发音/音频策略、排行榜和更精细的间隔算法参数
知识手册	Handbook*.tsx	已覆盖	前端需做好 Markdown/公式/图片渲染和搜索体验
分数线	ScorelinePage.tsx	已覆盖	动态字段/趋势、后台维护和 JSON 批量导入已有；后续补复杂筛选优化和 AI 择校数据上下文
商城/SVIP	Store.tsx、SvipModal.tsx	部分覆盖	套餐、订单、订单详情/状态轮询、权益、激活码预检查/兑换、优惠券领取/下单抵扣、微信支付/支付宝 provider 主链路、内部退款状态机、微信/支付宝发起退款、退款查询确认、退款通知 webhook、支付/退款补偿 worker 和全额退款权益撤销已有；缺完整资金流水对账、异常订单运营台和前端收银台/售后体验
个人中心	Profile.tsx	部分覆盖	基本资料、手机号绑定/换绑、权益、订单统计、练习历史、学习统计、签到积分、考试倒计时、趋势和勋章展示 API 已有；缺学习报告可视化
资料下载	QuestionExporterPublishModal.tsx 等	部分覆盖	资源台账、上传确认、签名下载和 PDF/图片预览基础已有；缺水印、防盗链、杀毒扫描和 worker 复检
AI 择校推荐	业务规划新增	未覆盖	需设计学生输入 schema、地区数据上下文、AI JSON 输出、PDF 报告
题目反馈	02-API接口.md 用户反馈	部分覆盖	学生提交、本人列表、租户后台处理、状态事件、反馈奖励积分已覆盖；缺处理通知、前端消息提醒和批量统计
签到积分	Profile.tsx、02-API接口.md	部分覆盖	每日签到、连续签到基础、积分流水、重复签到幂等已覆盖；缺积分兑换、活动任务和更完整的运营规则
排行榜	leaderboard.pb.js、02-API接口.md	部分覆盖	已有刷题数、积分、背单词、模考最高分排行榜，支持租户/地区/班级范围和当前用户排名；后续补防刷、日/周榜预聚合、运营后台排名看板

租户后台功能

旧功能/组件	新后端状态	待补齐
用户管理	已覆盖	租户成员、学生列表、学生资料、批量学生 upsert、禁用/恢复、批量分班、学生备注、跟进任务已实现；批量 CRM 推送、补绑、学习督导自动化待补
销售/代理管理	部分覆盖	referral/team/stats 已有；分佣设置、订单/激活码归因、结算单生成、审核、打款状态和本人/全局权限范围已覆盖；还缺真实打款、导出、发票/凭证和分佣看板
班级/教师管理	已覆盖	班级、班级成员、教师/班主任/助教/学生范围权限已有；可视化 UI 和更细数据范围组合待补
数据看板	部分覆盖	租户 dashboard 聚合 API 已覆盖收益、注册、答题、活跃、题型、科目、题量、套餐销量、运营动态、24h 活跃和激活码使用；后续补预聚合 worker、销售转化和分佣结算看板
地区管理	部分覆盖	地区和内容入口已有；平台公共题库已可按 SaaS 套餐/租户授权并由租户采纳；还缺更完整的全国/单地区套餐 UI 和版本同步策略
品牌配置	已覆盖	需要前端做预览和主题发布体验
自定义域名	已覆盖	生产需补 DNS 校验、证书状态、回源校验
主题系统	部分覆盖	当前 theme JSON 可用；缺三套平台主题模板和素材管理
商户收款配置	部分覆盖	配置 API 有；缺真实支付 provider 和验签
登录配置	部分覆盖	配置 API 有；缺真实短信/OAuth provider 实现
Banner/公告/FAQ/活动	已覆盖	前端运营后台可以接
考试日期/倒计时	已覆盖	租户后台维护、学生端和公开目录查询已有；前端需展示地区/院校匹配结果
SVIP 套餐	部分覆盖	地区/科目/题库范围校验已接入练习/资料/视频；后续补分类/专业增项购买和套餐规则 UI
优惠券	已覆盖	后台配置、前台领取、同用户同券幂等、下单抵扣、全额优惠自动开通权益已有；复杂活动规则和核销报表待补
激活码	已覆盖	批次、生成、预检查、兑换、自用码拒绝、地区校验主链路已有
勋章管理	部分覆盖	后台勋章维护、手动发放、重复发放幂等、学生端勋章展示和权限隔离已覆盖；自动发放规则、积分活动联动和前端运营 UI 待补
题库录入	已覆盖	单题创建/更新、题目/单词/知识手册/分数线/视频 JSON/CSV/Excel 同步/异步导入、集合/蓝图、导入后复检、模板下载和字段映射 API 已有；字段映射 UI 和复检结果操作台待补
题库导出 PDF/Word/JSON	部分覆盖	服务端 JSON、paper_json 和打印 payload 导出基础已补，含租户内容编辑权限、跨租户拒绝、答案/解析开关、子题脱敏、导出 job 和审计；PDF/Word 二进制、水印、发布到资料下载和导出 worker 待补
题型分组/模拟卷配置	部分覆盖	question_type_groups 表和 blueprint 有基础；后台配置体验待补
背单词维护	已覆盖	单元/单词 CRUD 和导入已有
知识手册维护	已覆盖	subject/chapter/entry CRUD 和导入已有
分数线维护	已覆盖	字段/院校/专业/记录 CRUD 和 JSON 批量导入已有
视频维护/绑定	已覆盖	video CRUD、question-video 绑定和视频 JSON 批量导入已有
CRM 配置和队列	部分覆盖	配置/队列已有；钉钉/飞书/企微真实发送 worker、签名、重试、死信待补
对象存储配置	部分覆盖	系统 env provider、上传签名、上传确认和预览下载签名已有；租户级存储策略、CDN/水印/杀毒待补

平台 SaaS 后台功能

功能	新后端状态	待补齐
创建/管理租户	已覆盖	平台后台页面待做
SaaS 套餐	部分覆盖	已和公共题库授权打通；后续继续补地区数量、科目范围、存储/学生数等组合套餐限制
年费/服务费账单	已覆盖	真实支付/开票/催缴流程待补
租户用量记录	已覆盖	自动采集 worker 待补
公共题库/地区题库	部分覆盖	已有平台公共题库列表、授权、租户可采纳列表、采纳快照复制、采纳后练习组卷、手动同步 API、自动同步 worker 和冲突查询 API；同步会重新校验授权、复制平台新增/更新题目，并对租户自改题目返回冲突不覆盖
跨租户运营看板	部分覆盖	overview 有基础；缺完整 BI 聚合
租户安全审计	部分覆盖	audit logs 有；缺平台级审计报表

旧功能中应重新设计的点

• 旧项目把很多用户状态放在 JSON 或前端逻辑里，新项目应拆到独立表或后端服务。
• 旧树形结构只作为迁移来源，新前端应使用 content_entries/content_nodes/question_collections/practice_blueprints。
• 旧资料/视频 URL 不能继续让前端直连私有资源，新项目统一走 content_assets 和签名 URL。
• 旧后台的一些“隐藏入口/超管直贴 JSON”应改为 preview/import/job/issue 审计流。
• 旧支付和激活码逻辑要统一成订单、支付事件、权益开通、幂等 webhook。
• 旧销售追踪要升级为租户内角色权限 + 首绑保护 + 分佣结算 + CRM worker。

后端补齐优先级

和旧题库相比仍缺的明确功能

这些是旧项目中已经出现过、但新后端还没有完整业务闭环的功能：

1. 排行榜增强：刷题、模考、背单词、积分排行榜主接口已有；还需防刷、日/周榜预聚合、运营后台排名看板。
2. 账号设置完整流：绑定/更换手机号基础 API 已完成；仍缺头像上传、微信/QQ 账号合并、密码/邮箱能力。
3. 题库导出：服务端 JSON/试卷 payload 导出、权限审计和答案脱敏已补；仍缺 PDF/Word 二进制生成、水印、资料发布和后台导出操作台。
4. 导入扩展：题目/单词/知识手册/分数线/视频已支持 JSON、CSV 和 Excel 预览导入，并可用 executionMode=async 进入 imports worker；导入后复检、模板下载和字段映射 API 已补，仍缺前端字段映射 UI 和真实数据 dry-run。
5. 公共题库商业化：平台公共/地区题库授权、租户快照采纳、手动同步、自动同步 worker、冲突查询和租户自改冲突保护已完成基础闭环；还需版本通知、冲突处理操作台和运营后台 UI。
6. CRM/销售结算：CRM worker、分佣规则、结算单、审核和打款状态基础闭环已完成；仍缺轮询/定向分配、打款导出、凭证和销售结算看板。
7. 题目反馈增强：处理通知、消息提醒、问题聚合统计和内容修复闭环。
8. 积分活动增强：积分兑换、活动任务、连续签到奖励规则和风控。
9. 勋章增强：后台维护和手动发放已有；仍缺按学习行为、签到、积分、活动任务自动发放，以及发放通知。

P0：前端联调到云端前

1. 正式鉴权：API 已支持 Supabase Auth JWT；继续补真实云端 Auth/JWKS 回归、RLS 深测和自定义角色权限细化。
2. 生产配置 fail-fast：默认密钥、CORS=*、mock SMS、平台默认 key 必须禁止。
3. JSON body size limit：导入接口可配置更大限制，但必须有上限。
4. 真实租户隔离测试：跨租户读写、角色越权、资源下载越权。
5. 真实短信/微信小程序登录生产账号联调。

P1：商用主链路

1. 微信/支付宝支付和 webhook 幂等。
2. 对象存储 PDF 预览、视频深度防盗链、动态水印。
3. 字段映射 UI、真实数据 dry-run 和导入复检结果操作台。
4. 数据看板预聚合 worker、销售/代理转化看板和分佣结算。
5. 公共题库版本通知、冲突处理操作台和租户确认/跳过策略。

P2：增强体验

1. 主题模板、素材库、主题预览/发布。
2. 班级、教师、学生分组和学习督导。
3. AI 择校推荐和 PDF 报告。
4. 题库导出二进制生成、试卷排版 worker、每日一练运营工具。