railwaysystem/docs/api-v2/07_service_boundary.md

RailwaySystem Service 聚合边界与模块责任划分

架构定位： 解决传统若依代码生成后业务逻辑严重泄漏在 Controller 层的痛点。 分层原则： Controller 仅负责参数接收与简单校验；所有跨表事务、业务不变量校验、状态机流转与外部系统适配编排全部收敛在 业务编排层 (Application Service)。底层保留轻量级的 基础领域持久化 Service (Domain / Mapper Service)。

---

1. Service 分层架构模型

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