文档接口：修订并冻结API Contract V1.0.2

2026-09-14 11:07:26 +08:00
1 parent 7fcaea29b8
commit 407de97810
@@ -173,3 +173,14 @@ flowchart LR

 ### 6.4 P0 Application Service 清单 (10 个 P0 业务编排 Service)
 `PlanAppService`, `EnrollmentAppService`, `SchedulingAppService`, `AccommodationAppService`, `ReportAppService`, `AttendanceAppService`, `ScoreAppService`, `LearningAppService`, `StatisticsAppService`, `ExternalIntegrationAppService`。
+
+---
+
+## 7. 版本说明 (Version History)
+
+### V1.0.2
+1. 补录40008 CLASSROOM_NAME_DUPLICATED
+2. 补录40009 SITE_NAME_DUPLICATED
+3. 冻结ClassroomDetailVO.boards为0..N班牌摘要列表
+4. 新增ClassroomBoardSummaryVO定义
+5. Endpoint Method/Path/Priority/Permission/count均不变
@@ -137,7 +137,11 @@
 ### 4.1 教室管理 (Classroom)
 - `GET /train/classroom/list` 【P0】【确认】(分页查询教室，排课选普通教室必用)
 - `GET /train/classroom/{classRoomId}` 【P0】【确认】(获取教室详情及绑定班牌)
- `POST /train/classroom` 【P0】【确认】(新增教室：`roomName`, `roomLocation`, `capacity`, `roomStatus`)
+  - **响应数据：** `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)
@@ -139,6 +139,41 @@

 ---

+### 1.10 教室详情视图：`ClassroomDetailVO` 【P0】【确认】
+- **定位：** 查看教室详情及关联班牌列表（对应 `GET /train/classroom/{classRoomId}`）。
+- **1:N 绑定关系：** 一个 Classroom 可关联 0..N 个 ElectronicBoard（依据 Database V2，`train_electronic_board.bind_classroom_id` 没有 UNIQUE 约束）。禁止契约定义 `electronicBoard`、`primaryBoard`、`preferredBoard`，严禁“取第一条班牌作为默认班牌”。
+- **字段规范：**
+
+| 字段名 | 类型 | 说明 |
+|:---|:---|:---|
+| `classRoomId` | String | 教室标识 |
+| `roomName` | String | 教室名称 |
+| `roomLocation` | String | 教室物理位置 |
+| `capacity` | Long | 容纳人数 |
+| `roomStatus` | Integer | 教室状态：0正在使用 1可用空闲 2其他 |
+| `remark` | String | 备注信息 |
+| `createTime` | DateTime | 创建时间 |
+| `boards` | List<ClassroomBoardSummaryVO> | 绑定的班牌摘要列表。无绑定班牌时返回 `[]`，不得返回 `null` |
+
+---
+
+### 1.11 班牌摘要视图：`ClassroomBoardSummaryVO` 【P0】【确认】
+- **定位：** 教室详情中内嵌的轻量班牌摘要对象（1:N 响应集合元素）。
+- **字段规范与语义：**
+
+| 字段名 | 类型 | 说明 | 语义来源 |
+|:---|:---|:---|:---|
+| `boardId` | String | 系统内部稳定班牌ID | `train_electronic_board.board_id` |
+| `boardSn` | String | 设备硬件序列号 | `train_electronic_board.board_sn` |
+| `boardStatus` | Integer | 班牌当前业务/设备状态 | 沿用 `train_electronic_board.board_status` 语义 |
+
+> **边界红线：**
+> 1. 本 VO 仅且只包含 `boardId`、`boardSn`、`boardStatus` 三个字段；
+> 2. 严禁加入 `boardIp`、`boardContent`、`bindPlanId`、`lastHeartbeat`、`createUser`、`updateTime` 以及完整 `TrainElectronicBoard` 实体字段；
+> 3. 无绑定班牌时，父级 `boards` 返回空列表 `[]`，不得返回 `null`。
+
+---
+
 ## 2. 核心业务命令与请求 DTO (Command & Request DTO)

 ### 2.1 P0 核心命令与请求 DTO (14 个)
@@ -108,6 +108,8 @@
 | **40005** | `BOARD_SN_DUPLICATED` | 电子班牌 SN 设备编号已存在 | 电子班牌 |
 | **40006** | `DORM_ROOM_DUPLICATED` | 同一楼栋下该宿舍房号已存在 | 宿舍房间 |
 | **40007** | `DORM_CAPACITY_CANNOT_SHRINK` | 房间容量不可调整至小于当前已入住人数 | 宿舍房间 |
+| **40008** | `CLASSROOM_NAME_DUPLICATED` | 教室名称已存在 | 教室 |
+| **40009** | `SITE_NAME_DUPLICATED` | 实训场地名称已存在 | 实训场地 |
 | **40010** | `PLAN_TIME_INVALID` | 培训计划起止时间不合法 (结束时间必须晚于开始时间) | 开班计划 (UC-01) |
 | **40011** | `PLAN_NAME_DUPLICATED` | 同名培训计划已存在 | 开班计划 (UC-01) |
 | **40012** | `PLAN_STATUS_LOCKED` | 当前培训计划已结训或取消，不允许修改 | 开班计划 (UC-02) |
@@ -138,3 +140,5 @@
 | **40093** | `SCORE_PLAN_MISMATCH` | 业务不变量校验失败：成绩录入学员工号与科目所属班次不符 | 成绩录入 (UC-21) |
 | **40100** | `STUDY_EVENT_INVALID` | 外部学习记录数据不合法 (结束时间早于开始时间或时长为负) | 学习接入 (UC-24) |
 | **40110** | `PORTRAIT_NOT_FOUND` | 该学员画像尚未生成，请先执行画像刷新 | 学员画像 (UC-28) |
+
+> **补录说明：** 错误码 `40008` (`CLASSROOM_NAME_DUPLICATED`) 与 `40009` (`SITE_NAME_DUPLICATED`) 属于 Issue Backlog 已有要求在错误码 Catalog 中的遗漏补录，不是新增业务需求。