From 407de9781020f08ac931d96bca858f2915823bac Mon Sep 17 00:00:00 2001 From: wangzhibiao Date: Mon, 14 Sep 2026 11:07:26 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=87=E6=A1=A3=E6=8E=A5=E5=8F=A3=EF=BC=9A?= =?UTF-8?q?=E4=BF=AE=E8=AE=A2=E5=B9=B6=E5=86=BB=E7=BB=93API=20Contract=20V?= =?UTF-8?q?1.0.2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/api-v2/00_readme.md | 11 ++++++ docs/api-v2/02_module_a_base_resource_api.md | 6 +++- docs/api-v2/06_dto_vo_catalog.md | 35 ++++++++++++++++++++ docs/api-v2/10_permission_and_error_codes.md | 4 +++ 4 files changed, 55 insertions(+), 1 deletion(-) diff --git a/docs/api-v2/00_readme.md b/docs/api-v2/00_readme.md index ab6605703..18040e65b 100644 --- a/docs/api-v2/00_readme.md +++ b/docs/api-v2/00_readme.md @@ -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均不变 diff --git a/docs/api-v2/02_module_a_base_resource_api.md b/docs/api-v2/02_module_a_base_resource_api.md index 51ebb2840..209ce57ff 100644 --- a/docs/api-v2/02_module_a_base_resource_api.md +++ b/docs/api-v2/02_module_a_base_resource_api.md @@ -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) diff --git a/docs/api-v2/06_dto_vo_catalog.md b/docs/api-v2/06_dto_vo_catalog.md index 9ea6459b9..148b907cd 100644 --- a/docs/api-v2/06_dto_vo_catalog.md +++ b/docs/api-v2/06_dto_vo_catalog.md @@ -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 | 绑定的班牌摘要列表。无绑定班牌时返回 `[]`，不得返回 `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 个) diff --git a/docs/api-v2/10_permission_and_error_codes.md b/docs/api-v2/10_permission_and_error_codes.md index c0ed42b60..60972c8c3 100644 --- a/docs/api-v2/10_permission_and_error_codes.md +++ b/docs/api-v2/10_permission_and_error_codes.md @@ -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 中的遗漏补录，不是新增业务需求。