8.9 KiB
8.9 KiB
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 | 按日期分组的课次排期集合 |
days[].date |
String | 日期 (yyyy-MM-dd) |
days[].dayOfWeek |
Integer | 星期几 (1~7) |
days[].lessons |
List | 当日课次列表 |
lessons[].lessonId |
Long | 课次 ID |
lessons[].courseName |
String | 本期课程名称 |
lessons[].teacherName |
String | 授课教师姓名 |
lessons[].startTime |
Date | 课次开始时间 |
lessons[].endTime |
Date | 课次结束时间 |
lessons[].venueType |
Integer | 场地类型 (1教室 2实训场地) |
lessons[].venueName |
String | 教室名称或实训场地名称 |
lessons[].boardSn |
String | 关联电子班牌 SN 号（若有） |
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 (冲突的现有课次明细)
1.5 全班综合成绩台账矩阵：PlanScoreMatrixVO 【P0】【确认/现场调整】
- 定位： 全班成绩汇总大表。
- 字段规范：
| 字段名 | 类型 | 确定性 | 说明 |
|---|---|---|---|
planId |
String | 【确认】 | 培训计划标识 |
headers |
List | 【确认】 | 表头科目定义：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 | 【默认/建议方案（待现场确认）】 | 指标集合（如出勤率、理论分、实操分、时长），支持前端动态渲染为雷达图或柱状图 |
tags |
List | 【默认/建议方案（待现场确认）】 | 画像标签集合（如 ["出勤良好", "实操突出"]），待现场确认具体标签集 |
summary |
String | 【默认/建议方案（待现场确认）】 | 综合评语概要 |
generatedTime |
Date | 【确认】 | 画像生成时间 |
1.9 实时房态看板：DormOccupancyBoardVO 【P1】【确认】
- 按楼栋 -> 楼层 -> 房间分组的网格视图。
2. 核心业务命令与请求 DTO (Command & Request DTO)
2.1 P0 核心命令与请求 DTO (14 个)
PlanCreateDTO【P0】:planName,startTime,endTime,reportDeadline,recruitNum,trainAddress,remarkPlanUpdateDTO【P0】: 计划修改PlanCourseAddDTO【P0】:cIds,remarkEnrollmentAddDTO【P0】:studentId,sourceType,accommodationRequiredEnrollmentBatchDTO【P0】:file,autoCreateStudentLessonCreateDTO【P0】:planCourseId,tId,startTime,endTime,venueType,classRoomId,siteIdLessonUpdateDTO【P0】: 课次修改LessonConflictCheckDTO【P0】: 排课预检AccommodationPreallocateDTO【P0】:preferredBuilding,genderSeparated,sameClassAdjacentAccommodationAdjustDTO【P0】:targetDormId,bedNo,reasonReportConfirmDTO【P0】:reportWay,reportDeviceSn,verifyNote,forceOverride(支持时限策略)AttendanceSignInDTO【P0】:enrollmentId,lessonId,boardId,checkinWay,signInTimeAttendanceSignOutDTO【P0】:enrollmentId,lessonId,signOutTimeScoreItemBatchConfigDTO【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】