railwaysystem/docs/_meta/code-verification-checklist.md

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. 未实现/差异项：明确标出设计文档与当前代码不符的具体点，供架构师组织文档更新。