diff --git a/docs/training-task-class-scope.md b/docs/training-task-class-scope.md
new file mode 100644
index 0000000..37fa963
--- /dev/null
+++ b/docs/training-task-class-scope.md
@@ -0,0 +1,178 @@
+# 实训任务按教学班配置逻辑说明
+
+## 一、背景
+
+本次调整解决的问题是：教师端编辑的实训要求、实训背景、实训目标、案例文档等内容，需要只影响对应教学班的学生，不能变成全局配置，也不能被其他教学班学生看到。
+
+调整后，系统形成三层逻辑：
+
+- 管理端维护默认实训任务。
+- 教师端维护自己创建的教学班的实训任务覆盖配置。
+- 学生端按自己所属教学班读取实训任务，未配置时回退默认任务。
+
+## 二、角色职责
+
+### 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`
+