176 lines
11 KiB
Markdown
176 lines
11 KiB
Markdown
# 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`。
|