111 lines
11 KiB
Markdown
111 lines
11 KiB
Markdown
# RailwaySystem Phase 3：研发分工与代码生成器策略 (Agent Assignment & Generator Strategy)
|
||
|
||
> **制定原则：** 最大化研发效能，合理配置 AI 算力与工程资源。
|
||
> **算力调度铁律：** **简单基础工作交由 Gemini Flash 高效完成，核心高难度/高并发/高风险架构工作保留给 Codex 集中攻坚，杜绝算力浪费。**
|
||
|
||
---
|
||
|
||
## 1. 代码生成器 (Generator V2) 实施策略
|
||
|
||
系统代码生成器已于 Phase 2 完成 KingbaseES 适配与基线冻结 (`generator-v2-ready-20260914`)。在 Phase 3 Issue 实施中，各 Issue 严格执行以下三级 Generator 策略：
|
||
|
||
```text
|
||
YES (4个 Issue) : 基础主数据单表，完全通过 Generator 快速生成 Entity、基础 Mapper XML 与基础 Service 骨架。
|
||
PARTIAL (11个 Issue) : 核心业务实体或敏感表，仅生成 Domain Entity 与基础 Mapper 骨架，Controller、DTO/VO、Application Service 业务编排必须严格按 API Contract 手写。
|
||
NO (11个 Issue) : 跨表聚合服务、并发锁算法、SPI防腐接口、系统权限字典方案、纯业务状态流转或端到端测试，严禁使用生成器代码。
|
||
```
|
||
|
||
### 1.1 Generator 策略明细矩阵
|
||
|
||
| Issue ID | Issue 名称 | Generator 策略 | 策略执行细则与约束 |
|
||
|:---|:---|:---:|:---|
|
||
| `ISSUE-01-01` | 师资主数据管理能力 | **YES** | 生成 `TrainTeacher` 实体、Mapper 与基础查询；在 Service 层补充手机号全局查重校验。 |
|
||
| `ISSUE-01-02` | 学员主档建档与安全脱敏管理 | **PARTIAL** | 生成 `TrainStudent` 实体骨架；**严禁生成明文落库代码**，手写安全散列查重与可逆密文存储逻辑。 |
|
||
| `ISSUE-01-03` | 课程库基础资料管理 | **YES** | 生成 `TrainCourse` 实体、Mapper 骨架；Service 层补充课程编码唯一性校验。 |
|
||
| `ISSUE-01-04` | 教学空间资源维护（教室与实训场地） | **YES** | 生成 `TrainClassroom` 与 `TrainTrainingSite` 单表骨架；补充容量大于零业务校验。 |
|
||
| `ISSUE-01-05` | 宿舍房间与楼宇基础数据维护 | **YES** | 生成 `TrainDormitoryInfo` 基础骨架；手写楼栋/楼层级联下拉树查询逻辑。 |
|
||
| `ISSUE-02-01` | 培训计划全生命周期创建与管理 | **PARTIAL** | 生成 `TrainClassPlan` 实体；**严禁使用生成器状态机**，手写状态流转校验与结训学员批量级联更新。 |
|
||
| `ISSUE-02-02` | 本期培训课程引入与配置 | **PARTIAL** | 生成 `TrainPlanCourse` 实体骨架；手写从课程库批量选课、防重与生成 `plan_course_id` 逻辑。 |
|
||
| `ISSUE-03-01` | 本期参训名单维护与单条录入 | **PARTIAL** | 生成 `TrainEnrollment` 实体；手写招生人数上限并发校验与 `enrollment_id` 核心上下文绑定。 |
|
||
| `ISSUE-03-02` | 参训人员 Excel 批量导入与防重校验 | **NO** | 纯业务批量事务与 EasyExcel 监听器，涉及多级错误行收集，全量手写。 |
|
||
| `ISSUE-04-01` | 课次编排与多维度排课并发冲突检测 | **PARTIAL** | 生成 `TrainLesson` 实体；**排课稳定主资源行锁 (FOR UPDATE) 与区间冲突算法必须纯手写**。 |
|
||
| `ISSUE-04-02` | 培训计划完整课程表聚合展示 | **NO** | 纯聚合只读服务，手写嵌套 `PlanTimetableVO` 结果集映射与周/日维度分组逻辑。 |
|
||
| `ISSUE-05-01` | 批量住宿智能预分配与防超卖控制 | **PARTIAL** | 生成 `TrainAccommodation` 实体；**严禁生成分房算法**，手写性别隔离、宿舍主表 `SELECT FOR UPDATE` 防超卖。 |
|
||
| `ISSUE-05-02` | 住宿人工调房、走读设置与住宿安排查看 | **NO** | 纯业务调房行锁、走读床位释放与状态流转，直接复用已有实体，严禁依赖生成器。 |
|
||
| `ISSUE-05-03` | 学员报到确认与生命周期时限控制 | **PARTIAL** | 生成 `TrainReportRecord` 实体；手写 `report_deadline` 策略核对、告警与强制放行逻辑。 |
|
||
| `ISSUE-06-01` | 外部设备适配器 SPI 体系与 Mock 桩实现 | **NO** | 纯架构防腐层设计，定义 3 大 SPI 接口及 Mock 实现类，手写。 |
|
||
| `ISSUE-06-02` | 门禁授权事务后解耦下发与失败手工重试 | **NO** | 涉及 Spring `afterCommit` 事务同步器注册与事务外解耦调用，手写。 |
|
||
| `ISSUE-07-01` | 课次班牌打卡签到签退与跨班不变量防护 | **PARTIAL** | 生成 `TrainAttendanceRecord` 实体；**硬不变量 INV-01 校验与幂等更新必须纯手写**。 |
|
||
| `ISSUE-07-02` | 课次考勤名单查看与人工考勤状态修正 | **PARTIAL** | 手写应到/实到花名册聚合左联 SQL、人工修正强制标记 `manual_flag = 1` 留痕。 |
|
||
| `ISSUE-08-01` | 本期成绩考核项与权重配置 | **PARTIAL** | 生成 `TrainScoreItem` 实体；手写总权重 100% 校验与硬不变量 INV-04 课程归属核验。 |
|
||
| `ISSUE-08-02` | 学员成绩录入、上限校验与全班成绩台账大表 | **NO** | 手写满分上限校验 (INV-05)、跨班阻断 (INV-02)、动态列行转列与加权总分计算。 |
|
||
| `ISSUE-09-01` | 外部实训系统自主学习流水幂等接入 | **PARTIAL** | 生成 `TrainStudyDuration` 实体；手写防重事件 ID 唯一性校验、三态响应与 INV-03 核查。 |
|
||
| `ISSUE-10-01` | 培训计划综合工作台聚合服务 | **NO** | 纯复杂 VO 聚合，跨 4 张表组装综合驾驶舱，手写。 |
|
||
| `ISSUE-10-02` | 培训计划综合成效统计概览 | **NO** | 纯跨模块业务指标聚合计算，含除零保护与四舍五入，手写。 |
|
||
| `ISSUE-11-01` | RuoYi RBAC 权限体系与按钮授权集成 | **NO** | 权限常量定义、`sys_menu` SQL 脚本方案与按钮权限梳理，纯系统基线工程。 |
|
||
| `ISSUE-11-02` | 培训业务数据字典与参数配置初始化方案 | **NO** | 16 组字典分类架构方案与静态字典初始化，纯数据架构分析。 |
|
||
| `ISSUE-12-01` | 智慧培训全生命周期主链路端到端集成测试与验收 | **NO** | 全链路自动化业务集成测试用例与验收套件，手写。 |
|
||
|
||
---
|
||
|
||
## 2. 研发智能体分配 (Gemini Flash vs Codex)
|
||
|
||
### 2.1 分配原则与算力调优
|
||
- **Gemini Flash (共 11 个 Issue)：**
|
||
- 适用场景：单表结构化 CRUD、VO/DTO 定义、权限常量梳理、数据字典方案、简单 Vue 列表页、单元测试数据构建。
|
||
- 核心优势：响应极其敏捷、大上下文处理结构清晰、遵循规范精准。
|
||
- **Codex (共 15 个 Issue)：**
|
||
- 适用场景：稳定主资源行排他锁 (`FOR UPDATE`)、防超卖算法、三类资源区间冲突查询、跨表强一致性硬不变量校验、事务提交后解耦、敏感数据安全脱敏、矩阵行转列与端到端验收。
|
||
- 核心优势：深度逻辑推理严密、并发锁死锁识别能力强、复杂领域模型抽象扎实。
|
||
|
||
### 2.2 详细分工清单
|
||
|
||
```mermaid
|
||
pie title Phase 3 Issue 研发分工比例 (总数 26)
|
||
"Gemini Flash (基础CRUD/聚合VO/基线)" : 11
|
||
"Codex (高并发锁/硬不变量/事务编排/验收)" : 15
|
||
```
|
||
|
||
| Issue ID | 推荐 Agent | 核心负责模块 / 任务边界 | 推荐理由与关键关注点 |
|
||
|:---|:---:|:---|:---|
|
||
| `ISSUE-11-01` | **Gemini Flash** | RBAC 权限体系与按钮授权 | 权限常量提取与标准 RuoYi 按钮匹配，规则明确标准。 |
|
||
| `ISSUE-11-02` | **Gemini Flash** | 字典分类方案梳理 | 评估 `007_dicts.sql` 语义，输出三类字典归属报告。 |
|
||
| `ISSUE-06-01` | **Gemini Flash** | 外部 Adapter SPI 与 Mock 桩 | 标准 Java Interface 与 Mock 类编写，快速高效。 |
|
||
| `ISSUE-01-01` | **Gemini Flash** | 教师主数据 CRUD | 标准单表管理，结构简单，适合快速落地。 |
|
||
| `ISSUE-01-02` | **Codex** | 学员主档脱敏与安全加密 | 涉及安全散列查重与可逆密文存储，需要严密的安全逻辑。 |
|
||
| `ISSUE-01-03` | **Gemini Flash** | 课程库基础资料管理 | 基础主档 CRUD，重点在于去除冗余版本字段。 |
|
||
| `ISSUE-01-04` | **Gemini Flash** | 教学空间资源维护 | 教室与场地标准数据维护，校验逻辑清晰。 |
|
||
| `ISSUE-01-05` | **Gemini Flash** | 宿舍房间与级联选项 | 楼栋/楼层级联树生成与基础房间录入。 |
|
||
| `ISSUE-02-01` | **Codex** | 培训计划生命周期管理 | 核心业务主干，涉及严格的时间校验与结训学员级联更新事务。 |
|
||
| `ISSUE-02-02` | **Gemini Flash** | 本期课程引入与配置 | 课程库与计划的关联，排重校验逻辑明确。 |
|
||
| `ISSUE-03-01` | **Codex** | 参训名单维护与单条录入 | 涉及 `enrollment_id` 核心领域标识生成与招生上限并发校验。 |
|
||
| `ISSUE-03-02` | **Codex** | Excel 批量导入与防重 | 大批量数据容错、身份证号校验、分批事务处理。 |
|
||
| `ISSUE-04-01` | **Codex** | 课次排课与稳定资源锁检测 | **高技术难度：** 必须使用教师/场地稳定行锁杜绝时段重叠穿透。 |
|
||
| `ISSUE-04-02` | **Gemini Flash** | 完整课表聚合展示 | 纯聚合查询，按日期嵌套展示课表，属于结构化组装。 |
|
||
| `ISSUE-05-01` | **Codex** | 批量住宿智能分配防超卖 | **高技术难度：** 锁定宿舍主表行 `SELECT FOR UPDATE` 彻底防并发超卖。 |
|
||
| `ISSUE-05-02` | **Codex** | 调房走读管理与锁控制 | 宿舍主表行锁核验容量与释放床位短事务，升序加锁防死锁。 |
|
||
| `ISSUE-05-03` | **Codex** | 学员报到与生命周期时限策略 | 涉及 `report_deadline` 弹性策略分支与管理员特批覆盖。 |
|
||
| `ISSUE-06-02` | **Codex** | 门禁 afterCommit 解耦下发 | **高架构要求：** 必须使用事务同步器解耦，外部失败严禁回滚。 |
|
||
| `ISSUE-07-01` | **Codex** | 课次打卡与 INV-01 防护 | **核心业务防线：** 强制校验学员班级与课次班级一致性。 |
|
||
| `ISSUE-07-02` | **Gemini Flash** | 考勤名单聚合与人工修正 | 课次应到实到名单左联与 `manual_flag = 1` 留痕。 |
|
||
| `ISSUE-08-01` | **Codex** | 成绩项目配置与 INV-04 | 权重严格总和 100% 校验与课程归属性校验。 |
|
||
| `ISSUE-08-02` | **Codex** | 成绩录入台账 INV-02/05 | **核心业务防线：** 满分上限校验、跨班打分阻断、加权总分计算。 |
|
||
| `ISSUE-09-01` | **Codex** | 外部学习记录接入与 INV-03 | **高可靠性要求：** 唯一事件 ID 查重三态幂等与跨班课程校验。 |
|
||
| `ISSUE-10-01` | **Gemini Flash** | 培训计划综合工作台 VO | 跨表只读数据组装，快速呈现大盘卡片与日程。 |
|
||
| `ISSUE-10-02` | **Codex** | 计划成效综合统计概览 | 报到率、出勤率、加权平均分多指标精准聚合与除零保护。 |
|
||
| `ISSUE-12-01` | **Codex** | P0 主链路端到端闭环验收 | **终极交付质量把关：** 串联 17 个 UC 完整业务流程验证。 |
|
||
|
||
---
|
||
|
||
## 3. 研发协同与代码审查 (Review) 规范
|
||
|
||
1. **并行开发阶段：**
|
||
- Gemini Flash 先行完成 Wave 0 与 Wave 1 中主数据部分 (`ISSUE-01-01`, `01-03`, `01-04`, `01-05`)，为后续业务提供数据实体；
|
||
- Codex 同步启动 `ISSUE-01-02` (安全脱敏) 与 `ISSUE-02-01` (计划生命周期)。
|
||
2. **核心业务攻坚阶段 (Wave 2 ~ Wave 5)：**
|
||
- Codex 集中精力攻克排课行锁 (`04-01`)、住宿防超卖 (`05-01`)、门禁解耦 (`06-02`) 以及 5 大硬不变量（INV-01 ~ INV-05）；
|
||
- Gemini Flash 配合完成课表展示 (`04-02`)、配课 (`02-02`)、考勤名单 (`07-02`) 等 VO 聚合及前端视图。
|
||
3. **代码合并准入卡点：**
|
||
- 任何涉及并发锁与硬不变量的 Codex 产出代码，必须包含对应的多线程并发单元测试或破坏性断言用例；
|
||
- 任何 Gemini Flash 产出的代码，严禁私自修改数据库 DDL 与生成器全局模板。
|