From 516f551a44d553be5dc274d8de66e5b919314a87 Mon Sep 17 00:00:00 2001 From: wangzhibiao Date: Mon, 14 Sep 2026 09:31:42 +0800 Subject: [PATCH] =?UTF-8?q?=E6=8C=81=E7=BB=AD=E9=9B=86=E6=88=90=EF=BC=9A?= =?UTF-8?q?=E6=96=B0=E5=A2=9EGitLab=20CI/CD=E8=87=AA=E5=8A=A8=E5=8C=96?= =?UTF-8?q?=E6=B5=81=E6=B0=B4=E7=BA=BF=E9=85=8D=E7=BD=AE=E4=B8=8E=E7=8E=AF?= =?UTF-8?q?=E5=A2=83=E6=94=AF=E6=8C=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .gitlab-ci.yml | 65 ++++++++ docs/issues-v1/00_readme.md | 117 ++++++++++++++ docs/issues-v1/01_epic_overview.md | 235 +++++++++++++++++++++++++++++ 3 files changed, 417 insertions(+) create mode 100644 .gitlab-ci.yml create mode 100644 docs/issues-v1/00_readme.md create mode 100644 docs/issues-v1/01_epic_overview.md diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml new file mode 100644 index 000000000..0aaf14736 --- /dev/null +++ b/.gitlab-ci.yml @@ -0,0 +1,65 @@ +stages: + - build_backend + - build_frontend + - deploy + +variables: + GIT_STRATEGY: clone + JAVA_HOME: "/usr/lib/jvm/java-8-openjdk-amd64" + M2_HOME: "/data2/wzb/tools/maven" + PATH: "/data2/wzb/tools/maven/bin:/usr/lib/jvm/java-8-openjdk-amd64/bin:/usr/local/bin:/usr/bin:/bin" + +# 1. 编译打包后端 +build_backend: + stage: build_backend + tags: + - railway-deploy + rules: + - if: '$CI_COMMIT_BRANCH' + script: + - echo "=== 开始编译后端 RuoYi-Vue ===" + - export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64 + - export PATH=/data2/wzb/tools/maven/bin:$JAVA_HOME/bin:$PATH + - cd RuoYi-Vue + - mvn clean package -DskipTests + - echo "=== 后端编译成功 ===" + artifacts: + expire_in: 2 days + paths: + - RuoYi-Vue/ruoyi-admin/target/ruoyi-admin.jar + +# 2. 编译打包前端 +build_frontend: + stage: build_frontend + tags: + - railway-deploy + rules: + - if: '$CI_COMMIT_BRANCH' + script: + - echo "=== 开始编译前端 build_ui ===" + - export NODE_OPTIONS=--openssl-legacy-provider + - cd build_ui + - npm install --registry=https://registry.npmmirror.com + - npm run build:prod + - echo "=== 前端编译成功 ===" + artifacts: + expire_in: 2 days + paths: + - build_ui/dist/ + +# 3. 部署到业务目录并平滑重启 +deploy_production: + stage: deploy + tags: + - railway-deploy + rules: + - if: '$CI_COMMIT_BRANCH' + script: + - echo "=== 开始部署应用 ===" + # 复制前端静态资源到发布目录 + - rm -rf /data2/wzb/deploy/frontend/* + - cp -r build_ui/dist/* /data2/wzb/deploy/frontend/ + # 复制后端 Jar 包并执行重启 + - cp RuoYi-Vue/ruoyi-admin/target/ruoyi-admin.jar /data2/wzb/deploy/backend/ + - bash /data2/wzb/deploy/restart-all.sh + - echo "=== 部署与自检成功完成！ ===" diff --git a/docs/issues-v1/00_readme.md b/docs/issues-v1/00_readme.md new file mode 100644 index 000000000..41cda965f --- /dev/null +++ b/docs/issues-v1/00_readme.md @@ -0,0 +1,117 @@ +# RailwaySystem Phase 3：P0 Epic / Issue 任务拆分总纲 + +> **阶段状态：** Phase 3 任务分解完成稿 (正式基线) +> **业务最高基线：** `doc/RailwaySystem 智慧培训系统一期 PRD V1.0.md` +> **数据库基线：** `db-v2-migration-passed-20260914` (21张表 KingbaseES 物理迁移验证通过) +> **代码生成器基线：** `generator-v2-ready-20260914` (Kingbase 只读验证通过) +> **API 契约基线：** `api-v2-contract-v1.0` (Review Round 1 修订版，91 个 API) +> **本阶段原则：** **业务能力驱动拆分，严禁一张表机械对应一个 Issue；只拆 P0，P1/P2 仅作 Backlog 登记；严禁编写业务代码与修改数据库。** + +--- + +## 1. 拆分目标与核心原则 + +本阶段旨在将 `api-v2-contract-v1.0` 中的 **49 个 P0 API** 以及支撑业务运转的核心基础设施，转化为**可独立开发、可代码审查 (Review)、可自动化测试、可业务验收**的 Epic 与 Issue。 + +### 1.1 最高拆分原则 +1. **业务能力驱动，拒绝单表 CRUD：** + - 错误做法：拆分为 `开发 train_enrollment 表 CRUD`、`开发 train_lesson 表 CRUD`。 + - 正确做法：拆分为 `实现培训计划参训人员管理 (含防重与名单)`、`实现课次排课与四维冲突排他锁检测`。 +2. **只拆 P0 闭环，严格控制范围：** + - 锁定 49 个 P0 API 作为本轮研发唯一核心目标； + - 40 个 P1 辅助 API 与 2 个 P2 远期 API 仅在 [`07_p1_p2_backlog.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/issues-v1/07_p1_p2_backlog.md) 中登记备查，不计入开发排期。 +3. **主数据最小必要集合原则：** + - 基础主数据不作为全量阻塞项，仅建设支撑主业务链路所必需的最小集合（Teacher, Student, Course, Classroom, TrainingSite, Dormitory）。 +4. **不变量与并发控制强行绑定：** + - 5 大跨表业务硬不变量（INV-01 ~ INV-05）与 1 项报到生命周期策略，责任落实到唯一的责任 Issue； + - 排课并发冲突（教师/教室/场地/班级）与宿舍分配防超卖（行锁 `SELECT FOR UPDATE` + 性别隔离），必须在 Issue 中明确 SQL 与锁策略。 +5. **外部对接 Mock 优先与事务轻量解耦：** + - 外部硬件系统（班牌、门禁、VR/3D）一期一律采用 SPI + Mock 桩实现，严禁引入 MQ、Kafka、RabbitMQ、Outbox 等重型中间件； + - 外部调用一律置于数据库本地事务之外，通过事务提交后（`afterCommit`）轻量解耦触发，外部失败绝不回滚已提交的业务数据，支持手动重试。 + +--- + +## 2. 主链路业务开发优先级 + +系统的所有 Issue 依赖与开发批次（Wave），均严格围绕以下**最短业务闭环主链路**展开推进： + +```mermaid +flowchart TD + M1[基础数据: 教师 / 学员 / 课程 / 空间] --> M2[创建培训计划 Plan] + M2 --> M3[配置本期课程 PlanCourse] + M3 --> M4[添加参训名单 Enrollment] + M4 --> M5[课次排课与冲突检测 Lesson] + M5 --> M6[聚合生成完整课表 Timetable] + M4 --> M7[住宿批量预分配 Accommodation] + M7 --> M8[学员报到确认 Report] + M5 --> M9[电子班牌打卡考勤 Attendance] + M8 --> M9 + M9 --> M10[成绩项目与打分台账 Score] + M4 --> M11[外部实训记录接入 StudyRecord] + M10 --> M12[培训综合统计与工作台 Statistics/Workbench] + M11 --> M12 + M12 --> M13[结束培训计划 Complete Plan] + + style M1 fill:#e1f5fe,stroke:#0288d1,stroke-width:2px + style M2 fill:#e8f5e9,stroke:#388e3c,stroke-width:2px + style M4 fill:#fff3e0,stroke:#f57c00,stroke-width:2px + style M5 fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px + style M7 fill:#e0f2f1,stroke:#00796b,stroke-width:2px + style M9 fill:#fbe9e7,stroke:#d84315,stroke-width:2px + style M10 fill:#fffde7,stroke:#fbc02d,stroke-width:2px + style M13 fill:#ede7f6,stroke:#512da8,stroke-width:2px +``` + +--- + +## 3. 全局核心统计指标 + +经严密分解与审查，Phase 3 输出的核心统计指标如下： + +| 统计维度 | 指标数值 | 备注说明 | +|:---|:---|:---| +| **Epic 总数** | **12 个** | 覆盖主数据、核心计划、排课、住宿、门禁、考勤、成绩、学习、统计、权限字典与端到端验收 | +| **P0 Issue 总数** | **21 个** | 每个 Issue 为 0.5~2 个开发日的独立可验收业务能力 | +| **P0 API 覆盖率** | **100% (49/49)** | 完整映射 API Contract 中全部 49 个 P0 API（且涵盖 Module A 全部 20 个接口） | +| **Contract Gap 数量** | **2 项** | 详见本文档第 4 节及 Risk Register，技术风险完全可控 | +| **开发 Wave 数量** | **8 个** | Wave 0 (准备) ~ Wave 7 (验收)，层层递进 | +| **首批可立即开发 Issue** | **8 个** | Wave 0 (3个) + Wave 1 中不依赖 Plan 的基础数据 (5个) | +| **必须等待 Module B 的 Issue** | **10 个** | 涵盖排课、住宿分配、报到、考勤、成绩配置/录入、学习记录、工作台与端到端验收 | +| **Generator 策略分布** | YES: **4**, PARTIAL: **10**, NO: **7** | 基础表用 YES/PARTIAL 生成骨架，核心领域逻辑与聚合手写 | +| **Recommended Agent 分工** | Gemini: **9**, Codex: **12** | Gemini 负责基础 CRUD/VO/权限字典；Codex 负责高并发锁/复杂事务/不变量/端到端 | + +--- + +## 4. 契约偏差审查 (Contract Gap Analysis) + +在对齐 `api-v2-contract-v1.0` 与 Issue 拆分过程中，识别并登记了 2 项契约统计与定义的细微偏差（Contract Gap）： + +### 4.1 Gap 1：Module A P0 统计数字与正文标注偏差 (16 vs 20) +- **现象：** `00_readme.md` 与 `02_module_a_base_resource_api.md` 概览统计声明 Module A 拥有 16 个 P0 API、22 个 P1 API（总数 38）。但正文中带有【P0】标记的条目实际有 20 个（教师 4 个、学员 3 个、课程 3 个、教室 3 个、场地 3 个、宿舍 4 个）。 +- **根因：** 宿舍管理的 4 个接口（`GET /train/dormitory/list`, `GET /train/dormitory/{dormId}`, `POST /train/dormitory`, `GET /train/dormitory/options`）在正文中被标记为 P0，但概览统计口径中未将其计入主数据最小必要集合（4+3+3+3+3 = 16）。 +- **处理策略：** + - 本次 Issue 拆分采取**最大化安全覆盖原则**：设立独立 `ISSUE-01-05` 完整实现宿舍 4 个基础维护接口，保证无论是按 16 还是 20 统计口径，实际业务均不受任何阻塞； + - 正式 API 覆盖率判定中，49/49 个 P0 API 实现 100% 全覆盖。 + +### 4.2 Gap 2：Module B 课次单查接口定义缺失 +- **现象：** `00_readme.md` 第 136 行概览描述写有“课次详情”，但 `03_module_b_plan_enrollment_schedule_api.md` 正文中未独立定义 `GET /train/lessons/{lessonId}` 接口。 +- **根因：** 排课界面的数据回显完全由 `GET /train/plans/{planId}/timetable`（完整课表 VO）及冲突预检接口支撑，不需要对单课次频繁发起独立的详情 HTTP 请求。 +- **处理策略：** 严格遵循“不得在 Issue 阶段擅自发明新 API”铁律，暂不新增独立的课次详情接口，排课回显通过现有 Timetable 接口与课次列表解决；若后续前端组件有强诉求，由技术负责人走 API Contract Change 流程统一增补。 + +--- + +## 5. 文档索引导航 (docs/issues-v1/) + +本套 Issue 任务分解规范包含以下 9 篇文档： + +| 序号 | 文档名称 | 核心内容 | +|:---|:---|:---| +| 00 | [`00_readme.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/issues-v1/00_readme.md) | 阶段总纲、最高原则、主链路、统计总览、Contract Gap 分析与文档索引 | +| 01 | [`01_epic_overview.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/issues-v1/01_epic_overview.md) | 12 个业务 Epic 概览、目标、业务边界与包含的 Issue 对应清单 | +| 02 | [`02_p0_issue_backlog.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/issues-v1/02_p0_issue_backlog.md) | 21 个 P0 Issue 详细技术卡片（严格包含 22 项技术定义与 Given/When/Then 验收准则） | +| 03 | [`03_dependency_graph.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/issues-v1/03_dependency_graph.md) | Mermaid DAG 依赖图，清晰展示串行依赖与并行泳道 | +| 04 | [`04_wave_plan.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/issues-v1/04_wave_plan.md) | Wave 0 ~ Wave 7 开发推进批次计划、进入条件、产出目标与退出准则 | +| 05 | [`05_agent_assignment.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/issues-v1/05_agent_assignment.md) | Gemini Flash 与 Codex 研发分工建议及 Generator (YES/PARTIAL/NO) 执行策略 | +| 06 | [`06_acceptance_matrix.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/issues-v1/06_acceptance_matrix.md) | 全链路追踪矩阵 (UC → API → Issue → Test) 及 5 大 Invariant / 1 项生命周期策略归属矩阵 | +| 07 | [`07_p1_p2_backlog.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/issues-v1/07_p1_p2_backlog.md) | 40 个 P1 辅助 API 与 2 个 P2 远期 API 的统一登记与后续演进规划 | +| 08 | [`08_risk_register.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/issues-v1/08_risk_register.md) | 技术风险登记册、并发防死锁策略、外部 Mock 隔离与现场确认事项应对策略 | diff --git a/docs/issues-v1/01_epic_overview.md b/docs/issues-v1/01_epic_overview.md new file mode 100644 index 000000000..71b8f4445 --- /dev/null +++ b/docs/issues-v1/01_epic_overview.md @@ -0,0 +1,235 @@ +# RailwaySystem Phase 3：Epic 架构概览 (Epic Overview) + +> **设计基线：** 紧扣 PRD V1.0 业务闭环与 API Contract V1.0，严禁按 21 张数据库表机械建 Epic。 +> **Epic 规划原则：** 每一个 Epic 代表一个**高内聚、有明确业务价值、对主链路有明确支撑的业务能力域**。 + +--- + +## 1. Epic 汇总视图 + +系统一期 P0 研发共划分为 **12 个核心 Epic**，覆盖从基础设施、主数据、开班排课、过程执行、效果评估到端到端验收的完整闭环： + +```mermaid +flowchart TB + subgraph CoreBase["支撑基线与基础数据"] + E11[EPIC-11 权限/字典/系统基线] + E01[EPIC-01 基础主数据必要集合] + E06[EPIC-06 门禁与外部设备Mock] + end + + subgraph PlanCore["开班与排课核心"] + E02[EPIC-02 培训计划与本期课程] + E03[EPIC-03 参训人员管理] + E04[EPIC-04 排课与课表管理] + end + + subgraph Execution["过程执行支撑"] + E05[EPIC-05 住宿与报到管理] + E07[EPIC-07 课次考勤管理] + E09[EPIC-09 外部学习记录接入] + end + + subgraph Assessment["效果评估与结训"] + E08[EPIC-08 成绩项目与成绩台账] + E10[EPIC-10 计划统计与综合工作台] + end + + subgraph Acceptance["端到端验收"] + E12[EPIC-12 P0端到端业务闭环验收] + end + + E11 --> E01 + E06 --> E05 + E06 --> E07 + E06 --> E09 + E01 --> E02 + E02 --> E03 + E02 --> E04 + E03 --> E05 + E04 --> E07 + E05 --> E07 + E07 --> E08 + E03 --> E09 + E08 --> E10 + E07 --> E10 + E02 --> E10 + E10 --> E12 + + style CoreBase fill:#f5f5f5,stroke:#9e9e9e,stroke-width:1px + style PlanCore fill:#e8f5e9,stroke:#4caf50,stroke-width:1px + style Execution fill:#e1f5fe,stroke:#03a9f4,stroke-width:1px + style Assessment fill:#fff8e1,stroke:#ffc107,stroke-width:1px + style Acceptance fill:#fce4ec,stroke:#e91e63,stroke-width:2px +``` + +--- + +## 2. Epic 详细定义 + +### EPIC-01 基础主数据必要集合 (Base Master Data) +- **Epic ID：** `EPIC-01` +- **业务目标：** 为整个智慧培训业务链路提供最小必需的师资、人员、课程、教室、场地和宿舍主数据底座，支撑后续计划选课、排课冲突校验与住宿分配。 +- **包含 P0 Issue：** + - `ISSUE-01-01`: 师资主数据管理能力 (Teacher CRUD) + - `ISSUE-01-02`: 学员主档建档与安全脱敏管理 (Student Security & Masking) + - `ISSUE-01-03`: 课程库基础资料管理 (Course Base CRUD) + - `ISSUE-01-04`: 教学空间资源维护（普通教室与实训场地） (Classroom & Site) + - `ISSUE-01-05`: 宿舍房间与楼宇基础数据维护 (Dormitory Info & Cascading Options) +- **对应 P0 API：** + - `GET /train/teacher/list`, `GET /train/teacher/{tId}`, `POST /train/teacher`, `PUT /train/teacher/{tId}` + - `GET /train/student/list`, `GET /train/student/{sId}`, `POST /train/student` + - `GET /train/course/list`, `GET /train/course/{cId}`, `POST /train/course` + - `GET /train/classroom/list`, `GET /train/classroom/{classRoomId}`, `POST /train/classroom` + - `GET /train/training-site/list`, `GET /train/training-site/{siteId}`, `POST /train/training-site` + - `GET /train/dormitory/list`, `GET /train/dormitory/{dormId}`, `POST /train/dormitory`, `GET /train/dormitory/options` +- **涉及数据表：** `train_teacher`, `train_student`, `train_course`, `train_classroom`, `train_training_site`, `train_dormitory_info` +- **明确不做什么：** 不做教师资质多版本审批、不做学员主档多机构合并、不做课程版本流转、不做独立教学资源管理与班牌注册管理（属于 P1）。 + +--- + +### EPIC-02 培训计划与本期课程 (Plan & Plan-Course) +- **Epic ID：** `EPIC-02` +- **业务目标：** 实现培训班级项目的立项、编辑、周期维护与结训归档，并支撑本期教学课程的选定与课时引入。 +- **包含 P0 Issue：** + - `ISSUE-02-01`: 培训计划全生命周期创建与管理 (Plan Lifecycle) + - `ISSUE-02-02`: 本期培训课程引入与配置 (Plan-Course Mapping) +- **对应 P0 API：** + - `GET /train/plans`, `POST /train/plans`, `GET /train/plans/{planId}`, `PUT /train/plans/{planId}`, `POST /train/plans/{planId}/complete` + - `GET /train/plans/{planId}/courses`, `POST /train/plans/{planId}/courses` +- **涉及数据表：** `train_class_plan`, `train_plan_course` +- **明确不做什么：** 不做多级立项审批流；一期结训不设考核不及格阻断结业的强制卡点（Review Round 1 明确剔除）。 + +--- + +### EPIC-03 参训人员管理 (Enrollment Lifecycle) +- **Epic ID：** `EPIC-03` +- **业务目标：** 建立特定培训计划与学员的强业务绑定关系（形成 `enrollment_id`），支持单名录入与 Excel 批量解析导入，提供参训全景档案查询。 +- **包含 P0 Issue：** + - `ISSUE-03-01`: 本期参训名单维护与单条录入 (Enrollment Core & Detail) + - `ISSUE-03-02`: 参训人员 Excel 批量导入与防重校验 (Batch Enrollment Import) +- **对应 P0 API：** + - `GET /train/plans/{planId}/enrollments`, `POST /train/plans/{planId}/enrollments`, `GET /train/enrollments/{enrollmentId}` + - `POST /train/plans/{planId}/enrollments/batch` +- **涉及数据表：** `train_enrollment`, `train_student` +- **明确不做什么：** 不做复杂的退宿连带手续审批（仅做参训状态变更）；批量导入错误行不引入异步消息通知，直接返回同步解析结果列表。 + +--- + +### EPIC-04 排课与课表管理 (Scheduling & Timetable) +- **Epic ID：** `EPIC-04` +- **业务目标：** 支撑培训班课程的教学时段排定，实现教师、普通教室、实训场地、班级时段四维冲突检测与数据库行级排他锁保护，聚合生成本班完整课程表。 +- **包含 P0 Issue：** + - `ISSUE-04-01`: 课次编排与多维度排课并发冲突检测 (Lesson Scheduling & Conflict Lock) + - `ISSUE-04-02`: 培训计划完整课程表聚合展示 (Plan Timetable Aggregation) +- **对应 P0 API：** + - `POST /train/plans/{planId}/lessons`, `PUT /train/lessons/{lessonId}`, `POST /train/lessons/check-conflict` + - `GET /train/plans/{planId}/timetable` +- **涉及数据表：** `train_lesson`, `train_plan_course`, `train_teacher`, `train_classroom`, `train_training_site` +- **明确不做什么：** 不做遗传算法自动智能排课；不做复杂的周循环与双周排课规则；教师个人课表属于 P1。 + +--- + +### EPIC-05 住宿与报到管理 (Accommodation & Report) +- **Epic ID：** `EPIC-05` +- **业务目标：** 管理学员参训期间的生活保障与入班核验，包含批量智能预分房（严格按性别隔离与行锁防超卖）、单人调房、走读设定，以及学员现场报到与生命周期时限告警控制。 +- **包含 P0 Issue：** + - `ISSUE-05-01`: 批量住宿智能预分配与防超卖控制 (Batch Accommodation Allocation) + - `ISSUE-05-02`: 住宿人工调房、走读设置与住宿安排查看 (Accommodation Adjustment & Roster) + - `ISSUE-05-03`: 学员报到确认与生命周期时限控制 (Student Report & Lifecycle Policy) +- **对应 P0 API：** + - `POST /train/plans/{planId}/accommodations/preallocate` + - `PUT /train/enrollments/{enrollmentId}/accommodation`, `PUT /train/enrollments/{enrollmentId}/accommodation/day-student`, `GET /train/plans/{planId}/accommodations` + - `POST /train/enrollments/{enrollmentId}/report` +- **涉及数据表：** `train_accommodation`, `train_report_record`, `train_dormitory_info`, `train_enrollment` +- **明确不做什么：** 不做水电费计量结算；房态实时网格看板属于 P1；报到逾期不做硬阻断数据库约束，采用弹性时限告警策略。 + +--- + +### EPIC-06 门禁与外部设备Mock (Device Integration & Mock) +- **Epic ID：** `EPIC-06` +- **业务目标：** 建立防腐适配器体系 (SPI)，提供电子班牌人脸考勤、智能门禁授权、外部 VR/3D 学习记录对接的 Mock 实现与测试桩，并通过事务提交后（`afterCommit`）轻量解耦触发门禁同步，支持失败重试。 +- **包含 P0 Issue：** + - `ISSUE-06-01`: 外部设备适配器 SPI 体系与 Mock 桩实现 (Adapter SPI & Mocks) + - `ISSUE-06-02`: 门禁授权事务后解耦下发与失败手工重试 (Door Auth After-Commit & Manual Retry) +- **对应 P0 API：** + - `POST /train/accommodations/{accommodationId}/auth/sync` +- **涉及数据表：** `train_dorm_auth`, `train_accommodation`, `train_student` +- **明确不做什么：** 严禁对接真实厂家硬件私有协议；严禁引入 MQ、Kafka、RabbitMQ、Outbox 等重型中间件；门禁授权下发流水查询属于 P1。 + +--- + +### EPIC-07 课次考勤管理 (Lesson Attendance) +- **Epic ID：** `EPIC-07` +- **业务目标：** 围绕具体课次 (`lesson_id`) 与参训档案 (`enrollment_id`) 开展出勤管理，支撑班牌刷脸打卡签到/签退、任课教师实时查看课次考勤明细，以及异常出勤的人工修正与留痕。 +- **包含 P0 Issue：** + - `ISSUE-07-01`: 课次班牌打卡签到签退与跨班不变量防护 (Check-in/Check-out & Invariant INV-01) + - `ISSUE-07-02`: 课次考勤名单查看与人工考勤状态修正 (Lesson Attendance Roster & Manual Rectification) +- **对应 P0 API：** + - `POST /train/attendance/sign-in`, `POST /train/attendance/sign-out` + - `GET /train/lessons/{lessonId}/attendance`, `PUT /train/attendance/{checkinId}` +- **涉及数据表：** `train_attendance_record`, `train_lesson`, `train_enrollment` +- **明确不做什么：** 不做基于 GPS 地理围栏的移动端打卡；人工补录未打卡记录属于 P1；不变量 INV-01（课次所属班级 == 学员参训班级）在此强制阻断。 + +--- + +### EPIC-08 成绩项目与成绩台账 (Score Management) +- **Epic ID：** `EPIC-08` +- **业务目标：** 实现培训班成绩考核科目与百分制权重配置，支持教师对单学员或批量录入成绩，强校验满分上限与跨班归属，生成全班加权综合得分台账大表与单人成绩单。 +- **包含 P0 Issue：** + - `ISSUE-08-01`: 本期成绩考核项与权重配置 (Score Items & Weight Config, Invariant INV-04) + - `ISSUE-08-02`: 学员成绩录入、上限校验与全班成绩台账大表 (Score Entry, Matrix VO, Invariant INV-02 & INV-05) +- **对应 P0 API：** + - `GET /train/plans/{planId}/score-items`, `POST /train/plans/{planId}/score-items` + - `POST /train/scores/entry`, `GET /train/plans/{planId}/scores/matrix`, `GET /train/enrollments/{enrollmentId}/scores` +- **涉及数据表：** `train_score_item`, `train_student_score`, `train_enrollment` +- **明确不做什么：** 不做成绩发布审批流程；Excel 批量导入成绩属于 P1；严禁硬编码及格线与不合格阻断（仅计算 `weightedTotalScore`）。 + +--- + +### EPIC-09 外部学习记录接入 (External Learning Records) +- **Epic ID：** `EPIC-09` +- **业务目标：** 对接高铁驾驶模拟舱、VR 实训室、3D 拆装等外部专业设备推送的学习学时流水，提供防重复推送的唯一幂等处理与三态响应。 +- **包含 P0 Issue：** + - `ISSUE-09-01`: 外部实训系统自主学习流水幂等接入 (Learning Record Ingestion & Invariant INV-03) +- **对应 P0 API：** + - `POST /train/study-records/receive` +- **涉及数据表：** `train_study_duration`, `train_enrollment`, `train_plan_course` +- **明确不做什么：** 不对接大文件视频播放断点与心跳上报；自主学习记录分页检索与单人流水详情属于 P1。 + +--- + +### EPIC-10 计划统计与综合工作台 (Plan Workbench & Statistics) +- **Epic ID：** `EPIC-10` +- **业务目标：** 为培训管理人员提供开班期间的“一站式计划综合工作台”与结训阶段的“计划综合统计概览”，聚合展示报到率、出勤率、课表进度、成绩分布与自主学时。 +- **包含 P0 Issue：** + - `ISSUE-10-01`: 培训计划综合工作台聚合服务 (Plan Workbench Aggregation) + - `ISSUE-10-02`: 培训计划综合成效统计概览 (Plan Statistics Aggregation) +- **对应 P0 API：** + - `GET /train/plans/{planId}/workbench` + - `GET /train/plans/{planId}/statistics/overview` +- **涉及数据表：** 跨表只读聚合查询（`train_class_plan`, `train_enrollment`, `train_lesson`, `train_attendance_record`, `train_student_score`, `train_study_duration`） +- **明确不做什么：** 不做复杂的多维 OLAP 钻取报表；不引入 Elasticsearch / ClickHouse 等外部大数据分析引擎；多维度成绩下钻图表属于 P2。 + +--- + +### EPIC-11 权限字典与系统基线支撑 (RBAC, Dict & System Baseline) +- **Epic ID：** `EPIC-11` +- **业务目标：** 夯实系统运行底座，全面统一以 `train:*` 为前缀的 RBAC 菜单与按钮授权体系，规范化分类梳理 16 组培训业务字典，消除旧系统权限混乱扩散。 +- **包含 P0 Issue：** + - `ISSUE-11-01`: RuoYi RBAC 权限体系与按钮授权集成 (RBAC Migration & Train Permissions) + - `ISSUE-11-02`: 培训业务数据字典与参数配置初始化方案 (Dictionary & SysConfig Strategy) +- **对应 P0 API：** + - 支撑全部 49 个 P0 API 的鉴权拦截与前端按钮 `v-hasPermi` 显隐控制。 +- **涉及数据表：** `sys_menu`, `sys_role_menu`, `sys_dict_type`, `sys_dict_data`, `sys_config` +- **明确不做什么：** 本轮严禁执行 `007_dicts.sql` 物理入库；不做动态自定义数据权限过滤规则（一期采用基于角色的标准 RBAC）。 + +--- + +### EPIC-12 P0端到端业务闭环验收 (End-to-End Acceptance) +- **Epic ID：** `EPIC-12` +- **业务目标：** 串联 17 个 P0 核心用例（UC-01 ~ UC-29），构建完整的端到端自动化测试链路与基线集成回归用例，确保最小业务闭环能够流畅无缝运转。 +- **包含 P0 Issue：** + - `ISSUE-12-01`: 智慧培训全生命周期主链路端到端集成测试与验收 (End-to-End Acceptance Suite) +- **对应 P0 API：** + - 贯穿覆盖全部 49 个 P0 API 的链路式调用与数据验证。 +- **业务价值：** 彻底杜绝“各个单接口测试通过，连起来无法走通完整培训班”的集成陷阱，作为 Phase 3 研发交付的最终质量闸门。