blp/railwaysystem
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
fix/iot-safety-hardening
railwaysystem/docs/api-v2/00_readme.md
T

11 KiB
Raw Permalink Blame History

RailwaySystem Phase 2：API Contract / DTO-VO / Service Boundary Design

阶段状态： Phase 2 契约设计冻结稿 (Review Round 1 修订版) 业务最高基线： 一期 PRD V1.0 数据持久化基线： 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 中全面沿用，禁止退化为旧式的多字段复合弱标识：

1. enrollment_id (参训档案标识)
   = 某个学员参加某个培训计划的唯一主线上下文。
   考勤、报到、住宿、成绩、学习记录、画像全部挂接此 ID。

2. plan_course_id (计划课程标识)
   = 某个公共课程被引入某个具体培训计划后的本期课程实例。
   课次排课、成绩项目可选绑定、学习内容挂接此 ID。

3. lesson_id (课次教学活动标识)
   = 本期某门课程在特定时间、特定场地、由特定教师开展的具体教学活动。
   电子班牌联动、课次签到/签退考勤明细直接绑定此 ID。

3. 业务闭环与模块分布

系统一期紧扣 PRD V1.0 冻结的业务主流程，划分为四大业务模块：

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 阶段总纲、架构全景、领域标识映射、最小合约视图与文档索引
01 01_api_design_principles.md API 架构原则、Resource vs Command、分页规范、返回包装与确定性/优先级定义
02 02_module_a_base_resource_api.md Module A 基础主数据 API 契约（教师、学员、课程、资源、教室、场地、班牌、宿舍）
03 03_module_b_plan_enrollment_schedule_api.md Module B 核心业务 API 契约（计划、工作台、本期课程、参训名单、排课冲突预检、课表、报到）
04 04_module_c_accommodation_attendance_api.md Module C 过程执行 API 契约（宿舍预分配、调整、门禁同步、班牌签到/签退、考勤修正）
05 05_module_d_score_learning_statistics_api.md Module D 业务成效 API 契约（成绩配置、打分台账、学习记录接入、统计下钻、学员画像）
06 06_dto_vo_catalog.md DTO / VO 领域模型资产全集（明确字段、类型、校验规则与用例映射）
07 07_service_boundary.md 业务编排 Application Service 与基础 CRUD Service 的职责与协作边界
08 08_transaction_and_invariants.md 事务控制边界、并发锁策略与 5 大跨表业务不变量 + 1 项报到生命周期策略落地规范
09 09_external_adapter_contract.md 外部适配器契约（班牌/人脸考勤、智能门禁、VR/3D学习接入，Mock与轻量异步机制）
10 10_permission_and_error_codes.md RuoYi RBAC 权限字符定义与全业务错误码模型规范
11 11_open_questions.md PRD V-01 ~ V-14 现场验证问题映射、API 影响与隔离应对策略
12 12_contract_review_round1.md Contract Review Round 1 审查报告（越界修正、P0/P1/P2裁定、结论A）

5. 一期规模与核心指标统计 (Review Round 1)

  • 一期 API 总数： 89 个 (以正文真实定义的 HTTP Method + Path 物理 Endpoint 为准)
    • P0 优先级 (核心闭环必须实现)： 53 个
    • P1 优先级 (辅助支撑能力)： 34 个
    • P2 优先级 (依赖现场确认/延后)： 2 个
  • 模块分布统计：
    • Module A (人员与基础资源)： 38 个 (P0: 20, P1: 18, P2: 0)
    • Module B (开班计划与排课)： 24 个 (P0: 17, P1: 6, P2: 1)
    • Module C (住宿/门禁/考勤)： 13 个 (P0: 9, P1: 4, P2: 0)
    • Module D (成绩/学习/统计/画像)： 14 个 (P0: 7, P1: 6, 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 规模概览 (共 53 个)

  • Module A (20个)： 教师列表/详情/增/改；学员列表/详情/录入；课程列表/详情/新增；教室列表/详情/新增；场地列表/详情/新增；宿舍列表/详情/新增/选项。
  • Module B (17个)： 计划列表/增/查/改/完成/工作台；本期课程列表/增；参训名单列表/单增/批量导入/详情；新增课次/修改课次/冲突预检/完整课表；报到确认。
  • Module C (9个)： 批量预分配宿舍/单人调房/走读设置/住宿列表；门禁同步重试；签到/签退/人工修正/课次考勤名单。
  • Module D (7个)： 成绩项目列表/权重配置；录入成绩；成绩台账大表/学员成绩单；学习记录接收；计划统计概览。

6.2 P0 核心 Command API 清单 (共 20 个：19 个核心业务流程 Command + 1 个 P0 计划管理更新)

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 清单

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。

7. 版本说明 (Version History)

V1.0.2

  1. 补录40008 CLASSROOM_NAME_DUPLICATED
  2. 补录40009 SITE_NAME_DUPLICATED
  3. 冻结ClassroomDetailVO.boards为0..N班牌摘要列表
  4. 新增ClassroomBoardSummaryVO定义
  5. Endpoint Method/Path/Priority/Permission/count均不变
Reference in new issue View Git Blame Copy Permalink