railwaysystem/docs/api-v2/06_dto_vo_catalog.md

# RailwaySystem DTO / VO 领域模型目录与字段规范

> **规范原则：** 坚决禁止 Controller 直接使用数据库持久化 Domain 作为前端接口契约。
> 明确区分 **Request DTO** (前端输入参数校验)、**Command DTO** (驱动业务动作)、**Query DTO** (查询筛选条件) 和 **Response VO** (安全脱敏与视图聚合)。
> **Review Round 1 修订：** 增加 P0 / P1 / P2 优先级标注；`weightedTotalScore` 作为核心【确认】成绩结果，及格判定 `passStatus` 降级为【默认/建议方案（待现场确认）】；学员画像调整为通用弹性指标集。

---

## 1. 核心聚合视图对象 (Core Aggregate VO)

### 1.1 培训计划综合工作台：`PlanWorkbenchVO` 【P0】【确认】
- **定位：** 管理员打开培训班核心工作台时的一次性状态概览与决策入口。
- **字段规范：**

| 字段名 | 类型 | 说明 | 业务来源 |
|:---|:---|:---|:---|
| `planId` | String | 培训计划唯一标识 | `train_class_plan.plan_id` |
| `planName` | String | 培训班名称 | `train_class_plan.plan_name` |
| `planStatus` | Integer | 状态：0未开始 1进行中 2已结束 3已取消 | `train_class_plan.plan_status` |
| `startTime` | Date | 开班时间 | `train_class_plan.start_time` |
| `endTime` | Date | 结业时间 | `train_class_plan.end_time` |
| `reportDeadline` | Date | 报到截止时间 | `train_class_plan.report_deadline` |
| `trainAddress` | String | 培训地点 | `train_class_plan.train_address` |
| `courseSummary` | Object | 本期课程概览 (`courseCount`, `courseNames`) | 聚合 `train_plan_course` |
| `enrollmentSummary` | Object | 参训人数统计 (`recruitNum`, `enrolledCount`, `reportedCount`, `leaveCount`) | 聚合 `train_enrollment` |
| `scheduleSummary` | Object | 排课状态 (`totalLessons`, `scheduledHours`, `hasConflict`) | 聚合 `train_lesson` |
| `accommodationSummary` | Object | 住宿概况 (`requiredCount`, `allocatedCount`, `dayStudentCount`) | 聚合 `train_accommodation` |
| `scoreConfigSummary` | Object | 成绩配置状态 (`isConfigured`, `itemCount`, `totalWeight`) | 聚合 `train_score_item` |
| `nextActionHint` | String | 工作台下一步建议操作指引 | 业务规则动态生成 |

---

### 1.2 计划完整课程表：`PlanTimetableVO` 【P0】【确认】
- **定位：** 全局展示该班从开班到结训的所有课次日历排期。
- **字段规范：**

| 字段名 | 类型 | 说明 |
|:---|:---|:---|
| `planId` | String | 培训计划标识 |
| `planName` | String | 培训班名称 |
| `startDate` | Date | 课表开始日期 |
| `endDate` | Date | 课表结束日期 |
| `days` | List<TimetableDayVO> | 按日期分组的课次排期集合 |
| `days[].date` | String | 日期 (yyyy-MM-dd) |
| `days[].dayOfWeek` | Integer | 星期几 (1~7) |
| `lessons[].lessonId` | Long | 课次主键标识 |
| `lessons[].planCourseId` | Long | 本期计划课程关联标识 (回显表单必需) |
| `lessons[].courseName` | String | 本期课程名称 |
| `lessons[].tId` | String | 授课教师工号/标识 (回显表单必需) |
| `lessons[].teacherName` | String | 授课教师姓名 |
| `lessons[].startTime` | Date | 课次开始时间 |
| `lessons[].endTime` | Date | 课次结束时间 |
| `lessons[].venueType` | Integer | 场地类型 (1教室 2实训场地) |
| `lessons[].classRoomId` | Long | 普通教室物理标识 (venueType=1 时有效，回显表单必需) |
| `lessons[].classRoomName` | String | 普通教室名称 |
| `lessons[].siteId` | Long | 实训场地物理标识 (venueType=2 时有效，回显表单必需) |
| `lessons[].siteName` | String | 实训场地名称 |
| `lessons[].venueName` | String | 场地聚合展示名称 |
| `lessons[].boardSn` | String | 关联电子班牌 SN 号（若有） |
| `lessons[].remark` | String | 课次备注 (回显表单必需) |

---

### 1.3 学员参训档案全景：`EnrollmentDetailVO` 【P0】【确认】
- **定位：** 查看某学员在某培训班的全生命周期全景档案。
- **字段规范：**

| 字段名 | 类型 | 说明 |
|:---|:---|:---|
| `enrollmentId` | Long | 参训档案标识 |
| `planId` | String | 培训计划标识 |
| `planName` | String | 培训计划名称 |
| `studentId` | String | 学员 ID |
| `studentName` | String | 学员姓名 |
| `gender` | String | 性别 |
| `idCardMasked` | String | 身份证脱敏展示 (`210102********1234`) |
| `orgName` | String | 选派单位 |
| `enrollmentStatus` | Integer | 状态：0待报到 1已报到 2请假 3放弃 4已完成 |
| `accommodationRequired` | Integer | 住宿需求 (0不住宿 1住宿) |
| `accommodation` | Object | 当前住宿分配详情 (`building`, `room`, `bedNo`, `authStatus`) |
| `report` | Object | 报到信息 (`reportTime`, `reportWay`, `verifyNote`) |

---

### 1.4 排课冲突检测结果：`LessonConflictVO` 【P0】【确认】
- **字段规范：**
  - `hasConflict`: Boolean (是否存在冲突)
  - `conflictType`: String (`NONE`, `TEACHER`, `CLASSROOM`, `SITE`, `PLAN_OVERLAP`)
  - `conflictMessage`: String (冲突描述文本)
  - `conflictingLessons`: List<ConflictItemVO> (冲突的现有课次明细)

---

### 1.5 全班综合成绩台账矩阵：`PlanScoreMatrixVO` 【P0】【确认/现场调整】
- **定位：** 全班成绩汇总大表。
- **字段规范：**

| 字段名 | 类型 | 确定性 | 说明 |
|:---|:---|:---|:---|
| `planId` | String | 【确认】 | 培训计划标识 |
| `headers` | List<ScoreHeaderVO> | 【确认】 | 表头科目定义：`scoreItemId`, `itemName`, `weight`, `fullScore` |
| `rows[].enrollmentId` | Long | 【确认】 | 参训档案标识 |
| `rows[].studentName` | String | 【确认】 | 学员姓名 |
| `rows[].orgName` | String | 【确认】 | 单位名称 |
| `rows[].scores` | Map<Long, Double> | 【确认】 | 各科目实际得分映射 (`scoreItemId -> score`) |
| `rows[].weightedTotalScore` | Double | 【确认】 | 核心业务结果：加权综合折算总分 |
| `rows[].passStatus` | Integer | 【默认/建议方案（待现场确认）】 | 及格判定：现场若确定及格线则输出(0不及格 1及格)，未确定前置为 null |

---

### 1.6 培训计划综合统计概览：`PlanStatisticsVO` 【P0】【确认】
- **定位：** 计划综合成效报表。包含参训/报到/结训人数、综合出勤率、课程出勤对比、各设备自主学习时长分布、平均综合得分（不包含固定及格率）。

---

### 1.7 学员个人全流程训练详情：`StudentTrainingDetailVO` 【P1】【确认】
- **定位：** 学员全流程档案流水（出勤流水、单科成绩流水、自主学习流水）。

---

### 1.8 学员综合画像：`StudentPortraitVO` 【P1】【确认/现场调整】
- **定位：** 简单画像展示 VO。避免过早写死四维雷达图与具体标签规则。
- **字段规范：**

| 字段名 | 类型 | 确定性 | 说明 |
|:---|:---|:---|:---|
| `enrollmentId` | Long | 【确认】 | 参训档案标识 |
| `studentName` | String | 【确认】 | 学员姓名 |
| `orgName` | String | 【确认】 | 单位名称 |
| `metrics` | List<PortraitMetricVO> | 【默认/建议方案（待现场确认）】 | 指标集合（如出勤率、理论分、实操分、时长），支持前端动态渲染为雷达图或柱状图 |
| `tags` | List<String> | 【默认/建议方案（待现场确认）】 | 画像标签集合（如 `["出勤良好", "实操突出"]`），待现场确认具体标签集 |
| `summary` | String | 【默认/建议方案（待现场确认）】 | 综合评语概要 |
| `generatedTime` | Date | 【确认】 | 画像生成时间 |

---

### 1.9 实时房态看板：`DormOccupancyBoardVO` 【P1】【确认】
- 按楼栋 -> 楼层 -> 房间分组的网格视图。

---

### 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 个)
- **`PlanCreateDTO`** 【P0】: `planName`, `startTime`, `endTime`, `reportDeadline`, `recruitNum`, `trainAddress`, `remark`
- **`PlanUpdateDTO`** 【P0】: 计划修改
- **`PlanCourseAddDTO`** 【P0】: `cIds`, `remark`
- **`EnrollmentAddDTO`** 【P0】: `studentId`, `sourceType`, `accommodationRequired`
- **`EnrollmentBatchDTO`** 【P0】: `file`, `autoCreateStudent`
- **`LessonCreateDTO`** 【P0】: `planCourseId`, `tId`, `startTime`, `endTime`, `venueType`, `classRoomId`, `siteId`
- **`LessonUpdateDTO`** 【P0】: 课次修改
- **`LessonConflictCheckDTO`** 【P0】: 排课预检
- **`AccommodationPreallocateDTO`** 【P0】: `preferredBuilding`, `genderSeparated`, `sameClassAdjacent`
- **`AccommodationAdjustDTO`** 【P0】: `targetDormId`, `bedNo`, `reason`
- **`ReportConfirmDTO`** 【P0】: `reportWay`, `reportDeviceSn`, `verifyNote`, `forceOverride` (支持时限策略)
- **`AttendanceSignInDTO`** 【P0】: `enrollmentId`, `lessonId`, `boardId`, `checkinWay`, `signInTime`
- **`AttendanceSignOutDTO`** 【P0】: `enrollmentId`, `lessonId`, `signOutTime`
- **`ScoreItemBatchConfigDTO`** 【P0】: `items` (包含科目名称、类型、权重、满分)
- **`ScoreEntryBatchDTO`** 【P0】: `entries` (`enrollmentId`, `scoreItemId`, `score`)
- **`StudyRecordReceiveDTO`** 【P0】: `enrollmentId`, `sourceSystem`, `sourceEventId`, `startTime`, `endTime`, `studySeconds`

### 2.2 P1 辅助命令与请求 DTO (4 个)
- **`AttendanceAdjustDTO`** 【P1】: 考勤人工修正 (`attendanceStatus`, `manualFlag=1`, `remark`)
- **`ScoreImportDTO`** 【P1】: Excel 导入成绩
- **`PortraitGenerateDTO`** 【P1】: 画像生成请求
- **`TeacherCreateDTO` / `StudentCreateDTO`** 等基础资料录入 DTO 【P0/P1】