railwaysystem/docs/api-v2/02_module_a_base_resource_api.md

# Module A：人员与基础资源 API 契约

> **模块定位：** 支撑培训业务运转的基础主数据管理（Teacher, Student, Course, Resource, Classroom, Site, Board, Dormitory）。
> **设计特点：** 标准基础资料型对象，保留规范化的资源 CRUD 与关联管理接口，严格遵循敏感信息脱敏与业务校验。不引入审批流、多版本、复杂搜索等过度设计。
> **优先级统计：** 共 38 个 API (P0: 20个, P1: 18个, P2: 0个)。

---

## 1. 教师管理 (Teacher)

### 1.1 分页查询教师列表 【P0】【确认】
- **业务目的：** 为管理员提供教师名录检索，排课选教师时必用。
- **HTTP Method：** `GET`
- **Path：** `/train/teacher/list`
- **Permission：** `train:teacher:list`
- **Request (Query)：** `pageNum`, `pageSize`, `tName`, `orgName`, `status`
- **Response (TableDataInfo)：** 返回包含 `tId`, `tName`, `tGender`, `tBirth`, `orgName`, `jobTitle`, `tPhone`, `tEmail`, `status` 等的教师列表。
- **核心校验：** `pageSize <= 100`。
- **涉及数据表：** `train_teacher`

### 1.2 获取教师详情 【P0】【确认】
- **HTTP Method：** `GET`
- **Path：** `/train/teacher/{tId}`
- **Permission：** `train:teacher:query`
- **核心校验：** 教师 ID 存在性。
- **错误码：** `TEACHER_NOT_FOUND (40401)`

### 1.3 新增教师 【P0】【确认】
- **业务目的：** 手工录入新培训教师。
- **HTTP Method：** `POST`
- **Path：** `/train/teacher`
- **Permission：** `train:teacher:add`
- **Request (TeacherCreateDTO)：** `tName`, `tGender`, `tBirth`, `orgName`, `jobTitle`, `tPhone`, `tEmail`, `remark`
- **核心校验：** `tName` 必填；电话格式校验。
- **涉及数据表：** `train_teacher`

### 1.4 修改教师 【P0】【确认】
- **HTTP Method：** `PUT`
- **Path：** `/train/teacher/{tId}`
- **Permission：** `train:teacher:edit`
- **Request (TeacherUpdateDTO)：** 允许变更联系方式、单位、职务、备注。

### 1.5 修改教师启停用状态 【P1】【确认】
- **HTTP Method：** `PUT`
- **Path：** `/train/teacher/{tId}/status`
- **Permission：** `train:teacher:edit`
- **Request (JSON)：** `{"status": 0}` (0 停用，1 启用)

---

## 2. 学员主档管理 (Student)

### 2.1 分页查询学员主档列表 【P0】【确认】
- **业务目的：** 检索系统学员库（长期主档）。
- **HTTP Method：** `GET`
- **Path：** `/train/student/list`
- **Permission：** `train:student:list`
- **Response (TableDataInfo)：** 身份证号默认只返回脱敏文本 `idCardMasked` 与 `idCardLast4`。

### 2.2 获取学员详情 【P0】【确认】
- **HTTP Method：** `GET`
- **Path：** `/train/student/{sId}`
- **Permission：** `train:student:query`
- **核心校验：** 学员存在性；身份证号默认脱敏展示。

### 2.3 新增学员 【P0】【确认】
- **业务目的：** 手工建档学员主数据。
- **HTTP Method：** `POST`
- **Path：** `/train/student`
- **Permission：** `train:student:add`
- **Request (StudentCreateDTO)：** `sName`, `sGender`, `sBirth`, `orgName`, `sPhone`, `sEmail`, `idCard`, `faceRef`, `remark`
- **核心校验：** 身份证号合规；后端计算 HMAC-SHA256 哈希作为 `id_card_hash` 查重；AES/SM4 可逆加密存入 `id_card_ciphertext`。
- **错误码：** `STUDENT_IDCARD_DUPLICATED (40002)`

### 2.4 修改学员主档 【P1】【确认】
- **HTTP Method：** `PUT`
- **Path：** `/train/student/{sId}`
- **Permission：** `train:student:edit`

### 2.5 Excel批量导入学员主档 【P1】【确认】
- **HTTP Method：** `POST`
- **Path：** `/train/student/import`
- **Permission：** `train:student:import`
- **说明：** 基地全局学员库的独立导入入口。计划内的名单批量导入优先使用 Module B 的 `/train/plans/{id}/enrollments/batch`。

---

## 3. 课程库与教学资源管理 (Course & Resource)

### 3.1 分页查询课程库列表 【P0】【确认】
- **HTTP Method：** `GET`
- **Path：** `/train/course/list`
- **Permission：** `train:course:list`
- **说明：** 极简设计，一期删除课程多版本、审批流程、热门标签。

### 3.2 获取课程详情及绑定资源 【P0】【确认】
- **HTTP Method：** `GET`
- **Path：** `/train/course/{cId}`
- **Permission：** `train:course:query`
- **Response (CourseDetailVO)：** 聚合返回课程基本信息及已关联的教学资源列表。

### 3.3 新增课程 【P0】【确认】
- **HTTP Method：** `POST`
- **Path：** `/train/course`
- **Permission：** `train:course:add`
- **Request (CourseCreateDTO)：** `cCode`, `cName`, `cType`, `cDuration`, `teachingObjective`, `courseContent`
- **核心校验：** `cCode` 唯一性；`cName` 必填。

### 3.4 修改课程 【P1】【确认】
- **HTTP Method：** `PUT`
- **Path：** `/train/course/{cId}`
- **Permission：** `train:course:edit`

### 3.5 课程绑定教学资源 【P1】【确认】
- **HTTP Method：** `POST`
- **Path：** `/train/course/{cId}/resources`
- **Permission：** `train:course:edit`
- **Request (JSON)：** `{"resourceId": "RES001", "sortNo": 1}`
- **主要数据表：** `train_course_resource`

### 3.6 课程解绑教学资源 【P1】【确认】
- **HTTP Method：** `DELETE`
- **Path：** `/train/course/{cId}/resources/{resourceId}`
- **Permission：** `train:course:edit`

### 3.7 教学资源独立 CRUD (5个 API) 【P1】【确认】
- `GET /train/resource/list` 【P1】(分页查询教学资源)
- `GET /train/resource/{resourceId}` 【P1】(获取资源详情)
- `POST /train/resource` 【P1】(新增教学资源：支持文档、视频、VR、3D、链接)
- `PUT /train/resource/{resourceId}` 【P1】(修改教学资源)
- `DELETE /train/resource/{resourceId}` 【P1】(删除教学资源，被课程引用时阻止删除)

---

## 4. 空间与设备资源管理 (Classroom, Site, Board, Dormitory)

### 4.1 教室管理 (Classroom)
- `GET /train/classroom/list` 【P0】【确认】(分页查询教室，排课选普通教室必用)
- `GET /train/classroom/{classRoomId}` 【P0】【确认】(获取教室详情及绑定班牌)
- `POST /train/classroom` 【P0】【确认】(新增教室：`roomName`, `roomLocation`, `capacity`, `roomStatus`)
- `PUT /train/classroom/{classRoomId}` 【P1】【确认】(修改教室)

### 4.2 实训场地管理 (Training Site)
- `GET /train/training-site/list` 【P0】【确认】(分页查询实训场地：VR区、3D拆解区、实操演练区，排课必用)
- `GET /train/training-site/{siteId}` 【P0】【确认】(获取实训场地详情)
- `POST /train/training-site` 【P0】【确认】(新增实训场地：`siteName`, `siteLocation`, `capacity`, `siteDevice`)
- `PUT /train/training-site/{siteId}` 【P1】【确认】(修改实训场地)

### 4.3 电子班牌管理 (Electronic Board)
- `GET /train/electronic-board/list` 【P1】【确认】(分页查询班牌设备)
- `GET /train/electronic-board/{boardId}` 【P1】【确认】(获取班牌详情)
- `POST /train/electronic-board` 【P1】【确认】(注册班牌：`boardName`, `boardSn`, `bindClassroomId`, `boardIp`, `apiEndpoint`)
- `PUT /train/electronic-board/{boardId}` 【P1】【确认】(修改班牌配置)

### 4.4 宿舍房间管理 (Dormitory Info)
- `GET /train/dormitory/list` 【P0】【确认】(分页查询宿舍房间列表，附带容量、已住人数、剩余床位)
- `GET /train/dormitory/{dormId}` 【P0】【确认】(获取指定房间详情及当前入住人员列表)
- `POST /train/dormitory` 【P0】【确认】(新增房间：`dormBuilding`, `dormFloor`, `dormRoom`, `capacity`, `genderType`, `lockDeviceSn`)
- `PUT /train/dormitory/{dormId}` 【P1】【确认】(修改房间信息，容量缩减不可小于当前已住人数)
- `GET /train/dormitory/options` 【P0】【确认】(获取楼栋、楼层级联下拉数据，分房弹窗必需)