124 lines
7.5 KiB
Markdown
124 lines
7.5 KiB
Markdown
|
# RailwaySystem Service 聚合边界与模块责任划分
|
||
|
|
|
||
|
|
> **架构定位：** 解决传统若依代码生成后业务逻辑严重泄漏在 Controller 层的痛点。
|
||
|
|
> **分层原则：** Controller 仅负责参数接收与简单校验；所有跨表事务、业务不变量校验、状态机流转与外部系统适配编排全部收敛在 **业务编排层 (Application Service)**。底层保留轻量级的 **基础领域持久化 Service (Domain / Mapper Service)**。
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 1. Service 分层架构模型
|
||
|
|
|
||
|
|
```mermaid
|
||
|
|
flowchart TD
|
||
|
|
subgraph ControllerLayer["Web Controller 层"]
|
||
|
|
C1[TrainClassPlanController]
|
||
|
|
C2[TrainEnrollmentController]
|
||
|
|
C3[TrainLessonController]
|
||
|
|
C4[TrainAccommodationController]
|
||
|
|
C5[TrainAttendanceController]
|
||
|
|
C6[TrainScoreController]
|
||
|
|
end
|
||
|
|
|
||
|
|
subgraph ApplicationServiceLayer["业务编排层 (Application Service / 事务边界)"]
|
||
|
|
AS1[PlanAppService]
|
||
|
|
AS2[EnrollmentAppService]
|
||
|
|
AS3[SchedulingAppService]
|
||
|
|
AS4[AccommodationAppService]
|
||
|
|
AS5[ReportAppService]
|
||
|
|
AS6[AttendanceAppService]
|
||
|
|
AS7[ScoreAppService]
|
||
|
|
AS8[LearningAppService]
|
||
|
|
AS9[StatisticsAppService]
|
||
|
|
AS10[PortraitAppService]
|
||
|
|
AS11[ExternalIntegrationAppService]
|
||
|
|
end
|
||
|
|
|
||
|
|
subgraph DomainServiceLayer["基础持久化与数据访问层 (Domain / Mapper Service)"]
|
||
|
|
DS1[ITrainClassPlanService]
|
||
|
|
DS2[ITrainEnrollmentService]
|
||
|
|
DS3[ITrainLessonService]
|
||
|
|
DS4[ITrainAccommodationService]
|
||
|
|
DS5[ITrainCheckinService]
|
||
|
|
DS6[ITrainScoreItemService]
|
||
|
|
DS7[ITrainStudentScoreService]
|
||
|
|
DS8[ITrainDormitoryInfoService]
|
||
|
|
DS9[ITrainTeacherService]
|
||
|
|
DS10[ITrainStudentService]
|
||
|
|
end
|
||
|
|
|
||
|
|
subgraph ExternalAdapters["外部适配器层 (Mock First / 轻量异步)"]
|
||
|
|
EA1[FaceAttendanceAdapter]
|
||
|
|
EA2[DoorAccessAdapter]
|
||
|
|
EA3[ExternalLearningAdapter]
|
||
|
|
end
|
||
|
|
|
||
|
|
ControllerLayer --> ApplicationServiceLayer
|
||
|
|
ApplicationServiceLayer --> DomainServiceLayer
|
||
|
|
ApplicationServiceLayer --> ExternalAdapters
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 2. 核心业务编排 Service 职责规范
|
||
|
|
|
||
|
|
### 2.1 `PlanAppService` (培训计划生命周期编排)
|
||
|
|
- **核心职责：** 开班计划的创建、编辑、状态流转、工作台聚合数据装配、结训归档。
|
||
|
|
- **关键方法：**
|
||
|
|
- `PlanWorkbenchVO getPlanWorkbench(String planId)`: 跨表聚合本期课程、学员入班、排课、住宿、成绩配置概况。
|
||
|
|
- `String createPlan(PlanCreateDTO dto)`: 校验起止时间与人数，初始化状态为未开始。
|
||
|
|
- `void updatePlan(PlanUpdateDTO dto)`: 校验计划状态与已排课次时段边界。
|
||
|
|
- `void completePlan(String planId, String operator)`: 结束培训计划，事务内将计划状态更新为 2 (已结束)，批量将该班有效参训记录更新为 4 (已完成)。
|
||
|
|
|
||
|
|
### 2.2 `EnrollmentAppService` (参训人员全流程编排)
|
||
|
|
- **核心职责：** 学员入班准入、查重、Excel批量名单解析、参训状态维护、退班清理。
|
||
|
|
- **关键方法：**
|
||
|
|
- `Long addEnrollment(String planId, EnrollmentAddDTO dto)`: 校验防重复参训 (`UNIQUE(plan_id, student_id)`)，创建参训档案。
|
||
|
|
- `BatchImportResultVO batchImportEnrollments(String planId, MultipartFile file, boolean autoCreate)`: 解析 Excel 批量原子入班。
|
||
|
|
- `void updateEnrollmentStatus(Long enrollmentId, Integer status, String reason)`: 维护请假、放弃状态。
|
||
|
|
|
||
|
|
### 2.3 `SchedulingAppService` (排课编排与冲突检测)
|
||
|
|
- **核心职责：** 课次增删改、四维排课冲突检测引擎、完整课程表结构化装配。
|
||
|
|
- **关键方法：**
|
||
|
|
- `LessonConflictVO checkConflict(LessonConflictCheckDTO dto)`: 四维排课冲突预检算法（教师、教室、场地、本班）。
|
||
|
|
- `Long createLesson(String planId, LessonCreateDTO dto)`: 行锁保护下排课入库。
|
||
|
|
- `void updateLesson(Long lessonId, LessonUpdateDTO dto)`: 排除自身后冲突校验；已有考勤记录阻断改期。
|
||
|
|
- `PlanTimetableVO getPlanTimetable(String planId)`: 组装日历日程矩阵。
|
||
|
|
|
||
|
|
### 2.4 `AccommodationAppService` (住宿策略与分配编排)
|
||
|
|
- **核心职责：** 批量住宿自动化预分配算法、单人调房、走读设置、房间入住看板聚合。
|
||
|
|
- **关键方法：**
|
||
|
|
- `void preallocateAccommodations(String planId, AccommodationPreallocateDTO dto)`: 按“男女分开、同班同寝、相邻房间优先”批量预分配，行锁保护容量。
|
||
|
|
- `void adjustAccommodation(Long enrollmentId, AccommodationAdjustDTO dto)`: 单人调房，校验目标房间容量与性别匹配。
|
||
|
|
- `void setDayStudent(Long enrollmentId, boolean isDayStudent, String remark)`: 走读免宿设置，清退床位。
|
||
|
|
|
||
|
|
### 2.5 `ReportAppService` (学员报到业务编排)
|
||
|
|
- **核心职责：** 报到身份确认、时效生命周期校验、联动信息（住宿、课表、首课）即时输出。
|
||
|
|
- **关键方法：**
|
||
|
|
- `ReportResultVO confirmReport(Long enrollmentId, ReportConfirmDTO dto)`: 检查 `report_deadline` 生命周期策略（支持严格阻断、警告提示或管理员强制覆盖三种模式），写入报到记录并更新参训状态为 1 (已报到)。
|
||
|
|
|
||
|
|
### 2.6 `AttendanceAppService` (考勤事件与人工修正)
|
||
|
|
- **核心职责：** 班牌签到/签退事件接入、业务不变量 1 校验、考勤状态判定、人工补签修正。
|
||
|
|
- **关键方法：**
|
||
|
|
- `void recordSignIn(AttendanceSignInDTO dto)`: 强校验 `enrollment.plan_id == lesson.plan_course.plan_id`，幂等记录签到。
|
||
|
|
- `void recordSignOut(AttendanceSignOutDTO dto)`: 记录签退并核算本次出勤是否达标。
|
||
|
|
- `void adjustAttendance(Long checkinId, AttendanceAdjustDTO dto)`: 人工修正考勤，`manual_flag = 1` 留痕。
|
||
|
|
|
||
|
|
### 2.7 `ScoreAppService` (成绩项目权重与折算引擎)
|
||
|
|
- **核心职责：** 成绩项权重总和 100% 校验、打分录入、满分上限校验、加权综合分实时计算。
|
||
|
|
- **关键方法：**
|
||
|
|
- `void configureScoreItems(String planId, ScoreItemBatchConfigDTO dto)`: 强校验权重总和 100.0 及课程归属性。
|
||
|
|
- `void recordScores(ScoreEntryBatchDTO dto)`: 强校验 `score <= fullScore` 及跨班不变量 2，批量入库。
|
||
|
|
- `PlanScoreMatrixVO getPlanScoreMatrix(String planId)`: 动态计算每名学员的加权综合成绩 `weightedTotalScore`，及格判定作为可选扩展。
|
||
|
|
|
||
|
|
### 2.8 `LearningAppService` (外部学习记录幂等接入)
|
||
|
|
- **核心职责：** 接收 VR/3D 学习时长、防重去重、时间与时长有效性校验。
|
||
|
|
- **关键方法：**
|
||
|
|
- `StudyEventResultVO receiveLearningRecord(StudyRecordReceiveDTO dto)`: 基于 `(source_system, source_event_id)` 幂等入库，返回 accepted / duplicate / invalid。
|
||
|
|
|
||
|
|
### 2.9 `StatisticsAppService` (多维实时统计聚合)
|
||
|
|
- **核心职责：** 计划大屏综合统计、课程出勤横向对比、自主学习时长分布（一期不设统计中间表）。
|
||
|
|
|
||
|
|
### 2.10 `PortraitAppService` (学员画像计算)
|
||
|
|
- **核心职责：** 基于考勤、理论、实操、学习时长生成简单画像指标集与标签集。
|
||
|
|
|
||
|
|
### 2.11 `ExternalIntegrationAppService` (外部系统防腐与适配编排)
|
||
|
|
- **核心职责：** 统一隔离外部网络波动与设备协议差异；数据库事务提交成功后通过 `afterCommit` 触发后续 Adapter 调用（一期默认建议：`afterCommit` → 轻量异步执行器 → Adapter；若未引入异步执行器则为当前线程事务外调用 Adapter，两者皆保证外部调用失败不回滚本地已提交事务，保留待同步状态并支持手工重试），一期不引入 MQ / Outbox / 分布式事务【扩展】。
|