chg_0012(T1): docs/dth/lms-v2/scenario.md — 4 scene 设计与 FRC 模板
- 验证 chg_0006 LMS v1 已在 src/backend/src/lms/ 完整存在(CLAUDE.md F-2 路径索引有误) - 实际 schema: lms_course(code,name,instructor) / lms_enrollment(status) - 实际 seed: S20200001/李雷 + CS101/数据安全导论(与 brief 描述不一致;以在盘为准) - 4 类 scene: slide / quiz / simulation / pbl(pbl v2 阶段仅占位 + 501) - 命名取舍: 保留 dth simulation 而非 OpenMAIC interactive(与 chg_0010/0011 术语一致) - MiniMD 5 节点规格: h1/h2/p/ul/li/code;非法节点原样保留 - FRC 6-scene 模板: 严格对位 chg_0010 S1-S6(6 simulation scene + order_index 1-6) - 6 个 v2 endpoint + 6 条关键不变量 + 4 前端组件 + 3 前端视图 Co-Authored-By: Claude <[email protected]>
This commit is contained in:
1 parent
650ef34b43
commit
441c6ca2f8
1 file changed
+165
@@ -0,0 +1,165 @@
|
||||
# LMS v2 多场景课程平台 — 4 类 Scene 设计 + FRC 模板
|
||||
|
||||
> chg_0012 · 2026-09-29 · owner: pm@dth · 状态:implemented
|
||||
>
|
||||
> 在 chg_0006 LMS v1(学员 / 课程 / 选课)基础上扩展 v2:把每门课程拆成
|
||||
> **有序 scene 序列**,scene 4 类(slide / quiz / simulation / pbl)。
|
||||
> 同时落地 **FRC 6-scene 模板**,把 chg_0010 的 6 步联合风控流程以
|
||||
> "可执行 simulation" 形式嵌入 LMS 课程。
|
||||
>
|
||||
> **0 新算子 / 0 新依赖 / 0 前端框架切换**。所有 scene 复用既有 chg_0008/0009 算子
|
||||
> (通过 `embed_url` 引用 `/experiment/runs` 形态)或前端纯组件渲染。
|
||||
|
||||
## 0. 状态核验(chg_0012 起点)
|
||||
|
||||
CLAUDE.md F-2 索引说 LMS 在 `src/backend/src/dth/lms/`,**实际位置是
|
||||
`src/backend/src/lms/`**(自 chg_0006 落地起就在此,未迁移至 `dth/` 子目录)。
|
||||
chg_0012 T1 不重建 v1,直接在此基础上扩展 v2。详见下文"实现路径"段。
|
||||
|
||||
实际字段命名与 brief 略有差异,本设计以**在盘代码为准**:
|
||||
|
||||
| 字段 | 本设计 | brief 描述 | 决策 |
|
||||
|---|---|---|---|
|
||||
| `lms_course.code` | `code` | `course_code` | **保持 `code`**(与 chg_0006 一致,e2e 已依赖) |
|
||||
| `lms_course.name` | `name` | `title` | **保持 `name`**(同上) |
|
||||
| `lms_course.instructor` | `instructor` | `teacher` | **保持 `instructor`**(同上) |
|
||||
| `lms_enrollment.status` | `status` | `progress_scene_ids JSON` | **保持 `status`**;v2 进度另开 `lms_course_scene` 表 |
|
||||
|
||||
种子数据也与 brief 不一致:
|
||||
|
||||
| 资源 | 实际 seed | brief 描述 |
|
||||
|---|---|---|
|
||||
| 学员 1 | `S20200001` / 李雷 / `[email protected]` | `S2026001` / 张三 |
|
||||
| 学员 2 | `S20200002` / 韩梅梅 / `[email protected]` | (未指定)|
|
||||
| 课程 1 | `CS101` / 数据安全导论 / 3 学分 / 王老师 | `C-INTRO` / 数智安全导论 |
|
||||
| 课程 2 | `CS201` / 隐私计算实战 / 4 学分 / 陈老师 | (未指定)|
|
||||
|
||||
> **Ruling**:v1 schema / seed 不动;chg_0012 在 v1 之上增量加 `lms_course_scene` 表 + v2 endpoints。
|
||||
> chg_0006 LMS e2e (`tests/e2e/dth_lms.test.sh`) 不回归。
|
||||
|
||||
## 1. 业务背景
|
||||
|
||||
LMS v1 的课程是"扁平"资源——只描述课程元信息(代码 / 学分 / 教师),
|
||||
不描述课程**怎么上**。v2 引入"场景化教学":每门课 = 一个**有序 scene 序列**,
|
||||
学员按 order_index 依次完成。
|
||||
|
||||
4 类 scene 对位教学法(沿用既有 chg_0008/0009 算子命名 + LMS 教学常识):
|
||||
|
||||
| scene_type | 教学法 | 实现 | 何时用 |
|
||||
|---|---|---|---|
|
||||
| `slide` | 讲解(教师讲) | 后端 MiniMD → 前端 `dangerouslySetInnerHTML` | 概念导入 / 算子原理讲解 |
|
||||
| `quiz` | 测验(学员练)| 前端本地判分 + 调用 `POST /scenes/:id/grade` 留痕 | 概念验证 / 选择题 + 简答题 |
|
||||
| `simulation` | 仿真(学员跑)| `embed_url` 指向既有算子 e2e 页面或 `experiment/runs` 触发页 | 真实算子协同演示(如 FRC 6 步) |
|
||||
| `pbl` | PBL(项目式学习)| **v2 阶段仅做占位 + 501 NOT_IMPLEMENTED** | 课程占位 / 后续 chg |
|
||||
|
||||
### 与 OpenMAIC 的对位(命名取舍)
|
||||
|
||||
OpenMAIC(multi-agent interactive classroom)的 scene 字典命名是
|
||||
`interactive`(默认)/ `video` / `audio` / `quiz` / `simulation`。
|
||||
我们**保留 dth 命名 `simulation` 而非 OpenMAIC 的 `interactive`**:
|
||||
|
||||
1. chg_0010 / chg_0011 已落地"6 步 simulation 流程"作为术语,
|
||||
改名会导致 e2e / 文档断裂;
|
||||
3. dth scene 字典保持简洁 4 类(slide/quiz/simulation/pbl),不引入 `video` / `audio`
|
||||
(实验台是后端工程师学习平台,视频/音频教学形态不属于 v0)。
|
||||
|
||||
## 2. 数据模型(PGlite 第 4 张表)
|
||||
|
||||
### lms_course_scene(v2 新增)
|
||||
|
||||
```sql
|
||||
CREATE TABLE IF NOT EXISTS lms_course_scene (
|
||||
id TEXT PRIMARY KEY, -- uuid v4
|
||||
course_id TEXT NOT NULL, -- FK → lms_course.id
|
||||
scene_type TEXT NOT NULL, -- enum: slide|quiz|simulation|pbl
|
||||
payload_json TEXT NOT NULL, -- 不同 scene 不同 schema
|
||||
order_index INTEGER NOT NULL, -- 1-based
|
||||
created_at TIMESTAMP NOT NULL DEFAULT NOW(),
|
||||
UNIQUE(course_id, order_index), -- 顺序不冲突
|
||||
CHECK(scene_type IN ('slide','quiz','simulation','pbl'))
|
||||
);
|
||||
CREATE INDEX IF NOT EXISTS idx_lms_course_scene_course ON lms_course_scene(course_id);
|
||||
```
|
||||
|
||||
### 4 类 payload schema(payload_json 内部)
|
||||
|
||||
| scene_type | payload_json 必填字段 | 可选字段 | 备注 |
|
||||
|---|---|---|---|
|
||||
| `slide` | `markdown: string`(MiniMD 5 节点) | `title: string` | 后端转换 HTML,前端 `dangerouslySetInnerHTML` |
|
||||
| `quiz` | `questions: [{id, type: 'choice'/'short', prompt, options?, answer?, keywords?}]` | `pass_score: number` | `answer` + `keywords` 用于判分(参考依据:服务端的黄金答案) |
|
||||
| `simulation` | `embed_url: string`(必须 http(s):// 前缀)| `height: number`、`sandbox: string` | 前端 iframe `sandbox=allow-same-origin`(默认) |
|
||||
| `pbl` | (v2 阶段无必填)| `placeholder: string` | 后端 render 返回 501 NOT_IMPLEMENTED |
|
||||
|
||||
### MiniMD 5 节点规格
|
||||
|
||||
| 节点 | Markdown 语法 | HTML 输出 | 非法节点处理 |
|
||||
|---|---|---|---|
|
||||
| `h1` | `# xxx` | `<h1>xxx</h1>` | 原样保留(含 `# xxx` 文本) |
|
||||
| `h2` | `## xxx` | `<h2>xxx</h2>` | 同上 |
|
||||
| `p` | 任意行(非标题 / 列表 / 代码) | `<p>xxx</p>` | 同上 |
|
||||
| `ul` / `li` | `- xxx` / ` - xxx` | `<ul><li>xxx</li></ul>` | 同上 |
|
||||
| `code` | `` ```xxx``` `` 或 ` `xxx` ` | (临时占位)| -- |
|
||||
|
||||
**非法节点策略 = 原样保留**(不抛错、不删字符),确保坏 Markdown 也能渲染(虽然丑)。
|
||||
实现路径:正则 5 类匹配 + 全局 fail-open 替换;这是**零新依赖**的关键。
|
||||
|
||||
## 3. API 设计(v2 endpoints)
|
||||
|
||||
| Method | Path | 鉴权 | 用途 |
|
||||
|---|---|---|---|
|
||||
| `POST` | `/api/ssw/dth/lms-v2/courses` | admin | 创建课程(**含 scenes[]**);重复 code → 409 DUPLICATE_COURSE_CODE |
|
||||
| `GET` | `/api/ssw/dth/lms-v2/courses/:courseId/scenes` | admin / 非 admin | 列出课程全部 scene(按 order_index 升序) |
|
||||
| `GET` | `/api/ssw/dth/lms-v2/courses/:courseId/scenes/:sceneId/render` | 学员 / admin | scene 渲染(slide → HTML;simulation → 校验 embed_url;pbl → 501) |
|
||||
| `POST` | `/api/ssw/dth/lms-v2/scenes/:sceneId/grade` | 学员 | quiz 判分 → `{score: 0..1, correct_count, total_count}` |
|
||||
| `POST` | `/api/ssw/dth/lms-v2/scenes/:sceneId/complete` | 学员 | 标记 scene 完成(**append-only 幂等**,进度 JSON 累积) |
|
||||
| `POST` | `/api/ssw/dth/lms-v2/courses/from-frc-template` | admin | 生成 FRC 6-scene 模板课程(见 §4) |
|
||||
|
||||
### 关键不变量
|
||||
|
||||
| 不变量 | 失败码 | 文案 |
|
||||
|---|---|---|
|
||||
| 重复 `course_code` | 409 | `DUPLICATE_COURSE_CODE` |
|
||||
| 重复 enroll(同 student × course)| 409 | `ALREADY_ENROLLED`(与 v1 一致)|
|
||||
| `progress_scene_ids` append-only | — | 重复 complete 不增 count(测试断言)|
|
||||
| 非法 `scene_type`(如 `video`)| 422 | `INVALID_SCENE_TYPE`(schema CHECK 兜底)|
|
||||
| `simulation.embed_url` 非 http(s):// | 400 | `INVALID_EMBED_URL` |
|
||||
| PBL scene render | 501 | `NOT_IMPLEMENTED`,文案:"PBL 场景 v2 实现,当前仅作课程占位" |
|
||||
|
||||
## 4. FRC 6-scene 模板
|
||||
|
||||
`POST /api/ssw/dth/lms-v2/courses/from-frc-template` 接受 `{course_code, teacher}`,
|
||||
创建 1 门含 **6 个 simulation scene** 的课程(order_index 1-6),embed_url
|
||||
严格对应 chg_0010 S1-S6:
|
||||
|
||||
| order | scene_id (chg_0010 S#) | title | embed_url 描述 |
|
||||
|---|---|---|---|
|
||||
| 1 | S1 | DID + TDS 联合身份验证 | `/exp/admin/iframe/s1` |
|
||||
| 2 | S2 | PSI 求三方交集 | `/exp/admin/iframe/s2` |
|
||||
| 3 | S3 | Paillier 同态求和 | `/exp/admin/iframe/s3` |
|
||||
| 4 | S4 | Threshold 2-of-3 签名 | `/exp/admin/iframe/s4` |
|
||||
| 5 | S5 | ABAC 联合风控策略 | `/exp/admin/iframe/s5` |
|
||||
| 6 | S6 | 审计链 HMAC 验证 | `/exp/admin/iframe/s6` |
|
||||
|
||||
`embed_url` 在本 chg 是占位 `/experiment/runs/<operator>` 的约定形式,
|
||||
**不是真实可达 URL**——LMS v2 不引入新前端路由;学员点击 scene → iframe 加载
|
||||
`embed_url`,后端校验前缀格式即可。
|
||||
|
||||
## 5. 前端视图(4 组件 + 3 视图)
|
||||
|
||||
```
|
||||
src/frontend/src/views/LMS/
|
||||
CourseList.tsx # 列出课程列表(GET /courses)
|
||||
CourseDetail.tsx # 课程详情 + scene 列表(GET /courses/:id/scenes)
|
||||
SceneRenderer.tsx # 路由 /courses/:courseId/scenes/:sceneId → 4 类 scene 之一
|
||||
SlideScene.tsx # dangerouslySetInnerHTML(MiniMD HTML)
|
||||
QuizScene.tsx # 本地填答案 + 调 /grade
|
||||
SimScene.tsx # iframe sandbox=allow-same-origin
|
||||
PBLScene.tsx # 显示 "即将推出" 占位文案(与后端 501 文案一致)
|
||||
```
|
||||
|
||||
路由:`/lms`(CourseList)→ `/lms/:courseId`(CourseDetail)→ `/lms/:courseId/:sceneId`(SceneRenderer)。
|
||||
挂载在 `App.tsx` 的 `<ProtectedRoute>` 下,与 Dashboard / OperatorList 平级。
|
||||
|
||||
## 6. e2e 覆盖(S1-S10)
|
||||
|
||||
详见 `tests/e2e/dth_lms_v2.test.sh`(chg_0012 T2 输出)。
|
||||
Reference in new issue
Block a user