dianshang-houduan/docs/training-task-class-scope.md

实训任务按教学班配置逻辑说明

一、背景

本次调整解决的问题是：教师端编辑的实训要求、实训背景、实训目标、案例文档等内容，需要只影响对应教学班的学生，不能变成全局配置，也不能被其他教学班学生看到。

调整后，系统形成三层逻辑：

• 管理端维护默认实训任务。
• 教师端维护自己创建的教学班的实训任务覆盖配置。
• 学生端按自己所属教学班读取实训任务，未配置时回退默认任务。

二、角色职责

1. 管理端

管理端新增“实训任务管理”菜单。

管理端维护的是系统默认实训任务，包括：

• 实训任务名称
• 实训背景
• 实训目标
• 实训要求
• 步骤名称
• 案例文档名称和地址
• 启用状态

默认任务用于兜底：当某个教学班没有单独配置实训任务时，学生端读取管理端默认配置。

2. 教师端

教师端“实训任务管理”改为按教学班维护。

教师进入页面后，需要先选择教学班。页面只展示当前教师自己创建的教学班。教师保存配置时，不再修改管理端默认任务，而是写入该教学班自己的覆盖配置。

教师端可维护内容包括：

• 实训任务名称
• 实训背景
• 实训目标
• 实训要求
• 步骤名称
• 案例文档名称和地址
• 启用状态

教师端已去掉“相关知识/任务分析”字段，学生端统一只展示：

• 实训背景
• 实训目标
• 实训要求

3. 学生端

学生端读取规则：

1. 根据当前学生账号找到学生所属教学班。
2. 查询该教学班是否配置了对应实训任务。
3. 如果有教学班配置，使用教学班配置。
4. 如果没有教学班配置，使用管理端默认配置。
5. 如果教学班配置存在且被禁用，则不回退默认任务，学生端不展示该任务。

案例文档也遵循同样规则：

• 教师给某个教学班上传的案例文档，只在该教学班学生的对应任务页面展示和下载。
• 其他教学班学生看不到这个案例文档。
• 如果没有案例文档，学生端仍展示下载按钮，点击时提示暂无案例资料。

三、数据优先级

学生端读取某个任务时的数据优先级如下：

教学班覆盖配置 > 管理端默认配置

但有一个特殊规则：

教学班覆盖配置存在且 enabled=false 时，直接视为禁用，不再回退管理端默认配置。

这样可以避免教师禁用了某个教学班任务后，学生端又因为默认配置而继续看到该任务。

四、接口范围

1. 默认任务接口

用于管理端维护默认实训任务：

• GET /api/training-tasks
• POST /api/training-tasks
• PUT /api/training-tasks/{id}
• DELETE /api/training-tasks/{id}
• POST /api/training-tasks/import
• GET /api/training-tasks/template

默认任务新增、编辑、删除、导入由管理端使用。

2. 教学班任务接口

用于教师端维护教学班覆盖配置：

• GET /api/training-tasks/classes/{teachingClassId}
• GET /api/training-tasks/classes/{teachingClassId}/key/{taskKey}
• PUT /api/training-tasks/classes/{teachingClassId}/{taskKey}

后端会校验该教学班是否由当前教师创建。不是自己创建的教学班不能编辑。

3. 学生端任务接口

学生端仍使用任务读取接口，但后端会按当前学生身份自动解析教学班：

• GET /api/training-tasks
• GET /api/training-tasks/key/{taskKey}

学生角色调用时，后端先取学生所属教学班，再合并教学班配置和默认配置。

五、数据库变化

新增教学班实训任务覆盖配置表：

• training_task_class_config

用途：

• 存储某个教学班对某个实训任务的覆盖配置。
• teaching_class_id + task_key 唯一。
• 不替换原来的默认任务表，而是在学生端读取时参与合并。

发版时需要执行 SQL：

link_commerce/docs/sql/2026-07-02-training-task-class-config.sql

六、发版注意事项

1. 先执行新增表 SQL。
2. 部署后端新 jar。
3. 部署前端新 dist。
4. 如果 nginx 只是代理静态文件和接口，不需要改 nginx 配置；如果替换了静态文件但浏览器仍缓存旧资源，可以清缓存或重启 nginx。
5. 确认前端生产接口地址仍走原来的相对代理路径，不应访问不允许的外部 API 地址。

七、验证清单

管理端

• 学校管理员能看到“实训任务管理”菜单。
• 管理端编辑默认实训任务后，未配置教学班的学生能看到默认内容。

教师端

• 教师端实训任务管理页面需要先选择教学班。
• 教学班下拉框只出现当前教师自己创建的教学班。
• 教师保存后，只影响当前选中的教学班。
• 教师上传案例文档后，只影响当前选中的教学班。

学生端

• 属于已配置教学班的学生，看到教师端该教学班配置的背景、目标、要求和案例文档。
• 属于未配置教学班的学生，看到管理端默认配置。
• 某教学班任务被禁用后，该教学班学生不再看到该任务，且不会回退默认任务。
• 没有案例文档时，学生端仍展示下载按钮，点击提示暂无案例资料。

八、当前已提交版本

后端提交：

• d2672d6 feat: add class scoped training task storage
• a1306bd feat: resolve training tasks by teaching class
• ac71703 feat: add role scoped training task APIs

前端提交：

• d7c8eb8 feat: add admin training task menu
• c0191fe feat: scope teacher training tasks to classes