168 lines
13 KiB
Markdown
168 lines
13 KiB
Markdown
# ISSUE-02-01 培训计划生命周期与基础管理开发验收
|
||
|
||
## 1. 基线与范围
|
||
|
||
- 分支：`feat/issue-02-01-plan`
|
||
- 起始 HEAD：`7fcaea29b8810546fd972ba0c9d366c71a357d63`
|
||
- Issue 基线：`issues-v1.0`
|
||
- API 基线：`api-v2-contract-v1.0.1`（`4873e5f555ecfe7d1d21d313007c2c8f6f65d6b6`）
|
||
- Generator 策略为 `PARTIAL`，本轮未执行 Generator Import。
|
||
- 本 Issue 只实现 Plan 自身的创建、编辑、列表、详情、结束和稳定上下文；未实现 PlanCourse、Enrollment、Lesson、Accommodation、Attendance、Score、Study、Statistics。
|
||
|
||
## 2. 旧实现审计
|
||
|
||
| 旧文件 | 判定 | 处理 |
|
||
|---|---|---|
|
||
| `TrainClassPlan.java` | MODIFY | 按 Database V2 删除 `cId/tId/createUser`，增加 `reportDeadline/delFlag`，使用标准审计字段。 |
|
||
| `TrainClassPlanMapper.java` | MODIFY | 移除物理删除能力，增加名称预查重、生命周期行锁读取和状态更新。 |
|
||
| `TrainClassPlanMapper.xml` | REPLACE | 旧单课程/单教师 SQL 替换为 V2 字段、有效状态、列表筛选、概览只读计数及行锁 SQL。 |
|
||
| `ITrainClassPlanService.java` | MODIFY | 保留为基础持久化边界，不承载生命周期编排。 |
|
||
| `TrainClassPlanServiceImpl.java` | MODIFY | 只封装 Mapper。 |
|
||
| `TrainClassPlanController.java` | DELETE | 删除旧 `/train/plan` CRUD、删除和导出端点。 |
|
||
| `TrainPlanController.java` | REPLACE | 使用正式 `/train/plans` Contract，只依赖 `PlanAppService`。 |
|
||
| `build_ui/src/api/train/plan.js` | MODIFY | 使用正式复数路径，删除 delete API，增加 complete Command。 |
|
||
| `build_ui/src/views/train/plan/index.vue` | REPLACE | 仅呈现和编辑 Plan 自身，不绑定单课程或单教师。 |
|
||
|
||
旧模型的 `Plan = 单课程 + 单教师` 已从 Domain、Mapper、Controller DTO/VO、前端 API 和页面中消除。课程属于 ISSUE-02-02 的 `PlanCourse`，教师属于具体 `Lesson`；本 Issue 未提前实现这些写能力。
|
||
|
||
## 3. 正式 P0 API 与 Controller 契约
|
||
|
||
| Priority | Method | Path | Permission | Request | Response |
|
||
|---|---|---|---|---|---|
|
||
| P0 | GET | `/train/plans` | `train:plan:list` | `PlanQuery`：`pageNum/pageSize` 由分页框架接管，业务字段为 `planName/planStatus/startTimeBegin/startTimeEnd` | `TableDataInfo<PlanItemVO>` |
|
||
| P0 | POST | `/train/plans` | `train:plan:add` | `PlanCreateDTO` | Contract 未命名专用响应 VO；当前为标准 `AjaxResult`，`data` 为 `plan_id` |
|
||
| P0 | GET | `/train/plans/{planId}` | `train:plan:query` | Path `planId` | `AjaxResult<PlanDetailVO>` |
|
||
| P0 | PUT | `/train/plans/{planId}` | `train:plan:edit` | Path `planId` + `PlanUpdateDTO` | 标准空 `AjaxResult` |
|
||
| P0 | POST | `/train/plans/{planId}/complete` | `train:plan:complete` | Path `planId`，无 Request Body | 标准空 `AjaxResult` |
|
||
|
||
`TrainPlanController` 没有 Contract 外 Endpoint；旧 `TrainClassPlanController` 已删除，不存在双 Controller 路由。Controller 未接收或返回 `TrainClassPlan` Persistence Domain。
|
||
|
||
### 3.1 实际 DTO/VO 清单
|
||
|
||
- `PlanCreateDTO`：`planName/startTime/endTime/reportDeadline/recruitNum/trainAddress/applyCondition/remark`。来源以 Module B 1.2 的具体 JSON 和校验规则为准。
|
||
- `PlanUpdateDTO`：`planName/startTime/endTime/reportDeadline/recruitNum/trainAddress/applyCondition/remark`，不接受 `planStatus`。Module B 1.4 明列名称、地址、人数、报到截止和备注；Issue 业务目标及 Service Boundary 同时要求起止时间维护与课次边界检查，因此保留起止时间。`applyCondition` 的更新字段在目录中未逐项展开，登记为 Contract 表述缺口，不修改冻结文档。
|
||
- `PlanQuery`：`planName/planStatus/startTimeBegin/startTimeEnd`；分页字段由 RuoYi 接管。
|
||
- `PlanItemVO`：`planId/planName/planStatus/startTime/endTime/reportDeadline/trainAddress/recruitNum/courseCount/enrolledCount`。
|
||
- `PlanDetailVO`：`planId/planName/planStatus/startTime/endTime/reportDeadline/trainAddress/recruitNum/applyCondition/remark/createBy/createTime/updateBy/updateTime`。
|
||
|
||
`docs/api-v2/06_dto_vo_catalog.md` 的 `PlanCreateDTO` 摘要未列 `applyCondition`，但 `docs/api-v2/03_module_b_plan_enrollment_schedule_api.md` 1.2 的确认 JSON 明确包含它；实现采用更具体的 Module B 定义，此差异作为 Contract Gap 记录。
|
||
|
||
## 4. PlanAppService 边界
|
||
|
||
- `listPlans`：读取分页概览，不做写操作。
|
||
- `getPlan`：读取 `PlanDetailVO`，不存在时抛出 Plan not found。
|
||
- `createPlan`：名称规范化与友好查重、时间/人数校验、生成技术主键、强制初始状态 0。
|
||
- `updatePlan`：行锁读取、有效状态校验、名称和字段校验后更新；客户端不能直接改状态。
|
||
- `completePlan`：先确认至少一个真实 Enrollment Completion Port 已接线，再行锁读取、校验并更新 Plan 状态，随后在同一同步事务调用 Port。
|
||
|
||
Controller 只处理 HTTP、Bean Validation、权限、日志和标准响应，不调用 Mapper 或编排多步业务。
|
||
|
||
## 5. 生命周期与 effective status
|
||
|
||
- 创建只写 `plan_status=0`。
|
||
- DB 不会因时间到达而将 0 写成 1；`TrainClassPlanMapper.xml#effectivePlanStatusPolicy` 是唯一生产规则源：持久化状态为 0 且 `start_time <= CURRENT_TIMESTAMP` 时，只读结果呈现为 1。
|
||
- 列表输出、`planStatus` 筛选、详情、编辑的 `FOR UPDATE` 读取、complete 的 `FOR UPDATE` 读取均复用该 SQL fragment。Application Service 不再重复时间判断。
|
||
- 查询不会写数据库，也不会根据 `end_time` 自动结束；结束只能由正式 complete Command 写状态 2。
|
||
- 状态 0 与派生状态 1 均允许 complete；Contract 未要求 `now >= end_time`，实现未增加该条件。
|
||
- 状态 2 重复 complete 返回 `40014`；状态 3 complete 返回 `40012`。
|
||
- 状态 2/3 禁止编辑。状态 3 仅作历史只读兼容；没有 cancel Endpoint，前端没有取消按钮。
|
||
- 后续业务若需判断 Plan 状态，应通过 `ITrainClassPlanService` 的正式读取/锁读取取得已应用 effective status 的 Plan，而不是自行复制时间判断。
|
||
|
||
## 6. Enrollment Completion Port 审计
|
||
|
||
- 接口：`PlanEnrollmentCompletionPort`。
|
||
- Main/生产实现类：无。
|
||
- `@Configuration/@Bean` 绑定：无。
|
||
- 构造注入：`PlanAppServiceImpl` 使用 `ObjectProvider<PlanEnrollmentCompletionPort>` 收集已注册 adapter；Bean 缺失不阻断应用启动，但执行 complete 时会 fail closed。
|
||
- 测试实现：测试类内部 `RecordingEnrollmentPort`，另有 lambda throwing fake 用于异常传播；都不进入生产 runtime。
|
||
- 分类：**Case C — 只有接口与测试 Fake，生产尚未接线**。
|
||
|
||
没有注册 silent no-op 实现，也没有伪造 Enrollment UPDATE。当前没有生产 adapter 时，`completePlan` 在任何 Plan 查询或状态更新前抛出无业务错误码的内部 `IllegalStateException`；请求失败，Plan 不会产生单边 `status=2`。ISSUE-03-01 必须实现真实 adapter，并以集成测试验证 `enrollment_status=4`、`complete_time` 以及任一步失败时的跨表回滚。
|
||
|
||
### AC-03 拆分
|
||
|
||
- **AC-03a — UNIT_PASS**：单元测试验证 Plan 状态更新、Completion Port 恰好调用一次、缺失 Port 时 fail closed、端口异常不被吞掉；同时确认 `completePlan` 使用 `@Transactional(rollbackFor=Exception.class)` 且端口在方法内同步调用。
|
||
- **AC-03b — INTEGRATION_PENDING (ISSUE-03-01)**：真实 Enrollment 批量 `status=4 + complete_time` 及跨表提交/回滚尚未验证。
|
||
- **Integration Safety — UNIT_PASS**：Port missing 时在 Plan update 前失败，状态更新调用次数为 0，Plan 保持原状态。
|
||
|
||
当前证据只能表述为“transaction orchestration seam 已验证”；不能表述为完整跨表事务或 Enrollment runtime 已通过。
|
||
|
||
## 7. 错误码映射与 Contract Gap
|
||
|
||
| 常量 | 值 | 冻结语义与来源 | 当前触发位置 |
|
||
|---|---:|---|---|
|
||
| `PLAN_TIME_INVALID` | 40010 | API 10 错误码表；Module B 1.2；ISSUE-02-01 | create/update 的 `start >= end`；`reportDeadline > startTime` 同属计划时间参数校验 |
|
||
| `PLAN_NAME_DUPLICATED` | 40011 | API 10；Module B 1.2；ISSUE-02-01 | create/update 的 Service 友好名称预查重 |
|
||
| `PLAN_STATUS_LOCKED` | 40012 | API 10；ISSUE-02-01 | 状态 2/3 编辑；状态 3 complete |
|
||
| `PLAN_LESSON_OUT_OF_BOUNDS` | 40013 | API 10（UC-02） | 本 Issue 不实现 Lesson，当前无触发点；待 Scheduling 边界接入，未伪造校验 |
|
||
| `PLAN_ALREADY_COMPLETED` | 40014 | API 10（UC-29）；ISSUE-02-01 | 状态 2 重复 complete |
|
||
| `PLAN_NOT_FOUND` | 40410 | 冻结 Issue Backlog 的多个 Plan 依赖用例 | detail/update/complete 的计划不存在 |
|
||
|
||
API 10 的全局错误码表未列 40410、Module B 1.3 也未为详情逐项列 not-found code，但冻结 Issue Backlog 已使用 `PLAN_NOT_FOUND (40410)`。实现未发明新码；此目录间缺口仅登记，不修改冻结文档。招生人数由 DTO Bean Validation 处理，Service 防御校验使用普通 `ServiceException`，不再错误复用 40010，也未新增业务错误码。
|
||
|
||
## 8. 名称唯一与技术主键
|
||
|
||
- Database V2 没有 `UNIQUE(plan_name)`；当前只有 Service 层忽略首尾空格与大小写的友好重复预检查，并发强唯一性不保证。本 Issue 不新增 UNIQUE。
|
||
- “自动编号”仅指 `plan_id = IdUtils.fastSimpleUUID()` 生成的 32 位 UUID 技术主键。没有、也未发明 `plan_code` 或 `plan_no` 物理字段。
|
||
|
||
## 9. 测试依赖与 14 个测试方法
|
||
|
||
`ruoyi-train/pom.xml` 仅新增：
|
||
|
||
```xml
|
||
<dependency>
|
||
<groupId>junit</groupId>
|
||
<artifactId>junit</artifactId>
|
||
<version>4.13.2</version>
|
||
<scope>test</scope>
|
||
</dependency>
|
||
```
|
||
|
||
没有新增 Mockito、Spring Boot Test、H2 或生产 runtime 依赖。全部 14 个测试使用 JVM `InMemoryPlanService` Fake 和测试 Port，不 Mock JDBC、不连接也不写真实数据库：
|
||
|
||
| # | `@Test` 方法 | 验证规则 |
|
||
|---:|---|---|
|
||
| 1 | `createPlanShouldGenerateIdAndForceInitialStatus` | 32 位 `plan_id`、名称 trim、强制状态 0、审计人，并通过反射确认 Domain 无 `cId/tId` |
|
||
| 2 | `createPlanShouldRejectReversedOrEqualTime` | `start > end` 与 `start == end` 均返回 40010 |
|
||
| 3 | `createPlanShouldRejectReportDeadlineAfterStart` | 报到截止晚于开班返回 40010 |
|
||
| 4 | `createPlanShouldRejectDuplicatedName` | 名称 trim/忽略大小写预查重返回 40011 |
|
||
| 5 | `getPlanShouldReturnDetailAndRejectMissingPlan` | detail VO 映射及不存在返回 40410 |
|
||
| 6 | `getPlanShouldExposeInProgressStatusAfterStartTime` | 0→1 有效状态只读呈现，且持久化 Fake 中仍为 0，证明查询不回写 |
|
||
| 7 | `updatePlanShouldUpdateEditablePlan` | 状态 0/1 可编辑与审计更新 |
|
||
| 8 | `updatePlanShouldRejectCompletedOrCancelledPlan` | 状态 2、状态 3 分别禁止 edit，均返回 40012 |
|
||
| 9 | `completePlanShouldUpdateStatusAndInvokeEnrollmentBoundary` | Plan→2、Port 参数/次数及事务注解 |
|
||
| 10 | `completePlanShouldPropagateEnrollmentPortFailure` | Port 运行时异常保持原异常向事务代理传播；Fake 记录更新发生在 Port 调用前 |
|
||
| 11 | `completePlanShouldFailClosedWhenEnrollmentPortMissing` | 无 Port 时抛内部异常、状态更新调用为 0、Plan 保持状态 0 |
|
||
| 12 | `completePlanShouldRejectRepeatedCompletion` | 重复 complete 返回 40014，Port 不重复调用 |
|
||
| 13 | `completePlanShouldRejectMissingOrCancelledPlan` | 不存在返回 40410；状态 3 complete 返回 40012 |
|
||
| 14 | `listPlansShouldDelegatePlanQuery` | list 委托并返回 `PlanItemVO` |
|
||
|
||
该单元测试不能证明真实 Spring 事务回滚或 Enrollment SQL；这些证据属于 AC-03b 集成门禁。
|
||
|
||
## 10. Database 与权限影响
|
||
|
||
- 未执行 Generator Import；无 DDL、迁移、ALTER/CREATE/DROP。
|
||
- 未修改 `007_dicts.sql`、`sys_menu`、`sys_dict`、`sys_role`、`sys_role_menu`。
|
||
- 未写任何测试/正式业务数据；测试均为 JVM 内存数据。
|
||
- 后端权限严格为 `train:plan:list/query/add/edit/complete`；前端按钮只使用 `train:plan:add/edit/complete`，无 `system:plan:*`。
|
||
|
||
## 11. Acceptance Criteria
|
||
|
||
| AC | 状态 | 证据与边界 |
|
||
|---|---|---|
|
||
| AC-01 逆序日期返回 40010 | UNIT_PASS | 逆序和相等边界均覆盖。 |
|
||
| AC-02 状态 2 修改返回 40012 | UNIT_PASS | 同时覆盖历史状态 3。 |
|
||
| AC-03a Plan complete orchestration seam | UNIT_PASS | 状态更新、Port 一次调用、缺失 Port fail closed、异常传播及事务注解已验证。 |
|
||
| AC-03b 30 名 Enrollment 真实联动 | INTEGRATION_PENDING (ISSUE-03-01) | 未实现 Enrollment adapter/SQL，后续必须验证 status=4、complete_time 与跨表回滚。 |
|
||
| Integration Safety | UNIT_PASS | Port missing 时 update 调用为 0，Plan 不会单边持久化为 2。 |
|
||
|
||
## 12. 验证记录
|
||
|
||
- `mvn test -pl ruoyi-train -am -f RuoYi-Vue/pom.xml`：14 tests，0 failures，0 errors，0 skipped，`BUILD SUCCESS`。
|
||
- `mvn compile -DskipTests -f RuoYi-Vue/pom.xml`：8 个 Reactor 模块全部成功，`BUILD SUCCESS`。
|
||
- 评审指定 ESLint（主目录已安装 executable + `--resolve-plugins-relative-to`，工作目录仍为本 Issue worktree）：退出码 0，无 error/warning。
|
||
- `npm run build:prod`：build complete；仅有仓库既有 `src/views/graph/antv/index.vue` 的 `@antv/x6 Addon` warning，与本 Issue 文件无关。
|
||
- Final Review 本轮未修改任何前端文件；沿用上一轮 ESLint/build 结果。
|
||
- 最终 `git diff --check`、`git status --short`、`git diff --stat` 结果以交付回复为准。
|
||
- 未执行 commit/merge/rebase，等待技术负责人复审。
|