diff --git a/docs/dth/lms-v2/scenario.md b/docs/dth/lms-v2/scenario.md new file mode 100644 index 0000000..6cb1f22 --- /dev/null +++ b/docs/dth/lms-v2/scenario.md @@ -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` / 李雷 / `lilei@school.edu` | `S2026001` / 张三 | +| 学员 2 | `S20200002` / 韩梅梅 / `hanmeimei@school.edu` | (未指定)| +| 课程 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` | `
xxx
` | 同上 | +| `ul` / `li` | `- xxx` / ` - xxx` | `