merge sandbox/f0cf2f4: chg_0006 LMS bootstrap (3 子系统 + 5 S 场景 + 6 cases)

Co-Authored-By: Claude Code <[email protected]>
This commit is contained in:
xstudio agentandClaude Code committed 2026-09-28 16:46:52 +08:00
1 parent f1a15c44f4
commit 5c27b0fd39
17 files changed
+1039 -1

No files matched your search

+149
View File
@@ -0,0 +1,149 @@
# LMS Module Design — chg_0006
## Overview
LMS 是数智安全人才平台的核心子系统(需求 §6.1)。本 chg 落地三个最小子系统:
学员管理 + 课程管理 + 选课。新 capability `lms`,S 编号从 1 起。
## 1. 3 表 Schema(PGlite)
### lms_student
```sql
CREATE TABLE IF NOT EXISTS lms_student (
id TEXT PRIMARY KEY,
student_no TEXT UNIQUE NOT NULL,
name TEXT NOT NULL,
email TEXT NOT NULL,
created_at TIMESTAMP NOT NULL DEFAULT NOW()
);
```
### lms_course
```sql
CREATE TABLE IF NOT EXISTS lms_course (
id TEXT PRIMARY KEY,
code TEXT UNIQUE NOT NULL,
name TEXT NOT NULL,
credits INTEGER NOT NULL DEFAULT 1,
instructor TEXT,
created_at TIMESTAMP NOT NULL DEFAULT NOW()
);
```
### lms_enrollment
```sql
CREATE TABLE IF NOT EXISTS lms_enrollment (
id TEXT PRIMARY KEY,
student_id TEXT NOT NULL,
course_id TEXT NOT NULL,
enrolled_at TIMESTAMP NOT NULL DEFAULT NOW(),
status TEXT NOT NULL DEFAULT 'active',
UNIQUE(student_id, course_id)
);
```
**设计要点**:
- `id` 用 TEXT(UUID v4),与现有 chg_0002 的 `run_id` 一致(字符串 UUID 而非 bigint)
- `student_no` / `code` 业务唯一键(学号 / 课程号),UNIQUE 约束避免重复
- `lms_enrollment.UNIQUE(student_id, course_id)` 保证同一学生同一课程不重复选课
- `status` 默认 `'active'`,预留 future 退课 / 完成状态
## 2. Seed 数据(启动期)
```sql
INSERT INTO lms_student (id, student_no, name, email) VALUES
('11111111-1111-1111-1111-111111111111', 'S20200001', '李雷', '[email protected]'),
('22222222-2222-2222-2222-222222222222', 'S20200002', '韩梅梅', '[email protected]')
ON CONFLICT DO NOTHING;
INSERT INTO lms_course (id, code, name, credits, instructor) VALUES
('aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa', 'CS101', '数据安全导论', 3, '王老师'),
('bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb', 'CS201', '隐私计算实战', 4, '陈老师')
ON CONFLICT DO NOTHING;
```
固定 UUID 便于 e2e 测试稳定引用(`S4` 直接用 `111...`/`aaaa...` 即可断言)。
## 3. 模块结构
```
src/backend/src/lms/
├── lms.module.ts
├── students.students.controller.ts
├── students.students.service.ts
├── courses.courses.controller.ts
├── courses.courses.service.ts
├── enrollments.enrollments.controller.ts
└── enrollments.enrollments.service.ts
```
命名沿用 chg_0002 风格(`<resource>.<resource>.controller.ts`)。
## 4. 7 类 Endpoint
### 学员
| Method | Path | 说明 | RBAC |
|--------|------|------|------|
| GET | `/api/ssw/dth/lms/students` | 列表 | admin |
| POST | `/api/ssw/dth/lms/students` | 创建(body: student_no/name/email) | admin |
| GET | `/api/ssw/dth/lms/students/:id` | 单个 | admin |
| PUT | `/api/ssw/dth/lms/students/:id` | 更新(body: name/email) | admin |
| DELETE | `/api/ssw/dth/lms/students/:id` | 删除 | admin |
| GET | `/api/ssw/dth/lms/students/:id/enrollments` | 该生选课列表 | admin |
### 课程
| Method | Path | 说明 | RBAC |
|--------|------|------|------|
| GET | `/api/ssw/dth/lms/courses` | 列表 | admin |
| POST | `/api/ssw/dth/lms/courses` | 创建(body: code/name/credits/instructor) | admin |
| GET | `/api/ssw/dth/lms/courses/:id` | 单个 | admin |
| PUT | `/api/ssw/dth/lms/courses/:id` | 更新 | admin |
| DELETE | `/api/ssw/dth/lms/courses/:id` | 删除 | admin |
### 选课
| Method | Path | 说明 | RBAC |
|--------|------|------|------|
| POST | `/api/ssw/dth/lms/courses/:id/enroll` | 选课(body: `{student_id}`) | admin |
| GET | `/api/ssw/dth/lms/courses/:id/enrollments` | 该课程选课列表 | admin |
## 5. 响应格式
沿用 chg_0002 的 ActionResultFilter 格式:
```json
{ "code": 200, "msg": "ok", "data": ... }
```
- 成功:`code = 200`
- 未登录:`code = 600`(JwtAuthGuard)
- 业务错误:`code = 400`(BadRequestException,比如 student_no 重复 / student_id 不存在)
- 权限不足:`code = 403`(RequireAdmin)
- 资源不存在:`code = 404`(NotFoundException)
## 6. RBAC
所有 LMS 端点套 `@UseGuards(JwtAuthGuard)` + `@RequireAdmin()`:
- 复用 chg_0002 的 `JwtAuthGuard` + `RequireAdmin()`(`src/backend/src/auth/jwt.guard.ts`)
- 不引入新鉴权机制
## 7. 与现有架构的关系
- **复用**:JwtAuthGuard / ActionResultFilter / PGlite init 入口 / uuid v4
- **不修改**:auth/、common/{cipher,action-result.filter}.ts、dth/、dth_user / dth_experiment_run 表
- **新增**:3 张 LMS 表 + 6 服务/控制器文件 + 1 module + e2e 测试
- **依赖**:仅 `@nestjs/common` / `@nestjs/jwt` / `uuid` / `bcryptjs`(均已装,不引入新依赖)
## 8. 错误处理边界条件(自评审)
- **缺参删除**:`DELETE /students/:id` 不存在 → 404
- **越权隔离**:非 admin 调用 → 403(RequireAdmin)
- **空列表**:新建项目 → list 返回 `[]`(业务兜底)
- **超长输入**:email 太长 / name 含特殊字符 → 业务层不严格校验(trust admin 输入;MVP 范围)
- **幂等重复 enroll**:同 (student_id, course_id) → UNIQUE 冲突 → 返回 400
## 9. 4 S 场景覆盖矩阵
| S | 触达端点 | 验证点 |
|---|----------|--------|
| S1 | GET /students | list.length ≥ 2 + 字段 schema |
| S2 | POST /students → GET /students/:id | id 是 UUID + name 一致 |
| S3 | GET /courses | list.length ≥ 2 + 字段 schema |
| S4 | POST /courses/:id/enroll → GET /students/:id/enrollments | code=200 + enrollments 含 course_id |
| all | tests/e2e/dth_lms.test.sh + check_spec_coverage.sh | exit 0 + gap=0 |