jiaoyu/docs/platform-parity-roadmap.md

同类 AI 教学平台功能路线

本项目目标是实现同类 AI 教学创作平台能力，功能逻辑对标，但品牌、文案、视觉素材和生成模板保持原创。

已落地

能力	当前实现
创作广场	首页资源卡片、分类筛选、快速创作入口
一句话生成互动课件	/courseware/create，AI 生成多页 HTML 互动课件
教学动画	/animation，AI 生成 HTML/CSS 教学动画，支持数学/物理/化学/生物/地理/通用
教学游戏/互动练习	/exercise，8种题型，互动答题（选择/填空）、即时反馈、计分、答案解析
AI 教案	/lesson-plan，按课题、学科、年级、目标生成教案
AI 命题	/exam，按学科、知识点、题型、难度生成试卷
作文批改	/essay-grade，作文评分、评语、优缺点和修改建议
模板社区/资源库	/community、/resources，资源展示、发布、点赞、评论；站内通知系统（评论/收藏自动触发、头部铃铛未读计数、一键已读）
课堂工具/数据回收	/classroom，投票、问答、测验、签到、反馈，支持提交统计
多模态入口雏形	首页支持文本材料上传、图片描述注入、浏览器语音识别
成果导出	课件/动画类 HTML 下载，试卷/教案 Word 下载 + 打印 PDF（浏览器原生打印对话框，可另存为 PDF）
材料智能解析	后端解析 docx、pptx、pdf、xlsx/txt/md/csv/json，图片经 AI 视觉 OCR 提取文字
数据回收学生端	/classroom/join 公开提交页、投放码/链接、投放大屏、实时统计、Excel 导出
会员/积分体系	生成扣费、每日签到、积分流水、余额实时同步
课件编辑器页面管理	添加/复制/移动/删除页面，页面标题、类型与备注编辑
课件编辑器撤销重做	历史栈撤销/重做，Ctrl+Z / Ctrl+Shift+Z 快捷键
管理后台	运营看板、用户管理（启停/角色/发积分）、资源审核（上下架）
数据库迁移	Alembic 初始化，autogenerate + batch 模式，初始迁移已 stamp
接口限流	slowapi 限流：登录/注册、AI 生成、材料解析接口
账号安全	修改密码（校验旧密码/禁止新旧相同/密码强度策略/审计日志）+ 找回密码（手机号验证码重置、限流、验证码 5 分钟过期）+ 头像上传（图片白名单/魔数校验/5MB）
令牌刷新	access_token 过期自动用 refresh_token 静默刷新（单飞去重，避免并发 401 重复刷新），刷新失败才跳登录；登录/注册同时存储 refresh_token
AI 思维导图	/mindmap，AI 生成层次化知识思维导图，交互式可折叠树、分支配色、展开/折叠、HTML 导出、保存到我的导图（CRUD + 耗积分）；后端 mind_maps 表与路由、AIService.generate_mindmap + fallback
动画模板库	36 个参数化学科动画模板：二次函数、正弦波、斜抛运动、简谐振动、分子运动、细胞分裂、太阳系公转、昼夜四季、几何变换、串并联电路、食物链能量流动、水循环、历史时间线、朝代更替轮、诗词意境、分数可视化、光的折射与全反射、酸碱中和滴定、光合作用过程、概率模拟（大数定律）、单词卡片翻转记忆（英语词汇）、英语时态时间轴（英语语法）、汉字笔顺动画（语文识字）、钢琴键盘与简谱（音乐）、三原色混色实验（美术）、二进制拨码开关（信息技术）、拼音四声调对比（语文）、元素周期表交互、化学键与分子结构、pH酸碱指示剂（化学拓展）；覆盖数学/物理/化学(5)/生物/地理/历史/语文/英语/音乐/美术/信息技术/通用 12 学科；TemplateGallery 组件接入动画生成页，免积分即用即改
游戏模板库	20 个参数化教学游戏模板：知识贪吃蛇、翻牌记忆配对、排序拖拽、冒险闯关问答、抢答打地鼠、填词连连看、转盘答题、找词游戏、知识飞行棋、知识合成 2048、打字竞速、猜词游戏（猜字母拼单词）、判断对错速答（限时连对奖励）、选词填空（Cloze 拖放）、算术竞速（四则限时）；TemplateGallery 接入练习生成页，模板自动映射题型；并修复贪吃蛇/转盘/找词三个旧模板的脚本语法错误
课件编辑器增强	6 套主题模板（简洁/暖橙/海洋/森林/深夜/日落）一键换肤 + 模板插入按钮（TemplateGallery 复用）；保留页面增删改/撤销重做
品牌替换	汉字/拼音/CSS 前缀全量切换为自有品牌 zj-（前端样式与后端生成模板），源码与 AI 生成内容（课件/动画/教案等）经全工作区扫描 + 多类型生成验证零残留
模板插值修复	修复 strokeOrder/4 个新模板的反引号字符串插值 bug：原 var X=\"+name+\" 写法在浏览器里被解析为字面字符串 \"+name+\" 而非变量值，导致参数实际未生效（仅靠 || 默认值 兜底掩盖）；统一改为正确的 ${name} 模板插值，参数现在真正传入 IIFE
AI 实时生成可用	修复核心瓶颈：_chat 读取超时 8s→120s（推理模型需 20-90s 思考）、OCR 30s→90s；空内容守卫（reasoning 模型思考耗尽预算时抛 AI_PROVIDER_EMPTY_RESPONSE 触发兜底）；max_tokens 默认 4096→8192（防复杂生成 JSON 截断），chat_teaching 2048→8192、mindmap 4096→8192；端到端验证：练习(勾股定理几何意义,92s,5题)+试卷(一元二次方程,64s,6题)均产出高质量真实内容，无截断、无兜底模板
JWT 密钥安全	修复高危漏洞：SECRET_KEY 原硬编码为 change-me-in-production 默认值，源码泄露即可伪造任意用户/管理员 token。改为 pydantic field_validator 启动校验——生产模式（DEBUG=False）遇到弱/默认/空/短(<32)密钥直接 RuntimeError 拒绝启动；开发模式自动生成临时密钥并警告；.env 已配置 64 字符随机强密钥。端到端验证：旧密钥伪造 token 返回 401
生产安全	上传安全校验（扩展名白名单/MIME 一致性/魔数检测/文件名清洗/大小限制）+ 审计日志覆盖登录/注册/材料解析/发布资源/管理员发积分/改用户/资源审核，admin 可查询 + AuditLog 表与 Alembic 迁移

| 练习/命题兜底题库扩展 | _exercise_kb() 从 14 个主题扩展到 35 个，覆盖历史(朝代/丝路/工业革命/抗战/文艺复兴/辛亥革命)、地理(气候/地形/河流/地球运动)、生物(细胞/光合/生态/遗传/人体)、化学(元素/反应/酸碱盐/原子)、物理(力学/电学/光学/运动)、数学(几何三角形/函数/方程/一元二次/二次函数/概率统计)、语文(荷塘月色/古诗词/记叙文/议论文)、英语(时态/从句)；修复核心缺口：用户请求「三角形内角和」时不再退回无关算术，而是生成三角形内角和(180°)、直角三角形判定、勾股定理等主题相关题目 | | AI 熔断器全局共享 | _ai_unavailable_until 从实例变量改为类变量，8 个路由模块的 AIService 实例共享一个熔断器；首次 AI 超时后，所有端点的后续调用立即走兜底(0.2s)，不再各自独立等待 10s 超时（5 端点连续调用从 ~50s 降至 ~11s） |

端到端验证覆盖（双账号真实链路）

以下链路均经真实 HTTP 调用端到端验证通过：

链路	验证结果
认证积分	注册201/登录/me初始130积分/签到+10/140 通过
AI生成8端点	课件/动画/教案/练习/思维导图/命题/作文批改全200，内容质量已核验
社交链路	A发资源→B收藏通知→B下载→B发帖→A评论→A点赞双向通知→全局搜索7维度 通过
收藏状态	跨账号is_favorited正确/收藏列表同步/取消重收准确 通过
课堂数据回收	创建投票→4学生公开提交→分析统计(选项50%/掌握度/教学建议)→Excel导出 通过
课件分享	生成token→公开访问→浏览数递增→我的分享列表→撤销后404 通过
旧品牌清除	源码0残留+所有生成类型产出0残留(课件原117处旧前缀全部清零) 通过
平台完整性审计	24视图无空壳(最小366行)、17路由+~125个前端API端点与后端对齐、3处TODO标记均为UI文案非未实现、找回密码/分享/通知/搜索等关键链路前后端完整；Playwright真实浏览器端到端验证：登录→首页(H1正确)→课件/动画/练习页加载→动画生成API 200→0控制台错误→无旧品牌残留
AI 兜底质量增强	修复 backend/services/ai_service.py 中 _exercise_kb 重复定义导致的 SyntaxError（""书名"" 双引号嵌套解析失败，删除冗余副本，保留已用《》/「」的正确版本）；思维导图/练习/教案 fallback 升级为学科+主题感知题库（30+ 高频主题：朝代/丝绸之路/光合作用/细胞/元素周期表/酸碱盐/欧姆定律/重力/一元二次方程/二次函数/荷塘月色/古诗词/时态/气候），冷门主题回退通用题库无回归；时态关键词扩充（现在时/过去时/进行时/完成时）、朝代关键词扩充（唐/汉/宋/明/清/秦）；HTTP + Playwright 端到端验证：一元二次方程→x²-5x+6=0、光合作用→叶绿体、欧姆定律→I=U/R、荷塘月色→朱自清、唐朝→朝代题库、0 控制台错误

| 练习标题去重 | 修复 _fallback_exercise 兜底标题把整段 prompt 当主题再拼「练习」导致「…练习练习」重复：改为正则去尾（练习题/练习/题目/试题/习题/题库/选择题/填空题/判断题/应用题/解答题/计算题/题 等）后再拼；已端到端验证 prompt「二次函数练习」→ 标题「二次函数练习」（原「二次函数练习练习」），3 题正常返回；全工作区旧品牌残留复核：源码+数据库+node_modules 字节级扫描 0 命中；16 个主视图浏览器遍历 0 控制台错误，登录/课件生成链路运行时健康 |

| 练习作答追踪（attempt） | 后端修复 POST /{id}/attempt（原忽略路径参数 exercise_id，改为显式赋值并校验练习存在）；新增 GET /{id}/attempts 供教师查询作答记录；schema 新增 ExerciseAttemptOut、ExerciseAttemptCreate 去掉冗余 exercise_id；前端新增 submitExerciseAttempt/getExerciseAttempts API + Exercise.vue 自动提交（答完全部题目或重置时触发，仅对已保存练习生效）+ 预览时加载并展示「已有 N 人完成 · 平均正确率 M%」徽章；端到端验证：创建练习→提交2条作答(2/3, 3/3)→GET列表返回2条完整记录 | | 全链路深度审计 | 品牌复核(源码+DB+node_modules 字节级 0 残留)；87前端API路径全部有对应后端端点；16主视图浏览器遍历 0 控制台错误；资源CRUD/课堂回收/社交/AI对话/签到/Profile统计 各链路端到端 HTTP 验证通过；TypeScript 零编译错误 |

| 管理后台致命 Bug 修复 | admin.py 缺少 from services.audit import log_action 导入，导致 update_user / grant_user_credits / moderate_resource 三个端点全部 500（NameError）。修复后端到端验证：发放积分 200、启用/禁用用户 200、资源上下架 200，审计日志正确记录；全路由文件 AST 扫描确认无其他缺失导入 | | 全功能端到端审计 | 七大生成流(课件/动画/练习/教案/思维导图/命题/作文) × 全生命周期(生成→保存→列表→详情→导出→改编→删除)；课件分享链路(token→公开访问→列表→撤销→404)；社交链路(发帖→评论→点赞→收藏→搜索5维度)；AI对话(创建→发消息→历史加载→删除)；课堂数据回收(创建→发布→4学生公开提交→分析统计→Excel导出)；密码安全(改密/旧密码校验/新旧不同/强度策略)；材料解析(文件上传→解析→入库)；管理后台(看板15指标/用户CRUD/资源审核/审计日志50条) |

待完善（持续打磨）

能力	建议实现
模板库持续扩展	持续补充学科/题型覆盖（当前 36 动画 + 20 游戏），打磨生成与模板质量
安全增强	余项：病毒扫描集成；✅ JWT 密钥安全已落地（SECRET_KEY 启动校验：生产模式拒绝弱/默认/空密钥，开发模式生成临时密钥并警告；当前 .env 已配置 64 字符强密钥；旧默认密钥伪造的 token 端到端验证被拒）；密码强度策略已覆盖注册/改密/重置，刷新令牌限流 30/min 已落地

开发优先级

1. 材料解析、数据回收学生端、积分体系和管理后台已落地，持续打磨生成质量。
2. ✅ 课件编辑器组件化（主题模板 + 模板插入）已落地。
3. ✅ 动画/游戏模板库（36 + 20）已落地，覆盖数学/物理/化学/生物/地理/历史/语文/英语/通用多学科场景；并修复 3 个旧游戏模板的脚本错误。
4. ✅ 生产安全（上传校验 + 审计日志 + 修改密码）已落地，持续扩展审计覆盖与安全增强。