dianshang-houduan/docs/superpowers/specs/2026-07-30-teacher-student-demo-mode-design.md

教师学生端讲解模式设计

目标

教师可以选择自己创建的教学班，在新窗口以学生端界面讲解任务流程。演示会话读取所选教学班的任务、任务分配和页面配置，但不会创建虚拟学生账号、不会写入教学班成员关系，也不会持久化答案、进度、成绩或其他学生业务数据。

不采用 _ys 账号的原因

学生端当前通过 teaching_class_student 的有效成员记录确定教学班。为 张辉_ys 一类账号提供内容，必须把账号加入教学班；而现有模型只会取该学生最近的一条有效教学班归属。切换讲解班级会导致成员关系迁移，并污染学生名单、学习记录、成绩和账号管理。

因此，演示模式使用受控的虚拟会话，不创建 userinfo 学生记录，也不新增 teaching_class_student 记录。

会话与单点进入

教师端

教师端新增“学生端讲解”入口。点击后展示本人创建的教学班列表；未选择教学班不能进入。

教师选择班级后，前端调用教师专用接口创建一次性演示票据。后端必须验证：

1. 当前用户为教师；
2. 教学班类型为 TEACHING；
3. school_class.created_by 等于当前教师用户 ID。

前端打开独立学生端窗口，并将一次性票据通过同源 postMessage 发送给新窗口，不把 JWT 放入 URL、浏览器历史或 Referer。

后端

新增演示会话接口：

接口	用途
POST /api/teacher/student-demo-sessions	教师为本人教学班创建短时、单次使用的演示票据。
POST /api/student-demo-sessions/exchange	新窗口使用票据换取演示学生 token。

票据存储字段包括票据值哈希、来源教师 ID、教学班 ID、学校 ID、过期时间、已使用时间和创建时间。票据有效期为 5 分钟，成功兑换后立即失效。演示 token 有效期为 30 分钟。

兑换后的 JWT 维持学生端 roleId=4，并增加如下声明：

• demoMode=true
• demoTeachingClassId
• sourceTeacherId

JwtUser 与 TokenProvider 解析这些声明，供后续服务统一判断演示上下文。

教学班解析规则

新增统一的学生上下文解析器：

1. 普通学生：保留现有 teaching_class_student 有效成员关系查询。
2. 演示学生：直接使用 JWT 的 demoTeachingClassId；不查询、不创建成员关系。

任务详情、任务列表、任务分配、成绩参考、进度展示等学生端读取服务均使用该解析器，确保教师看到的是所选教学班的真实教学内容和配置。

演示 token 不允许通过传入其他班级 ID 改变上下文；任何请求中的教学班 ID 必须与 demoTeachingClassId 一致，否则拒绝。

演示数据隔离

演示会话不能持久化任何学生业务数据。

类型	演示模式行为
读取任务、任务分配、班级配置	使用 demoTeachingClassId 正常读取。
查询答案与进度	返回当前窗口的临时数据；首次进入为未开始、空答案。
保存、提交、重置或删除答案	前端写入 sessionStorage 并展示成功，不调用持久化接口。
成绩、排名、进度写入	禁止调用或返回演示提示，不写数据库。
AI 助学、AI 评测及外部资源调用	在演示模式禁用，避免产生外部调用成本或写入结果。

关闭演示窗口或演示 token 过期后，临时数据自动丢弃。教师端、学生端和后端均不保留演示答案内容。

前端交互

1. 教师端按钮只对教师可见，班级选择框只展示当前教师创建的教学班。
2. 新窗口进入专用学生端演示路由，等待父窗口发送票据并换取 token；若票据缺失、过期或已使用，展示“演示链接已失效，请返回教师端重新打开”。
3. 演示学生端顶部展示醒目条：演示模式：{教学班名称}，并提供“退出演示”按钮。
4. 学生端菜单与普通学生一致；被禁用的 AI、成绩提交等操作提供明确的“演示模式不保存数据”提示。
5. 演示窗口使用独立的 session storage 键保存 token 和临时答案，不覆盖教师窗口或普通学生窗口的登录状态。

安全与边界

• 创建票据和兑换票据均校验有效期、单次使用状态和来源学校。
• 教师只能创建本人教学班的演示会话，不能进入其他教师的班级。
• 演示 token 不拥有教师管理权限；仅拥有学生端读取权限和演示上下文。
• 所有持久化写接口在后端额外识别 demoMode 并拒绝写入，不能仅依赖前端禁用。
• 不创建 _ys 用户、密码、学生档案、班级成员或成绩记录。

验收标准

1. 教师可在新窗口进入自己创建的教学班对应的学生端，并看到该班任务内容。
2. 教师无法为非本人创建的教学班创建演示会话。
3. 普通学生的登录、任务读取、答案保存和班级归属逻辑保持不变。
4. 演示过程中填写答案、切换步骤、提交或退出后，数据库的答案、进度、成绩、排名和成员数据均无新增或变更。
5. 票据不能重复兑换，过期票据无法兑换；演示 token 过期后必须重新从教师端进入。