docs: plan teacher student demo mode

1 month ago · 52ba31731c
parent 2bc3ab05ba
commit 52ba31731c
1 changed files with 253 additions and 0 deletions
--- a/docs/superpowers/plans/2026-07-30-teacher-student-demo-mode.md
+++ b/docs/superpowers/plans/2026-07-30-teacher-student-demo-mode.md
@ -0,0 +1,253 @@
+# 教师进入学生端讲解模式实施计划
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use `superpowers:executing-plans` to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 教师从教师端选择本人创建的教学班后，可在独立新窗口进入该班对应的学生端进行讲解；演示窗口能读取该教学班的任务与任务分配，但不会创建 `_ys` 学生、不会写入成员关系、答案、进度、成绩、学习时长、访问次数、文件或 AI 评价数据。
+
+**Architecture:** 使用短时、一次性的演示票据交换 30 分钟的虚拟学生 JWT。JWT 保持 `roleId=4`，另带 `demoMode`、`demoTeachingClassId` 与 `sourceTeacherId` 声明。后端统一从 JWT 解析学生教学班上下文：普通学生继续读取 `teaching_class_student`，演示学生仅使用声明中的教学班。前端在新窗口的 `sessionStorage` 保存演示令牌和临时答题数据；认证 Cookie、真实学生答案和教师窗口均不受影响。
+
+**Tech Stack:** Spring Boot、Spring Security、JWT、MyBatis、MySQL、Vue 3、Element Plus、Axios、JUnit 5 + Mockito、Node `assert`。
+
+## Global Constraints
+
+- 不创建 `userinfo`、`teaching_class_student` 或任何 `_ys` 账号数据。
+- 创建票据者必须是 roleId=3 的教师，且教学班必须为 `TEACHING` 并由该教师创建；管理员教师不获得其他教师教学班的讲解权限。
+- 明文票据只返回给创建它的教师浏览器，数据库只保存 SHA-256 哈希；票据 5 分钟有效且只可兑换一次。
+- 演示 JWT 仅 30 分钟有效，roleId 固定为 4，不能携带教师管理权限。
+- 票据与 JWT 不进入 URL、浏览器历史或 Referer；窗口间仅以相同 origin 的 `postMessage` 传递票据。
+- 普通学生既有的班级归属、答题、提交、成绩与路由逻辑必须保持不变。
+- 演示模式的任何持久化写入都必须在后端再拦截一次，不能只依赖前端禁用按钮。
+
+---
+
+## 文件结构
+
+| 文件 | 责任 |
+| --- | --- |
+| `docs/sql/2026-07-30-student-demo-session.sql` | 创建一次性演示票据表和必要索引。 |
+| `entity/StudentDemoSession.java`、`mapper/StudentDemoSessionMapper.java`、`resources/mappers/StudentDemoSessionMapper.xml` | 演示票据持久化模型及原子兑换 SQL。 |
+| `service/StudentDemoSessionService.java`、`service/impl/StudentDemoSessionServiceImpl.java` | 教师班级校验、票据签发与一次性兑换。 |
+| `controller/stu/StudentDemoSessionController.java` | 教师创建票据、匿名交换票据为演示 token 的 REST 接口。 |
+| `config/security/JwtUser.java`、`config/security/TokenProvider.java` | 演示 JWT 声明、30 分钟签发和解析。 |
+| `service/StudentTeachingClassResolver.java`、`service/impl/StudentTeachingClassResolverImpl.java` | 普通学生/演示学生统一解析教学班并验证请求班级。 |
+| `service/impl/TrainingTaskServiceImpl.java`、`controller/stu/TrainingTaskController.java` | 学生任务列表与详情改用统一教学班上下文。 |
+| `controller/stu/TaskAllocationController.java`、`controller/stu/UserController.java` | 任务分配和当前教学班查询改用 JWT 上下文。 |
+| `service/impl/StudentTrainingAnswerServiceImpl.java`、`service/impl/AiTrainingEvaluationServiceImpl.java` | 后端拒绝演示模式写答案或调用 AI。 |
+| `src/utils/auth.js`、`src/utils/request.js` | 演示窗口优先使用 sessionStorage 认证，且不会删除父窗口 Cookie。 |
+| `src/views/studentDemo/index.vue`、`src/router/index.js`、`src/permission.js` | 独立握手页、票据交换和演示窗口启动路由。 |
+| `src/api/studentDemo.js`、`src/views/teacherEnd/trainingTask/index.vue` | 教师端入口、开窗和安全 `postMessage` 握手。 |
+| `src/utils/studentDemo.js`、`src/api/studentTrainingAnswer.js`、`src/views/training/GenericTrainingPage.vue` | 演示答案只写 sessionStorage，且阻止上传。 |
+| `src/layout/components/AppMain.vue`、`src/layout/components/Sidebar/index.vue`、`src/views/components/TrainingAiEvaluation.vue` | 演示横幅/退出、演示教学班读取、禁用学习行为记录和 AI。 |
+| `src/test/java/...`、`e-commerce-internet/tests/student-demo-mode.static.test.cjs` | 后端行为测试和前端静态契约测试。 |
+
+## Task 1: 演示票据、权限和 JWT
+
+**Files:**
+
+- Create: `docs/sql/2026-07-30-student-demo-session.sql`
+- Create: `src/main/java/com/sztzjy/linkCommerce/entity/StudentDemoSession.java`
+- Create: `src/main/java/com/sztzjy/linkCommerce/mapper/StudentDemoSessionMapper.java`
+- Create: `src/main/resources/mappers/StudentDemoSessionMapper.xml`
+- Create: `src/main/java/com/sztzjy/linkCommerce/service/StudentDemoSessionService.java`
+- Create: `src/main/java/com/sztzjy/linkCommerce/service/impl/StudentDemoSessionServiceImpl.java`
+- Create: `src/main/java/com/sztzjy/linkCommerce/controller/stu/StudentDemoSessionController.java`
+- Modify: `src/main/java/com/sztzjy/linkCommerce/config/security/JwtUser.java`
+- Modify: `src/main/java/com/sztzjy/linkCommerce/config/security/TokenProvider.java`
+- Test: `src/test/java/com/sztzjy/linkCommerce/service/impl/StudentDemoSessionServiceImplTest.java`
+- Test: `src/test/java/com/sztzjy/linkCommerce/controller/stu/StudentDemoSessionControllerTest.java`
+
+- [ ] **Step 1: 先写失败测试。**
+
+覆盖以下契约：教师可为自己创建的 `TEACHING` 班签发票据；非本人班级、行政班、非教师角色均抛出 `FORBIDDEN`；有效票据只能兑换一次；过期票据不能兑换；兑换结果 token 的 roleId 为 4、`demoMode=true`、教学班与来源教师均正确。
+
+- [ ] **Step 2: 创建迁移和 Mapper。**
+
+SQL 创建 `student_demo_session`，字段为 `id`、`ticket_hash`（唯一）、`teacher_user_id`、`school_id`、`teaching_class_id`、`expires_at`、`used_at`、`create_time`。创建 `(expires_at)` 索引用于清理/查询。Mapper 提供插入、按哈希查询，以及以 `used_at is null and expires_at > now()` 为条件的原子 `markUsed`；兑换时只有 update 返回 1 才视为成功，避免并发重复兑换。
+
+- [ ] **Step 3: 实现服务与 token。**
+
+服务用 `SecureRandom` 生成至少 32 字节 base64url 票据，保存 SHA-256 哈希，票据有效期 5 分钟。签发前通过 `SchoolClassMapper.selectByPrimaryKey` 验证 `classType=TEACHING`、`createdBy=teacherUserId` 且 `schoolId` 与教师相同。兑换后生成不落库的虚拟学生 `JwtUser`：`userId` 为 `demo:{sessionId}`，`name` 为“{教师姓名}（演示）”，`roleId=4`，并写入三个演示声明。
+
+在 `TokenProvider` 中加入 `DEMO_EXP_TIME = 30 minutes` 的专用签发方法；常规 `createToken` 时长保持 12 小时不变。`getJWTUser` 同时解析 `demoMode`、`demoTeachingClassId`、`sourceTeacherId`，不能影响旧 token。
+
+- [ ] **Step 4: 暴露 REST 契约。**
+
+实现：
+
+```text
+POST /api/teacher/student-demo-sessions
+body: { teachingClassId }
+response: { ticket, expiresAt, teachingClassId, className }
+
+POST /api/student-demo-sessions/exchange
+body: { ticket }
+response: { token, userId, name, username, roleId: "4", schoolId,
+            classId, className, demoMode: true, demoTeachingClassId }
+```
+
+创建接口从 `TokenProvider.getJWTUser(request)` 取教师身份；兑换接口标记为匿名，只接受票据，不接受教师或教学班 ID，避免前端伪造上下文。
+
+- [ ] **Step 5: 验证。**
+
+Run: `mvn -q -Dtest=StudentDemoSessionServiceImplTest,StudentDemoSessionControllerTest test`
+
+Expected: 所有权限、过期、一次性与 JWT 声明测试通过。
+
+## Task 2: 统一学生教学班上下文并保护后端写入
+
+**Files:**
+
+- Create: `src/main/java/com/sztzjy/linkCommerce/service/StudentTeachingClassResolver.java`
+- Create: `src/main/java/com/sztzjy/linkCommerce/service/impl/StudentTeachingClassResolverImpl.java`
+- Modify: `src/main/java/com/sztzjy/linkCommerce/service/TrainingTaskService.java`
+- Modify: `src/main/java/com/sztzjy/linkCommerce/service/impl/TrainingTaskServiceImpl.java`
+- Modify: `src/main/java/com/sztzjy/linkCommerce/controller/stu/TrainingTaskController.java`
+- Modify: `src/main/java/com/sztzjy/linkCommerce/controller/stu/TaskAllocationController.java`
+- Modify: `src/main/java/com/sztzjy/linkCommerce/controller/stu/UserController.java`
+- Modify: `src/main/java/com/sztzjy/linkCommerce/service/impl/StudentTrainingAnswerServiceImpl.java`
+- Modify: `src/main/java/com/sztzjy/linkCommerce/service/impl/AiTrainingEvaluationServiceImpl.java`
+- Test: `src/test/java/com/sztzjy/linkCommerce/service/impl/StudentTeachingClassResolverImplTest.java`
+- Test: `src/test/java/com/sztzjy/linkCommerce/service/impl/StudentTrainingAnswerServiceImplTest.java`
+- Test: `src/test/java/com/sztzjy/linkCommerce/service/impl/AiTrainingEvaluationServiceImplTest.java`
+- Test: `src/test/java/com/sztzjy/linkCommerce/controller/stu/TaskAllocationControllerTest.java`
+
+- [ ] **Step 1: 先写失败测试。**
+
+解析器测试普通学生仍从 `selectActiveByStudentUserId` 获得班级；演示学生不查询成员表、直接得到 `demoTeachingClassId`；演示 token 请求其它班级 ID 时拒绝。答案保存/删除测试演示用户得到 `FORBIDDEN`，且不调用任何 answer mapper 或 `JdbcTemplate` 写方法。AI 助学与助评测试演示用户被拒绝，且不调用模型客户端、评价 mapper 或成绩写入。
+
+- [ ] **Step 2: 实现 `StudentTeachingClassResolver`。**
+
+接口提供 `resolveRequired(JwtUser)` 和 `resolveRequested(JwtUser, requestedTeachingClassId)`。两种模式都验证班级存在、类型为 `TEACHING`，且班级学校与 JWT 学校一致：
+
+1. 普通学生：保留当前有效成员关系查询；
+2. 演示学生：仅使用签名 JWT 的 `demoTeachingClassId`，不读取或写入成员关系；
+3. 所有带班级参数的演示请求：必须等于 JWT 班级，否则返回 `FORBIDDEN`。
+
+- [ ] **Step 3: 接入学生端读取路径。**
+
+将 `TrainingTaskService` 的学生读取方法改为接收 `JwtUser`，由解析器获得班级后读取该班的任务副本。`TrainingTaskController` 将当前 JWT 传入服务。`TaskAllocationController.selectTaskAllocationByStudentUserId` 和 `UserController.selectCurrentTeachingClass` 改为优先从当前学生 JWT 解析上下文，不再相信请求中的 `userId`；为兼容旧非学生调用保留原查询分支。普通学生返回值和现有 API 路径不变。
+
+- [ ] **Step 4: 加后端写入保护。**
+
+在 `StudentTrainingAnswerServiceImpl` 的 `save` 与 `delete` 开头，以及 `AiTrainingEvaluationServiceImpl` 的 `get`、`generateHelp`、`generateAssessment` 的入口处调用统一的 `requireNotDemo(user)`。演示模式统一返回 `403 / 演示模式不保存数据`，确保即使绕过前端直接请求也不会保存答案、进度、AI 评价或成绩。
+
+同时审查所有学生端持久化入口（以 `rg -n "insert|update|delete|JdbcTemplate.*update" src/main/java/com/sztzjy/linkCommerce/controller/stu src/main/java/com/sztzjy/linkCommerce/service` 为清单）：凡是可被 roleId=4 调用的写服务，统一补充同一 guard；只读但使用 POST 的旧接口保留可用，不能以 HTTP 方法粗暴拦截。
+
+- [ ] **Step 5: 验证。**
+
+Run: `mvn -q -Dtest=StudentTeachingClassResolverImplTest,StudentTrainingAnswerServiceImplTest,AiTrainingEvaluationServiceImplTest,TaskAllocationControllerTest,TrainingTaskServiceImplTest test`
+
+Expected: 演示模式读到所选教学班；普通学生的既有测试继续通过；演示写入与 AI 调用均被拒绝。
+
+## Task 3: 教师开窗、一次性握手和独立认证
+
+**Files (frontend repository `E:\workspace\dianshang\e-commerce-internet`):**
+
+- Create: `src/api/studentDemo.js`
+- Create: `src/utils/studentDemo.js`
+- Create: `src/views/studentDemo/index.vue`
+- Modify: `src/utils/auth.js`
+- Modify: `src/utils/request.js`
+- Modify: `src/router/index.js`
+- Modify: `src/permission.js`
+- Modify: `src/views/teacherEnd/trainingTask/index.vue`
+- Test: `tests/student-demo-mode.static.test.cjs`
+
+- [ ] **Step 1: 先写失败的前端静态契约测试。**
+
+断言存在教师创建、匿名兑换两个 API；认证工具使用 `sessionStorage` 的演示键且优先于 Cookie；教师端通过 `window.open('/student-demo', ...)` 打开空白演示路由；双方使用固定消息类型、`window.location.origin` 与来源窗口校验；源码中没有将 `ticket` 或 `token` 拼入 URL；演示 token 通过 session 存储后执行 `location.replace('/index')`。
+
+- [ ] **Step 2: 实现独立认证存储。**
+
+在 `studentDemo.js` 固定定义 `STUDENT_DEMO_STORAGE_KEY`，包含 `{ token, userInfo, expiresAt }`，并提供 `isStudentDemo`、读写与清理函数。`auth.js` 的 `getToken`、`getUserInfo` 在当前标签存在有效演示会话时优先读取它；`removeToken`、`removeUserInfo` 在演示标签只清 sessionStorage，绝不删除教师 Cookie。`request.js` 复用 `getToken`，让演示标签自动携带演示 JWT；兑换请求明确 `isToken:false`。
+
+- [ ] **Step 3: 实现新窗口握手页。**
+
+在常量路由中添加隐藏的 `/student-demo` 路由，且在 `permission.js` 白名单放行它。该页加载后向 `window.opener` 发送 `STUDENT_DEMO_READY`；只接受来源等于 `window.location.origin` 且 `event.source === window.opener` 的 `STUDENT_DEMO_TICKET`。接到票据后调用 exchange API，写入演示 session，再以 `location.replace('/index')` 重新启动应用，使 store、路由和侧边栏按 roleId=4 初始化。无 opener、票据失效或兑换失败时显示“演示链接已失效，请返回教师端重新打开”。
+
+- [ ] **Step 4: 实现教师端入口。**
+
+在 `teacherEnd/trainingTask/index.vue` 的已有教学班筛选工具栏中，仅当 `selectedTeachingClass` 存在时显示“学生端讲解”。点击后：
+
+1. 先同步 `window.open('/student-demo', '_blank')`，使其不被浏览器当作弹窗拦截；
+2. 调用创建票据 API；
+3. 监听该窗口的 `STUDENT_DEMO_READY`，核对 `event.origin` 与 `event.source` 后，以 `postMessage({ type: 'STUDENT_DEMO_TICKET', ticket }, window.location.origin)` 发送；
+4. 创建失败或窗口关闭时关闭演示窗口并给出提示；收到握手成功后移除监听器和超时器。
+
+票据与 JWT 都不得出现在 query/hash、控制台日志或通知文本中。
+
+- [ ] **Step 5: 验证。**
+
+Run: `node tests/student-demo-mode.static.test.cjs`
+
+Expected: 安全开窗、独立认证和无 URL 凭据契约全部通过。
+
+## Task 4: 演示界面、临时答案和非持久化行为
+
+**Files (frontend repository `E:\workspace\dianshang\e-commerce-internet`):**
+
+- Modify: `src/api/studentTrainingAnswer.js`
+- Modify: `src/views/training/GenericTrainingPage.vue`
+- Modify: `src/views/components/TrainingAiEvaluation.vue`
+- Modify: `src/layout/components/AppMain.vue`
+- Modify: `src/layout/components/Sidebar/index.vue`
+- Modify: `src/layout/index.vue` 或新增 `src/components/StudentDemoBanner.vue`
+- Modify: `tests/student-demo-mode.static.test.cjs`
+
+- [ ] **Step 1: 将新实训页答案改为演示内存数据。**
+
+`studentTrainingAnswer.js` 在演示模式下不发起 `GET/POST/DELETE /api/student-training-answers`：按 `{ demoTeachingClassId, taskKey }` 作为键从 sessionStorage 返回或保存模拟 `StudentTrainingAnswer`。正常学生继续走原 API，函数签名和普通流程不变。`GenericTrainingPage.vue` 复用这三个 API，因此保存、提交、重置在演示窗口有可见反馈但关闭标签即丢失。
+
+文件上传是持久化副作用：演示模式下禁用上传按钮并说明“演示模式不上传文件”。导出 JSON 是本地浏览器行为，保留可用。
+
+- [ ] **Step 2: 禁用 AI 与学习行为写入。**
+
+`TrainingAiEvaluation.vue` 在演示模式下显示明确提示并禁用助学、助评和重试，不请求 AI 状态或模型。`AppMain.vue` 在演示模式下不调用 `updateStudyTime`、`updateVisitCount`、`getCurrentTeachingClass`；当前教学班由演示 session 中的 `demoTeachingClassId` 提供。`Sidebar/index.vue` 获取学生任务分配时仍使用已认证请求，由后端上下文解析为所选教学班，不能依赖虚拟 `userId`。
+
+- [ ] **Step 3: 加持续可见的演示标识与退出。**
+
+在学生布局顶部渲染横幅“演示模式：{className}”。“退出演示”只清除本标签的演示 session 并导航至 `/student-demo` 的失效页/关闭窗口提示；不调用全局 logout，也不修改教师 Cookie。普通学生与教师布局不显示该横幅。
+
+- [ ] **Step 4: 完成前端构建验证。**
+
+Run: `node tests/student-demo-mode.static.test.cjs; node tests/training-task-restore.static.test.cjs; node tests/school-default-task.static.test.cjs; npm run build:prod`
+
+Expected: 所有静态契约与构建通过；允许保留仓库已有 warning，但不得出现新编译错误。
+
+## Task 5: 集成回归与人工验收
+
+**Files:**
+
+- Modify: `docs/superpowers/plans/2026-07-30-teacher-student-demo-mode.md`
+
+- [ ] **Step 1: 后端完整回归。**
+
+Run: `mvn -q -DforkCount=0 test`
+
+Expected: PASS。
+
+- [ ] **Step 2: 前端完整回归。**
+
+Run: `node tests/student-demo-mode.static.test.cjs; node tests/training-task-restore.static.test.cjs; node tests/school-default-task.static.test.cjs; npm run build:prod`
+
+Expected: PASS。
+
+- [ ] **Step 3: 人工验收。**
+
+1. 用教师 A 登录，在实训任务页选中 A 创建的教学班，点击“学生端讲解”。确认新窗口打开学生端、顶部显示该班名称、任务内容是该班自定义任务。
+2. 用教师 A 尝试伪造/选择教师 B 的教学班 ID，确认创建会话返回无权限；对行政班同样被拒绝。
+3. 在演示窗口填写、保存、提交、重置一个任务，关闭窗口并重新打开。确认答案、当前步骤与提交状态均为空；数据库中没有新增 `student_training_answer`、进度、成绩、评价或成员记录。
+4. 点击 AI、文件上传、退出演示，确认前两项有明确禁用说明，退出后教师原窗口仍保持登录。
+5. 用真实学生登录，确认其任务、班级归属、答案保存、上传和 AI 功能与改造前一致。
+6. 对同一票据重复调用 exchange，并在 5 分钟后重试，均确认失败；30 分钟后演示 token 请求受保护资源确认返回未授权。
+
+- [ ] **Step 4: 记录实际执行结果。**
+
+在本计划底部添加实际运行的命令、退出码、已处理的既有 warning 和未完成的人工项；不要把计划中的“Expected”当作实际结果。
+
+## 自检
+
+- 需求覆盖：教师进入学生端、教学班所有权、无 `_ys` 帐号、同窗隔离、临时答案、AI/学习数据禁写、普通学生不回归均有对应任务。
+- 安全覆盖：票据哈希、短有效期、一次性兑换、JWT 最小权限、JWT 不入 URL、`postMessage` 双向来源验证、后端写入 guard 均有明确实现点。
+- 数据边界：不写 `userinfo`、`teaching_class_student`、答案、进度、成绩、AI、学习时长、访问次数或上传文件。
+- 占位扫描：无 TBD、TODO 或“按需补充”步骤。