← 返回使用指南OpenMAIC 产品需求文档（PRD）· 2026-09 上线版

OpenMAIC AI 原生教学平台 · 产品需求文档（PRD）

文档信息

项目	内容
文档版本	2026-09 上线版（v2.2）
更新日期	2026-09-07
适用站点	https://thu2026.online（ECS 生产环境）
使用手册	https://guide.thu2026.online（指南站）
文档状态	已发布（全部能力已上线并通过线上回归验证）
代码基线	GitHub `ZSZ666666/openmaic` main 分支（v2.2 Live Lecture 发布，含 012/013 迁移与 agent-service 流式转写代理）
变更记录	v2.0（2026-08-23）深度详化重写；v2.1（2026-09-03）新增苏格拉底会话持久化与教师回看（`d9c5e69`）、外部 PPT 上传与 AI 智能优化（`4192810`）；v2.2（2026-09-07）新增 Live Lecture 课堂录音转写与智能出题（教师直播授课 / 学生课堂笔记 / 课后回顾），转写支持「高质量分段 / 实时流式」双方案可配置（`transcribe_mode`）
阅读对象	产品、研发、测试、教学运营

说明：本文档所有功能描述均从已上线代码与线上回归结果反查整理，不包含未上线能力。每个功能小节统一包含：功能概述、操作步骤、页面与交互细节、边界与异常用例、关联接口与数据表、验收用例六个部分，部分小节另含 Mermaid 业务流程图。

1. 产品概述与定位

OpenMAIC（Open Multi-Agent Interactive Classroom）是 AI 原生教学平台，能够将任意主题或文档转化为多智能体互动课堂。本实践版以《智慧物流系统设计》课程为载体，面向高校教学场景，提供「教师 AI 做课 → 发布 → 学生选课学习 → 互动课堂 → 随堂测验 → AI 分身答疑 → 教师纠错进化」的完整教学闭环。

核心价值主张：

教师侧：AI 承担做课、出题、批改、学情分析等重复劳动，教师聚焦教学设计与纠错把关
学生侧：7×24 小时 AI 分身答疑、有声互动课堂、即时判分与解析回看，个性化学习随时可用
平台侧：AI 能力与教学平台解耦（独立 agent-service），知识库 RAG 保证答疑贴合课程内容

1.1 页面全景表

教师端（左侧固定导航 + 快捷入口）

路径	功能	导航位置
`/teacher`	课程管理（本地课堂 + 已上架课程 + 快捷卡片）	主导航「课程管理」
`/teacher/live`	直播授课（课堂录音 / 实时逐字稿 / AI 滚动总结 / 基于已讲内容一键出题）	主导航「直播授课」
`/studio`	AI 做课工作室（主题/文档生成互动课堂）	课程管理页「创建新课堂」按钮
`/classroom/{id}`	课堂预览与编辑（多场景互动舞台）	课程管理页打开本地课堂
`/teacher/questions`	题库管理（含学生提交题审核）	课程管理页快捷卡片
`/teacher/inclass`	随堂测验（AI 出题 / 发起测验 / 实时监控三 Tab）	主导航「随堂测验」
`/teacher/dashboard`	学情看板（全班统计/热力图/预警）	课程管理页快捷卡片
`/teacher/assignments`	作业管理	课程管理页快捷卡片
`/teacher/avatar`	AI 分身配置	主导航「AI 分身」
`/teacher/avatar/review`	答疑纠错（对话复核 + 纠错管理）	主导航「答疑纠错」
`/teacher/emergency`	紧急事件案例管理	主导航「紧急事件」
`/vibe-coding`	AI 编程工作台（游戏/课件生成与发布）	主导航「AI 编程工作台」

学生端（左侧固定导航 + 快捷入口）

路径	功能	导航位置
`/student`	我的学习（已选课程 + 快捷卡片）	主导航「我的学习」
`/courses`	课程市场（浏览/搜索/选课）	主导航「课程市场」
`/courses/{id}`	课程详情（章节列表 + 学习功能入口 + 学生出题）	课程市场点进课程
`/classroom/{stageId}`	互动课堂（有声多场景学习）	课程章节「开始学习」
`/courses/{id}/practice`	习题练习（按知识点/难度刷题）	课程详情学习功能
`/courses/{id}/assignments`	我的作业列表	课程详情学习功能
`/courses/{id}/assignments/{aid}/submit`	作业提交	作业列表进入
`/courses/{id}/knowledge`	知识体系树	课程详情学习功能
`/courses/{id}/preview`	预习任务	课程详情学习功能
`/student/quiz`	随堂测验（作答 + 结果回看）	主导航「随堂测验」
`/student/live`	课堂笔记（录音转写 / AI 实时总结 / 一键标记重点 / 重点自测题）	主导航「课堂笔记」
`/live/{id}`	课堂录音课后回顾（播放器 + 逐字稿 + AI 总结/章节/重点，教师与学生共用）	直播授课 / 课堂笔记页「查看课后回顾」
`/student/emergency`	紧急事件挑战（弹窗作答 + 历史记录）	主导航「紧急事件」
`/student/tutor`	AI 辅导（聚合入口，按课程找分身）	主导航「AI 辅导」
`/learn/{courseId}/ask`	AI 分身答疑对话（流式 + 语音）	AI 辅导页「向 AI 分身提问」
`/student/dashboard`	学生学情看板	「我的学习」快捷卡片
`/student/wrong-answers`	错题本	「我的学习」快捷卡片
`/student/games`	教学游戏中心	学生端入口
`/play/{token}`	游戏分享链接游玩页	教师分享链接
`/vibe-coding`	AI 编程工作台（学生亦可创作）	主导航「AI 编程工作台」

公共页面

路径	功能
`/`	产品首页（能力介绍与入口）
`/login`	登录（教师/学生角色自动识别）

2. 用户角色与核心场景

角色	画像	核心场景
教师	高校物流课程教师，希望降低做课、出题、批改、答疑的重复劳动	AI 做课 → 发布课程 → 组卷发起随堂测验 → 实时监控与学情诊断 → 复核答疑并纠错 → 持续进化分身
学生	选修物流课程的学生，需要随时可学的互动内容与即时反馈	选课 → 互动课堂学习 → 随堂测验作答并回看解析 → 错题复习 → 向教师 AI 分身提问 → 参与紧急事件挑战与教学游戏

2.1 教师核心旅程

在 /studio 输入课程主题或上传文档，AI 生成分场景互动课堂大纲与媒体内容
在 /classroom/{id} 预览并微调课堂（场景、旁白、白板、角色），保存到本地或发布到课程
在 /teacher 管理课程状态（草稿/已发布/已归档），学生即可在课程市场选课
在 /teacher/inclass 用 AI 按知识点批量出题，入库形成题库；也可直接在 /teacher/questions 手工建题
按难度分布一键组卷发起测验，学生端即时收到待作答测验
在「实时监控」查看交卷进度与每题正确率，对低正确率题一键生成讲解话术，并发起一键学情诊断
学生在 /learn/{courseId}/ask 向分身提问后，教师在 /teacher/avatar/review 复核对话、标记纠错，分身知识库随纠错持续进化
在 /teacher/emergency 创建沉浸式紧急事件案例并发布，学生以弹窗形式限时挑战
在 /vibe-coding 用自然语言生成教学游戏并发布到学生游戏中心或生成分享链接

2.2 学生核心旅程

在 /courses 浏览已发布课程并选课，进入 /student 查看学习进度
点击章节进入 /classroom/{stageId}，体验有声多角色互动课堂
在 /student/quiz 作答教师发起的随堂测验，提交后约 30-60 秒获得判分，可随时回看逐题解析
答错的题自动进入 /student/wrong-answers 错题本，可按知识点筛选、标记掌握
遇到不懂的问题，在 /student/tutor 找到课程对应教师分身，进入对话页语音或文字提问
教师发布紧急事件后，进入 /student/emergency 自动弹出挑战，完成后得分同步进知识系统
在 /student/games 游玩教师发布的教学游戏，或通过分享链接 /play/{token} 直接游玩

3. 整体业务架构

3.1 教学闭环

graph TB
    A[教师 AI 做课 Studio] --> B[课堂预览编辑 Classroom]
    B --> C[发布课程 课程管理]
    C --> D[学生选课 课程市场]
    D --> E[互动课堂学习]
    E --> F[随堂测验]
    F --> G[即时判分与解析回看]
    G --> H[错题本与薄弱知识点]
    H --> I[AI 分身答疑]
    I --> J[教师答疑纠错]
    J --> I
    G --> K[教师学情看板]
    K --> A

3.2 答疑纠错进化闭环

graph TB
    A[学生提问 文字或语音] --> B[AI 分身流式回答]
    B --> C[对话记录入库]
    C --> D[教师答疑纠错页复核]
    D -->|回答正确| E[标记已复核通过]
    D -->|回答有误| F[录入纠错条目]
    F --> G[分身知识配置更新]
    G --> B

3.3 随堂测验判分流程

graph TB
    A[教师配置难度分布] --> B[创建测验配置 create-config]
    B --> C[从审核通过题池抽题 generate-quiz]
    C --> D[学生作答 状态按 slot 记录]
    D --> E[提交答案 submit-answers]
    E --> F[客观题规则判分]
    E --> G[主观题 AI 判分 约30-60秒]
    F --> H[写回 quiz_sessions 总分与奖励分]
    G --> H
    H --> I[逐题结果持久化 results]
    I --> J[学生查看详情回看解析]
    H --> K[教师实时监控与学情诊断]

3.4 课堂录音转写与智能出题流程（Live Lecture）

graph TB
    A[师生选择音源与转写方案] --> B[创建录音会话 lecture_recordings]
    B --> C[MediaRecorder 45s 分段切片]
    C --> D[POST segments 服务端 ffmpeg 转 16k WAV]
    D --> E[百炼文件转写 qwen3-asr-flash]
    E --> F[写 lecture_segments 逐字稿定稿]
    B --> G{transcribe_mode = stream}
    G -->|是| H[AudioWorklet 采 PCM 16k]
    H --> I[WS 经 agent-service 8788 代理]
    I --> J[paraformer-realtime-v2 秒级 interim]
    J --> K[interim 上屏 分段定稿覆盖]
    G -->|否或流式不可用降级| F
    F --> L[滚动总结 overall + chapters + tags]
    L --> M[教师 基于逐字稿一键出题 题库匹配 + AI]
    L --> N[学生 标记重点 生成标题摘要与自测题]
    M --> O[入库并发起随堂测验]
    F --> P[课后回顾 live 播放器 + 逐字稿 + 总结]

4. 教师端功能详述

T1. AI 做课工作室（/studio）

功能概述

教师输入课程主题或上传文档（PDF），AI 自动生成分章节、分场景的互动课堂大纲，并可继续生成场景内容、角色台词、图像/视频/语音等媒体素材，产出可在课堂舞台播放的完整课件。

操作步骤

登录教师账号，进入 /teacher，点击「创建新课堂」进入 /studio
输入课程主题（如「智慧物流系统设计」），或上传课程文档由 /api/parse-pdf、/api/extract-document 解析
调用 /api/generate-classroom 发起课堂生成任务，通过 /api/generate-classroom/{jobId} 轮询进度
生成场景大纲（/api/generate/scene-outlines-stream 流式输出），教师可逐条调整
为场景生成具体内容与角色动作（/api/generate/scene-content、/api/generate/scene-actions）
按需生成图像、视频、语音、角色画像（/api/generate/image、/api/generate/video、/api/generate/tts、/api/generate/agent-profiles）
保存为本地课堂（IndexedDB），回到 /teacher 可打开预览或发布到课程

页面与交互细节

生成过程为异步任务制：提交后返回 jobId，前端轮询状态直到完成
大纲生成使用流式接口，逐字渲染，支持中途停止
媒体生成任务统一管理于媒体编排器（media-orchestrator），失败可单项重试
本地课堂数据存浏览器 IndexedDB，跨设备需通过发布到课程同步

边界与异常用例

场景	行为
LLM 未配置	生成接口返回错误，前端提示需配置模型供应商
生成超时/中断	任务可重新发起；已生成的大纲不丢失
PDF 解析失败	返回错误提示，教师可改为手动输入主题
媒体生成部分失败	单项重试（`retrySingleOutline`），不阻塞其他场景

关联接口与数据表

接口：/api/generate-classroom、/api/generate-classroom/[jobId]、/api/generate/scene-outlines-stream、/api/generate/scene-content、/api/generate/scene-actions、/api/generate/agent-profiles、/api/generate/image、/api/generate/video、/api/generate/tts、/api/generate/voice、/api/parse-pdf、/api/extract-document、/api/classroom
数据表：courses、course_stages（发布后）；本地草稿存 IndexedDB

验收用例

编号	前置条件	步骤	预期结果
T1-01	教师已登录且模型供应商已配置	输入主题发起生成	任务创建成功，进度可见，最终产出场景大纲
T1-02	大纲已生成	对单个场景生成内容/媒体	场景内容与媒体就位，课堂可播放
T1-03	课堂已保存	在 `/teacher` 打开该课堂	进入 `/classroom/{id}` 正常加载，音频/图像正常

T2. 课程管理（/teacher）

功能概述

教师端的课程总入口：管理本地课堂草稿与已上架课程（草稿/已发布/已归档），并提供学情看板、题库管理、作业管理三个快捷卡片。

操作步骤

打开 /teacher，页面分为「本地课堂」与「已上架课程」两个区域
本地课堂条目：点击「打开」进入 /classroom/{id} 预览编辑；点击「发布到课程」打开发布弹窗（PublishCourseDialog）填写课程信息后发布
已上架课程条目：查看状态标签（草稿/已发布/已归档），可编辑、发布或归档
点击「创建新课堂」进入 /studio 开始新的 AI 做课
点击快捷卡片分别跳转 /teacher/dashboard、/teacher/questions、/teacher/assignments

页面与交互细节

本地课堂来源于浏览器 IndexedDB（stage 数据），与平台账号无强绑定
发布到课程调用 /api/platform/courses 创建课程记录，章节写入 course_stages
状态流转：draft（草稿）→ published（已发布，学生可选课）→ archived（已归档，不再展示选课）

边界与异常用例

场景	行为
平台未配置 Supabase	toast 提示「平台未配置」，发布入口不可用，本地课堂仍可预览
无本地课堂且无课程	显示空态并引导「创建新课堂」
归档课程	学生端课程市场不再展示，已选课学生历史数据保留

关联接口与数据表

接口：/api/platform/courses、/api/platform/courses/[id]、/api/platform/courses/[id]/stages、/api/classroom
数据表：courses、course_stages

验收用例

编号	前置条件	步骤	预期结果
T2-01	存在本地课堂	点击发布到课程并填写信息	课程以草稿态出现在已上架列表
T2-02	课程为草稿	执行发布	状态变为已发布，学生端课程市场可见
T2-03	课程已发布	执行归档	状态变为已归档，学生市场不再展示

T3. AI 出题与题库管理（/teacher/inclass 出题 Tab + /teacher/questions）

功能概述

题库是全平台组卷、练习、作业的题目来源，支持三种题目来源：教师手工创建、AI 批量生成、学生提交（需 AI 初审 + 教师复核）。共支持 9 种题型：单选、多选、判断、填空、简答、计算、场景分析、方案调优、方案设计。

操作步骤（AI 出题）

进入 /teacher/inclass 的「AI 出题」Tab
在知识点文本框输入知识点描述（如「仓储布局与 ABC 分类法」）
选择题型（单选/多选/判断/简答，四选一互斥）与生成数量（1/2/3/5/8/10）
点击生成，等待约 20-40 秒（调用 POST /api/platform/inclass/teacher/generate-ai-questions）
生成结果以候选题卡片展示：难度（n/5）、知识标签、答案、解析
对单题点击「入库」，或点击「全部入库」批量入库（POST /api/platform/questions）

操作步骤（题库管理）

进入 /teacher/questions，列表展示本课程全部题目，可按题型筛选
点击「新建题目」打开 QuestionEditor 弹窗，选择题型、填写题干、选项、答案、解析、知识标签、难度
对已有题目可编辑或删除（删除前有 confirm 确认）
学生提交的题目标注「学生提交」徽标（琥珀色边框）与待审核状态，展示 AI 评估条（建议通过/驳回、难度、置信度、理由）
教师点击「通过」或「驳回」（POST /api/platform/inclass/teacher/review-question），通过的题进入组卷题池

页面与交互细节

AI 生成的难度 1-5 映射为三档：≤2 为 easy、3 为 medium、≥4 为 hard（difficulty_level 字段保留原始 1-5 级）
题目 source 字段区分 teacher/student；status 区分 pending/approved/rejected
AI 评估结果存于 agent_evaluation JSONB 字段
可选反 AI 特色标签（question_tags）：如 anti-ai（反 AI 新型题）、分层推演、AI 纠错、手绘、材料限定

边界与异常用例

场景	行为
AI 出题降级（fallback）	返回兜底题目并 toast 警告「当前为降级生成」，教师可编辑后入库
生成超时	前端保持加载态直到超时提示，可重试
删除已被测验引用的题	历史测验会话保留快照引用，不影响已交卷记录
学生提交题未复核	`status=pending`，不会进入组卷池

关联接口与数据表

接口：/api/platform/inclass/teacher/generate-ai-questions、/api/platform/questions、/api/platform/questions/[id]、/api/platform/inclass/teacher/review-question、/api/agent/capabilities/evaluate-question
数据表：questions（含 difficulty_level、source、submitter_id、status、agent_evaluation、question_tags）

验收用例

编号	前置条件	步骤	预期结果
T3-01	教师已进入随堂测验出题 Tab	输入知识点选题型与数量生成	20-40 秒内返回候选题卡片，字段完整
T3-02	候选题已生成	点击全部入库	题目进入题库，难度映射正确（≤2 easy / ≥4 hard）
T3-03	学生已提交题目	教师点击通过	题目状态变 approved，可被组卷抽中
T3-04	教师手工新建单选题	保存	题库列表出现新题，可编辑可删除

T4. 随堂测验发起与实时监控（/teacher/inclass 发起测验与监控 Tab）

功能概述

教师按难度分布一键组卷发起测验，系统从「审核通过」题池抽题生成学生答卷；发起后可在实时监控页查看交卷进度、每题正确率，并对薄弱题生成讲解话术。

操作步骤（发起测验）

进入 /teacher/inclass 的「发起测验」Tab
为简单/中等/困难三档分别设置题数（每档 0-5 题）
系统构造分布参数 distribution = [{slot, difficulty_level(1/3/5), score(1/3/5)}]
调用 POST /api/platform/inclass/teacher/create-config 创建测验配置
调用 POST /api/platform/inclass/teacher/generate-quiz 抽题组卷，为学生生成测验会话
学生端 /student/quiz 立即出现待作答测验

操作步骤（实时监控）

切换到「实时监控」Tab，下拉选择测验（展示最近 10 次）
页面每 6 秒自动轮询 GET /api/platform/inclass/teacher/live-monitor
查看交卷进度（x/y 人已交卷）与每题正确率色条：<60% 红色、<80% 黄色、≥80% 绿色
对低正确率题点击「讲解话术」按钮，调用 POST /api/platform/inclass/teacher/teaching-assist，返回 needs_explanation（是否需要讲解）、teaching_script（讲解话术）、focus_points（重点）
点击「一键学情诊断」调用 POST /api/platform/inclass/teacher/diagnose，返回 weak_points（薄弱点）、report（诊断报告）、suggestions（教学建议）

页面与交互细节

题池范围：本课程内 status=approved 的题目，涵盖教师自建、AI 入库、学生提交复核通过三类
「讲解话术」按钮在该题 0 人作答时禁用（无数据可判）
轮询区分「加载中」与「真实空态」，防止切换测验时列表闪烁
组卷对提交者本人执行「回避替换」：学生不会抽中自己提交的题（replaced_own 标记）

边界与异常用例

场景	行为
题池题目不足	抽题结果少于配置题数，按实际生成
某题 0 人作答	正确率不显示、讲解话术按钮禁用
学生重复提交	`quiz_sessions` 对 (config, student) 唯一约束，重复提交被拒绝
网络异常轮询失败	保留上一次数据，下一个 6 秒周期重试

关联接口与数据表

接口：/api/platform/inclass/teacher/create-config、generate-quiz、live-monitor、teaching-assist、diagnose、generate-distractors（干扰项生成）；学生侧 my-sessions、session-questions、submit-answers、session-detail
数据表：quiz_configs、quiz_sessions（含 results）、quiz_session_questions

验收用例

编号	前置条件	步骤	预期结果
T4-01	题池存在审核通过题目	配置 1 简单 +1 中等 +1 困难并发起	配置与会话创建成功，学生端出现待作答测验
T4-02	学生已交卷	教师打开实时监控	显示交卷人数与每题正确率色条
T4-03	某题正确率 <60%	点击讲解话术	返回是否需要讲解、话术与重点
T4-04	测验已有交卷数据	点击一键学情诊断	返回薄弱点、报告与建议
T4-05	学生提交了某题且被复核通过	该学生参加测验	该学生不会抽中自己提交的题

T5. 学情看板（/teacher/dashboard）

功能概述

面向教师的全班学情总览：统计卡、知识点掌握度热力图、高频错题、作业完成情况与学情预警。

操作步骤

从 /teacher 快捷卡片或地址栏进入 /teacher/dashboard
选择课程，页面调用 GET /api/platform/dashboard/teacher?courseId=
查看四张统计卡：学生总数、平均进度、平均正确率、预警学生数
查看知识点掌握度热力图（按知识点聚合全班正确率）
查看高频错题 Top5（显示 x 人错）
查看作业完成情况（x/y 已交 + 均分）
查看学情预警列表：进度滞后、正确率低、未交作业三类

页面与交互细节

热力图颜色随正确率渐变，低掌握度知识点显著标红
预警规则由后端聚合 learning_progress、quiz_attempts、assignment_submissions 计算

边界与异常用例

场景	行为
课程无学生选课	统计卡显示 0，热力图与预警为空态
无作答数据	平均正确率显示占位符，不报错
跨课程切换	数据按所选课程隔离

关联接口与数据表

接口：/api/platform/dashboard/teacher
数据表：enrollments、learning_progress、quiz_attempts、wrong_answers、assignment_submissions、mastery_profiles

验收用例

编号	前置条件	步骤	预期结果
T5-01	课程有学生且有测验记录	打开看板	统计卡、热力图、高频错题数据正确
T5-02	某学生进度明显滞后	查看预警列表	该学生出现在预警列表并注明原因类别

T6. AI 分身配置（/teacher/avatar）

功能概述

教师配置自己的 AI 分身：名称、教学风格、分级提示深度、回答边界与课程知识概要。分身是学生答疑的载体，保存后立即对学生生效。

操作步骤

进入 /teacher/avatar（主导航「AI 分身」）
填写分身名称（≤30 字）
选择教学风格三选一：严谨型（rigorous）、幽默型（humorous）、苏格拉底式（socratic）
设置分级提示深度 1-3 级：1 级只给方向；2 级方向 + 关键提示；3 级方向 → 提示 → 引导得出答案
可选填写自定义风格补充说明
配置回答边界：禁答话题（每行一个）与引导话术（默认「这个问题建议直接问老师本人哦～」）
填写课程知识概要（供分身回答时参考）
打开启用开关并保存（POST /api/platform/avatar）

页面与交互细节

页面加载时 GET /api/platform/avatar 回填已有配置
教学风格决定对话语气与引导策略；苏格拉底式下分身只反问和提示，不给答案
边界命中时分身输出引导话术而非直接回答
保存成功后立即生效，学生下一次对话即使用新配置

边界与异常用例

场景	行为
分身未启用	学生辅导页显示「教师尚未启用 AI 分身，仍可尝试提问」
名称超 30 字	前端限制无法输入更多
问题命中禁答话题	分身返回引导话术，不泄露越界内容
LLM 未配置	对话页展示降级提示（见 S4）

关联接口与数据表

接口：/api/platform/avatar（GET/POST）
数据表：teacher_avatars（name、teaching_style、style_prompt、boundary_rules、hint_levels、knowledge_config、corrections、is_active）

验收用例

编号	前置条件	步骤	预期结果
T6-01	教师首次进入	填写全部配置并保存	保存成功，学生端辅导页显示分身名称
T6-02	配置了禁答话题	学生提问命中话题	分身返回引导话术
T6-03	风格选苏格拉底式	学生提问知识题	分身反问引导而非直接给答案

T7. 答疑纠错（/teacher/avatar/review）

功能概述

教师复核学生与分身的对话记录，对错误回答录入纠错条目。纠错写入分身知识配置，使分身后续回答持续进化，形成「答疑 → 纠错 → 进化」闭环。对话列表按会话存储，展示模式徽标（苏格拉底/普通）与提问轮数，便于识别学生思考路径。

操作步骤

进入 /teacher/avatar/review（主导航「答疑纠错」）
查看对话列表（GET /api/platform/avatar/conversations），筛选未复核对话
点开对话查看完整消息流，判断分身回答质量
回答正确：标记已复核；回答有误：录入纠错条目（问题、错误回答、正确答案），调用 /api/platform/avatar/corrections
纠错写入 teacher_avatars.corrections，分身后续对话自动参考

页面与交互细节

对话记录含学生、课程、时间、是否已复核（teacher_reviewed）、是否已解决（resolved）
纠错条目同步用于答疑检索增强，提高同类问题的回答正确率
会话按活跃时间（updated_at）倒序排列；每条会话显示学生模式徽标（「苏格拉底」琥珀色/「普通」蓝色）与「N 轮提问」计数，时间显示最近活跃时间
会话化存储（011 迁移）：一个学生×一门课程的一次完整对话对应一条记录（按 student_id+session_id upsert），同会话多轮问答不产生重复记录

边界与异常用例

场景	行为
无待复核对话	显示空态提示
对话被删除或课程下线	列表按现有记录展示，课程字段兜底显示
历史对话记录（011 迁移前）	迁移后同一学生×课程仅保留最新快照，列表不再重复展示；旧记录 session_id 为空不受唯一约束

关联接口与数据表

接口：/api/platform/avatar/conversations、/api/platform/avatar/corrections
数据表：avatar_conversations、teacher_avatars.corrections

验收用例

编号	前置条件	步骤	预期结果
T7-01	学生已与分身对话	教师打开答疑纠错	对话出现在列表，消息完整
T7-02	教师录入纠错	学生再次提出同类问题	分身回答体现纠错内容
T7-03	学生以苏格拉底模式完成多轮问答	教师打开答疑纠错	该会话仅一条记录，带「苏格拉底」徽标与轮数，按最近活跃时间排序

T8. 紧急事件案例管理（/teacher/emergency）

功能概述

教师创建沉浸式「紧急事件」案例：以突发事件叙事为背景，学生在限时场景中做选择题，不同选项对应不同得分与故事后果。支持案例编辑、预览、发布、结束、CSV 导入导出与知识库同步。

操作步骤

进入 /teacher/emergency，左侧为案例库列表，右侧为编辑/预览区
点击「新建案例」，填写：标题、描述、案例来源、玩家角色、开场叙事（沉浸式引入）
编辑结局（标题、最低分、最高分、结局叙事），按得分区间匹配不同结局
添加题目章节：章节标题、场景描述、沉浸式叙事场景、问题、时间限制（秒）、知识点标签
为每题添加选项：内容、得分（0-10）、解析、故事后果
保存（切换案例前若有未保存内容会弹出确认）
点击「发布」：状态变 published，学生端自动弹窗通知挑战
挑战周期结束后点击「结束」（状态 ended）；也可「删除」案例
可用「下载模板」获取 CSV 模板，或「导入」CSV 批量建案例；「导出」将当前案例导出为 CSV

页面与交互细节

预览模式下选项得分以色标展示：≥10 绿、>0 黄、=0 灰
CSV 格式含 BOM 头，结构为三段：[事件信息]（标题/描述/案例来源/玩家角色/开场叙事）、[结局]（标题/最低分/最高分/叙事）、[题目]（章节标题/场景描述/沉浸式叙事场景/问题/时间限制秒/知识点标签/选项内容/得分 0-10/选项解析/选项故事后果）
学生作答完成后，薄弱知识点、错题记录同步进平台知识系统（热力图/错题本可见）
可用「AI 增强」（/api/platform/emergency/enhance）润色叙事

边界与异常用例

场景	行为
未保存即切换案例	弹出确认框，防止内容丢失
案例被删除但学生有历史记录	学生历史页按记录中引用的事件信息兜底展示
CSV 格式错误	导入失败并提示，不影响现有案例
发布后再编辑	需先结束或重新发布，状态机约束

关联接口与数据表

接口：/api/platform/emergency/enhance；案例与作答数据直连 Supabase（emergency-db 封装）
数据表：emergency_events（含 player_role、story_intro、story_endings）、emergency_completions、emergency_answers

验收用例

编号	前置条件	步骤	预期结果
T8-01	教师已登录	新建案例并填写完整内容保存	案例出现在列表，预览显示得分色标
T8-02	案例已保存	点击发布	学生端进入紧急事件页自动弹出挑战
T8-03	案例已完成	导出 CSV	文件含三段结构且带 BOM 头，可重新导入
T8-04	编辑中有未保存内容	切换到其他案例	弹出未保存确认

T9. AI 编程工作台（/vibe-coding）

功能概述

教师（与学生）用自然语言对话生成教学游戏或互动课件（单文件 HTML），支持分镜脚本生成、图像与配音生成、多设备预览、版本管理与发布（平台游戏中心 / 分享链接）。

操作步骤

进入 /vibe-coding（教师与学生导航均有入口）
新建项目，在对话框用自然语言描述想要的游戏/课件（如「做一个仓储分拣小游戏」）
调用 POST /api/vibe-code/generate 生成代码，右侧实时预览
继续对话微调（/api/vibe-code/modify），每次生成产生代码版本（vibe_code_versions）
可选：用分镜功能生成脚本、图像与配音（/api/vibe-code/storyboard/generate-image、generate-tts、check-capability）
多设备预览（手机/平板/桌面视口切换）验证效果
「保存到本地」暂存，或「导入」既有代码（/api/vibe-code/import）
点击发布（/api/vibe-code/publish）：选择发布到平台（学生游戏中心可见）或生成分享链接（/play/{token}）
在统计页（/api/vibe-code/stats）查看游玩数据

页面与交互细节

工作区布局：左侧新侧边栏（项目列表/对话），右侧预览与代码视图
项目数据存 vibe_projects（type 区分 game / video-script），对话记录存 vibe_chat_messages
发布产物写入 vibe_game_publications，学生游玩记录写入 vibe_game_stats

边界与异常用例

场景	行为
生成超时	前端提示可重试，项目代码保留上一版本
分镜能力未配置	`check-capability` 返回不可用，入口提示
发布后下线	`status=archived`，分享链接显示「此游戏已下线」

关联接口与数据表

接口：/api/vibe-code/generate、modify、import、publish、stats、/api/vibe-code/storyboard/check-capability、generate-image、generate-tts
数据表：vibe_projects、vibe_code_versions、vibe_chat_messages、vibe_game_publications、vibe_game_stats、vibe_user_templates

验收用例

编号	前置条件	步骤	预期结果
T9-01	教师已登录	描述需求发起生成	生成可运行的单文件游戏并在预览区运行
T9-02	项目已生成	继续对话修改	新版本代码生成，版本历史可查
T9-03	项目效果满意	发布到平台	学生游戏中心出现该游戏，可游玩并记录分数
T9-04	项目已发布	复制分享链接访问 `/play/{token}`	游戏正常运行，页脚显示「由 OpenMAIC 提供」

T10. 作业管理（/teacher/assignments）

功能概述

教师按课程创建作业（知识型、仿真参考、AI 协作、设计、综合、应急响应、高管访谈等类型），支持个性化参数（每个学生题目参数不同，防抄袭）、AI 预审（格式/完整性/质量/原创性）与批改。

操作步骤

从 /teacher 快捷卡片进入 /teacher/assignments
创建作业：标题、描述、类型、知识标签、截止时间、满分
可选开启个性化参数配置（personal_params_config），系统为每个学生生成不同参数
发布后学生端课程作业列表可见；学生提交后可触发 AI 预审
教师查看提交列表（/api/platform/assignments/[id]/submissions），人工批改打分与评语（/api/platform/assignments/[id]/grade）
「高管访谈」类作业可用专属对话能力（/api/platform/assignments/executive-chat）

页面与交互细节

提交状态流转：submitted → prechecked → reviewed → returned
每生唯一提交（(assignment, student) 唯一约束），重复提交覆盖前稿
批改记录 graded_by 追溯批改人

边界与异常用例

场景	行为
超过截止时间	前端提示逾期，是否可补交由教师控制
学生未选课	无法查看该课程作业
AI 预审服务不可用	跳过预审直接进入人工批改流程

关联接口与数据表

接口：/api/platform/assignments、[id]、[id]/grade、[id]/personal-params、[id]/submissions、[id]/submit、my-submissions、executive-chat
数据表：assignments、assignment_submissions、assignment_personal_params

验收用例

编号	前置条件	步骤	预期结果
T10-01	教师已创建作业	发布	学生课程作业列表出现该作业
T10-02	开启个性化参数	两名学生分别查看	两人拿到的题目参数不同
T10-03	学生已提交	教师批改打分	学生端可见分数与评语，看板作业统计更新

T11. 外部 PPT 上传与 AI 智能优化（/studio「上传 PPT 智能优化」）

功能概述

教师上传外部 .pptx 课件，平台在浏览器端解析后由 AI 按「案例与示例更新 / 算法展示可视化升级 / 整体视觉智能化提升 / 动效与过渡优化」四个方向逐页改写，并统一全局设计系统（配色/字体层级/留白/图标风格），产出可在平台播放的互动课堂；交付物含本地可打开的优化版 .pptx（逐页 fade 过渡动效）与逐页修改说明清单（Markdown）。雨课堂风格互动页自动识别并转换为平台测验场景（支持 AI 判分）。

操作步骤

登录教师账号进入 /studio（AI 做课工作室），点击「上传 PPT 智能优化」按钮
选择 .pptx 文件，浏览器本地用 @openmaic/importer 解析全部幻灯片（按钮显示「正在解析 PPTX...」；41 页课件约需 3-4 分钟，解析完成后才弹出对话框）
「PPT 智能优化」对话框展示文件名与总页数；勾选优化方向（四项默认全选，至少保留一项）
可选填写「目标风格说明」（自由文本，如「学术汇报风格，深色科技感，突出 AI 主题」）；可选打开「同时生成 AI 讲解语音（TTS）」开关（默认关闭，开启后耗时更长）
点击「开始优化」提交任务，对话框切换为进度态：进度条 + 逐页计数（N/总页数 · 百分比），每 3 秒轮询一次
完成后展示结果摘要（生成场景数 + 课堂名）与设计系统色板，提供三个操作：「下载优化版 PPTX」（得到 {原文件名}-AI优化版.pptx）、「修改说明清单」（得到 {原文件名}-修改说明清单.md）、「打开课堂」（进入 /classroom/{id}）

页面与交互细节

对话框四阶段：config（方向/风格/TTS 配置）→ running（进度轮询）→ done（交付物）/ error（错误信息 + 关闭按钮）；任务在服务端后台执行，页面提示「页面较多时需要数分钟，可保持本窗口打开」
进度阶段：initializing(3%) → planning(8%，生成全局设计系统 + 逐页优化方案) → optimizing_pages(10-88%，逐页改写) → generating_tts(90%，仅开启讲解语音时) → persisting(96%，课堂落库服务端) → completed(100%)
逐页优化以原页为基线（保留原有图片与版式骨架），叠加全局设计系统与页级 editDirective 改写；单页失败自动降级保留原页内容，不阻塞其余页
优化后的课堂持久化到服务端课堂存储，通过「打开课堂」或直链 /classroom/{id} 播放与编辑；不在 /teacher 本地课堂列表（IndexedDB）中展示，如需发布到课程供学生选课，可在课堂内导出 .maic.zip 后经首页「导入课堂」转为本地课堂，再从 /teacher 发布
导出 pptx 复用课堂同款导出器（buildPptxBlob）并在 zip 层注入 fade 过渡（speed=med）；测验场景不进 pptx，仅在课堂播放中呈现
修改说明清单只记录实际发生的修改（真实性原则）：全局设计系统（设计理念/配色/字体层级/留白节奏/图标风格）+ 逐页记录（页码/标题/类型/状态/修改点/修改前后摘要）；页状态四种：已优化（optimized）、保留原始页面（kept_original）、转换为课堂测验（converted_quiz）、优化失败（failed）

优化管线流程

graph TB
    A[上传 pptx 客户端解析] --> B[POST /api/ppt-optimize 创建任务 202]
    B --> C[planning 全局设计系统 + 逐页优化方案]
    C --> D{逐页处理 页面类型}
    D -->|普通页| E[EDIT 模式优化 基线+editDirective]
    D -->|雨课堂互动页| F[生成测验场景 支持 AI 判分]
    E -->|单页失败| G[保留原始页 kept_original]
    E --> H[generating_tts 可选讲解语音]
    F --> H
    G --> H
    H --> I[persisting 课堂落库服务端]
    I --> J[前端轮询获取 result]
    J --> K[下载优化版 pptx 注入 fade 过渡]
    J --> L[下载修改说明清单 Markdown]
    J --> M[打开课堂 classroom 播放]

边界与异常用例

场景	行为
pptx 解析失败	toast 提示「PPTX 解析失败，请检查文件是否有效」，不弹优化对话框
未勾选任何优化方向	「开始优化」按钮禁用；接口层同样拒绝（400，至少需一个方向）
提交空 slides	接口返回 400（Missing or empty field: slides）
单页优化失败	保留原始页面内容，清单标记 kept_original，其余页继续；全部页失败时任务 failed（No pages could be optimized）
雨课堂互动页	自动转为平台测验场景，清单标记 converted_quiz；导出 pptx 不含该页
任务超 30 分钟无进度	stale 看门狗判为 failed，对话框展示错误（服务重启中断同理）
LLM 未配置/供应商拒绝	任务 failed，对话框展示具体错误信息，可关闭后重新发起
下载导出失败	toast「下载失败，请重试」，课堂数据不受影响可再次下载

关联接口与数据表

接口：POST /api/ppt-optimize（创建任务）、GET /api/ppt-optimize/{jobId}（轮询）、GET /api/classroom?id=（导出时拉取课堂）；管线内部复用 /api/generate/scene-content、/api/generate/scene-actions 同款生成能力与 TTS 接口
存储：任务元数据文件 data/ppt-optimize-jobs/{jobId}.json（见 8.8）；优化后课堂经 persistClassroom 写入服务端课堂存储；无新增数据库表

验收用例

编号	前置条件	步骤	预期结果
T11-01	教师已登录且模型已配置	在 /studio 上传 41 页真实课件，四方向全选发起优化	任务最终 succeeded，逐页状态均为 optimized/converted_quiz，无 failed（实测本地 41/41、生产 37/37）
T11-02	任务已完成	点击「下载优化版 PPTX」	得到 `{原文件名}-AI优化版.pptx`，本地 Office/WPS 可打开，页数与幻灯片场景数一致，每页含 fade 过渡动效
T11-03	任务已完成	点击「修改说明清单」	得到 Markdown 清单：含全局设计系统与逐页记录，只记录实际发生的修改
T11-04	任务已完成	点击「打开课堂」	进入 `/classroom/{id}` 正常播放；转换的测验场景在课堂中呈现并可作答
T11-05	原课件含雨课堂互动页	发起优化	该页转换为测验场景（清单标记 converted_quiz），导出 pptx 不包含该页
T11-06	某页 AI 优化失败（或模拟失败）	发起优化	该页保留原始内容并在清单标记 kept_original，任务整体仍完成

T12. 直播授课（课堂录音转写与智能出题，/teacher/live）

功能概述

教师上课（线下讲解或雨课堂等线上网课）时录音，平台实时转写为逐字稿并滚动生成 AI 总结与章节；教师可基于「已讲内容」一键出题（本地题库标签匹配 + AI 补充），预览后入库并直接发起随堂测验，形成「讲课 → 转写 → 总结 → 出题 → 测验」的课堂闭环。录音结束后可进入课后回顾页（/live/{id}）回看播放器、逐字稿与总结。

操作步骤

进入 /teacher/live（主导航「直播授课」），顶部下拉选择要授课的已发布课程（必选）
选择音源：麦克风（线下讲解）或系统声音（录制雨课堂等网课标签页音频，浏览器弹窗需勾选「分享标签页音频」）
选择转写方案：高质量分段（默认，分钟级、质量高）或实时流式（秒级 interim 上屏，最终仍由分段转写覆盖定稿）
点击「开始录音」：每 45 秒切片上传转写，逐字稿分段上屏（流式方案下先秒级 interim 上屏）；每累积一个总结窗口自动触发 AI 滚动总结（整体总结 + 章节 + 知识点标签）
讲到阶段性内容后，在右侧「一键出题」面板基于最近 N 分钟已讲内容生成候选题（题库匹配题标记 bank、AI 生成题标记 ai），预览后入库
入库题目进入本课程题库（approved），可直接在随堂测验组卷发起（复用 T4 链路）
点击「停止并保存」，完整音频落盘、录音置 ready；点击「查看课后回顾」进入 /live/{id}
历史录音列表展示本人全部录音，可随时回看

页面与交互细节

三栏布局：左侧录音控制（音源/方案切换 + 计时 + 声纹波形 + 开始/暂停/继续/停止），中部逐字稿（流式 interim 以灰色尾串「实时识别中…」呈现，分段定稿覆盖），右侧 AI 滚动总结（整体总结 + 章节 + 知识点标签）与一键出题面板
转写方案与音源在录音开始后锁定（modeLocked/sourceLocked），防止中途切换导致数据错乱
转写按 45s 分段（LECTURE_SEGMENT_SEC），逐段 upsert 到 lecture_segments（(recording_id, seq) 唯一），静音/无内容段不入库
滚动总结以「上一版整体总结 + 新窗口逐字稿」增量更新：overall 覆盖式刷新、chapters 累计合并并按起点排序、knowledge_tags 供出题匹配题库
一键出题：先按窗口总结的知识点标签从本课程 approved 题库匹配 Top3（source=bank），再由 agent-service 出题 Agent 补充（source=ai），agent-service 不可用时用主应用 LLM 基于逐字稿本地降级出题

边界与异常用例

场景	行为
未选课程点击开始	toast「请先选择要授课的课程」，不创建录音
ASR 未配置（缺 `DASHSCOPE_API_KEY`/`SILICONFLOW_API_KEY`）	分段转写返回 503，前端 toast 转写降级提示，录音不中断
实时流式不可用（未配 WS/Key、握手失败、连接中断）	自动降级为高质量分段，toast 提示，录音与分段转写不受影响
AI 总结未配置模型	`summarize` 返回 503，前端 toast 警告，逐字稿仍正常
出题时窗口内无逐字稿	返回 400「暂无逐字稿内容，请先讲课一段时间」
停止录音上传音频失败	录音状态保持可重试；已分段落库的逐字稿与总结不丢失

关联接口与数据表

接口：POST/GET /api/platform/live/recordings、GET/PATCH /api/platform/live/recordings/{id}、GET /api/platform/live/recordings/{id}/audio、POST/GET /api/platform/live/recordings/{id}/segments、GET/POST /api/platform/live/recordings/{id}/summarize、POST /api/platform/live/teacher/generate-quiz、POST /api/platform/live/asr-ticket（流式方案票据）；agent-service WS /v1/asr-stream（端口 8788）
数据表：lecture_recordings（含 transcribe_mode）、lecture_segments、lecture_summaries；出题入库写 questions

验收用例

编号	前置条件	步骤	预期结果
T12-01	教师已登录且有已发布课程	选择课程与音源开始录音并讲课	逐字稿分段上屏，滚动总结与章节生成
T12-02	录音进行中且已有逐字稿	在「一键出题」面板基于最近内容生成	返回 bank/ai 混合候选题，可预览入库
T12-03	候选题已入库	进入随堂测验组卷发起	新入库题目可被抽中，学生端出现待作答测验
T12-04	转写方案选「实时流式」且服务就绪	开始录音讲课	秒级 interim 上屏，45s 分段定稿覆盖 interim
T12-05	转写方案选「实时流式」但 WS/Key 未就绪	开始录音	toast 提示自动降级为高质量分段，录音与分段转写正常
T12-06	录音已停止保存	点击「查看课后回顾」	进入 `/live/{id}`，播放器/逐字稿/总结/章节正常加载

5. 学生端功能详述

S1. 我的学习（/student）

功能概述

学生端首页：展示已选课程卡片与学习进度，并提供学情看板、习题练习、我的作业、错题本四个快捷入口。

操作步骤

登录学生账号，进入 /student
查看已选课程卡片：封面、学科、难度标签（入门/进阶/高级）、学习进度条
点击「开始学习」或「继续学习」进入 /courses/{id} 课程详情
点击快捷卡片进入：学情看板（/student/dashboard）、习题练习（课程练习页）、我的作业、错题本（/student/wrong-answers）

页面与交互细节

进度数据来自 enrollments.progress_pct，随课堂场景完成情况更新
难度标签映射：easy=入门（绿）、medium=进阶（琥珀）、hard=高级（红）

边界与异常用例

场景	行为
未登录	引导登录
已登录未选课	空态提示并引导去课程市场选课
课程封面缺失	显示默认占位封面

关联接口与数据表

接口：/api/platform/enrollments、/api/platform/courses/[id]
数据表：enrollments、courses、learning_progress

验收用例

编号	前置条件	步骤	预期结果
S1-01	学生已选课	打开我的学习	课程卡片展示，进度条与学习记录一致
S1-02	学生未选课	打开我的学习	显示空态与选课引导入口

S2. 课程市场与课程详情（/courses、/courses/{id}）

功能概述

学生浏览、搜索已发布课程并选课；课程详情页展示章节列表与学习功能入口，并支持学生出题（提交题目供教师审核）。

操作步骤（选课）

进入 /courses，页面加载全部 status=published 课程（GET /api/platform/courses）
使用搜索框按标题过滤
点击课程卡片进入 /courses/{id} 查看详情（简介、教师、章节）
点击「选课」（POST /api/platform/enrollments），选课成功后按钮变为「继续学习」

操作步骤（课程详情学习入口）

章节列表点击「开始学习」进入 /classroom/{stageId} 互动课堂
学习功能区四个入口：知识体系（/courses/{id}/knowledge）、预习任务（/courses/{id}/preview）、习题练习（/courses/{id}/practice）、我的作业（/courses/{id}/assignments）
「向 AI 提问」入口直达 /learn/{id}/ask
学生出题：打开提问弹窗，选择题型（单选/多选/判断等），填写题干提交（POST /api/platform/inclass/student/submit-question），返回 AI 评估结果（建议通过/驳回、难度、理由）

页面与交互细节

选课需要登录，未登录点击选课跳转 /login
课程与教师信息联查（profiles.display_name、头像）
学生提交的题目进入教师题库待审核队列（见 T3）

边界与异常用例

场景	行为
重复选课	唯一约束兜底，前端显示已选课状态
课程被归档	详情页提示课程不可用，返回市场
学生出题内容为空	提交按钮禁用
AI 评估服务异常	题目仍入库为待审核，评估条显示兜底文案

关联接口与数据表

接口：/api/platform/courses、/api/platform/courses/[id]、/api/platform/enrollments、/api/platform/inclass/student/submit-question、/api/agent/capabilities/evaluate-question
数据表：courses、course_stages、enrollments、questions

验收用例

编号	前置条件	步骤	预期结果
S2-01	存在已发布课程	浏览并选课	选课成功，我的学习出现该课程
S2-02	已选课	点击章节开始学习	进入互动课堂正常播放
S2-03	学生在详情页出题	提交题目	返回 AI 评估，教师端出现待审核题

S3. 互动课堂（/classroom/{stageId}）

功能概述

学生端沉浸式学习场景：多场景舞台按顺序播放，含角色对话、旁白语音（TTS）、图像/视频媒体、白板演示与场景间测验，学习进度自动记录。

操作步骤

从课程详情点击章节「开始学习」进入 /classroom/{stageId}
课堂自动加载：优先本地缓存（IndexedDB），缓存与远端不一致时应用补丁场景（applyPatchedScenes），缓存失效则回源加载（applyFallbackScenes）
场景按序播放：角色台词逐条展示并伴随语音朗读，可随时暂停/继续
场景内媒体（图像、视频）自动加载；白板演示按历史快照回放
场景完成自动写入学习进度（learning_progress），驱动课程进度条

页面与交互细节

加载流程由 runClassroomLoad 编排，claimStageSceneLoadToken 防止课程切换时的竞态（旧课堂数据不会污染新课堂）
切换课堂时清理媒体任务与白板历史，防止跨课堂串数据
语音播放支持静音开关；媒体加载失败时场景仍可继续（文字内容兜底）
已生成的媒体任务恢复机制：刷新页面后媒体任务从存储恢复继续

边界与异常用例

场景	行为
本地缓存损坏/过期	回源远端加载并重建缓存
音频文件缺失	场景静默继续播放，不中断
快速切换课堂	加载令牌机制丢弃过期加载结果
网络断开	媒体降级，文字内容可用

关联接口与数据表

接口：/api/classroom、/api/classroom-media/[classroomId]/[...path]、/api/proxy-media
数据表：course_stages、learning_progress

验收用例

编号	前置条件	步骤	预期结果
S3-01	已选课	打开章节课堂	场景加载并播放，语音正常（可暂停）
S3-02	播放中刷新页面	重新进入	缓存恢复，媒体与白板历史正常
S3-03	完成一个场景	返回课程详情	学习进度条增长

S4. AI 辅导与分身答疑（/student/tutor、/learn/{courseId}/ask）

功能概述

学生通过聚合入口找到自己每门课程的教师 AI 分身，进入对话页进行文字或语音提问。分身基于课程知识库（RAG）与教师配置的风格、提示深度、边界规则流式回答，遵循「引导而非直接给答案」的教学原则。

操作步骤（聚合入口）

进入 /student/tutor（主导航「AI 辅导」）
页面列出已选课程卡片：课程标题、简介、教师分身名称（GET /api/platform/student/tutors）
点击「向 AI 分身提问」进入 /learn/{courseId}/ask

操作步骤（对话页）

进入对话页自动恢复最近会话（显示「正在恢复对话记录…」，GET /api/platform/avatar/history 回填历史消息与模式）；无历史会话时空态显示三个建议问题快捷按钮，点击即发送
在输入框输入问题（Enter 发送，Shift+Enter 换行），或点击语音按钮录音提问（ASR 转文字后自动发送）
分身流式返回回答，逐字渲染；流式期间显示「思考中…」
回答完成后可自动语音播报（TTS），右上角喇叭按钮切换静音
继续多轮追问，上下文保持
点击「新对话」按钮清空当前对话开启新会话（流式生成中或无消息时禁用）

页面与交互细节

状态栏文案随状态切换：「正在聆听…」（录音中）、「{分身名} 正在播报…」（TTS 播放）、「思考中…」（流式生成）、「{分身名} 在线，支持语音提问」（空闲）
苏格拉底模式下页面提示「AI 分身只反问和提示，不给答案，引导你自己思考」
对话按会话持久化：同一学生×课程的一次完整对话对应一个 session_id（浏览器 localStorage 同步缓存校验），每轮问答后将完整消息数组连同模式 upsert 到 avatar_conversations（不再每轮 insert 快照）；刷新页面或更换设备后重新进入自动恢复，供教师答疑纠错复核（见 T7）
顶部模式徽标可切换「普通模式/苏格拉底模式」，切换后对后续问答即时生效并随会话记录，教师回看可识别
流式生成期间空回复消息显示「思考中…」占位（思考终点态），回答完成后替换为正文
答疑内容检索课程知识库（document_chunks 向量检索 + 纠错记录）

边界与异常用例

场景	行为
教师未启用分身	辅导页提示「教师尚未启用 AI 分身，仍可尝试提问」
LLM 未配置/调用失败	页面展示琥珀色降级提示，不白屏
学生未选课	辅导页空态引导去选课
命中禁答话题	分身返回教师配置的引导话术
语音识别失败	提示重试，输入框可改用文字
历史恢复失败或无历史会话	展示空态与建议问题，可正常开启新对话

关联接口与数据表

接口：/api/platform/student/tutors、/api/platform/avatar/chat、/api/platform/avatar/history、/api/platform/asr、/api/platform/tts、/api/platform/knowledge/[courseId]
数据表：teacher_avatars、avatar_conversations、course_documents、document_chunks

验收用例

编号	前置条件	步骤	预期结果
S4-01	学生已选课且分身已启用	打开辅导页	显示课程卡与分身名称
S4-02	进入对话页	发送课程相关问题	流式返回贴合课程内容的回答
S4-03	进入对话页	语音提问	录音转文字并自动发送
S4-04	教师配置禁答话题	提问命中话题	返回引导话术
S4-05	学生已与分身多轮问答	刷新页面或重新进入对话页	历史消息自动恢复，模式徽标与此前一致
S4-06	存在历史会话	点击「新对话」后再次提问	当前对话清空并开启新会话，旧会话在教师回看列表仍为独立一条

S5. 随堂测验作答与回看（/student/quiz）

功能概述

学生查看教师发起的测验（待作答/已完成两组），按题型作答提交，获得即时判分与奖励分，并可随时回看逐题对错、自己的作答、AI 解析与知识点。

操作步骤（作答）

进入 /student/quiz（主导航「随堂测验」），页面列出待作答与已完成测验（GET /api/platform/inclass/student/my-sessions）
对待作答测验点击「开始作答」，调用 GET /api/platform/inclass/student/session-questions 获取题目
按题型作答：单选（radio）、多选（checkbox）、判断（两按钮）、填空/计算（输入框）、简答/场景分析/方案调优/方案设计/紧急事件（多行文本框）
点击提交；未答完时弹出 confirm 确认
提交后判分约 30-60 秒（主观题 AI 判分），页面轮询直到出结果

操作步骤（回看）

已完成列表显示分数与奖励分，点击「查看详情」
调用 GET /api/platform/inclass/student/session-detail 获取逐题结果
逐题展示：对错图标、你的作答、AI 解析、知识点（key_points）

页面与交互细节

作答状态以 slot 为 key 存储，防止同一题重复出现时状态联动错乱
结果视图顶部显示总分与答对数
客观题规则判分即时完成；主观题由 /api/quiz-grade AI 判分，产出 earned、explanation、key_points
判分结果持久化到 quiz_sessions.results，保证回看数据稳定

边界与异常用例

场景	行为
历史数据无逐题详情	查看详情时 toast「该测验提交时未记录逐题详情（历史数据），仅可查看总分」
重复提交	服务端唯一约束拒绝，前端提示已提交
判分超时	保持判分中状态可重试查看
网络中断提交失败	提示重试，已填答案保留

关联接口与数据表

接口：/api/platform/inclass/student/my-sessions、session-questions、submit-answers、session-detail、/api/quiz-grade、/api/platform/quiz/attempt、/api/platform/quiz/stats
数据表：quiz_sessions（含 results）、quiz_session_questions、quiz_attempts、wrong_answers

验收用例

编号	前置条件	步骤	预期结果
S5-01	教师已发起测验	学生打开随堂测验	出现待作答测验
S5-02	全部作答并提交	等待判分	30-60 秒内出分，显示总分/答对数/奖励分
S5-03	测验已完成	点击查看详情	逐题显示对错、作答与解析
S5-04	历史测验无逐题记录	点击查看详情	显示历史数据兜底文案，仅展示总分
S5-05	未答完点击提交	触发确认弹窗	确认后提交成功

S6. 错题本（/student/wrong-answers）

功能概述

自动收集学生答错的题目（测验、练习、紧急事件），支持按课程与知识点标签筛选、重做练习、标记掌握。

操作步骤

从 /student 快捷卡片进入 /student/wrong-answers（可带 ?courseId= 直达）
查看统计卡：总错题数、待复习数（未标记掌握）
选择课程下拉框（默认第一门已选课程），加载该课程错题（GET /api/platform/quiz/wrong-answers?courseId=）
可选按知识点标签二级筛选
每条错题显示：错 n 次、题型、知识标签、题干、解析、最近错误时间
点击「重做」跳转 /courses/{courseId}/practice；点击「标记掌握」（PUT /api/platform/quiz/wrong-answers）后该题显示「已掌握」徽标

页面与交互细节

未登录时显示「登录后查看你的错题记录」引导态
错题聚合自 wrong_answers 表并联查题目详情（questions）
紧急事件答错的知识点也会同步进错题体系（知识系统同步）

边界与异常用例

场景	行为
未登录	引导登录提示
无错题	空态「暂无错题，继续保持！」
筛选无结果	空态「该筛选条件下无错题」
标记掌握失败	toast「操作失败」，状态不变

关联接口与数据表

接口：/api/platform/quiz/wrong-answers（GET/PUT）、/api/platform/enrollments
数据表：wrong_answers、questions

验收用例

编号	前置条件	步骤	预期结果
S6-01	学生答错过题目	打开错题本	错题列出，错次与标签正确
S6-02	错题列表非空	按知识点筛选	仅显示匹配标签的错题
S6-03	选中一道错题	点击标记掌握	出现「已掌握」徽标，待复习数减一

S7. 学生学情看板（/student/dashboard）

功能概述

学生个人学情分析：学习进度、正确率、错题数、作业情况与薄弱知识点，并提供薄弱点专练入口。

操作步骤

从 /student 快捷卡片进入 /student/dashboard
选择课程下拉框，加载个人学情（GET /api/platform/dashboard/student?courseId=）
查看四张统计卡：学习进度 %、正确率 %、错题数、已提交作业 x/y
查看作业情况区块：总作业数、已批改数、平均分
查看薄弱知识点（正确率最低的标签，附进度条），点击「去做薄弱点专练」跳转练习页

页面与交互细节

薄弱知识点最多展示 5 条，按正确率升序
平均分无数据时显示 -

边界与异常用例

场景	行为
无学习数据	空态「暂无学情数据」
无薄弱知识点	不显示该区块
未选课	无课程下拉，提示先选课

关联接口与数据表

接口：/api/platform/dashboard/student、/api/platform/enrollments
数据表：learning_progress、quiz_attempts、wrong_answers、assignment_submissions、mastery_profiles

验收用例

编号	前置条件	步骤	预期结果
S7-01	学生有学习与测验记录	打开看板	统计卡数值与实际记录一致
S7-02	存在低正确率知识点	查看薄弱知识点	出现标签与正确率条，专练入口可跳转

S8. 紧急事件挑战与教学游戏（/student/emergency、/student/games、/play/{token}）

功能概述

学生完成教师发布的紧急事件挑战（弹窗式限时作答，结果同步知识系统），并在游戏中心游玩教师发布的教学游戏或通过分享链接游玩。

操作步骤（紧急事件）

进入 /student/emergency，页面加载已发布事件与本人历史作答记录
若存在未完成的已发布事件，500 毫秒后自动弹出挑战弹窗并 toast 提示「你有未完成的紧急事件挑战：{标题}」
在弹窗中按章节推进：阅读沉浸式叙事场景，在时间限制内选择选项
完成后计算结果：总分、满分、正确率；保存到平台并同步薄弱知识点、错题、教师热力图（同步失败不阻塞主流程）
历史作答记录列表可随时回看（含事件标题、得分、时间）

操作步骤（教学游戏）

进入 /student/games，页面列出 status=active 的已发布游戏（按发布时间倒序）
每张游戏卡显示标题、简介、学科标签、本人累计分数与已玩关卡数
点击「开始游戏」/「继续游戏」进入全屏 iframe 游玩，顶栏可「退出游戏」
教师分享链接场景：直接访问 /play/{token}，校验 share_token 后游玩

页面与交互细节

紧急事件弹窗内选项得分与后果在作答后揭示；不同总分区间的结局叙事不同
游戏代码以 srcDoc 注入 iframe，sandbox="allow-scripts" 隔离（平台内游玩额外允许 same-origin 以记录分数）
游玩成绩写入 vibe_game_stats（关卡、分数、用时、是否通关、错误记录、知识标签）

边界与异常用例

场景	行为
无已发布事件	历史页正常展示历史记录，不弹窗
事件被删除但有历史记录	通过 `getEventById` 兜底加载事件信息展示
保存作答失败	toast「保存结果失败，请重试」，保留弹窗状态
分享链接无效	`/play/{token}` 显示「游戏不存在或链接无效」
游戏已下线	显示「此游戏已下线」
无游戏可玩	空态「暂无游戏，等待教师发布教学游戏」

关联接口与数据表

接口：紧急事件经 emergency-db 封装直连 Supabase；/api/platform/emergency/enhance
数据表：emergency_events、emergency_completions、emergency_answers、vibe_game_publications、vibe_game_stats

验收用例

编号	前置条件	步骤	预期结果
S8-01	教师已发布事件且学生未完成	进入紧急事件页	自动弹出挑战弹窗并提示
S8-02	完成挑战	提交全部答案	显示得分/满分/正确率，历史记录出现该条
S8-03	挑战中有答错知识点	查看错题本/教师热力图	相应知识点被记录
S8-04	教师已发布游戏	进入游戏中心并开始游戏	游戏正常运行，退出后累计分数更新
S8-05	持有分享链接	访问 /play/{token}	游戏正常运行

S9. 课堂笔记与课后回顾（/student/live、/live/{id}）

功能概述

学生上课录音，平台实时转写为逐字稿并滚动生成 AI 总结（只读）；学生讲到重点时一键标记（按钮或快捷键 Cmd/Ctrl+M，可选标记前 1/3/5 分钟窗口），系统自动为重点生成标题与摘要，并可进一步生成 2-3 道自测题（单选/判断/简答）帮助检验是否听懂。课后进入回顾页（/live/{id}）以「听悟式」布局回看：播放器 + 逐字稿（点击跳转、播放高亮）+ AI 总结/章节/重点三 Tab。

操作步骤（课堂笔记）

进入 /student/live（主导航「课堂笔记」），可选关联已选课程（不关联则为个人录音；关联后重点归属该课程便于回顾）
选择音源（麦克风/系统声音）与转写方案（高质量分段/实时流式）
点击「开始录音」，逐字稿与 AI 滚动总结实时上屏（总结为只读）
讲到重点时点击「标记重点」按钮或按 Cmd/Ctrl+M，选择窗口 1/3/5 分钟（默认 3 分钟），系统截取该窗口逐字稿并 AI 生成重点标题/摘要
对某条重点点击「生成自测题」，AI 基于该段逐字稿出 2-3 道题（单选/判断/简答，附答案与解析）
点击重点可在逐字稿中高亮对应起点段
点击「停止并保存」，进入课后回顾

操作步骤（课后回顾 /live/{id}）

从课堂笔记/直播授课页「查看课后回顾」或历史录音进入 /live/{id}
顶部播放器可播放录音；左侧逐字稿随播放高亮当前段，点击任一段可跳转播放位置
右侧三 Tab：AI 总结（整体总结 + 知识点标签）、章节（点击章节跳转播放）、重点（学生标记的重点，可再生成自测题）

页面与交互细节

重点标记快捷键 Cmd/Ctrl+M 仅在录音进行中生效；窗口可选 60/180/300 秒，默认 180 秒
重点存 lecture_keypoints（含 transcript_text 摘录、title、ai_summary、questions JSONB），仅本人可写、本人可读，课程教师可读作学情参考
自测题题型限 single_choice/true_false/short_answer，严格基于重点段逐字稿生成，不编造
回顾页逐字稿点击 seek、播放进度驱动高亮（落段间隙时取最近前一段）
学生的答题链路仍走现有「随堂测验」，课堂笔记的自测题为重点自检，不计入测验成绩

边界与异常用例

场景	行为
标记重点时该时间段无逐字稿	返回 400「该时间段暂无逐字稿内容，无法标记重点」
非学生角色调用标记重点	返回 403「Student only」
AI 生成标题/摘要不可用（未配置模型）	重点以时间兜底标题保存（「重点 HH:MM:SS」），`ai_summary` 为空
生成自测题失败	toast 提示，重点保留可重试
回顾页录音不存在/无权访问/未登录	分别显示「录音不存在或已删除」/「无权访问该录音」/「请先登录后再查看」

关联接口与数据表

接口：POST/GET /api/platform/live/keypoints、POST /api/platform/live/keypoints/{id}/questions；录音与逐字稿/总结/音频接口同 T12；回顾页读取 recordings/{id}、segments、summarize、keypoints
数据表：lecture_keypoints（含 questions JSONB）、lecture_recordings、lecture_segments、lecture_summaries

验收用例

编号	前置条件	步骤	预期结果
S9-01	学生已登录并录音	讲到重点点击标记重点（窗口 3 分钟）	生成重点条目，含 AI 标题/摘要
S9-02	重点已标记	点击「生成自测题」	返回 2-3 道题（单选/判断/简答）含答案与解析
S9-03	录音进行中	按 Cmd/Ctrl+M	等效点击标记重点，快捷生成重点
S9-04	录音已保存	进入课后回顾 `/live/{id}`	播放器可播放，逐字稿随播放高亮，点击段可跳转
S9-05	回顾页右侧切换 Tab	查看 AI 总结/章节/重点	三 Tab 内容正确，章节点击跳转播放
S9-06	标记重点但该段无逐字稿	点击标记重点	提示「该时间段暂无逐字稿内容，无法标记重点」

6. 平台基础设施

6.1 自建 Supabase（数据与认证）

以 Docker Compose 自托管 Supabase（PostgreSQL + Auth + Storage + Realtime），不依赖外部 SaaS
全部核心业务表开启 RLS（Row Level Security），策略按角色与归属校验：

教师仅可读写自己的课程、分身、案例、游戏发布
学生仅可读写自己的选课、进度、作答、错题；可读已发布课程与事件

向量扩展 vector：知识库分块嵌入（1024 维），ivfflat 索引 + 全文检索 gin 索引双通道

6.2 agent-service（AI 能力服务）

独立部署的 AI 能力服务，与教学平台解耦，通过 HTTP 接口提供：

出题（generate-ai-questions）、题目评估（evaluate-question）、讲解辅助（teaching-assist）、学情诊断（diagnose）
主观题判分（quiz-grade）、分身对话（avatar/chat 流式）

未配置或不可用时全线降级：出题走兜底模板、对话页显示降级提示，不阻塞其他功能

6.3 知识库 RAG

教师上传课程文档（/api/platform/documents），解析入库 course_documents
文档分块（document_chunks）并生成 1024 维嵌入向量
分身答疑时先向量检索相关分块，再结合纠错记录与教师知识概要生成回答，保证答疑贴合课程内容

6.4 语音能力（TTS / ASR）

TTS：课堂旁白与分身播报（/api/platform/tts、/api/generate/tts、/api/azure-voices），课堂音频按场景预生成并缓存
ASR：学生语音提问转文字（/api/platform/asr、/api/transcription），录音组件带声纹波形反馈
课堂录音转写（Live Lecture，v2.2 新增）双方案：高质量分段（默认）MediaRecorder 每 45s 切片上传，服务端 ffmpeg 转 16k 单声道 WAV 后走百炼 qwen3-asr-flash（或 SiliconFlow SenseVoiceSmall）文件转写定稿；实时流式额外经 AudioWorklet 采集 PCM，由 agent-service WS 代理转发百炼 paraformer-realtime-v2 出秒级 interim，最终仍由 45s 分段文件转写覆盖定稿；流式不可用自动降级分段，录音不中断
音频缺失时静默降级，不中断教学流程（本轮已修复并全量补配音）

6.5 部署架构

单机 ECS（火山引擎）Docker Compose 部署，caddy 边缘反代统一 HTTPS 入口（thu2026.online 主站 / guide.thu2026.online 手册 / api.thu2026.online Supabase / www 301 跳裸域；仅监听 443，TLS-ALPN-01 自动签发续期 Let's Encrypt 证书，80 端口归宿主机其他项目）：

openmaic：Next.js 应用，内网端口 3000（主站，经 Caddy 反代 https://thu2026.online）
guide-site：静态指南站，内网端口 80（使用手册，经 Caddy 反代 https://guide.thu2026.online）
supabase 全套容器（经 Caddy 反代 https://api.thu2026.online）+ agent-service（内网能力端口 8787 不对外；v2.2 新增流式转写 WS 代理，内网端口 8788 经 Caddy 以 wss://thu2026.online/v1/asr-stream 暴露，仅挂载该路径，密钥不出服务端）

发布流程：git pull → docker compose build && up -d 重建（openmaic 需带 NEXT_PUBLIC_* build args）；migrate.sh 按序应用 supabase/migrations/*.sql
健康检查：/api/health；媒体代理 /api/proxy-media 处理外链资源

6.6 其他平台能力

对话主通道 /api/chat 与 /api/chat/pi（通用对话）
PBL 项目式学习引擎（/api/pbl/v2/*：任务、评估、模拟、导师）
视频导出（/api/export-video/*）、联网搜索（/api/web-search）
供应商校验与探测（/api/verify-*、/api/server-providers、/api/provider/probe-models）、用量统计（/api/usage）
访问码（/api/access-code/*）用于受控分发场景

6.7 PPT 智能优化管线（后台任务与导出后处理）

任务执行模型：POST /api/ppt-optimize 返回 202 后由 Next.js after() 钩子在服务端后台执行优化管线（与课堂生成任务同模式）；任务元数据写入文件型 job store（data/ppt-optimize-jobs/{jobId}.json，原子写 + 进程内互斥锁），生产环境位于容器卷 /app/data（docker 命名卷 openmaic-data）；解析后的课件全量数据仅在 runner 内存中流转，不落盘
stale 看门狗：running 状态任务超过 30 分钟无进度更新，读取时自动判为 failed（服务重启中断的任务不会永久卡在运行中）
pptx 过渡动效后处理：pptxgenjs 导出器不支持页面切换动效，导出链路在 zip 层为每张幻灯片 XML 注入 <p:transition spd="med"><p:fade/></p:transition>（lib/export/pptx-transitions.ts）
模型调用策略：优化管线固定禁用推理（SiliconFlow 兼容端点传 enable_thinking: false；该供应商拒绝 thinking_budget <= 0，故禁用推理时不下发该参数，见 lib/ai/providers.ts）

7. API 接口清单

以下清单源自 app/api 目录反查（共约 97 个路由），按模块分组。路径中 {} 表示动态参数。

7.1 平台课程与选课

路径	方法	用途
`/api/platform/courses`	GET/POST	课程列表（学生看已发布）/ 创建课程
`/api/platform/courses/{id}`	GET/PATCH/DELETE	课程详情 / 更新（发布、归档）/ 删除
`/api/platform/courses/{id}/stages`	GET/POST	课程章节列表 / 写入章节
`/api/platform/enrollments`	GET/POST/DELETE	选课记录查询 / 选课 / 退课
`/api/platform/profile`	GET/PATCH	用户资料（角色、昵称）
`/api/platform/notifications`	GET/PATCH	消息通知列表 / 标记已读

7.2 题库与随堂测验（教师）

路径	方法	用途
`/api/platform/questions`	GET/POST	题目列表（可按状态/题型筛选）/ 创建题目
`/api/platform/questions/{id}`	PATCH/DELETE	编辑 / 删除题目
`/api/platform/inclass/teacher/generate-ai-questions`	POST	AI 按知识点批量出题
`/api/platform/inclass/teacher/generate-distractors`	POST	AI 生成选择题干扰项
`/api/platform/inclass/teacher/review-question`	POST	复核学生提交题（通过/驳回）
`/api/platform/inclass/teacher/create-config`	POST	创建测验配置（难度分布）
`/api/platform/inclass/teacher/generate-quiz`	POST	抽题组卷生成学生测验会话
`/api/platform/inclass/teacher/live-monitor`	GET	实时监控（交卷进度、每题正确率）
`/api/platform/inclass/teacher/teaching-assist`	POST	低正确率题讲解话术
`/api/platform/inclass/teacher/diagnose`	POST	一键学情诊断

7.3 随堂测验（学生）与判分

路径	方法	用途
`/api/platform/inclass/student/my-sessions`	GET	我的测验列表（待作答/已完成）
`/api/platform/inclass/student/session-questions`	GET	测验题目（作答视图）
`/api/platform/inclass/student/submit-answers`	POST	提交答案
`/api/platform/inclass/student/session-detail`	GET	测验逐题结果回看
`/api/platform/inclass/student/submit-question`	POST	学生出题（含 AI 初评）
`/api/quiz-grade`	POST	主观题 AI 判分
`/api/platform/quiz/attempt`	POST	练习做题记录
`/api/platform/quiz/stats`	GET	做题统计
`/api/platform/quiz/wrong-answers`	GET/PUT	错题列表 / 标记掌握

7.4 AI 分身与答疑

路径	方法	用途
`/api/platform/avatar`	GET/POST	分身配置读取 / 保存
`/api/platform/avatar/chat`	POST	分身对话（流式）
`/api/platform/avatar/conversations`	GET/PATCH	对话记录（教师复核）
`/api/platform/avatar/history`	GET	学生恢复最近分身会话（`?courseId=`；返回 sessionId/messages/mode/updatedAt，RLS 限本人）
`/api/platform/avatar/corrections`	GET/POST/DELETE	纠错条目管理
`/api/platform/student/tutors`	GET	学生辅导聚合列表
`/api/agent/capabilities/evaluate-question`	POST	题目质量评估
`/api/agent/capabilities/explain-question`	POST	题目讲解生成

7.5 学情、作业与知识体系

路径	方法	用途
`/api/platform/dashboard/teacher`	GET	教师学情看板数据
`/api/platform/dashboard/student`	GET	学生个人学情数据
`/api/platform/assignments`	GET/POST	作业列表 / 创建
`/api/platform/assignments/{id}`	GET/PATCH/DELETE	作业详情与更新
`/api/platform/assignments/{id}/grade`	POST	批改打分
`/api/platform/assignments/{id}/personal-params`	GET/POST	个性化参数
`/api/platform/assignments/{id}/submissions`	GET	提交列表（教师）
`/api/platform/assignments/{id}/submit`	POST	学生提交作业
`/api/platform/assignments/my-submissions`	GET	我的提交（学生）
`/api/platform/assignments/executive-chat`	POST	高管访谈对话
`/api/platform/knowledge/{courseId}`	GET	课程知识体系/掌握度
`/api/platform/notes`	GET/POST/PATCH	学习笔记
`/api/platform/preview-tasks`	GET/POST	预习任务

7.6 知识库、语音与紧急事件

路径	方法	用途
`/api/platform/documents`	GET/POST	课程文档列表 / 上传
`/api/platform/documents/{id}`	DELETE	删除文档
`/api/platform/tts`	POST	平台语音合成
`/api/platform/asr`	POST	语音识别
`/api/azure-voices`	GET	可用音色列表
`/api/platform/emergency/enhance`	POST	紧急事件叙事 AI 增强

7.7 课堂与媒体生成

路径	方法	用途
`/api/classroom`	GET/POST	课堂数据读写
`/api/classroom-media/{classroomId}/{...path}`	GET	课堂媒体资源
`/api/generate-classroom`	POST	发起课堂生成任务
`/api/generate-classroom/{jobId}`	GET	生成任务进度
`/api/ppt-optimize`	POST	发起 PPT 智能优化任务（详见 T11；请求 {fileName, slides, directions, styleNote?, enableTTS?}，202 返回 {jobId, pollUrl, pollIntervalMs}）
`/api/ppt-optimize/{jobId}`	GET	PPT 优化任务轮询（status/step/progress/pagesOptimized/totalPages/result/error）
`/api/generate/scene-outlines-stream`	POST	场景大纲流式生成
`/api/generate/scene-content`	POST	场景内容生成
`/api/generate/scene-actions`	POST	角色动作生成
`/api/generate/agent-profiles`	POST	角色画像生成
`/api/generate/image`	POST	图像生成
`/api/generate/video`	POST	视频生成
`/api/generate/tts`	POST	课堂语音合成
`/api/generate/voice`	POST	音色克隆/生成
`/api/parse-pdf`	POST	PDF 解析
`/api/extract-document`	POST	文档内容抽取
`/api/proxy-media`	GET	外链媒体代理
`/api/comfyui-workflows`	GET	可用工作流列表

7.8 AI 编程工作台与游戏

路径	方法	用途
`/api/vibe-code/generate`	POST	自然语言生成代码
`/api/vibe-code/modify`	POST	对话式修改代码
`/api/vibe-code/import`	POST	导入既有代码
`/api/vibe-code/publish`	POST	发布游戏（平台/分享链接）
`/api/vibe-code/stats`	GET	游玩统计
`/api/vibe-code/storyboard/check-capability`	GET	分镜能力探测
`/api/vibe-code/storyboard/generate-image`	POST	分镜图像生成
`/api/vibe-code/storyboard/generate-tts`	POST	分镜配音生成

7.9 平台运维与扩展能力

路径	方法	用途
`/api/health`	GET	健康检查
`/api/usage`	GET	用量统计
`/api/chat`、`/api/chat/pi`	POST	通用对话通道
`/api/pbl/v2/open-task`、`task/update`、`evaluate`、`instructor`、`simulator`、`chat`	POST/GET	PBL 项目式学习引擎
`/api/export-video/capability`、`render`、`render/{jobId}`、`render/{jobId}/download`	GET/POST	视频导出
`/api/web-search`	POST	联网搜索
`/api/agent/edit`	POST	智能体编辑
`/api/transcription`	POST	转写
`/api/access-code/status`、`verify`	GET/POST	访问码校验
`/api/verify-model`、`verify-image-provider`、`verify-pdf-provider`、`verify-video-provider`、`server-providers`、`provider/probe-models`	GET/POST	供应商配置校验与探测

7.10 课堂录音与实时转写（Live Lecture，v2.2）

路径	方法	用途
`/api/platform/live/recordings`	GET/POST	录音列表 / 创建录音（body 含 `transcribe_mode`：segment/stream，默认取 `LIVE_ASR_DEFAULT_MODE`）
`/api/platform/live/recordings/{id}`	GET/PATCH	录音详情（本人或课程教师）/ 更新（JSON 改状态标题时长，或 multipart 停录落盘置 ready）
`/api/platform/live/recordings/{id}/audio`	GET	录音音频回放
`/api/platform/live/recordings/{id}/segments`	GET/POST	分段列表 / 上传分段音频（multipart audio+seq+start_sec+end_sec）→ 文件转写 upsert（静音段不入库；ASR 未配置返 503）
`/api/platform/live/recordings/{id}/summarize`	GET/POST	读取滚动总结（overall/chapters/knowledge_tags/windows）/ 触发窗口增量总结（无模型 503，窗口无内容 400）
`/api/platform/live/keypoints`	GET/POST	学生重点标记列表 / 创建（`at_sec`+`window_sec`∈[60,180,300]，仅 student，非学生 403，无逐字稿 400）
`/api/platform/live/keypoints/{id}/questions`	POST	为重点片段生成 2-3 道自测题（single_choice/true_false/short_answer）
`/api/platform/live/teacher/generate-quiz`	POST	教师一键出题（`window_minutes` 默认 10、`count` 默认 5）→ 题库匹配(bank) + AI 补充(ai) 混合候选
`/api/platform/live/asr-ticket`	POST	签发流式转写 5min HMAC 票据（`{ticket, ws_url}`），供浏览器连 agent-service WS
`wss://thu2026.online/v1/asr-stream?ticket=`	WS	agent-service 流式转写代理（转发百炼 `paraformer-realtime-v2`，回推 interim/定稿句）

8. 数据模型详表

源自 supabase/migrations/（15 个迁移文件，30 张业务表）。下表列出核心字段与用途；全表默认含 created_at/updated_at 时间戳的不再重复标注。

8.1 账号与课程域（001）

表	关键字段	用途
`profiles`	id(=auth.users)、role(teacher/student)、display_name、avatar_url、bio	用户档案，角色识别
`courses`	teacher_id、title、description、cover_url、subject、difficulty(easy/medium/hard)、status(draft/published/archived)、config(JSONB)、published_at	课程主表
`course_stages`	course_id、stage_id、title、order_index、stage_data(JSONB)	课程章节（课堂数据快照）
`enrollments`	student_id、course_id、progress_pct、last_accessed_at；UNIQUE(student,course)	选课与学习进度
`teacher_avatars`	teacher_id(UNIQUE)、name、knowledge_config、teaching_style(rigorous/humorous/socratic)、style_prompt、boundary_rules、hint_levels(1-3)、corrections(JSONB)、is_active	AI 分身配置与纠错库
`avatar_conversations`	avatar_id、student_id、course_id、messages(JSONB)、session_id、mode(normal/socratic)、resolved、teacher_reviewed；UNIQUE(student_id,session_id)（011 会话化）	分身对话记录（按会话存储，供学生恢复与教师复核）
`assignments`	course_id、title、description、precheck_config、due_at、max_score、assignment_type(7 类)、knowledge_tags、ai_process_required、personal_params_config、time_limit_minutes、executive_role	作业定义（001+003+004）
`assignment_submissions`	assignment_id、student_id、file_urls、content、precheck_result、status(submitted/prechecked/reviewed/returned)、score、feedback、ai_process_log、personal_params、graded_by；UNIQUE(assignment,student)	作业提交与批改
`learning_progress`	student_id、course_id、stage_id、scene_id、scene_type、status(not_started/in_progress/completed)、quiz_score/quiz_total、interaction_data	场景级学习进度
`mastery_profiles`	student_id、course_id、mastery_data、radar_data；UNIQUE(student,course)	能力图谱

8.2 习题与学情域（003、004、007）

表	关键字段	用途
`questions`	course_id、stage_id、question_type(9 类)、content(JSONB)、knowledge_tags、difficulty(easy/medium/hard)、difficulty_level(1-5)、score、created_by、source(teacher/student)、submitter_id、status(pending/approved/rejected)、agent_evaluation(JSONB)、question_tags	题库（组卷/练习/作业共用）
`quiz_attempts`	student_id、question_id、course_id、student_answer、is_correct、time_spent_ms	做题记录
`wrong_answers`	student_id、question_id、course_id、wrong_count、last_wrong_at、reviewed；UNIQUE(student,question)	错题本
`knowledge_nodes`	course_id、parent_id、title、description、stage_id、order_index	知识体系树
`preview_tasks`	course_id、stage_id、requirements、question_ids、due_at、created_by	预习任务
`student_notes`	student_id、course_id、stage_id、content、knowledge_tags	学习笔记
`notifications`	user_id、type(6 类)、title、body、link_url、read	消息通知
`assignment_personal_params`	assignment_id、student_id、params；UNIQUE(assignment,student)	作业个性化参数

8.3 随堂测验域（005、010）

表	关键字段	用途
`quiz_configs`	course_id、teacher_id、distribution(JSONB)、grading_mode(fixed/dynamic)、fixed_score、reward_score、status(active/closed)	测验配置（难度分布与计分）
`quiz_sessions`	config_id、course_id、student_id、status(in_progress/submitted)、total_score、reward_earned、started_at、submitted_at、results(JSONB：逐题判分快照)；UNIQUE(config,student)	学生测验会话；010 增加 results 支撑详情回看
`quiz_session_questions`	session_id、question_id、slot、score、replaced_own；UNIQUE(session,slot)	会话抽题明细（含提交者回避标记）

8.4 知识库域（006）

表	关键字段	用途
`course_documents`	course_id、teacher_id、file_name、mime_type、full_text、char_count、chunk_count、embedded	课程文档（RAG 语料）
`document_chunks`	document_id、course_id、chunk_index、heading、content、token_count、embedding(vector 1024)	分块嵌入（ivfflat 向量索引 + gin 全文索引）

8.5 紧急事件域（006、008）

表	关键字段	用途
`emergency_events`	user_id、title、description、case_source、status(draft/published/ended)、questions(JSONB)、player_role、story_intro、story_endings(JSONB)、published_at、ended_at	紧急事件案例（008 增加叙事字段）
`emergency_completions`	event_id、user_id、total_score、max_score、correct_count、total_questions、started_at、completed_at	学生作答总记录
`emergency_answers`	completion_id、event_id、question_id、selected_option_id、is_correct、score、time_spent、answered_at	逐题作答明细

8.6 AI 编程与游戏域（005、009）

表	关键字段	用途
`vibe_projects`	user_id、name、type(game/video-script)、code	工作台项目
`vibe_code_versions`	project_id、code、source(ai/user)、message	代码版本历史
`vibe_chat_messages`	project_id、role(user/assistant)、content、code_snapshot	对话记录
`vibe_game_publications`	project_id、teacher_id、course_id、title、description、grade、subject、language、game_code、game_config、share_token(UNIQUE)、status(active/archived)、published_at	游戏发布
`vibe_game_stats`	publication_id、student_id、level_index、level_name、score、max_score、time_spent、is_passed、mistakes、knowledge_tags、played_at	游玩成绩
`vibe_user_templates`	user_id、name、description、game_type、code_snapshot、config	用户游戏模板

8.7 关键约束与策略摘要

enrollments、wrong_answers、assignment_submissions、assignment_personal_params、quiz_sessions、mastery_profiles 均设业务唯一约束，防重复数据
全部表启用 RLS；紧急事件、游戏发布对「本人 + 已发布内容」开放读
002 修复触发器（updated_at 维护）；010 以 JSONB 快照方式保证判分结果回看稳定
011 将 avatar_conversations 会话化：新增 session_id（(student_id,session_id) 唯一索引，upsert 冲突键）、mode（normal/socratic）、updated_at（会话恢复与教师列表排序），并清理历史每轮全量快照（同一学生×课程仅保留最新一条），教师回看不再出现重复记录

8.8 PPT 优化任务文件（非数据库存储）

data/ppt-optimize-jobs/{jobId}.json，每任务一个 JSON 文件（原子写），仅存进度元数据与最终结果，不存课件内容：

字段	说明
`id`、`status`	任务 ID（nanoid 10 位）；状态 `queued`/`running`/`succeeded`/`failed`
`step`、`progress`、`message`	阶段（`initializing`/`planning`/`optimizing_pages`/`generating_tts`/`persisting`/`completed`，异常时 `failed`）、百分比、进度文案
`inputSummary`	`{fileName, pageCount, directions}`（方向取值 cases/visualization/visual/motion）
`pagesOptimized`、`totalPages`	逐页进度计数
`createdAt`/`updatedAt`/`startedAt`/`completedAt`	时间戳（`updatedAt` 驱动 30 分钟 stale 看门狗）
`result`	`{classroomId, url, stageName, scenesCount, designSystem{concept,palette,typography,spacing,iconography}, changelog[]}`；changelog 条目 `{page, title, type(slide/quiz), status(optimized/kept_original/converted_quiz/failed), changes[], before, after}`
`error`	失败原因（failed 时存在）

8.9 课堂录音域（012、013，Live Lecture）

表	关键字段	用途
`lecture_recordings`	owner_id(→profiles)、role(teacher/student)、course_id(→courses 可空)、title、source(mic/system)、status(recording/ready/failed)、duration_sec、audio_path、`transcribe_mode`(segment/stream，013 新增，默认 segment)	课堂录音主表（师生每次录音一条，记录所选转写方案）
`lecture_segments`	recording_id、seq、start_sec、end_sec、text；UNIQUE(recording_id,seq)	分段逐字稿（45s 切片文件转写定稿结果，按 seq upsert）
`lecture_summaries`	recording_id、kind(window/overall)、start_sec、end_sec、content、chapters(JSONB)、knowledge_tags(JSONB)	滚动总结（window 增量行 + overall 最新整体总结/章节/知识点标签，供出题匹配题库）
`lecture_keypoints`	recording_id、student_id、start_sec、end_sec、transcript_text、title、ai_summary、questions(JSONB)	学生重点标记（截取窗口逐字稿 + AI 标题/摘要 + 可选自测题）

RLS：lecture_recordings 本人 + 课程教师可 SELECT，本人 INSERT/UPDATE/DELETE；lecture_segments/lecture_summaries 经 recording 归属间接控制；lecture_keypoints 本人 + 课程教师可读、本人可写
013 迁移幂等：ADD COLUMN IF NOT EXISTS transcribe_mode + 重建 CHECK 约束（segment/stream）

9. 本版本新增能力

9.1 2026-09 上线版（当前版本 v2.2）

以下能力已发布至生产环境（https://thu2026.online）。苏格拉底持久化与 PPT 优化已通过生产回归验证；Live Lecture 随 v2.2 发布上线，线上双模式录音回归于部署后执行：

能力	说明	验收结论
Live Lecture 课堂录音转写与智能出题（双转写方案可配置）	教师「直播授课」/ 学生「课堂笔记」录音，实时逐字稿 + AI 滚动总结（整体/章节/知识点标签）+ 基于已讲内容一键出题（题库 bank 匹配 + AI 补充）+ 学生重点标记（Cmd/Ctrl+M，60/180/300s 窗口，可生成自测题）+ 课后回顾页 `/live/{id}`（播放器/逐字稿/总结/章节/重点）；转写支持「高质量分段（45s 文件转写定稿）/ 实时流式（paraformer-realtime-v2 秒级 interim + 分段覆盖定稿）」双方案，录音前自选写入 `transcribe_mode`，流式不可用自动降级分段（详见 T12 / S9）	随 v2.2 发布上线；本地静态校验 tsc/eslint/build + agent-service typecheck 全绿；线上双模式录音（分段/流式/降级）回归于部署后执行
苏格拉底问答对话持久化与教师端回看	对话会话化（按 student_id+session_id upsert 全量消息，替代每轮 insert 快照）并记录对话模式（normal/socratic）；学生刷新/换设备自动恢复历史会话；教师回看列表按活跃时间排序、显示模式徽标与提问轮数	生产上线（commit `d9c5e69`）；学生恢复、教师回看徽标与去重回归正常
外部 PPT 上传与 AI 智能优化	上传 .pptx 客户端解析，AI 按四方向（案例更新/算法可视化/视觉智能化/动效过渡）逐页改写并统一设计系统，雨课堂互动页自动转平台测验场景；交付平台互动课堂 + 带 fade 过渡的优化版 .pptx + 逐页修改说明清单（详见 T11）	生产上线（commit `4192810`）；本地 41 页课件实测 41/41 成功（36 优化 + 5 转测验），生产环境复测 37/37 成功，导出 pptx 校验 32 页且逐页含过渡动效

9.2 2026-08 合并版

以下能力在该版本完成上线并通过线上回归验证：

能力	说明	验收结论
课堂音频修复与补配音	定位音频缺失双根因并修复，完成 129 条场景语音补配音，课堂播放全程有声	线上播放正常，可暂停，音频资源 206 正常
课堂媒体缓存补丁	课堂加载缓存与远端不一致时自动打补丁/回源，修复切课堂串数据	刷新与切换课堂加载正确
测验详情回看	`quiz_sessions.results` 持久化逐题判分，学生可查看对错、作答与解析；历史数据兜底文案	9 条记录查看详情正常，历史兜底生效
AI 辅导聚合入口	`/student/tutor` 按课程聚合教师分身，一键进入答疑对话	课程卡与提问入口正常
答疑纠错管理	教师复核对话、录入纠错，分身持续进化	纠错区块与对话列表正常
AI 编程工作台（合并版）	新侧边栏、多设备预览、保存到本地、分镜图像与配音、游戏发布与分享链接	接口全 200/201，功能闭环可用
双方代码合并	合并协作者提交（含分镜预览等），修复合并引入的 4 个类型错误	tsc/eslint 零错误，构建通过

10. 非功能需求

维度	要求
兼容性	主流现代浏览器（Chrome/Edge/Safari）；课堂与测验页在桌面与移动端均可用；工作台支持手机/平板/桌面三视口预览
可靠性	判分、组卷等关键路径具备唯一约束与幂等；媒体加载失败不中断教学流程；对话与生成任务支持失败重试
性能	实时监控 6 秒轮询；AI 出题约 20-40 秒、判分约 30-60 秒，均以加载态明确提示；课堂媒体本地缓存优先
降级策略	AI 服务不可用：出题兜底模板、对话降级提示、预审跳过人工批改；音频缺失静默继续；知识库未配置时基于分身配置回答
安全	全表 RLS；游戏代码 iframe 沙箱隔离；禁答话题边界约束分身输出；访问码受控分发
数据一致性	关键表业务唯一约束；判分结果快照化；本地课堂与课程章节发布流程单向同步
质量门槛	代码合并需通过 tsc 与 eslint 零错误；上线前完成线上全量回归（见第 9 章）

11. 风险与说明

AI 生成耗时：出题、判分、课堂生成均为秒级至分钟级异步过程，依赖模型服务稳定性；已通过加载态、任务轮询与兜底模板缓解，但极端情况下仍需教师人工介入
本地课堂依赖浏览器存储：本地草稿存于 IndexedDB，更换浏览器/设备会丢失未发布草稿，重要内容应及时发布到课程
主观题判分为 AI 评估：结果供教学参考，最终解释权在教师（可人工复核批改）
历史数据兼容：010 迁移前交卷的测验无逐题详情，回看页以兜底文案说明，不做数据回填
单机部署：当前为单台 ECS 承载全部容器，适合教学试点规模；扩容需拆分数据库与应用层
角色切换：教师与学生共用同一浏览器会话时需登出重登，不支持同浏览器双角色并行
本文档描述的接口行为与字段以代码基线为准；后续迭代如变更接口契约，需同步更新本文档

（完）