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

## 一、背景

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

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

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

## 二、角色职责

### 1. 管理端

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

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

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

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

### 2. 教师端

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

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

教师端可维护内容包括：

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

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

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

### 3. 学生端

学生端读取规则：

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

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

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

## 三、数据优先级

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

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

但有一个特殊规则：

```text
教学班覆盖配置存在且 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：

```text
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`