125 lines
9.2 KiB
Markdown
125 lines
9.2 KiB
Markdown
# RailwaySystem 阶段 B 代码级事实抽取核验任务书 (Code Verification Checklist)
|
||
> **任务性质：** 事实抽取任务书 (严格禁止预设主观猜测答案，所有结论必须从源码提取)
|
||
> **指派对象：** Codex Agent (或后端/前端代码专家)
|
||
> **制定人：** Documentation Architect
|
||
> **核验代码基线分支：** `integration/wave2-20260914`
|
||
> **基线 Commit (命令实测值)：** `196c6c47c70330119693f2ab7a6c35b8a22d5300` (短哈希 `196c6c47`)
|
||
> **工作区 HEAD：** `87322511c78e9109c7fe5af000d3db74b5c6cdfc`
|
||
> **核验目标：** 为编写各模块正式技术文档 (`docs/modules/*.md`) 提供 100% 取自源码的确定性事实支撑，杜绝文档与真实实现脱节。
|
||
|
||
---
|
||
|
||
## 一、核验规范与执行铁律
|
||
|
||
1. **事实抽取原则**：所有任务项均为“从代码提取真实事实”，Codex 回答时必须给出物理源码文件路径与具体代码行号。
|
||
2. **拒绝猜测与补齐**：若某特性在源码中尚未实现或属于历史遗留，如实记录为“代码未实现”或“遗留实现”，严禁脑补业务含义。
|
||
3. **标记规范**：
|
||
- 经源码确认的事实，标注为 `[CODE_VERIFIED]`。
|
||
- 依赖真实服务启动与浏览器交互的条目，标注为 `[RUNTIME_PENDING]`。
|
||
|
||
---
|
||
|
||
## 二、逐模块代码级事实抽取任务
|
||
|
||
### 1. 培训计划模块 (Plan)
|
||
- [ ] `[VERIFY_WITH_CODE]` **表结构与实体映射**：
|
||
- 从 `train_class_plan` 表 DDL、实体类 `TrainClassPlan.java` 及 `TrainClassPlanMapper.xml` 中提取全部字段列表，确认实体属性与数据库列的映射关系。
|
||
- [ ] `[VERIFY_WITH_CODE]` **Controller 路由与契约**：
|
||
- 从 `TrainPlanController.java` 中提取 `@RequestMapping` 基础路径。
|
||
- 提取列表查询、详情查询、创建计划、更新计划、结班操作的精确 URL 路径、HTTP Method、权限字符 (`@ss.hasPermi`) 与出入参对象类型。
|
||
- [ ] `[VERIFY_WITH_CODE]` **状态机枚举与状态迁移**：
|
||
- 从 `TrainClassPlan.java`、`PlanCreateDTO.java`、`PlanUpdateDTO.java`、`TrainPlanServiceImpl.java` 以及前端 `build_ui/src/views/train/plan/index.vue` 中提取 `plan_status` 全部真实枚举值。
|
||
- 提取代码中实际实现的计划状态迁移规则与拦截逻辑（包括前端何时锁定 `isPlanLocked`，后端在哪些状态下禁止修改或结班）。
|
||
|
||
### 2. 本期课程模块 (PlanCourse)
|
||
- [ ] `[VERIFY_WITH_CODE]` **Controller 路由与契约**：
|
||
- 从 `TrainPlanCourseController.java` 提取查询本期课程、新增本期课程、移除本期课程的真实 URL 路径、HTTP Method 与权限字符。
|
||
- [ ] `[VERIFY_WITH_CODE]` **业务规则与约束**：
|
||
- 从 `TrainPlanCourseServiceImpl.java` 中提取添加与移除本期课程时的前置校验逻辑（例如：计划状态校验、讲师指派校验、排课关联阻断校验）。
|
||
|
||
### 3. 参训人员管理 (Enrollment)
|
||
- [ ] `[VERIFY_WITH_CODE]` **sourceType 真实枚举核验**：
|
||
- 从 `EnrollmentAddDTO.java`、`EnrollmentCreateDTO.java`、`TrainEnrollment.java` 以及前端 `EnrollmentPanel.vue` 中三方核验 `source_type` 真实枚举值与字典定义（严禁使用任何主观猜测的字典定义）。
|
||
- [ ] `[VERIFY_WITH_CODE]` **Controller 路由与端点**：
|
||
- 从 `TrainEnrollmentController.java` 提取参训列表、单人报名、批量导入、详情查询、状态变更、移除参训的精确 URL、HTTP Method、入参 DTO 与出参 VO。
|
||
- [ ] `[VERIFY_WITH_CODE]` **学额与防重控制逻辑**：
|
||
- 从 `TrainEnrollmentServiceImpl.java` 中提取报名时关于计划容纳人数（学额超编校验）的实际处理代码，确认是硬性拦截抛异常还是记录提示。
|
||
- 提取重复报名时的数据库唯一约束与代码捕获处理逻辑。
|
||
|
||
### 4. 智能排课与课表 (Scheduling / Lesson)
|
||
- [ ] `[VERIFY_WITH_CODE]` **Controller 路由与端点**：
|
||
- 从 `TrainLessonController.java` 提取课次新增、课次编辑、课次删除、排课冲突预检、获取完整课表的精确 URL、HTTP Method 与入参出参模型。
|
||
- [ ] `[VERIFY_WITH_CODE]` **冲突检测维度与 Soft Warning 交互**：
|
||
- 从 `TrainLessonServiceImpl.java` 的 `checkLessonConflict` 方法中提取当前实现的全部冲突检测维度（核验是否存在 `TEACHER`, `CLASSROOM`, `SITE`, `PLAN_OVERLAP` 语义）。
|
||
- 提取冲突判定的时间区间数学/逻辑算法代码。
|
||
- 从 `TimetablePanel.vue` 与 `TrainLessonController.java` 中提取排课保存时若检测到冲突的处理流程，确认管理员确认后是否允许保存（Soft Warning 语义确认）。
|
||
|
||
### 5. 学员基础档案 (Student)
|
||
- [ ] `[VERIFY_WITH_CODE]` **Controller 路由与端点**：
|
||
- 从 `TrainStudentController.java` 提取列表、详情、新增的真实 URL 路径、HTTP Method 与参数绑定形式。
|
||
- [ ] `[VERIFY_WITH_CODE]` **隐私脱敏与校验事实**：
|
||
- 从 `TrainStudent.java`、`StudentDetailVO.java`、`StudentItemVO.java` 中提取身份证号 (`id_card`) 与手机号 (`phonenumber`) 的脱敏实现位置（后端注解脱敏、Service 处理或前端脱敏）。
|
||
- 从 DTO 与校验类中提取身份证有效性校验的具体实现方式。
|
||
|
||
### 6. 师资主数据管理 (Teacher)
|
||
- [ ] `[VERIFY_WITH_CODE]` **Controller 路由与字段**：
|
||
- 从 `TrainTeacherController.java`、`TrainTeacher.java` 提取实际端点、HTTP Method、权限字符以及教师资质/职称/内外聘标识字段。
|
||
|
||
### 7. 课程库资源管理 (Course)
|
||
- [ ] `[VERIFY_WITH_CODE]` **Controller 路由与端点状态**：
|
||
- 从 `TrainCourseController.java` 提取列表、详情、新增、修改端点的真实实现情况（核验 `PUT /train/course/{cId}` 是否已落地）。
|
||
- 提取课程学时换算与统一资源解耦关系的实现事实。
|
||
|
||
### 8. 普通教室资源 (Classroom)
|
||
- [ ] `[VERIFY_WITH_CODE]` **Controller 路由与端点状态**：
|
||
- 从 `TrainClassroomInfoController.java` 提取列表、详情、新增、修改端点的真实实现情况（核验 `PUT /train/classroom/{classRoomId}` 是否已落地）。
|
||
- 提取教室座位容量、教学楼属性字段。
|
||
|
||
### 9. 铁路实训场地 (TrainingSite)
|
||
- [ ] `[VERIFY_WITH_CODE]` **Controller 路由与特种属性**：
|
||
- 从 `TrainTrainingSiteController.java` 提取全部实际端点、HTTP Method 及权限字符。
|
||
- 从实体和数据库提取实训场地类型、安全规程等特有字段。
|
||
|
||
### 10. 宿舍楼宇与房态 (Dormitory)
|
||
- [ ] `[VERIFY_WITH_CODE]` **Controller 路由与房态计算**：
|
||
- 从 `TrainDormitoryInfoController.java` 提取列表、详情、新增、房态选项等端点。
|
||
- 从 DDL、Mapper 及 Service 中核实数据库是否存在独立床位表（确认是否为楼宇/房间两级无独立床位表架构），提取已住人数与可用床位的代码计算逻辑。
|
||
|
||
### 11. 电子班牌模块 (ElectronicBoard)
|
||
- [ ] `[VERIFY_WITH_CODE]` **外设绑定范围核验**：
|
||
- 从 `TrainElectronicBoard.java`、`TrainElectronicBoardMapper.xml` 及 DDL 中提取班牌外键关联字段，确认当前代码是否仅实现 `bind_classroom_id`，核验当前是否支持实训场地 (`site_id`) 绑定。
|
||
- [ ] `[VERIFY_WITH_CODE]` **Controller 路由与权限字符**：
|
||
- 从 `TrainElectronicBoardController.java` 提取当前端点列表与实际声明的权限字符（核验是 `train:board:*` 还是 `system:board:*`）。
|
||
|
||
---
|
||
|
||
## 三、系统级架构与集成事实抽取任务
|
||
|
||
### 1. 全局异常与业务错误码核验
|
||
- [ ] `[VERIFY_WITH_CODE]` **真实错误码抽取**：
|
||
- 检索代码中所有抛出业务异常的位置（`throw new ServiceException(...)`），提取实际使用的错误码数值与提示文本。
|
||
- 核查代码中实际抛出的错误码是否落在 `10000~59999` 规划区间内，统计是否存在未声明业务错误码直接裸抛的情况。
|
||
|
||
### 2. 权限字符与数据库菜单配置核验
|
||
- [ ] `[VERIFY_WITH_CODE]` **权限字符清单抽取**：
|
||
- 汇总提取所有 Train 相关 Controller 上的 `@ss.hasPermi` 权限字符串。
|
||
- 从数据库初始化 SQL（如 `ry_20250522.sql`、`007_dicts.sql`）或 `sys_menu` 表结构中，核验上述权限字符是否已配置对应菜单记录。
|
||
|
||
### 3. CI/CD 流水线事实核验
|
||
- [ ] `[VERIFY_WITH_CODE]` **GitLab CI/CD 配置抽取**：
|
||
- 从仓库根目录的 `.gitlab-ci.yml` 配置文件中，提取实际配置的流水线阶段 (stages)、各任务作业 (jobs)、构建镜像、编译指令与静态检查规则（杜绝出现 GitHub Actions 相关表述）。
|
||
|
||
### 4. 运行时与环境配置核验
|
||
- [ ] `[RUNTIME_PENDING]` **服务端口与运行实测**：
|
||
- 从 `application.yml`、`application-druid.yml` 以及前端 `vue.config.js` / `.env.development` 中提取配置的默认端口与上下文路径。
|
||
- 实际监听端口、真实数据库连接地址以及前端访问入口，统一标记为 `RUNTIME_PENDING`，以 Final Runtime Gate 最终实测报告为准。
|
||
|
||
---
|
||
|
||
## 四、Codex 产出规范
|
||
|
||
Codex 执行完毕后，应输出纯粹的事实结果报告（建议存为 `docs/_meta/code-verification-results.md`），格式规范：
|
||
1. **代码事实条目**：标明文件路径与行号区间。
|
||
2. **事实结论**：不加主观修饰的真实代码逻辑与枚举值。
|
||
3. **未实现/差异项**：明确标出设计文档与当前代码不符的具体点，供架构师组织文档更新。
|