From 441c6ca2f8eaa7eebd1c3e3a20c17fae50d1de61 Mon Sep 17 00:00:00 2001 From: xstudio agent Date: Tue, 29 Sep 2026 16:05:08 +0800 Subject: [PATCH] =?UTF-8?q?chg=5F0012(T1):=20docs/dth/lms-v2/scenario.md?= =?UTF-8?q?=20=E2=80=94=204=20scene=20=E8=AE=BE=E8=AE=A1=E4=B8=8E=20FRC=20?= =?UTF-8?q?=E6=A8=A1=E6=9D=BF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 验证 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 --- docs/dth/lms-v2/scenario.md | 165 ++++++++++++++++++++++++++++++++++++ 1 file changed, 165 insertions(+) create mode 100644 docs/dth/lms-v2/scenario.md 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

` | 原样保留(含 `# xxx` 文本) | +| `h2` | `## xxx` | `

xxx

` | 同上 | +| `p` | 任意行(非标题 / 列表 / 代码) | `

xxx

` | 同上 | +| `ul` / `li` | `- xxx` / ` - xxx` | `` | 同上 | +| `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/` 的约定形式, +**不是真实可达 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` 的 `` 下,与 Dashboard / OperatorList 平级。 + +## 6. e2e 覆盖(S1-S10) + +详见 `tests/e2e/dth_lms_v2.test.sh`(chg_0012 T2 输出)。 \ No newline at end of file