# RailwaySystem Phase 2：API Contract / DTO-VO / Service Boundary Design > **阶段状态：** Phase 2 契约设计冻结稿 (Review Round 1 修订版) > **业务最高基线：** `doc/RailwaySystem 智慧培训系统一期 PRD V1.0.md` > **数据持久化基线：** `doc/RailwaySystem 数据库 V2 字段设计与 Kingbase DDL 规范 V1.0.md` (21张表) > **代码生成器基线：** `generator-v2-ready-20260914` (只读验证通过) > **审查基线：** `docs/api-v2/12_contract_review_round1.md` (Review Round 1 判定通过: A) > **设计原则：** 业务工作台驱动 / 业务流程闭环驱动，坚决抵制 21 张表单表 CRUD 堆砌。 --- ## 1. 阶段目标与定位 本阶段处于数据库 V2 冻结与正式业务编码之间，目标为： > **在不编写业务代码的前提下，把 PRD V1.0、Database V2 和业务流程正式转换成 API 契约、DTO/VO、Service 聚合边界和模块责任。** 本系统定位为**在职人员智慧培训业务系统**，其核心价值是支撑铁路培训基地开展“学员参训全生命周期”的培训管理，而不是 21 张表的后台增删改查。所有接口均紧密围绕**业务工作台**、**业务动作（Command）**与**业务查询（Resource）**展开。 --- ## 2. 领域核心标识映射 数据库 V2 确立的三大业务领域主键在 API 与 DTO/VO 中全面沿用，禁止退化为旧式的多字段复合弱标识： ```text 1. enrollment_id (参训档案标识) = 某个学员参加某个培训计划的唯一主线上下文。 考勤、报到、住宿、成绩、学习记录、画像全部挂接此 ID。 2. plan_course_id (计划课程标识) = 某个公共课程被引入某个具体培训计划后的本期课程实例。 课次排课、成绩项目可选绑定、学习内容挂接此 ID。 3. lesson_id (课次教学活动标识) = 本期某门课程在特定时间、特定场地、由特定教师开展的具体教学活动。 电子班牌联动、课次签到/签退考勤明细直接绑定此 ID。 ``` --- ## 3. 业务闭环与模块分布 系统一期紧扣 PRD V1.0 冻结的业务主流程，划分为四大业务模块： ```mermaid flowchart LR subgraph ModuleA["Module A: 人员与基础资源"] A1[教师/学员主档] A2[课程库/教学资源] A3[教室/场地/班牌/宿舍房态] end subgraph ModuleB["Module B: 开班计划与排课 (核心业务)"] B1[创建/编辑培训计划] B2[配置本期课程] B3[参训人员名单/导入] B4[课次编排与冲突检测] B5[学员报到确认] B6[计划综合工作台] end subgraph ModuleC["Module C: 住宿/门禁/考勤"] C1[批量住宿预分配/调整] C2[门禁授权下发/重试] C3[班牌考勤签到/签退] C4[考勤人工修正/补录] end subgraph ModuleD["Module D: 成绩/学习/统计/画像"] D1[成绩项目权重配置] D2[成绩录入/导入/台账] D3[外部学习记录接入] D4[计划统计/成绩下钻] D5[学员综合画像] end ModuleA --> ModuleB ModuleB --> ModuleC ModuleB --> ModuleD ModuleC --> ModuleD ``` --- ## 4. 文档目录导航 (docs/api-v2/) 本设计规范包含以下 13 篇核心文档，相互支撑，构成完整的开发契约： | 序号 | 文档名称 | 核心内容 | |:---|:---|:---| | 00 | [`00_readme.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/api-v2/00_readme.md) | 阶段总纲、架构全景、领域标识映射、最小合约视图与文档索引 | | 01 | [`01_api_design_principles.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/api-v2/01_api_design_principles.md) | API 架构原则、Resource vs Command、分页规范、返回包装与确定性/优先级定义 | | 02 | [`02_module_a_base_resource_api.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/api-v2/02_module_a_base_resource_api.md) | Module A 基础主数据 API 契约（教师、学员、课程、资源、教室、场地、班牌、宿舍） | | 03 | [`03_module_b_plan_enrollment_schedule_api.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/api-v2/03_module_b_plan_enrollment_schedule_api.md) | Module B 核心业务 API 契约（计划、工作台、本期课程、参训名单、排课冲突预检、课表、报到） | | 04 | [`04_module_c_accommodation_attendance_api.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/api-v2/04_module_c_accommodation_attendance_api.md) | Module C 过程执行 API 契约（宿舍预分配、调整、门禁同步、班牌签到/签退、考勤修正） | | 05 | [`05_module_d_score_learning_statistics_api.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/api-v2/05_module_d_score_learning_statistics_api.md) | Module D 业务成效 API 契约（成绩配置、打分台账、学习记录接入、统计下钻、学员画像） | | 06 | [`06_dto_vo_catalog.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/api-v2/06_dto_vo_catalog.md) | DTO / VO 领域模型资产全集（明确字段、类型、校验规则与用例映射） | | 07 | [`07_service_boundary.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/api-v2/07_service_boundary.md) | 业务编排 Application Service 与基础 CRUD Service 的职责与协作边界 | | 08 | [`08_transaction_and_invariants.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/api-v2/08_transaction_and_invariants.md) | 事务控制边界、并发锁策略与 5 大跨表业务不变量 + 1 项报到生命周期策略落地规范 | | 09 | [`09_external_adapter_contract.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/api-v2/09_external_adapter_contract.md) | 外部适配器契约（班牌/人脸考勤、智能门禁、VR/3D学习接入，Mock与轻量异步机制） | | 10 | [`10_permission_and_error_codes.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/api-v2/10_permission_and_error_codes.md) | RuoYi RBAC 权限字符定义与全业务错误码模型规范 | | 11 | [`11_open_questions.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/api-v2/11_open_questions.md) | PRD V-01 ~ V-14 现场验证问题映射、API 影响与隔离应对策略 | | 12 | [`12_contract_review_round1.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/api-v2/12_contract_review_round1.md) | Contract Review Round 1 审查报告（越界修正、P0/P1/P2裁定、结论A） | --- ## 5. 一期规模与核心指标统计 (Review Round 1) - **一期 API 总数：** 91 个 - **P0 优先级 (核心闭环必须实现)：** 49 个 - **P1 优先级 (辅助支撑能力)：** 40 个 - **P2 优先级 (依赖现场确认/延后)：** 2 个 - **模块分布统计：** - **Module A (人员与基础资源)：** 38 个 (P0: 16, P1: 22, P2: 0) - **Module B (开班计划与排课)：** 25 个 (P0: 17, P1: 7, P2: 1) - **Module C (住宿/门禁/考勤)：** 13 个 (P0: 9, P1: 4, P2: 0) - **Module D (成绩/学习/统计/画像)：** 15 个 (P0: 7, P1: 7, P2: 1) - **外部 Adapter 接口数量：** 3 个 (`FaceAttendanceAdapter`, `DoorAccessAdapter`, `ExternalLearningAdapter`) - **核心业务 Command API 数量：** 24 个 (包含 P0 核心 Command API 20 个 [19 个核心业务流程 Command + 1 个 P0 计划管理更新: `PUT /train/plans/{planId}`], P1 辅助 Command 4 个) - **核心聚合 VO 数量：** 8 个 - **DTO / VO 定义总数：** 46 个 (P0 核心 DTO/VO: 26 个) - **业务 Application Service：** 11 个 (包含 10 个 P0 Application Service + 1 个 P1 PortraitAppService) - **标准事务控制边界：** 8 个 - **跨表业务强制不变量 (Cross-table Invariants)：** 5 项 - **业务生命周期控制策略 (Lifecycle Policy)：** 1 项 (Report Deadline) --- ## 6. Phase 1 Minimal Contract (P0 核心开发基线) 为确保后续 Issue 拆分与开发聚焦于最小可用的完整培训业务闭环，特设立 **Phase 1 Minimal Contract** 视图。后续开发阶段将首先按此基线开展编码与单元测试： ### 6.1 P0 API 规模概览 (共 49 个) - **Module A (16个)：** 教师列表/详情/增/改；学员列表/详情/录入；课程列表/详情/新增；教室列表/详情/新增；场地列表/详情/新增；宿舍列表/详情/新增/选项。 - **Module B (17个)：** 计划列表/增/查/改/完成/工作台；本期课程列表/增；参训名单列表/单增/批量导入/详情；新增课次/修改课次/课次详情/冲突预检/完整课表；报到确认。 - **Module C (9个)：** 批量预分配宿舍/单人调房/走读设置/住宿列表；门禁同步重试；签到/签退/人工修正/课次考勤名单。 - **Module D (7个)：** 成绩项目列表/权重配置；录入成绩；成绩台账大表/学员成绩单；学习记录接收；计划统计概览。 ### 6.2 P0 核心 Command API 清单 (共 20 个：19 个核心业务流程 Command + 1 个 P0 计划管理更新) ```text 1. POST /train/plans (创建培训计划) 2. PUT /train/plans/{planId} (P0计划管理更新：编辑培训计划) 3. POST /train/plans/{planId}/complete (结束培训计划) 4. POST /train/plans/{planId}/courses (配置本期课程) 5. POST /train/plans/{planId}/enrollments (添加参训人员) 6. POST /train/plans/{planId}/enrollments/batch (Excel批量导入参训人员) 7. POST /train/plans/{planId}/lessons (新增课次) 8. PUT /train/lessons/{lessonId} (修改课次) 9. POST /train/lessons/check-conflict (课次冲突预检) 10. POST /train/enrollments/{enrollmentId}/report (学员报到确认) 11. POST /train/plans/{planId}/accommodations/preallocate (批量住宿预分配) 12. PUT /train/enrollments/{enrollmentId}/accommodation (单人调房) 13. PUT /train/enrollments/{enrollmentId}/accommodation/day-student (设置走读) 14. POST /train/accommodations/{id}/auth/sync (门禁授权手动同步) 15. POST /train/attendance/sign-in (课次签到) 16. POST /train/attendance/sign-out (课次签退) 17. PUT /train/attendance/{checkinId} (人工修正考勤) 18. POST /train/plans/{planId}/score-items (成绩项目与权重配置) 19. POST /train/scores/entry (录入学员成绩) 20. POST /train/study-records/receive (外部学习记录接入) ``` ### 6.3 P0 核心聚合 VO 清单 ```text 1. PlanWorkbenchVO (培训计划综合工作台 VO) 2. PlanTimetableVO (计划完整课程表 VO) 3. EnrollmentDetailVO (学员参训全景档案 VO) 4. LessonConflictVO (排课冲突预检结果 VO) 5. PlanScoreMatrixVO (全班成绩台账大表 VO，只包含加权综合得分，不硬编码及格线) 6. PlanStatisticsVO (计划综合统计概览 VO) ``` ### 6.4 P0 Application Service 清单 (10 个 P0 业务编排 Service) `PlanAppService`, `EnrollmentAppService`, `SchedulingAppService`, `AccommodationAppService`, `ReportAppService`, `AttendanceAppService`, `ScoreAppService`, `LearningAppService`, `StatisticsAppService`, `ExternalIntegrationAppService`。