# 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 / 分布式事务【扩展】。