8.5 KiB
8.5 KiB
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】【确认】(获取教室详情及绑定班牌)- 响应数据：
ClassroomDetailVO(教室状态roomStatus语义为：0 正在使用, 1 可用空闲, 2 其他) - 1:N 关联语义： 一个 Classroom 可关联 0..N 个 ElectronicBoard（依据 Database V2，
train_electronic_board.bind_classroom_id没有 UNIQUE 约束）。严禁将关联关系弱化为 1:1，禁止在契约中定义electronicBoard、primaryBoard或preferredBoard，严禁“取第一条班牌作为默认班牌”。 - 空值处理： 当教室无绑定班牌时，
boards属性必须返回空列表[]，不得返回null。 - 端点边界： 不新增独立子资源接口（如
/classroom/{id}/boards），班牌轻量摘要信息作为教室详情响应（ClassroomDetailVO.boards）内嵌返回。
- 响应数据：
POST /train/classroom【P0】【确认】(新增教室：roomName,roomLocation,capacity,roomStatus[0正在使用 1可用空闲 2其他])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】【确认】(获取楼栋、楼层级联下拉数据，分房弹窗必需)