# 教师学生端讲解模式设计

## 目标

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

## 不采用 `_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 过期后必须重新从教师端进入。