diff --git a/.gitignore b/.gitignore index 72e655aa0..e34d2c934 100644 --- a/.gitignore +++ b/.gitignore @@ -38,3 +38,17 @@ uploadPath/ .idea/ *.iml .vscode/ + +# 测试探针与浏览器自动化临时产物 +.playwright-mcp/ +**/.playwright-mcp/ + +# Python 缓存与临时文件 +__pycache__/ +**/__pycache__/ +*.py[cod] +*$py.class + +# 临时备份文件 +*.tmp +*.bak diff --git a/README.md b/README.md index dafc4023c..2d378da54 100644 --- a/README.md +++ b/README.md @@ -10,8 +10,8 @@ RailwaySystem 是一套面向铁路职工与业务学员的一站式智慧培训 | 文档中心 | 目录入口 | 核心重点内容 | 适用角色 | | :--- | :--- | :--- | :--- | -| **业务与产品需求中心** | [doc/README.md](file:///Users/wzb/Desktop/项目/RailwaySystem/doc/README.md) | ★★★ [PRD V1.0 业务需求基线](file:///Users/wzb/Desktop/项目/RailwaySystem/doc/RailwaySystem 智慧培训系统一期 PRD V1.0.md)（正式冻结基线，32章全景规范）、原始甲供资料、历史版本演进 | 产品经理、业务方、测试、全栈开发 | -| **技术架构与系统审计中心** | [docs/README.md](file:///Users/wzb/Desktop/项目/RailwaySystem/docs/README.md) | ★★★ [Phase 0 真实基线与审计总结](file:///Users/wzb/Desktop/项目/RailwaySystem/docs/codebase-audit/17_phase0_summary.md)、18 篇全景代码与数据库实测快照报告 | 架构师、后端研发、前端研发、DBA | +| **业务与产品需求中心** | [doc/README.md](doc/README.md) | ★★★ [PRD V1.0 业务需求基线](doc/RailwaySystem%20智慧培训系统一期%20PRD%20V1.0.md)（正式冻结基线，32章全景规范）、原始甲供资料、历史版本演进 | 产品经理、业务方、测试、全栈开发 | +| **技术架构与系统审计中心** | [docs/README.md](docs/README.md) | ★★★ [Phase 0 真实基线与审计总结](docs/codebase-audit/17_phase0_summary.md)、18 篇全景代码与数据库实测快照报告 | 架构师、后端研发、前端研发、DBA | --- @@ -35,7 +35,7 @@ RailwaySystem 是一套面向铁路职工与业务学员的一站式智慧培训 ### 2. 一键启动（推荐） -项目根目录下已提供一键启动脚本 [start-local.sh](file:///Users/wzb/Desktop/项目/RailwaySystem/start-local.sh)： +项目根目录下已提供一键启动脚本 [start-local.sh](start-local.sh)： ```bash cd /Users/wzb/Desktop/项目/RailwaySystem @@ -67,18 +67,19 @@ RailwaySystem/ │ ├── ruoyi-admin/ # Web 启动入口与 Controller 接口层 │ ├── ruoyi-framework/ # 框架核心配置、WebSecurity 与拦截器 │ ├── ruoyi-system/ # 核心业务模块（含培训管理业务 Entity/Mapper/Service） -│ └── ruoyi-common/ # 公共常量、工具类与通用组件 -├── build_ui/ # 前端工程（Vue 2 + Element UI） +│ ├── ruoyi-common/ # 公共常量、工具类与通用组件 +│ └── ruoyi-ui/ # 若依原始/历史前端资产（不作为当前 Final Browser Acceptance 主构建源） +├── build_ui/ # 当前 Final Candidate 实际构建和部署使用的 Vue 前端工程 │ ├── src/api/ # 前端 Axios 接口层（含 train 培训业务接口） -│ ├── src/views/train/ # 培训业务页面视图（学员、排课、宿舍、成绩等） -│ └── package.json # 前端依赖配置 +│ ├── src/views/train/ # 培训业务页面视图（学员、排课、宿舍、考勤等） +│ └── package.json # 前端依赖与 Webpack 构建配置 ├── doc/ # 业务与产品需求中心（PRD V1.0、原始资料与归档） -└── docs/ # 技术架构与代码审计中心（18 篇深度审计与快照） +└── docs/ # 技术架构、发布门禁与代码审计中心（包含 V2 架构、API/DB 规范与验收证据） ``` --- ## 📌 开发与演进原则 -1. **业务基线不可逆**：任何新页面开发、字段扩充与业务校验，统一以 [PRD V1.0](file:///Users/wzb/Desktop/项目/RailwaySystem/doc/RailwaySystem 智慧培训系统一期 PRD V1.0.md) 为唯一依据，旧版草案已全部归档。 +1. **业务基线不可逆**：任何新页面开发、字段扩充与业务校验，统一以 [PRD V1.0](doc/RailwaySystem%20智慧培训系统一期%20PRD%20V1.0.md) 为唯一依据，旧版草案已全部归档。 2. **非破坏性演进**：对 Kingbase 数据库与若依权限系统进行改造时，严格遵循技术审计报告结论，保持历史数据安全与可回滚性。 diff --git a/docs/_meta/code-verification-checklist.md b/docs/_meta/code-verification-checklist.md new file mode 100644 index 000000000..facb0edbf --- /dev/null +++ b/docs/_meta/code-verification-checklist.md @@ -0,0 +1,124 @@ +# 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. **未实现/差异项**：明确标出设计文档与当前代码不符的具体点，供架构师组织文档更新。 diff --git a/docs/_meta/deployment-gate-checklist.md b/docs/_meta/deployment-gate-checklist.md new file mode 100644 index 000000000..b82af0636 --- /dev/null +++ b/docs/_meta/deployment-gate-checklist.md @@ -0,0 +1,122 @@ +# RailwaySystem 最终部署门禁与运行时验收清单 (Deployment Gate Checklist) + +> **当前正式开发基线：** `integration/wave2-20260914` +> **当前 Integration HEAD：** `d162954cd1e26c6948408a8304ca333ba9fe7a40` +> **最终发布版本 HEAD 标记：** `FINAL_HEAD_PENDING` +> **目标发布分支：** `origin/feat/cicd-pipeline` +> **部署目标环境：** 服务器别名 `sict`，根目录 `/data2/wzb/deploy`，后端 `8092`，前端 `8082` +> **使用说明：** 本清单规范了发布前门禁、标准化部署动作序列、基于精准三态判定的运行时验收，以及基于归档制品的应急回滚方案。 + +--- + +## 一、发布前门禁 (Pre-Deployment Gates) + +### Gate 1: Git 版本与基线门禁 +- [ ] **G1.1 分支合并状态确认**：确认 `origin/feat/cicd-pipeline` 目前落后当前基线 2 个 commit（`e2d7e63d`, `d162954c`）。最终发版提交标注为 `FINAL_HEAD_PENDING`，待所有并行任务（Legacy Analytics V2 Contract 与 Business Scenario Test Pack）并入后统一核准。 +- [ ] **G1.2 仓库状态审查**：保持本地工作区未残留临时变更，**HOLD COMMIT**，未获发版审批前严禁随意提交。 +- [ ] **G1.3 远端推送许可确认**：严格遵守发版纪律，保持 **DO NOT PUSH**。 + +### Gate 2: 数据库 Migration 分类与增量门禁 +- [ ] **G2.1 目标库 Schema 版本判定**：在执行部署前，首先判定目标库是否已处于 V2 基线。 + - **若目标库已是 V2 基线：** **仅需且仅允许执行当前 Release Delta migration**（`RuoYi-Vue/sql/system/kingbase/001_sys_oper_log_cost_time.sql`）。 + - **历史 V2 脚本隔离：** 历史 V2 脚本（`sql/train/v2/*` 及 `sql/generator/kingbase/*`）已从常规发布执行清单中移除，**严禁在已有 V2 库上重复执行**历史备份、重建与删表操作。 +- [ ] **G2.2 `001_sys_oper_log_cost_time.sql` 准备度**：确认目标库已执行补齐 `cost_time` 字段；若未补齐，后端启动前必须执行（具备 `IF NOT EXISTS` 幂等保护）。 +- [ ] **G2.3 零破坏纪律**：**严禁执行 `007_dicts.sql` (DO NOT EXECUTE)**；严禁执行任何 DROP TABLE 操作。 + +### Gate 3: CI/CD 构建与依赖门禁 +- [ ] **G3.1 Kingbase JDBC 8.6.0 Preflight**： + - 依赖文件：`${HOME}/.m2/repository/com/kingbase/kingbase8/8.6.0/kingbase8-8.6.0.jar` + - SHA256 强校验：`346d5602477ed472b19c5e25729fff5a58b1d83cec56162a56ac4b86d9546c32` 匹配无误。 +- [ ] **G3.2 后端编译与打包**：`mvn clean package` 成功，生成 `RuoYi-Vue/ruoyi-admin/target/ruoyi-admin.jar`。 +- [ ] **G3.3 前端构建**：`npm run build:prod` 成功，生成 `build_ui/dist/`。 +- [ ] **G3.4 运行时安全环境变量就绪**： + - 导出 `TRAIN_STUDENT_IDENTITY_ENCRYPTION_KEY` + - 导出 `TRAIN_STUDENT_IDENTITY_HASH_KEY` + - 导出 `SPRING_REDIS_PASSWORD` + +--- + +## 二、标准化部署执行步骤 (Deployment Steps) + +| 步骤编号 | 操作名称 | 责任操作与说明 | 验证方法 | +| :---: | :--- | :--- | :--- | +| **`DEPLOY_STEP_01`** | **环境与凭据预检** | 确认目标机 `sict` 上 JDK 8、Maven、Nginx 可用，三大敏感环境变量已导出 | 执行 `echo` 检查变量存在且非空 | +| **`DEPLOY_STEP_02`** | **Schema 判定与 Delta 补丁** | 判定目标库当前 Schema 版本。**若已是 V2，仅执行当前 Release Delta migration (`001_sys_oper_log_cost_time.sql`)**；严禁重跑历史 V2 脚本 | 确认 `sys_oper_log.cost_time` 存在 | +| **`DEPLOY_STEP_03`** | **现网制品备份** | 备份已有后端 Jar 与前端静态文件：
`cp ruoyi-admin.jar ruoyi-admin.jar.bak`
`cp -r frontend frontend.bak` | 检查备份文件生成成功 | +| **`DEPLOY_STEP_04`** | **CI 构建物拉取/生成** | 运行流水线或获取当前版本产物 `ruoyi-admin.jar` 与 `dist/` | 校验产物 MD5/SHA256 与构建日志 | +| **`DEPLOY_STEP_05`** | **前端静态资源更新** | 清理并覆盖部署：
`rm -rf /data2/wzb/deploy/frontend/*`
`cp -r build_ui/dist/* /data2/wzb/deploy/frontend/` | 确认 `frontend/index.html` 存在 | +| **`DEPLOY_STEP_06`** | **后端 Jar 包发布** | 将新构建 Jar 拷贝到发布目录：
`cp ruoyi-admin.jar /data2/wzb/deploy/backend/` | 确认物理文件更新且大小正常 | +| **`DEPLOY_STEP_07`** | **执行平滑重启调度** | 赋予权限并调用统一调度脚本：
`chmod +x deploy/restart-all.sh && bash deploy/restart-all.sh` | 脚本流程不抛出语法或环境异常 | +| **`DEPLOY_STEP_08`** | **后端进程平滑切换** | 脚本向旧进程发送 `kill -15`，超时发送 `kill -9`；以端口 `8092` 启动新进程并记录 `app.pid` | `ps -ef \| grep ruoyi-admin.jar` 确认新 PID | +| **`DEPLOY_STEP_09`** | **健康自检探针断言** | 脚本自动轮询 `http://127.0.0.1:8092/captchaImage`（最多 35 次，每 2s 一次），断言返回 `"code":200` | 脚本输出 `后端健康检查通过！` | +| **`DEPLOY_STEP_10`** | **前端 Nginx 平滑重载** | 验证 `/data2/wzb/deploy/nginx/nginx.conf` 语法，执行 `nginx -s reload` 或拉起服务 | 检查端口 8082 处于 LISTEN 状态 | + +--- + +## 三、部署后运行时验收清单 (Runtime Verification Checklist) + +> **审计状态规范说明：** +> - `VERIFIED_ON_CURRENT_HEAD`: 在当前 Integration HEAD (`d162954c`) 上重新执行并通过验收的项； +> - `PREVIOUSLY_VERIFIED_ON_PRIOR_RC`: 在先前发布版本/分支上已完成真实执行验证，但当前 HEAD 尚未重新运行部署验收的项； +> - `PENDING_FINAL_GATE`: 等待最终集成发版门禁在完整部署后执行验收的项； +> - `PENDING_CODEX`: 依赖并行 Codex Agent 交付的专项模块。 + +### 1. 基础连通性与平台 API +| 验收编号 | 检验项 | 验证端点 / 方式 | 当前状态判定 | 状态说明 | +| :---: | :--- | :--- | :---: | :--- | +| **RTC-01** | Backend Health | `GET http://127.0.0.1:8092/captchaImage` | **PREVIOUSLY_VERIFIED_ON_PRIOR_RC** | 先前发布版本自检通过，当前 HEAD 待最终部署验证 | +| **RTC-02** | Kingbase Connectivity | 启动连接池与元数据读取 | **PREVIOUSLY_VERIFIED_ON_PRIOR_RC** | 历史实测通过，当前 HEAD 待最终部署验证 | +| **RTC-03** | Redis Connectivity | Captcha 缓存与 Token 存取 | **PREVIOUSLY_VERIFIED_ON_PRIOR_RC** | 历史实测通过，当前 HEAD 待最终部署验证 | +| **RTC-04** | User Login | `POST /prod-api/login` | **PREVIOUSLY_VERIFIED_ON_PRIOR_RC** | 历史实测通过，当前 HEAD 待最终部署验证 | +| **RTC-05** | OperLog 耗时字段查询 | `GET /prod-api/monitor/operlog/list` | **PREVIOUSLY_VERIFIED / DB_FIX_VALIDATED** | `cost_time` 补丁在测试库实测通过，当前 integration 待部署验证 | + +### 2. Wave 2 业务模块核心验收 (纠正 UI 入口与 API 路由) +| 验收编号 | 业务模块 | 正确 UI 入口导航 | 对应核心 API 契约 | 当前状态判定 | +| :---: | :--- | :--- | :--- | :---: | +| **RTC-06** | **培训计划 (Plan)** | 课程管理 → 开班计划 | `/train/plan/*` | **PENDING_FINAL_GATE** | +| **RTC-07** | **参训人员 (Enrollment)** | 课程管理 → 开班计划 → 参训人员 (内部Tab) | `POST/GET /train/plans/{planId}/enrollments...` | **PENDING_FINAL_GATE** | +| **RTC-08** | **排课课表 (Scheduling)** | 课程管理 → 开班计划 → 排课课表 (内部Tab) | `/train/lessons/*`
`/train/plans/{planId}/timetable` | **PENDING_FINAL_GATE** | +| **RTC-09** | **电子班牌 (Board)** | 设施设备 → 电子班牌 (**正式路径: `/train/board`**) | `/train/board/*` | **PENDING_FINAL_GATE** | + +### 3. Legacy Analytics 分析模块 (并行交付项) +| 验收编号 | 业务模块 | UI 路由入口 | 当前状态判定 | 说明 | +| :---: | :--- | :--- | :---: | :--- | +| **RTC-10** | 培训总评分析 (Class Report) | 教学评估 → 培训总评分析 (`/analysis/report`) | **PENDING_CODEX** | 等待 Codex Agent 交付 V2 契约 | +| **RTC-11** | 学员打卡记录 (Student Checkin) | 考勤与打卡 → 学员打卡记录 (`/analysis/checkin`) | **PENDING_CODEX** | 等待 Codex Agent 交付 V2 契约 | +| **RTC-12** | 学习时长统计 (Study Duration) | 学习监控 → 学习时长统计 (`/analysis/duration`) | **PENDING_CODEX** | 等待 Codex Agent 交付 V2 契约 | +| **RTC-13** | 学员画像分析 (Student Portrait) | 学员画像 → 画像分析 (`/portrait`) | **PENDING_CODEX** | 等待 Codex Agent 交付 V2 契约 | + +### 4. 综合体验与全站质量门禁 +| 验收编号 | 检验项 | 验证内容 | 当前状态判定 | +| :---: | :--- | :--- | :---: | +| **RTC-14** | Frontend Entry 8082 | 访问 `http://192.168.139.230:8082`，前端路由与静态资源无 404 | **PENDING_FINAL_GATE** | +| **RTC-15** | 全站 Network 500 = 0 | 完整业务端到端流转中，网络请求 **500 报错数量严格为 0** | **PENDING_FINAL_GATE** | + +--- + +## 四、回滚预案与应急处置 (Rollback Gate) + +### 1. 触发条件 +- 部署后 `/captchaImage` 健康自检连续 35 次超时失败； +- 系统日志或核心功能持续出现 HTTP 500 异常； +- 出现严重影响主业务的未预期缺陷。 + +### 2. 执行回滚操作规范 +- **严禁通过重新执行旧 V2 脚本来进行回滚**； +- 统一使用**上一个已归档制品**执行回退： + ```bash + # 1. 恢复后端稳定 Jar + cp /data2/wzb/deploy/backend/ruoyi-admin.jar.bak /data2/wzb/deploy/backend/ruoyi-admin.jar + + # 2. 恢复前端稳定静态资源 + rm -rf /data2/wzb/deploy/frontend/* + cp -r /data2/wzb/deploy/frontend.bak/* /data2/wzb/deploy/frontend/ + + # 3. 触发平滑重启脚本 + bash /data2/wzb/deploy/restart-all.sh + ``` + +### 3. 数据库 Migration 回滚安全准则 +- `001_sys_oper_log_cost_time.sql` 属于**向前兼容（Backward-Compatible）**字段； +- 旧版本后端代码在不读取该字段的情况下完全可以正常运行； +- **回滚代码时严禁对数据库执行 `ALTER TABLE ... DROP COLUMN cost_time`**，以避免锁表与元数据不可逆破坏。 diff --git a/docs/_meta/document-audit-draft.md b/docs/_meta/document-audit-draft.md new file mode 100644 index 000000000..fbfe9cf4c --- /dev/null +++ b/docs/_meta/document-audit-draft.md @@ -0,0 +1,215 @@ +# RailwaySystem 文档信息架构审计草案 (Document Audit Draft) - Phase A.1 CORRECTION +> **状态：** DRAFT / RUNTIME_PENDING (Phase A.1 修正输出，禁止 git add) +> **审计基线分支：** `integration/wave2-20260914` +> **基线 Commit (命令实测值)：** `196c6c47c70330119693f2ab7a6c35b8a22d5300` (短哈希 `196c6c47`) +> **工作区 HEAD：** `87322511c78e9109c7fe5af000d3db74b5c6cdfc` +> **审计人：** Documentation Architect +> **核心原则：** +> 1. **严禁主观推断**：Documentation Architect 是信息架构师，不是代码事实裁判。凡未经 Integration 源码直接确认的枚举、字段、状态、不变量与端口，一律不得写成确定事实。 +> 2. **事实置信度分离**：全量文档按 `Fact Confidence` 严格区分事实来源与可靠程度。 +> 3. **环境依赖标记**：凡依赖真实服务运行、网络通信与界面渲染的内容，一律标记为 `RUNTIME_PENDING`。 + +--- + +## 一、审计概览与统计指标 + +本轮对 `docs/` 目录下全部 **68** 份技术文档、设计草案、评审纪要及开发验收报告进行了逐一深入审计（涵盖 67 份基线跟踪文档与 1 份未跟踪本地会话记录）。 + +### 1. 动作推荐汇总统计 (已彻底复审原 KEEP 分类) +| 推荐动作 (Recommended Action) | 文件数量 | 占比 | 核心定义与处理说明 | +|:---|:---:|:---:|:---| +| **KEEP** | **0** | **0.0%** | **经严格核验，原 8 篇 KEEP 文档均包含旧状态、旧 API、旧不变量或未落地设计，无法满足“100% 符合当前代码事实”的标准，已全数重分类，无原样保留项。** | +| **UPDATE_FROM_CODE** | 4 | 5.9% | 核心技术规范骨架有效，但存在旧接口示例、旧分层或旧不变量（如 Scheduling 需补充 Soft Warning 语义），需根据代码事实就地重构更新。 | +| **UPDATE_AFTER_RUNTIME** | 5 | 7.3% | 强依赖真实运行环境。包括环境实操手册、全局入口、权限与错误码终态核查、端到端验收矩阵与风险登记册，待 Final Runtime Gate 终态冻结后更新。 | +| **MERGE** | 21 | 30.9% | 文档所含工程事实与业务规则具有长期参考价值，但分散在零散文件或跨域混杂，提炼其高价值事实并入各 Module 文档或系统 Handbook。 | +| **ARCHIVE** | 35 | 51.5% | 历史阶段性过程产物。包括 Phase 0 遗留代码快照、中间审查报告、数据库迁移阶段流水、会话 log 等，统一移入 `docs/archive/` 永久备查。 | +| **REVIEW_REQUIRED** | 3 | 4.4% | 涉及硬件外设防腐适配器、成绩/学时遗留代码或打卡考勤范围，与当前代码存在较大落差，需交由 Codex 与架构师核验决策。 | +| **GENERATED** | 0 | 0.0% | 现有存量文档均为手工维护 Markdown，规划未来由 CI/CD 自动生成的文档标记为该类型。 | +| **合计** | **68** | **100.0%** | — | + +### 2. 事实置信度分布统计 (Fact Confidence) +- `CODE_VERIFIED`：**0**（作为 Phase A.1 文档审计，未经 Codex 专项任务书逐行核验前，存量文档不擅自赋予代码完全验证标签） +- `DOC_ONLY`：**11**（设计期提出的契约与规范，需结合代码求证） +- `RUNTIME_PENDING`：**5**（强依赖运行时环境与实测数据） +- `HISTORICAL`：**47**（历史过程记录、审查报告、迁移验证流水、前期快照） +- `VERIFY_WITH_CODE`：**5**（在当前代码中有对应实现，但细节状态与枚举必须经 Codex 深度核验） + +--- + +## 二、全量 68 份文档逐项审计明细表 + +> **分类映射定义（12大类）：** +> 1. `Product / Business` | 2. `Architecture` | 3. `API / Contract` | 4. `Database` | 5. `Frontend` | 6. `Security / Permission` +> 7. `Runtime / Deployment` | 8. `Testing / Release` | 9. `Module Documentation` | 10. `Historical Development Record` +> 11. `Database Migration Asset` | 12. `Generated Human Documentation` +> +> **Fact Confidence 取值定义：** +> `CODE_VERIFIED` \| `DOC_ONLY` \| `RUNTIME_PENDING` \| `HISTORICAL` \| `VERIFY_WITH_CODE` + +| 序号 | 路径 (Path) | 标题 (Title) | 分类 (Category) | 时态 (Temporal) | 事实置信度 (Fact Confidence) | 重复/重叠文档 | 建议动作 (Action) | 处置理由与重构建议 (Reason) | +|:---:|:---|:---|:---|:---:|:---:|:---|:---:|:---| +| 1 | `docs/README.md` | RailwaySystem 技术架构与代码审计中心（docs） | 2. Architecture | history | `RUNTIME_PENDING` | 无 | **UPDATE_AFTER_RUNTIME** | 仅记录 Phase 0 审计目录，严重滞后。需待 Runtime 终态与信息架构重组完成后重写为全局总入口。 | +| 2 | `docs/conversation_record.md` | RailwaySystem 会话全流程记录归档 | 10. Historical Development Record | history | `HISTORICAL` | `generator-v2/01`, `development/issue-01-03` | **ARCHIVE** | 记录特定调试会话的流水账，属过程追溯材料，归入 `archive/conversations/`。 | +| 3 | `docs/api-v2/00_readme.md` | Phase 2：API Contract / DTO-VO / Service Boundary Design | 3. API / Contract | current | `DOC_ONLY` | `01`~`10` 章节总述 | **MERGE** | 作为 API 契约总纲，核心规范与目录架构提炼合并入 `handbook/api/api-overview.md`。 | +| 4 | `docs/api-v2/01_api_design_principles.md` | RailwaySystem API 设计原则与规范 | 3. API / Contract | current | `VERIFY_WITH_CODE` | 无 | **UPDATE_FROM_CODE** | 原标记 KEEP。核查发现文中包含未实现的 Command API 示例，需从代码核验后修正示例。 | +| 5 | `docs/api-v2/02_module_a_base_resource_api.md` | Module A：人员与基础资源 API 契约 | 3. API / Contract | current | `VERIFY_WITH_CODE` | 各基础模块开发验收文档 | **MERGE** | 揉杂 5 个基础业务域，违反高内聚。应提炼并分别合并入各独立 `docs/modules/*.md`。 | +| 6 | `docs/api-v2/03_module_b_plan_enrollment_schedule_api.md` | Module B：开班计划与排课 API 契约 | 3. API / Contract | current | `VERIFY_WITH_CODE` | `development/issue-02-01`, `issue-02-02` | **MERGE** | 核心主链路契约。应按业务域拆解合并入 Plan, PlanCourse, Enrollment, Scheduling, Board 模块。 | +| 7 | `docs/api-v2/04_module_c_accommodation_attendance_api.md` | Module C：住宿 / 门禁 / 考勤 API 契约 | 3. API / Contract | review | `DOC_ONLY` | 遗留打卡 Controller | **REVIEW_REQUIRED** | 混杂门禁授权与外设打卡，需 Codex 核验当前代码实际落地端点与 mock 机制。 | +| 8 | `docs/api-v2/05_module_d_score_learning_statistics_api.md` | Module D：成绩 / 学习 / 统计 / 画像 API 契约 | 3. API / Contract | review | `DOC_ONLY` | 遗留 Controller 代码 | **REVIEW_REQUIRED** | 所列端点多为遗留若依旧版实现或 P1 规划，与当前 Wave 2 存在落差，需 Codex 核查实际可用性。 | +| 9 | `docs/api-v2/06_dto_vo_catalog.md` | RailwaySystem DTO / VO 领域模型目录与字段规范 | 3. API / Contract | current | `VERIFY_WITH_CODE` | 后端代码中的 DTO/VO 类 | **MERGE** | 集中定义了核心模型，但难独立维护。通用规约并入 Handbook，具体字段拆入各模块文档。 | +| 10 | `docs/api-v2/07_service_boundary.md` | RailwaySystem Service 聚合边界与模块责任划分 | 2. Architecture | current | `DOC_ONLY` | 无 | **UPDATE_FROM_CODE** | 原标记 KEEP。经查文中设计的独立 ApplicationService 分层与当前多包单体实际结构不一致，需依代码重构。 | +| 11 | `docs/api-v2/08_transaction_and_invariants.md` | RailwaySystem 事务边界与业务不变量设计 | 2. Architecture | current | `DOC_ONLY` | 无 | **UPDATE_FROM_CODE** | 原标记 KEEP。旧“排课无重叠”硬不变量与当前 Warning 语义冲突，必须从代码核验后重写。 | +| 12 | `docs/api-v2/09_external_adapter_contract.md` | 外部系统适配器契约设计 (Integration Contract) | 2. Architecture | current | `DOC_ONLY` | 无 | **REVIEW_REQUIRED** | 原标记 KEEP。文中人脸与门禁 SPI 接口在代码中未落地，属设计资产，需架构师核验后定位。 | +| 13 | `docs/api-v2/10_permission_and_error_codes.md` | 权限字符与业务错误码规范 | 6. Security / Permission | review | `RUNTIME_PENDING` | 数据库 sys_menu 及异常类 | **UPDATE_AFTER_RUNTIME** | 错误码与权限规范良好，但必须经由 Runtime 实测与 Codex 逐行核实真实抛出错误码后定稿。 | +| 14 | `docs/api-v2/11_open_questions.md` | 现场验证问题映射与 API 应对策略 (Open Questions) | 1. Product / Business | history | `HISTORICAL` | 各模块业务规则 | **ARCHIVE** | 早期现场需求调研备忘录，其有效结论已固化至设计契约中，原件归入 `archive/`。 | +| 15 | `docs/api-v2/12_contract_review_round1.md` | Phase 2 Contract Review Round 1 审查报告 | 8. Testing / Release | history | `HISTORICAL` | `api-v2/13` 补丁 | **ARCHIVE** | 里程碑评审会议纪要，结论已通过 V1.0.1 补丁闭环，归档作为过程质保资产。 | +| 16 | `docs/api-v2/13_contract_patch_v1.0.1.md` | API Contract V1.0.1 Patch 说明 | 3. API / Contract | current | `DOC_ONLY` | `api-v2/00`, `02`, `06` | **MERGE** | 记录了 CG-01~CG-04 修正，其技术事实合并入各模块文档后，补丁说明归档。 | +| 17 | `docs/codebase-audit/00_project_overview.md` | 代码基线审计：项目概览 | 2. Architecture | history | `HISTORICAL` | 系统全景 | **ARCHIVE** | Phase 0 历史概览，基于遗留工程快照，归入 `archive/phase0-audit/`。 | +| 18 | `docs/codebase-audit/01_project_tree.md` | 简化项目树 | 2. Architecture | history | `HISTORICAL` | `handbook/architecture/` | **ARCHIVE** | Phase 0 单体工程目录树快照，已被当前多包结构取代，归档。 | +| 19 | `docs/codebase-audit/02_training_modules_inventory.md` | 培训业务模块与 14 组 CRUD 盘点 | 1. Product / Business | history | `HISTORICAL` | 各模块业务背景 | **MERGE** | 包含对旧 14 张培训业务表的业务逻辑剖析，有价值的背景提炼入 Handbook，原件归档。 | +| 20 | `docs/codebase-audit/03_database_current_state.md` | 数据库当前状态 (Phase 0) | 4. Database | history | `HISTORICAL` | `database-v2/` 体系 | **ARCHIVE** | 记录旧库 73 张表历史结构，已被 Database V2 物理迁移彻底取代，归档。 | +| 21 | `docs/codebase-audit/04_api_inventory.md` | 培训接口盘点 (Phase 0) | 3. API / Contract | history | `HISTORICAL` | `api-v2/` 体系 | **ARCHIVE** | 旧若依无契约 CRUD 接口清单，已被全面重构，归档。 | +| 22 | `docs/codebase-audit/05_frontend_inventory.md` | 培训前端现状 (Phase 0) | 5. Frontend | history | `HISTORICAL` | `build_ui/` 现有视图 | **ARCHIVE** | Phase 0 前端遗留视图快照，归入归档目录。 | +| 23 | `docs/codebase-audit/06_security_and_permissions.md` | 权限与账号体系 (Phase 0) | 6. Security / Permission | history | `HISTORICAL` | 若依通用安全设计 | **MERGE** | 提取其对若依原生鉴权机制的分析入 Handbook 安全篇，原件归档。 | +| 24 | `docs/codebase-audit/07_runtime_and_environment.md` | 启动方式与运行环境 | 7. Runtime / Deployment | review | `RUNTIME_PENDING` | CI/CD 与部署手册 | **UPDATE_AFTER_RUNTIME** | 记录了 Docker、JDK、Node 运行要求，必须以 Final Runtime Gate 实测报告为准更新。 | +| 25 | `docs/codebase-audit/08_git_status.md` | Git 状态（只读快照） | 10. Historical Development Record | history | `HISTORICAL` | 无 | **ARCHIVE** | 当时审计执行时的临时 git status 备份，纯历史过程数据，归档。 | +| 26 | `docs/codebase-audit/09_reusable_ruoyi_capabilities.md` | 可复用的若依能力 | 2. Architecture | current | `HISTORICAL` | 无 | **MERGE** | 原标记 KEEP。经查包含大量 Phase 0 历史缺陷分析，应提炼若依复用能力入 Handbook，原件归档。 | +| 27 | `docs/codebase-audit/10_gap_and_conflict_analysis.md` | 当前实现与未来业务设计的冲突点 | 1. Product / Business | history | `HISTORICAL` | `issues-v1/02` | **ARCHIVE** | Phase 0 识别的 12 项业务冲突均已在 Phase 2/3 消化落地，归档。 | +| 28 | `docs/codebase-audit/11_executive_summary.md` | 代码基线审计 Executive Summary | 1. Product / Business | history | `HISTORICAL` | 阶段总结报告 | **ARCHIVE** | Phase 0 审计管理层摘要，作为里程碑审计成果归档。 | +| 29 | `docs/codebase-audit/12_baseline_classification.md` | Phase 0：当前 Git 基线分类 | 10. Historical Development Record | history | `HISTORICAL` | 无 | **ARCHIVE** | 早期基线分类与标签管理方案，归入历史资产。 | +| 30 | `docs/codebase-audit/13_live_database_snapshot.md` | Kingbase 实时数据库快照 (Phase 0) | 4. Database | history | `HISTORICAL` | 旧库结构 | **ARCHIVE** | 当时只读探测快照，作为历史基准归档。 | +| 31 | `docs/codebase-audit/14_database_code_diff.md` | 设计文档、实时Kingbase与代码三方差异 | 4. Database | history | `HISTORICAL` | 旧差异报告 | **ARCHIVE** | 当时三方一致性校验报告，归入归档目录。 | +| 32 | `docs/codebase-audit/15_live_permission_snapshot.md` | 培训菜单与权限实时快照 | 6. Security / Permission | history | `HISTORICAL` | 权限审计 | **ARCHIVE** | 记录了当时 23 个菜单项无权限字符串的事实，归入归档目录。 | +| 33 | `docs/codebase-audit/16_kingbase_readonly_compatibility.md` | Kingbase 只读兼容性核验 | 4. Database | current | `HISTORICAL` | 无 | **MERGE** | 原标记 KEEP。内含旧代码生成器把 db 当 schema 的历史记录（已修复），提炼经验入 Handbook 后归档。 | +| 34 | `docs/codebase-audit/17_phase0_summary.md` | Phase 0 工程与数据库真实基线总结 | 10. Historical Development Record | history | `HISTORICAL` | 里程碑总结 | **ARCHIVE** | Phase 0 阶段性总结，归档存查。 | +| 35 | `docs/codebase-audit/18_phase05_runtime_fix.md` | Phase 0.5 基础运行修复审计报告 | 8. Testing / Release | history | `HISTORICAL` | 修复记录 | **ARCHIVE** | 早期启动修复与运行阻断排除验证报告，归档存查。 | +| 36 | `docs/database-v2/00_readme.md` | 数据库 V2 DDL 生成与设计审查概览 | 4. Database | current | `DOC_ONLY` | `database-v2/01` | **MERGE** | 数据库总体架构与设计思想，提炼合并入 `handbook/database/data-architecture.md`。 | +| 37 | `docs/database-v2/01_table_inventory.md` | 数据库 V2 表结构清单与模型比对 | 4. Database | current | `DOC_ONLY` | 各模块数据表设计 | **MERGE** | 21 张物理表字段字典，总表并入数据模型 Handbook，分表拆入各 Module 文档。 | +| 38 | `docs/database-v2/02_migration_plan.md` | 数据库 V2 迁移执行计划 | 11. Database Migration Asset | history | `HISTORICAL` | 执行脚本 | **ARCHIVE** | 6 阶段迁移计划，物理迁移已执行通过，归入 `archive/migrations/`。 | +| 39 | `docs/database-v2/03_constraint_index_review.md` | 数据库 V2 约束与索引技术审查报告 | 4. Database | current | `HISTORICAL` | 无 | **MERGE** | 原标记 KEEP。属于阶段性审查报告，将外键拓扑与索引建议并入 Handbook 数据库章节，原件归档。 | +| 40 | `docs/database-v2/04_risk_review.md` | 数据库 V2 关键设计风险深度审查报告 | 4. Database | history | `HISTORICAL` | 风险登记册 | **ARCHIVE** | 针对 R-01~R-17 风险的审查，已在迁移中落地规避，归入归档。 | +| 41 | `docs/database-v2/05_execution_contract.md` | 数据库 V2 迁移执行契约 | 11. Database Migration Asset | history | `HISTORICAL` | 迁移计划 | **ARCHIVE** | 迁移过程执行约束，属于实施过程约束，归档。 | +| 42 | `docs/database-v2/06_review_round1_changes.md` | 数据库 V2 DDL Review 修订记录表 (Round 1) | 11. Database Migration Asset | history | `HISTORICAL` | 修订日志 | **ARCHIVE** | 第一次 DDL 修改纪要，归档。 | +| 43 | `docs/database-v2/07_review_round2_changes.md` | 数据库 V2 DDL Review Round 2 变更记录 | 11. Database Migration Asset | history | `HISTORICAL` | 修订日志 | **ARCHIVE** | 第二次 DDL 修改纪要，归档。 | +| 44 | `docs/database-v2/08_gate_ab_validation.md` | 数据库 V2 双门禁验证报告 (Gate A / Gate B) | 8. Testing / Release | history | `HISTORICAL` | 门禁报告 | **ARCHIVE** | 静态语法与隔离门禁通过报告，归入测试归档。 | +| 45 | `docs/database-v2/09_stage1_backup_validation.md` | 数据库 V2 Stage 1 备份阶段验证报告 | 11. Database Migration Asset | history | `HISTORICAL` | 备份日志 | **ARCHIVE** | Stage 1 备份验证流水，归入迁移归档。 | +| 46 | `docs/database-v2/10_stage2_6_structure_validation.md` | 数据库 V2 Stage 2~6 结构迁移验证报告 | 11. Database Migration Asset | history | `HISTORICAL` | 结构验证 | **ARCHIVE** | DDL 实际生效验证流水，归入迁移归档。 | +| 47 | `docs/database-v2/11_final_migration_validation.md` | 数据库 V2 最终迁移验收报告 (010_verify PASS) | 8. Testing / Release | history | `HISTORICAL` | 终验报告 | **ARCHIVE** | 010_verify 脚本全绿验收里程碑报告，归入归档。 | +| 48 | `docs/database-v2/12_generator_v2_readonly_validation.md` | Database V2 Generator 只读验证报告 | 8. Testing / Release | history | `HISTORICAL` | 生成器补丁 | **ARCHIVE** | 代码生成器只读验证测试报告，归档。 | +| 49 | `docs/database-v2/13_generator_kingbase_fix_validation.md` | Generator Kingbase V2 元数据适配修复报告 | 8. Testing / Release | history | `HISTORICAL` | `generator-v2/01` | **ARCHIVE** | 代码生成器 Kingbase 元数据适配复验记录，归档。 | +| 50 | `docs/development/demo-electronic-board-cleanup.md` | Electronic Board Demo-Safe Cleanup 实施报告 | 9. Module Documentation | current | `HISTORICAL` | ElectronicBoard 模块 | **ARCHIVE** | 班牌清洗方案报告，核心清洗规则提炼入 `modules/11_electronic-board.md` 后原件归档。 | +| 51 | `docs/development/issue-01-01-teacher.md` | ISSUE-01-01：师资主数据开发与验收报告 | 9. Module Documentation | current | `HISTORICAL` | Teacher 模块 | **MERGE** | 师资主数据开发验收事实，提取规则、API 与前端交互合并入 `modules/06_teacher.md`。 | +| 52 | `docs/development/issue-01-02-student.md` | ISSUE-01-02：学员基础主数据开发与验收报告 | 9. Module Documentation | current | `HISTORICAL` | Student 模块 | **MERGE** | 学员脱敏、身份证校验、双来源模型合并入 `modules/05_student.md`。 | +| 53 | `docs/development/issue-01-03-course.md` | ISSUE-01-03：课程库基础资料开发与验收文档 | 9. Module Documentation | current | `HISTORICAL` | Course 模块 | **MERGE** | 课程属性、学时课时换算规则合并入 `modules/07_course.md`。 | +| 54 | `docs/development/issue-01-04-space.md` | ISSUE-01-04：教学空间资源维护开发验收文档 | 9. Module Documentation | current | `HISTORICAL` | Classroom & Site 模块 | **MERGE** | 教室与实训场地分离建模、容量规则合并入 `modules/08_classroom.md` 与 `modules/09_training-site.md`。 | +| 55 | `docs/development/issue-01-05-dormitory.md` | ISSUE-01-05：宿舍房间与楼宇基础数据维护开发验收文档 | 9. Module Documentation | current | `HISTORICAL` | Dormitory 模块 | **MERGE** | 楼宇、房间、床位动态计算模型合并入 `modules/10_dormitory.md`。 | +| 56 | `docs/development/issue-02-01-plan.md` | ISSUE-02-01：培训计划生命周期开发验收 | 9. Module Documentation | current | `HISTORICAL` | Plan 模块 | **MERGE** | 计划状态机、编号规则、生命周期流转合并入 `modules/01_plan.md`。 | +| 57 | `docs/development/issue-02-02-plan-course.md` | ISSUE-02-02：本期培训课程引入与配置开发验收 | 9. Module Documentation | current | `HISTORICAL` | PlanCourse 模块 | **MERGE** | 本期课程选择、讲师选派、计划课时匹配规则合并入 `modules/02_plan-course.md`。 | +| 58 | `docs/generator-v2/01_kingbase_import_identity_patch.md` | Generator 基础设施补丁 — Kingbase Import Identity | 10. Historical Development Record | history | `HISTORICAL` | `database-v2/13` | **ARCHIVE** | 代码生成器底层驱动补丁技术记录，归入历史开发记录归档。 | +| 59 | `docs/issues-v1/00_readme.md` | Phase 3：P0 Epic / Issue 任务拆分总纲 | 1. Product / Business | history | `HISTORICAL` | `issues-v1/01` | **ARCHIVE** | Phase 3 任务分解管理方案，研发已完成，归入项目管理归档。 | +| 60 | `docs/issues-v1/01_epic_overview.md` | Phase 3：Epic 架构概览 (Epic Overview) | 1. Product / Business | current | `DOC_ONLY` | 业务全流程 | **MERGE** | 紧扣 PRD 的业务能力域与主链路设计，提炼合并入系统业务架构与流程全景图。 | +| 61 | `docs/issues-v1/02_p0_issue_backlog.md` | Phase 3：P0 Issue 详细清单 (P0 Issue Backlog) | 1. Product / Business | current | `DOC_ONLY` | 各模块具体规范 | **MERGE** | 包含 26 个 Issue 的详尽设计，应按业务域拆解合并入各具体 Module 文档，原全局清单归档。 | +| 62 | `docs/issues-v1/03_dependency_graph.md` | Phase 3：Issue 依赖关系有向无环图 (Dependency DAG) | 10. Historical Development Record | history | `HISTORICAL` | 排期图表 | **ARCHIVE** | 敏捷研发批次依赖 DAG 图，属于研发调度历史资产，归档。 | +| 63 | `docs/issues-v1/04_wave_plan.md` | Phase 3：开发批次计划 (Wave Plan) | 10. Historical Development Record | history | `HISTORICAL` | 研发排期 | **ARCHIVE** | Wave 0~7 开发推进计划，研发阶段性资产，归档。 | +| 64 | `docs/issues-v1/05_agent_assignment.md` | 研发分工与代码生成器策略 | 10. Historical Development Record | history | `HISTORICAL` | 研发组织方案 | **ARCHIVE** | 多 Agent 研发调度与分工规范，归档。 | +| 65 | `docs/issues-v1/06_acceptance_matrix.md` | Phase 3：端到端验收矩阵与追踪表 | 8. Testing / Release | review | `RUNTIME_PENDING` | 最终验收报告 | **UPDATE_AFTER_RUNTIME** | 53 个 P0 API 端到端追踪表，必须待 Runtime Gate 最终实测验证后更新并标记 CLOSED。 | +| 66 | `docs/issues-v1/07_p1_p2_backlog.md` | Phase 3：P1 / P2 需求储备池 (Backlog Register) | 1. Product / Business | current | `DOC_ONLY` | 无 | **UPDATE_FROM_CODE** | 原标记 KEEP。经查部分被列为 P1 的修改端点已在 Wave 2 实现，需从代码核验后剔除已实现项。 | +| 67 | `docs/issues-v1/08_risk_register.md` | 技术与业务风险登记册 (Risk Register) | 8. Testing / Release | review | `RUNTIME_PENDING` | 已知问题列表 | **UPDATE_AFTER_RUNTIME** | 记录并发锁与业务一致性风险，必须待 Runtime Gate 实测结束后标记最终缓解状态。 | +| 68 | `docs/issues-v1/09_issue_review_round1.md` | Issue Review Round 1 评审整改报告 | 8. Testing / Release | history | `HISTORICAL` | 评审整改记录 | **ARCHIVE** | 记录 Phase 3 初审整改过程与落地证明，归入过程质量归档。 | + +--- + +## 三、推荐的目标信息架构与物理目录树 + +遵循 **“工程事实 (Handbook/Modules) — 人类表达 (Visual/Demo) — 历史记录 (Archive)”** 严格三权分立原则： + +```text +docs/ +├── README.md # [SSOT] 全局文档总索引与快速导航入口 (UPDATE_AFTER_RUNTIME) +│ +├── handbook/ # [系统级工程事实指南与架构规范] +│ ├── business/ +│ │ ├── business-overview.md # 铁路全流程培训业务价值与闭环说明 (MERGE) +│ │ └── future-backlog.md # 二期需求储备池 (需从代码核验已实现项后维护) (UPDATE_FROM_CODE) +│ ├── architecture/ +│ │ ├── system-architecture.md # 总体分层与多包架构 (RuoYi-Vue + ruoyi-train) (MERGE) +│ │ ├── service-boundaries.md # 模块聚合边界与禁止越权规则 (UPDATE_FROM_CODE) +│ │ └── transactions-and-invariants.md # 事务边界与核心业务不变量 (含排课 Soft Warning 语义) (UPDATE_FROM_CODE) +│ ├── api/ +│ │ ├── api-principles.md # RESTful API 设计准则与规范 (UPDATE_FROM_CODE) +│ │ └── permissions-and-errors.md # 全局错误码与权限字符规范 (UPDATE_AFTER_RUNTIME) +│ ├── database/ +│ │ ├── data-architecture.md # 21张物理表架构总览与关系字典 (MERGE) +│ │ ├── indexes-and-constraints.md # 约束、索引与高并发锁优化规范 (MERGE) +│ │ └── kingbase-compatibility.md # 金仓 KingbaseES 避坑实战指南 (MERGE) +│ ├── engineering/ +│ │ ├── ruoyi-capabilities.md # 若依框架可复用工程能力指南 (MERGE) +│ │ └── external-adapters.md # 门禁/硬件外设防腐层集成契约 (REVIEW_REQUIRED) +│ └── deployment/ +│ ├── runtime-environment.md # 运行环境、依赖栈与配置规格 (端口以实测为准) (UPDATE_AFTER_RUNTIME) +│ └── cicd-pipeline.md # GitLab CI/CD 流水线配置说明 (VERIFY_WITH_CODE) +│ +├── modules/ # [11大高内聚独立业务模块全要素文档] +│ ├── 01_plan.md # 培训计划生命周期模块 (状态机: VERIFY_WITH_CODE) +│ ├── 02_plan-course.md # 本期培训课程引入与配置模块 +│ ├── 03_enrollment.md # 学员参训档案与名单导入模块 (sourceType: VERIFY_WITH_CODE) +│ ├── 04_scheduling.md # 智能排课、课次编排与冲突检测模块 (Soft Warning 语义) +│ ├── 05_student.md # 学员基础主档与隐私安全脱敏模块 +│ ├── 06_teacher.md # 师资资源主数据管理模块 +│ ├── 07_course.md # 课程基础资源库模块 +│ ├── 08_classroom.md # 普通教室教学空间资源模块 +│ ├── 09_training-site.md # 铁路实训演练场地模块 +│ ├── 10_dormitory.md # 学员宿舍楼宇与房态房源模块 +│ └── 11_electronic-board.md # 电子班牌模块 (仅确认绑定教室，场地支持: VERIFY_WITH_CODE) +│ +├── visual/ # [现代化交互式 HTML 文档站与汇报大屏] +│ ├── index.html # 视觉文档站仪表盘主入口 +│ ├── system-overview.html # 交互式系统全景与指标看板 +│ ├── business-flow.html # 动态主业务闭环全流程流转图 +│ ├── architecture.html # 分层技术架构与防腐层交互拓扑图 +│ ├── data-model.html # 21张表核心实体 ER 关系与模型关系图 +│ ├── api-map.html # 53个 P0 API 全局交互式全景地图 +│ ├── deployment.html # 运行环境、容器拓扑与 GitLab CI/CD 流程图 +│ ├── demo.html # 16:9 高保真交互式答辩/演示 Presentation (截图以实测为准) +│ └── modules/ # 11大模块专属交互式展示页面 +│ +├── assets/ # [工程静态资产与真实截图集中营] +│ ├── diagrams/ # 架构图、流程图、时序图矢量 SVG / Mermaid 源码 +│ └── screenshots/ # Runtime Gate 捕获的高保真实测 UI 截图 +│ +├── archive/ # [历史过程产物与阶段性追溯材料归档 (35份)] +│ ├── conversations/ # 会话调试与操作过程日志 +│ ├── reviews/ # 阶段性 Review 审查报告 (Round 1/2) +│ ├── migrations/ # Database V2 物理迁移阶段验证与测试记录 +│ ├── phase0-audit/ # Phase 0 历史基线与旧库审计快照 +│ └── phase3-planning/ # Phase 3 敏捷排期、DAG 依赖图与分工计划 +│ +└── _meta/ # [架构治理元数据与核验清单] + ├── document-audit-draft.md # [本文档] Phase A.1 文档信息架构审计草案 (修正版) + └── code-verification-checklist.md # 严密事实抽取任务书 (无预设猜测答案) +``` + +--- + +## 四、11 大 Module 规格要素定义 + +未来在 `docs/modules/*.md` 中建立的每个模块文档，均须统一严格覆盖以下 **18 项要素**： + +1. **模块是什么 (Definition)**：一句话定义其领域边界。 +2. **业务价值 (Value Proposition)**：解决什么核心管理痛点与业务收益。 +3. **在总业务流程的位置 (Position in Flow)**：前置依赖谁，后置触发谁。 +4. **用户入口 (User Entry)**：菜单路径、导航定位、角色视窗。 +5. **页面与组件 (Pages & Components)**：对应的 Vue 视图文件与子组件（如 `TimetablePanel.vue`）。 +6. **核心业务流程 (Core Workflow)**：带泳道或时序的端到端业务流转。 +7. **状态与状态机 (State Machine)**：从代码中提取的枚举值及其状态迁移矩阵 (`VERIFY_WITH_CODE`)。 +8. **核心业务规则 (Business Invariants)**：硬性校验、软性警告 (Soft Warning)、超编限制。 +9. **API 契约 (API Contract)**：端点、HTTP 方法、请求头。 +10. **DTO / VO 规格 (Data Contracts)**：入参校验规则与出参脱敏规范。 +11. **数据库物理结构 (Database Tables)**：涉及的主从物理表、关键字段与唯一索引。 +12. **安全与权限控制 (Security & Perms)**：按钮级 `v-hasPermi` 与接口 `@ss.hasPermi` 映射。 +13. **业务错误码 (Business Errors)**：模块专属错误码常量与提示文本。 +14. **跨模块联动 (Cross-Module Interactions)**：只读引用边界与领域事件通知。 +15. **Runtime 验证 (Runtime Verification)**：自动化与实测验证用例集（标记 `RUNTIME_PENDING`）。 +16. **当前已知限制 (Known Limitations)**：本期未支持特性与二期演进计划。 +17. **代码导航 (Code Map)**：Controller, Service, Mapper, XML, Vue 关键物理源码超链接。 +18. **Demo 演练步骤 (Demo Walkthrough)**：5步内可复现的完整演示剧本。 diff --git a/docs/_meta/final-browser-evidence/01-plan-list.png b/docs/_meta/final-browser-evidence/01-plan-list.png new file mode 100644 index 000000000..704480b79 Binary files /dev/null and b/docs/_meta/final-browser-evidence/01-plan-list.png differ diff --git a/docs/_meta/final-browser-evidence/02-plan-course.png b/docs/_meta/final-browser-evidence/02-plan-course.png new file mode 100644 index 000000000..55f8d09d2 Binary files /dev/null and b/docs/_meta/final-browser-evidence/02-plan-course.png differ diff --git a/docs/_meta/final-browser-evidence/03-enrollment.png b/docs/_meta/final-browser-evidence/03-enrollment.png new file mode 100644 index 000000000..66e023a9e Binary files /dev/null and b/docs/_meta/final-browser-evidence/03-enrollment.png differ diff --git a/docs/_meta/final-browser-evidence/04-scheduling-form.png b/docs/_meta/final-browser-evidence/04-scheduling-form.png new file mode 100644 index 000000000..97df90fb5 Binary files /dev/null and b/docs/_meta/final-browser-evidence/04-scheduling-form.png differ diff --git a/docs/_meta/final-browser-evidence/05-conflict-warning.png b/docs/_meta/final-browser-evidence/05-conflict-warning.png new file mode 100644 index 000000000..cb75ce3ff Binary files /dev/null and b/docs/_meta/final-browser-evidence/05-conflict-warning.png differ diff --git a/docs/_meta/final-browser-evidence/06-timetable.png b/docs/_meta/final-browser-evidence/06-timetable.png new file mode 100644 index 000000000..8b1dd8abb Binary files /dev/null and b/docs/_meta/final-browser-evidence/06-timetable.png differ diff --git a/docs/_meta/final-browser-evidence/07-board-list.png b/docs/_meta/final-browser-evidence/07-board-list.png new file mode 100644 index 000000000..625e7a074 Binary files /dev/null and b/docs/_meta/final-browser-evidence/07-board-list.png differ diff --git a/docs/_meta/final-browser-evidence/08-board-form.png b/docs/_meta/final-browser-evidence/08-board-form.png new file mode 100644 index 000000000..0404da83a Binary files /dev/null and b/docs/_meta/final-browser-evidence/08-board-form.png differ diff --git a/docs/_meta/final-release-readiness.md b/docs/_meta/final-release-readiness.md new file mode 100644 index 000000000..aec91b5d7 --- /dev/null +++ b/docs/_meta/final-release-readiness.md @@ -0,0 +1,225 @@ +# RailwaySystem - Final Release Readiness Audit Report + +> **当前正式开发基线分支：** `integration/wave2-20260914` +> **当前 Integration HEAD：** `d162954cd1e26c6948408a8304ca333ba9fe7a40` +> **最终发布版本 HEAD 标记：** `FINAL_HEAD_PENDING` +> **目标远程发布分支：** `origin/feat/cicd-pipeline` +> **审计属性：** 发布准备度审计、CI/CD 门禁验证、Migration 分类盘点、部署与回滚方案定义 +> **纪律铁律：** 只做审计、只写文档、禁止修改业务代码、禁止部署、禁止 push、禁止执行 Browser 测试、HOLD COMMIT + +--- + +## 1. 当前发布事实与 Git 状态审计 + +### 1.1 分支与 HEAD 状态对照 +- **目标远程分支：** `origin/feat/cicd-pipeline` +- **当前 Remote HEAD (`origin/feat/cicd-pipeline`)：** + `5d93c217d99ff3cb21ced7ca082d3d8685d4adb5` + *(Commit Message: `chore(ci): 增加Kingbase JDBC依赖预检与初始化流程`)* +- **当前 Integration HEAD (`integration/wave2-20260914`)：** + `d162954cd1e26c6948408a8304ca333ba9fe7a40` + *(Commit Message: `fix(ui): 清理最终交付界面技术字段与品牌文案`)* +- **工作区 HEAD：** `d162954cd1e26c6948408a8304ca333ba9fe7a40` (detached HEAD) + +### 1.2 差异分析与分支滞后事实 +- **Remote 分支是否落后：** **是 (Behind)** +- **落后 Commit 数量：** **落后 2 个 Commit** +- **领先提交清单：** + 1. `e2d7e63d8e157417c5aa83fba536834951a2ea25` - `fix(db): 补齐Kingbase操作日志耗时字段` + 2. `d162954cd1e26c6948408a8304ca333ba9fe7a40` - `fix(ui): 清理最终交付界面技术字段与品牌文案` +- **发布准则：** 保持 **HOLD COMMIT** 与 **DO NOT PUSH**，等待并行任务全部并入并由发版负责人统筹合并。 + +--- + +## 2. Current Release Delta Migration (当前版本增量迁移) + +### 2.1 增量定义与范围 +当前 `FINAL_HEAD_PENDING` 相对于上一稳定 RC/基线分支（`origin/feat/cicd-pipeline`），**唯一的数据库增量变更**为： + +- **增量脚本文件：** + [`RuoYi-Vue/sql/system/kingbase/001_sys_oper_log_cost_time.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/system/kingbase/001_sys_oper_log_cost_time.sql) +- **变更目标：** + 为若依系统核心日志表 `public.sys_oper_log` 补齐缺失的 `cost_time` 字段（`BIGINT DEFAULT 0`），对齐 Java 实体 `SysOperLog.costTime`，消除系统日志查询接口 `/monitor/operlog/list` 报 500 的系统级阻断缺陷。 +- **幂等性保障：** + 脚本采用 `ALTER TABLE public.sys_oper_log ADD COLUMN IF NOT EXISTS cost_time BIGINT DEFAULT 0;` 与补偿 `UPDATE public.sys_oper_log SET cost_time = 0 WHERE cost_time IS NULL;`，具备严格语法级存在性保护与数据安全性。 +- **发布执行判定：** + **若部署目标数据库已经是 V2 基线，本次发布仅需且必须执行该增量脚本，即可完成数据库端升级对齐。** + +### 2.2 历史资产声明 (Historical Assets) +仓库中 `sql/train/v2/*` 与 `sql/generator/kingbase/*` 属于 **Historical Bootstrap / Upgrade / Verification Assets (历史引导/整库升级/验收资产)**。 +目标库在当前已经处于 V2 基线状态下，**绝对严禁在每次版本发布时重复执行这些历史脚本**（如备份快照、重建业务表、删除成绩表等），历史脚本仅用于全新空环境初始化或特定旧库全量升级。 + +--- + +## 3. Migration 分类盘点与准确统计 + +遵循专业规范，将工程内所有 17 个 Kingbase SQL 脚本严格按照工程属性分类，杜绝混合统计口径： + +### 3.1 准确分类统计汇总 +- **A 类: Schema/Data Migration（模式与数据迁移）：** **11 个**（含 1 个当前 Release Delta，10 个历史迁移） +- **B 类: Preflight/Probe/Verification（预检/探测/验收断言）：** **5 个**（纯只读探测或自带事务显式回滚） +- **C 类: Intentionally Disabled（明确禁用/审计禁止）：** **1 个**（`007_dicts.sql`，保护系统字典） +- **总计脚本资产：** **17 个** + +--- + +### 3.2 详细分类清单与执行事实 + +#### A 类：Schema/Data Migration (模式与数据迁移，共 11 个) +| 脚本路径 | 资产属性 | 用途说明 | 是否幂等 | 目标库已是V2时是否执行 | 历史测试环境实测状态 | +| :--- | :---: | :--- | :---: | :---: | :---: | +| `RuoYi-Vue/sql/system/kingbase/001_sys_oper_log_cost_time.sql` | **Current Release Delta** | 为 `sys_oper_log` 补齐 `cost_time` 字段，解决 500 报错 | **是** | **必须执行 (若未补齐)** | **已执行** (P0阶段已实测验证) | +| `RuoYi-Vue/sql/generator/kingbase/002a_gen_table_identity_patch.sql` | Historical Bootstrap | 为 `gen_table.table_id` 添加自增 Identity | 否 | 严禁重复执行 | **已执行** | +| `RuoYi-Vue/sql/generator/kingbase/002b_gen_table_column_identity_patch.sql` | Historical Bootstrap | 为 `gen_table_column.column_id` 添加自增 Identity | 否 | 严禁重复执行 | **已执行** | +| `RuoYi-Vue/sql/train/v2/001_backup_current_schema.sql` | Historical Upgrade | 备份 14 张历史业务表为 `bak_v1_*` 快照 | 否 | 严禁重复执行 | **已执行** | +| `RuoYi-Vue/sql/train/v2/002_create_new_tables.sql` | Historical Upgrade | 创建 8 张 V2 新业务表 | 否 | 严禁重复执行 | **已执行** | +| `RuoYi-Vue/sql/train/v2/003_alter_master_tables.sql` | Historical Upgrade | 解耦改造 8 张主表结构，卸载旧触发器 | 否 | 严禁重复执行 | **已执行** | +| `RuoYi-Vue/sql/train/v2/004_rebuild_business_tables.sql` | Historical Upgrade | 重建 5 张业务过程表结构 | 否 | 严禁重复执行 | **已执行** | +| `RuoYi-Vue/sql/train/v2/005_constraints.sql` | Historical Upgrade | 建立 13 组 UNIQUE, 26 组 FK, 9 组 CHECK | 否 | 严禁重复执行 | **已执行** | +| `RuoYi-Vue/sql/train/v2/006_indexes.sql` | Historical Upgrade | 创建排课三复合索引及部分唯一索引 | 否 | 严禁重复执行 | **已执行** | +| `RuoYi-Vue/sql/train/v2/008_migrate_teacher.sql` | Historical Upgrade | 迁移旧教师数据并固化 NOT NULL | 否 | 严禁重复执行 | **已执行** | +| `RuoYi-Vue/sql/train/v2/009_drop_legacy_score.sql` | Historical Upgrade | 下线 0 行旧表 `train_score_info` | 是 | 严禁重复执行 | **已执行** | + +#### B 类：Preflight/Probe/Verification (预检/探测/验收断言，共 5 个) +| 脚本路径 | 资产属性 | 用途说明 | 执行特性 | 是否曾真实执行 | 执行结果与断言结论 | +| :--- | :---: | :--- | :---: | :---: | :---: | +| `RuoYi-Vue/sql/generator/kingbase/001_generator_identity_precheck.sql` | Preflight | 预检 Generator 两张表自增属性 Case 分支 | 只读诊断探针 | **是** | 输出 CASE_2 分支，无状态修改 | +| `RuoYi-Vue/sql/generator/kingbase/003_generator_identity_verify.sql` | Verification | 验证 Generator 表自增、依赖及序列游标对齐 | 只读断言 | **是** | 输出 `VERIFY: PASS` | +| `RuoYi-Vue/sql/train/v2/000_tx_capability_probe.sql` | Probe (Gate A) | 探测 KingbaseES 实例 DDL 事务原子性与回滚机制 | 临时表+显式 ROLLBACK | **是** | 显式回滚成功，输出 `[Probe-PASS]`，零残留 | +| `RuoYi-Vue/sql/train/v2/000_preflight.sql` | Preflight (Gate B) | Phase 0.5 基线强校验 (断言 14旧表, 1教师, 24外键) | **纯只读强断言** | **是** | **在 Gate B 阶段实测执行通过**，输出 `[Preflight-PASS]` | +| `RuoYi-Vue/sql/train/v2/010_verify.sql` | Verification | 21 张 V2 业务表定义级全量深度验收断言脚本 | 纯只读强断言 | **是** | 实测执行通过，输出 `[Verify-PASS]` | + +> [!IMPORTANT] +> **关于 `000_preflight.sql` 真实状态的确定性说明：** +> `000_preflight.sql` 属于纯只读前置基线断言探针（Gate B 门禁）。它**已在历史 V2 迁移准入阶段在真实测试库上完整执行过**并输出 `[Preflight-PASS]`。它不包含任何 DDL/DML 写入，不改变任何数据，不属于发布变更脚本。在当前已升级至 V2 的数据库上，无需再次执行（若再次执行会因表结构已演进至 V2 而断言拦截，这正是其预检保护的设计初衷）。 + +#### C 类：Intentionally Disabled (明确审计禁止执行，共 1 个) +| 脚本路径 | 资产属性 | 审计结论与处置规则 | +| :--- | :---: | :--- | +| `RuoYi-Vue/sql/train/v2/007_dicts.sql` | Intentionally Disabled | **DO NOT EXECUTE (严禁执行)**。经全链路审计确认，当前生产/测试环境 `sys_dict_*` 表处于 44/500 条纯净基线。为保护若依底座零破坏，严禁执行该脚本，直到后续契约专项重新审定。 | + +--- + +## 4. CI Readiness 审计与最终 Gate 顺序 + +### 4.1 CI 配置与预检核查 (`.gitlab-ci.yml`) +- **Stage 顺序：** `build_backend` → `build_frontend` → `deploy` +- **Kingbase JDBC Preflight：** 由 [check-kingbase-jdbc.sh](file:///Users/wzb/Desktop/项目/RailwaySystem/scripts/bootstrap/check-kingbase-jdbc.sh) 执行，严格比对本地驱动与授权 SHA256 哈希 `346d5602477ed472b19c5e25729fff5a58b1d83cec56162a56ac4b86d9546c32`； +- **Redis Runtime Preflight：** 部署前强制检查 `SPRING_REDIS_PASSWORD` 非空； +- **Maven Test/Package：** `mvn clean package` 输出 `ruoyi-admin.jar`； +- **Frontend Build：** 注入兼容选项并软链本地缓存，`npm run build:prod` 输出 `build_ui/dist/`； +- **Secret 相关检查：** 强制校验 `TRAIN_STUDENT_IDENTITY_ENCRYPTION_KEY`, `TRAIN_STUDENT_IDENTITY_HASH_KEY`, `SPRING_REDIS_PASSWORD`。 + +### 4.2 最终 CI Gate 顺序 +```text +[CI_GATE_01] Backend Environment Setup (JDK 8, Maven 工具链验证) + ↓ +[CI_GATE_02] Kingbase JDBC 8.6.0 Integrity Preflight (SHA256 驱动强校验) + ↓ +[CI_GATE_03] Maven Package & Test Gate (ruoyi-admin.jar 产物构建与测试) + ↓ +[CI_GATE_04] Frontend Node Runtime & Cache Linking (Node 配置与依赖软链) + ↓ +[CI_GATE_05] Frontend Build Gate (Webpack 生产模式构建 build_ui/dist) + ↓ +[CI_GATE_06] Deployment Branch Filter Gate (仅 feat/cicd-pipeline 分支允许触发) + ↓ +[CI_GATE_07] Runtime Secret & Security Preflight (学员加密密钥、Hash密钥、Redis密码校验) + ↓ +[CI_GATE_08] Process Graceful Shutdown (kill -15 优雅下线，超时 kill -9) + ↓ +[CI_GATE_09] Backend Service Boot & Captcha Health Check (/captchaImage 轮询断言 code:200) + ↓ +[CI_GATE_10] Frontend Static Assets Refresh & Nginx Reload (8082 端口平滑重载) +``` + +--- + +## 5. Deployment Readiness 审计与步骤修正 + +### 5.1 部署环境定义 +- **服务器别名：** `sict` +- **部署根目录：** `/data2/wzb/deploy` +- **后端服务端口：** `8092` +- **前端 Nginx 端口：** `8082` +- **Kingbase 数据库服务：** `192.168.139.218:4321/training` +- **部署管理脚本：** `deploy/restart-all.sh` +- **Nginx 配置文件：** `/data2/wzb/deploy/nginx/nginx.conf` +- **后端 Jar 物理路径：** `/data2/wzb/deploy/backend/ruoyi-admin.jar` +- **前端 Dist 物理路径：** `/data2/wzb/deploy/frontend/` + +### 5.2 修正后的部署步骤 (DEPLOY_STEP_01 ~ DEPLOY_STEP_10) + +- **`DEPLOY_STEP_01` (环境与凭据预检):** 确认目标机 `sict` 上敏感环境变量（`TRAIN_STUDENT_IDENTITY_ENCRYPTION_KEY`, `TRAIN_STUDENT_IDENTITY_HASH_KEY`, `SPRING_REDIS_PASSWORD`）已就绪。 +- **`DEPLOY_STEP_02` (数据库 Schema 版本判定与 Delta 执行):** + **先判断目标库当前 schema 版本**： + - 若目标库**已经是 V2 基线**：**仅执行当前 Release Delta migration**（即 `RuoYi-Vue/sql/system/kingbase/001_sys_oper_log_cost_time.sql`），**严禁重复执行历史 V2 rebuild/drop/backup 脚本**； + - 若目标库为全新库或历史旧库：按受控初始化手册逐步升级。 +- **`DEPLOY_STEP_03` (现网制品备份):** 备份当前运行中的 `ruoyi-admin.jar` 为 `ruoyi-admin.jar.bak`，备份 `frontend` 为 `frontend.bak`。 +- **`DEPLOY_STEP_04` (CI 构建产物生成与归档):** 运行发布流水线，生成后端 `ruoyi-admin.jar` 与前端 `dist/` 构建物。 +- **`DEPLOY_STEP_05` (前端静态资源覆盖部署):** 清空 `/data2/wzb/deploy/frontend/*`，将新构建的 `dist/*` 内容拷贝至该目录。 +- **`DEPLOY_STEP_06` (后端 Jar 包更新部署):** 将新构建的 `ruoyi-admin.jar` 拷贝至 `/data2/wzb/deploy/backend/`。 +- **`DEPLOY_STEP_07` (执行平滑重启调度):** 调用 `bash deploy/restart-all.sh`。 +- **`DEPLOY_STEP_08` (后端优雅停机与新实例启动):** 脚本优雅终止旧进程并在端口 `8092` 启动新进程。 +- **`DEPLOY_STEP_09` (健康自检探针验证):** 脚本自动轮询 `http://127.0.0.1:8092/captchaImage`，35 次内确认返回 `"code":200`。 +- **`DEPLOY_STEP_10` (前端 Nginx 平滑重载):** 验证配置并执行 `nginx -s reload`，确保 8082 端口对外访问就绪。 + +--- + +## 6. Runtime Verification Checklist (精准三态定义) + +由于本次仅为审计与准备任务，未部署、未启动 Browser，所有验收项严谨标注当前真实状态，**不得将当前 HEAD 未重新执行项写成已通过**： + +| 验收编号 | 检验项 / 模块 | UI 路由入口 / API 真实端点 | 真实核验状态判定 | 状态说明 | +| :---: | :--- | :--- | :---: | :--- | +| **RTC-01** | Backend Health | `GET http://127.0.0.1:8092/captchaImage` | **PREVIOUSLY_VERIFIED_ON_PRIOR_RC** | 脚本中自检逻辑已在历史发布实测通过，当前 HEAD 未部署 | +| **RTC-02** | Kingbase Connectivity | 后端启动连接池与元数据读取 | **PREVIOUSLY_VERIFIED_ON_PRIOR_RC** | 历史实测通过，当前 HEAD 待最终部署验证 | +| **RTC-03** | Redis Connectivity | Captcha 缓存与 Token 存储 | **PREVIOUSLY_VERIFIED_ON_PRIOR_RC** | 历史实测通过，当前 HEAD 待最终部署验证 | +| **RTC-04** | User Login | `POST /prod-api/login` | **PREVIOUSLY_VERIFIED_ON_PRIOR_RC** | 历史实测通过，当前 HEAD 待最终部署验证 | +| **RTC-05** | OperLog 耗时字段查询 | `GET /prod-api/monitor/operlog/list` | **PREVIOUSLY_VERIFIED / DB_FIX_VALIDATED** | `cost_time` 数据库补丁在当前测试库实测执行并验证 200，但当前 integration 尚未部署验证 | +| **RTC-06** | Plan (培训计划) | **UI:** 课程管理 → 开班计划
**API:** `/train/plan/*` | **PENDING_FINAL_GATE** | Safe UI Polish 涉及页面，待最终发版门禁运行时验证 | +| **RTC-07** | Enrollment (参训人员) | **UI:** 课程管理 → 开班计划 → 参训人员 (Tab)
**API:** `POST/GET /train/plans/{planId}/enrollments...` | **PENDING_FINAL_GATE** | 内部 Tab 视图，Safe UI Polish 涉及页面，待最终门禁验证 | +| **RTC-08** | Scheduling (智能排课) | **UI:** 课程管理 → 开班计划 → 排课课表 (Tab)
**API:** `/train/lessons/*` 及 `/train/plans/{planId}/timetable` | **PENDING_FINAL_GATE** | 内部 Tab 视图，冲突 Soft Warning，待最终门禁验证 | +| **RTC-09** | Board (电子班牌) | **UI:** 设施设备 → 电子班牌
**正式路由:** `/train/board`
**API:** `/train/board/*` | **PENDING_FINAL_GATE** | Safe UI Polish 涉及页面，正式路径 `/train/board`，待最终门禁验证 | +| **RTC-10** | Legacy Analytics 1: 培训总评分析 | **UI:** 教学评估 → 培训总评分析 (`/analysis/report`) | **PENDING_CODEX** | 处于并行处理中，等待 Codex 交付后验收 | +| **RTC-11** | Legacy Analytics 2: 学员打卡记录 | **UI:** 考勤与打卡 → 学员打卡记录 (`/analysis/checkin`) | **PENDING_CODEX** | 处于并行处理中，等待 Codex 交付后验收 | +| **RTC-12** | Legacy Analytics 3: 学习时长统计 | **UI:** 学习监控 → 学习时长统计 (`/analysis/duration`) | **PENDING_CODEX** | 处于并行处理中，等待 Codex 交付后验收 | +| **RTC-13** | Legacy Analytics 4: 学员画像分析 | **UI:** 学员画像 → 画像分析 (`/portrait`) | **PENDING_CODEX** | 处于并行处理中，等待 Codex 交付后验收 | +| **RTC-14** | Frontend Nginx 8082 | `http://192.168.139.230:8082` | **PENDING_FINAL_GATE** | 待部署后验证反向代理与静态资源加载 | +| **RTC-15** | Global Network Quality | 全模块页面跳转与 API 交互 | **PENDING_FINAL_GATE** | 待全部集成合并后执行全站 **Network 500 = 0** 门禁断言 | + +--- + +## 7. Rollback Plan (版本与数据回滚预案) + +### 7.1 代码与前端回滚策略 +- **禁止通过执行旧 V2 脚本进行回滚**； +- 采用**上一个已归档稳定制品**进行平滑回退： + ```bash + # 恢复后端稳定 Jar + cp /data2/wzb/deploy/backend/ruoyi-admin.jar.bak /data2/wzb/deploy/backend/ruoyi-admin.jar + + # 恢复前端稳定 Dist + rm -rf /data2/wzb/deploy/frontend/* + cp -r /data2/wzb/deploy/frontend.bak/* /data2/wzb/deploy/frontend/ + + # 触发平滑重启 + bash deploy/restart-all.sh + ``` + +### 7.2 数据库 Migration 回滚安全准则 +- **零 DROP 原则：** `cost_time` 新增列属于向前兼容字段（DEFAULT 0），旧版本代码不读取该列即可正常运行。 +- **无需且严禁 DROP COLUMN：** 代码回滚时**严禁为数据库删除 `cost_time` 列**，杜绝锁表与元数据破坏。 + +--- + +## 8. Release Artifact Manifest (发布产物清单) + +1. **后端 Jar 包：** `RuoYi-Vue/ruoyi-admin/target/ruoyi-admin.jar` +2. **前端静态制品：** `build_ui/dist/` +3. **当前发布 Delta Migration：** `RuoYi-Vue/sql/system/kingbase/001_sys_oper_log_cost_time.sql` +4. **历史引导/升级/验收资产包：** `RuoYi-Vue/sql/train/v2/*`, `RuoYi-Vue/sql/generator/kingbase/*` +5. **部署配置与运维脚本：** `deploy/restart-all.sh`, `deploy/nginx.conf.example`, `scripts/bootstrap/check-kingbase-jdbc.sh`, `.gitlab-ci.yml` +6. **版本基线 HEAD：** `FINAL_HEAD_PENDING` (当前开发基线 `d162954cd1e26c6948408a8304ca333ba9fe7a40`) +7. **测试与准备报告：** `docs/_meta/final-release-readiness.md`, `docs/_meta/deployment-gate-checklist.md` +8. **Browser 审计报告：** `docs/ui-audit-screenshots/` diff --git a/docs/conversation_record.md b/docs/conversation_record.md new file mode 100644 index 000000000..c676fff23 --- /dev/null +++ b/docs/conversation_record.md @@ -0,0 +1,120 @@ +# RailwaySystem 会话全流程记录归档 + +- **会话 ID (Conversation ID)**: `6b8b4a8c-efd8-4d41-a82d-b8f1e04d8a76` +- **归档时间**: 2026-09-14 11:17:00 (GMT+8) +- **基线版本**: `issues-v1.0` (`7fcaea29b8810546fd972ba0c9d366c71a357d63`) +- **涉及 Worktree 与分支**: + 1. `/Users/wzb/Desktop/项目/RailwaySystem-worktrees/fix-generator-import-identity` (`fix/generator-import-identity`) + 2. `/Users/wzb/Desktop/项目/RailwaySystem-worktrees/issue-01-03-course` (`feat/issue-01-03-course`) + +--- + +## 一、阶段概览与核心交付 + +| 阶段 | 核心任务 | 关键动作与成果 | 状态 | +|:---|:---|:---|:---:| +| **阶段 1** | 创建独立工作树 | 创建并检出 `fix/generator-import-identity` 分支于 `fix-generator-import-identity` 目录 | **DONE** | +| **阶段 2** | Generator 基础设施补丁设计 | 审计 `ry_20250522.sql`；建立预检、补丁、验证脚本及技术文档；零业务表改动 | **DONE** | +| **阶段 3** | Review (A- / Safety Check) 加固 | 探测共享库 Sequence 实际位置；拆分补丁为 002a/002b 保证局部安全；增强 Verify 序列对齐校验；补齐四态执行矩阵与文档 | **DONE** | +| **阶段 4** | 释放 SLOT 并执行 Course Pilot | 释放 `GENERATOR SLOT = COURSE`；仅导入 `train_course`；核验 `c_id` 属性；代码生成隔离至 `/tmp/...`；完成三方比对并更新任务书；Maven 与 ESLint 全绿通过 | **DONE** | + +--- + +## 二、详细执行过程记录 + +### 1. 阶段一：创建工作树 (Worktree Setup) +- **执行命令**: + ```bash + cd "/Users/wzb/Desktop/项目/RailwaySystem" + git worktree add -b fix/generator-import-identity \ + "/Users/wzb/Desktop/项目/RailwaySystem-worktrees/fix-generator-import-identity" \ + issues-v1.0 + ``` +- **验证结果**: Worktree 创建成功，工作区 clean，HEAD 指向 `7fcaea29`。 + +--- + +### 2. 阶段二：Generator 基础设施补丁初版设计 +- **问题根因**: RuoYi Generator 在 MyBatis 中配置 `useGeneratedKeys="true"`，但 KingbaseES 初始化建表时缺失 `GENERATED BY DEFAULT AS IDENTITY`，导致真实导入生成主键为 0 并冲突。 +- **原始审计**: + - `gen_table`: `table_id bigint(20) not null auto_increment` + - `gen_table_column`: `column_id bigint(20) not null auto_increment` +- **交付内容**: + - 新建目录 `RuoYi-Vue/sql/generator/kingbase/` + - 编写 `001_generator_identity_precheck.sql`、`002_generator_identity_patch.sql`、`003_generator_identity_verify.sql`、`README.md` + - 新建技术文档 `docs/generator-v2/01_kingbase_import_identity_patch.md` + - 严格保持只读，禁止重复 ALTER。 + +--- + +### 3. 阶段三：技术负责人 Review 安全加固 (A- / Final Safety Check) +针对“Sequence 与已有 MAX(id) 对齐”及“Partial Patch 局部补丁安全”两个核心安全问题进行专项加固： + +1. **GIR-01 & GIR-02：实测共享库现有数据与 Sequence 状态**： + - `gen_table`: `row_count = 1`, `max_id = 1` (`train_teacher`), `last_value = 2`, `is_called = true` -> 下一个生成值 `3 > 1` (**SAFE**) + - `gen_table_column`: `row_count = 16`, `max_id = 16`, `last_value = 32`, `is_called = true` -> 下一个生成值 `33 > 16` (**SAFE**) + - **初始化语义判定**：Kingbase `sys_sequences` 显示 `start_value = 1`，按最保守原则处理，**不宣称自动对齐**，非空环境必须校验与人工对齐。 +2. **GIR-04：Partial Patch 安全与文件拆分（方案 A）**： + - 彻底删除原合并补丁 `002_generator_identity_patch.sql`； + - 拆分为两个独立原子补丁： + - `002a_gen_table_identity_patch.sql`（针对 `gen_table.table_id`） + - `002b_gen_table_column_identity_patch.sql`（针对 `gen_table_column.column_id`） + - `001` 预检脚本增强为可精确区分并输出 4 种全局场景： + - `CASE_1_BOTH_NEED_PATCH` + - `CASE_2_BOTH_ALREADY_PATCHED` + - `CASE_3_ONLY_COLUMN_NEEDS_PATCH` + - `CASE_4_ONLY_TABLE_NEEDS_PATCH` +3. **GIR-05：增强 Verify 只读校验**： + - `003_generator_identity_verify.sql` 增加第 4 节：利用纯只读子查询比对已有 `MAX(id)` 与 Sequence 下一分配值，输出 `EMPTY_TABLE_SAFE` / `SAFE` / `UNSAFE`； + - 最终判定综合列属性、序列存在、依赖类型（`deptype = 'i'`）与游标安全，一致通过方输出 `VERIFY: PASS`。 +4. **GIR-06 & GIR-07：README 决策矩阵与文档同步**： + - `README.md` 明确 Scenario A~D 执行矩阵与空表 vs 非空表的维护操作要求； + - 技术文档 `01_kingbase_import_identity_patch.md` 补充 Existing Metadata Safety、Partial Patch Safety、Sequence Alignment 章节。 +5. **Secret Scan & Git 检查**： + - `git grep -nE 'jdbc:kingbase8://|password[[:space:]]*=|sict123456|DriverManager\.getConnection'` 结果为 0（无敏感信息）； + - `git diff --check` 通过；零 commit，等待审核。 + +--- + +### 4. 阶段四：正式释放 GENERATOR SLOT = COURSE 并执行 Generator Pilot +在 Worktree `issue-01-03-course`（分支 `feat/issue-01-03-course`）上执行课程库生成器试点： + +1. **执行 Pilot 约束与隔离**： + - 待选列表核验：`bak_v1_*` 表数量精确为 0，历史备份表不可见； + - 严格单表导入：仅且唯独导入 `train_course`，写入 `gen_table`（`table_id = 3`）及 14 列元数据； + - 关键列核验：`c_id` 确认 `isPk = 1`、`isIncrement = 0`、`javaType = String`（验证完全通过）； + - 生成代码隔离：写入沙箱 `/tmp/railwaysystem-generator/issue-01-03-course/`，严禁覆盖现有源码。 +2. **Generated vs Existing vs API Contract V1.0.1 三方深度比对**： + - **实体层**：Existing 恪守持久化纯洁性彻底移除 `resources`，优于 Generated； + - **详情传输层**：Existing 采用契约规定的 `CourseDetailVO`，Generated 缺失 VO 层； + - **Controller 层**：Existing 严格收敛至 4 个端点，Generated 存在越界端点（DELETE 与 export）； + - **Service 层**：Existing 包含 32 位 UUID 分配、`cCode` 防重（40003）与学时正整数校验，Generated 仅为单表空壳； + - **Mapper 与前端**：Existing 包含逻辑删除过滤，前端页面收敛无用按钮并校验完备； + - **裁定**：坚决保留现有手工精细化对齐代码，拒绝使用 Generator 产物覆盖。 +3. **任务书更新与验收状态**： + - 更新 `docs/development/issue-01-03-course.md` 第 4 节与第 8 节（`Generator Pilot completed (PASS)`）。 +4. **最终质量验证**： + - 后端 Maven 编译：`BUILD SUCCESS`（8 模块全通过）； + - 前端 ESLint 检查：退出码 `0`（`0 errors, 0 warnings` 通过）； + - `git diff --check` 通过； + - `git status` 清晰，零 commit，等待授权。 + +--- + +## 三、文件变更清单与路径索引 + +### 1. `fix-generator-import-identity` 分支新增文件 +- [`RuoYi-Vue/sql/generator/kingbase/001_generator_identity_precheck.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem-worktrees/fix-generator-import-identity/RuoYi-Vue/sql/generator/kingbase/001_generator_identity_precheck.sql) +- [`RuoYi-Vue/sql/generator/kingbase/002a_gen_table_identity_patch.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem-worktrees/fix-generator-import-identity/RuoYi-Vue/sql/generator/kingbase/002a_gen_table_identity_patch.sql) +- [`RuoYi-Vue/sql/generator/kingbase/002b_gen_table_column_identity_patch.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem-worktrees/fix-generator-import-identity/RuoYi-Vue/sql/generator/kingbase/002b_gen_table_column_identity_patch.sql) +- [`RuoYi-Vue/sql/generator/kingbase/003_generator_identity_verify.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem-worktrees/fix-generator-import-identity/RuoYi-Vue/sql/generator/kingbase/003_generator_identity_verify.sql) +- [`RuoYi-Vue/sql/generator/kingbase/README.md`](file:///Users/wzb/Desktop/项目/RailwaySystem-worktrees/fix-generator-import-identity/RuoYi-Vue/sql/generator/kingbase/README.md) +- [`docs/generator-v2/01_kingbase_import_identity_patch.md`](file:///Users/wzb/Desktop/项目/RailwaySystem-worktrees/fix-generator-import-identity/docs/generator-v2/01_kingbase_import_identity_patch.md) + +### 2. `feat/issue-01-03-course` 分支相关文件 +- [`docs/development/issue-01-03-course.md`](file:///Users/wzb/Desktop/项目/RailwaySystem-worktrees/issue-01-03-course/docs/development/issue-01-03-course.md)（已更新 Pilot 执行与比对矩阵） +- [`/tmp/railwaysystem-generator/issue-01-03-course/`](file:///tmp/railwaysystem-generator/issue-01-03-course/)（代码生成沙箱隔离目录） + +### 3. 本地原始 Transcript 日志位置 +- **原始会话完整日志**: [`/Users/wzb/.gemini/antigravity-ide/brain/6b8b4a8c-efd8-4d41-a82d-b8f1e04d8a76/.system_generated/logs/transcript.jsonl`](file:///Users/wzb/.gemini/antigravity-ide/brain/6b8b4a8c-efd8-4d41-a82d-b8f1e04d8a76/.system_generated/logs/transcript.jsonl) +- **非截断完整日志**: [`/Users/wzb/.gemini/antigravity-ide/brain/6b8b4a8c-efd8-4d41-a82d-b8f1e04d8a76/.system_generated/logs/transcript_full.jsonl`](file:///Users/wzb/.gemini/antigravity-ide/brain/6b8b4a8c-efd8-4d41-a82d-b8f1e04d8a76/.system_generated/logs/transcript_full.jsonl) diff --git a/docs/ui-audit-screenshots/01_index.png b/docs/ui-audit-screenshots/01_index.png new file mode 100644 index 000000000..dbe5e7860 Binary files /dev/null and b/docs/ui-audit-screenshots/01_index.png differ diff --git a/docs/ui-audit-screenshots/02_person_teacher.png b/docs/ui-audit-screenshots/02_person_teacher.png new file mode 100644 index 000000000..86ae445af Binary files /dev/null and b/docs/ui-audit-screenshots/02_person_teacher.png differ diff --git a/docs/ui-audit-screenshots/03_person_student.png b/docs/ui-audit-screenshots/03_person_student.png new file mode 100644 index 000000000..f4ce348c2 Binary files /dev/null and b/docs/ui-audit-screenshots/03_person_student.png differ diff --git a/docs/ui-audit-screenshots/04_equip_classroom.png b/docs/ui-audit-screenshots/04_equip_classroom.png new file mode 100644 index 000000000..662fb1130 Binary files /dev/null and b/docs/ui-audit-screenshots/04_equip_classroom.png differ diff --git a/docs/ui-audit-screenshots/05_equip_site.png b/docs/ui-audit-screenshots/05_equip_site.png new file mode 100644 index 000000000..92e0929f0 Binary files /dev/null and b/docs/ui-audit-screenshots/05_equip_site.png differ diff --git a/docs/ui-audit-screenshots/06_equip_dormitory.png b/docs/ui-audit-screenshots/06_equip_dormitory.png new file mode 100644 index 000000000..000e5ac43 Binary files /dev/null and b/docs/ui-audit-screenshots/06_equip_dormitory.png differ diff --git a/docs/ui-audit-screenshots/07_equip_board.png b/docs/ui-audit-screenshots/07_equip_board.png new file mode 100644 index 000000000..6f3392bc8 Binary files /dev/null and b/docs/ui-audit-screenshots/07_equip_board.png differ diff --git a/docs/ui-audit-screenshots/08_equip_extra.png b/docs/ui-audit-screenshots/08_equip_extra.png new file mode 100644 index 000000000..23df922f3 Binary files /dev/null and b/docs/ui-audit-screenshots/08_equip_extra.png differ diff --git a/docs/ui-audit-screenshots/09_coursemgr_course.png b/docs/ui-audit-screenshots/09_coursemgr_course.png new file mode 100644 index 000000000..94a1b31c7 Binary files /dev/null and b/docs/ui-audit-screenshots/09_coursemgr_course.png differ diff --git a/docs/ui-audit-screenshots/10_coursemgr_plan_course_config.png b/docs/ui-audit-screenshots/10_coursemgr_plan_course_config.png new file mode 100644 index 000000000..7607170a3 Binary files /dev/null and b/docs/ui-audit-screenshots/10_coursemgr_plan_course_config.png differ diff --git a/docs/ui-audit-screenshots/10_coursemgr_plan_enrollment.png b/docs/ui-audit-screenshots/10_coursemgr_plan_enrollment.png new file mode 100644 index 000000000..87e2c2e25 Binary files /dev/null and b/docs/ui-audit-screenshots/10_coursemgr_plan_enrollment.png differ diff --git a/docs/ui-audit-screenshots/10_coursemgr_plan_lesson_form.png b/docs/ui-audit-screenshots/10_coursemgr_plan_lesson_form.png new file mode 100644 index 000000000..a6fd5fecd Binary files /dev/null and b/docs/ui-audit-screenshots/10_coursemgr_plan_lesson_form.png differ diff --git a/docs/ui-audit-screenshots/10_coursemgr_plan_main.png b/docs/ui-audit-screenshots/10_coursemgr_plan_main.png new file mode 100644 index 000000000..6a5405d52 Binary files /dev/null and b/docs/ui-audit-screenshots/10_coursemgr_plan_main.png differ diff --git a/docs/ui-audit-screenshots/10_coursemgr_plan_timetable.png b/docs/ui-audit-screenshots/10_coursemgr_plan_timetable.png new file mode 100644 index 000000000..53d598046 Binary files /dev/null and b/docs/ui-audit-screenshots/10_coursemgr_plan_timetable.png differ diff --git a/docs/ui-audit-screenshots/10_coursemgr_plan_timetable_table.png b/docs/ui-audit-screenshots/10_coursemgr_plan_timetable_table.png new file mode 100644 index 000000000..168250053 Binary files /dev/null and b/docs/ui-audit-screenshots/10_coursemgr_plan_timetable_table.png differ diff --git a/docs/ui-audit-screenshots/11_tool_build.png b/docs/ui-audit-screenshots/11_tool_build.png new file mode 100644 index 000000000..c2ede62b3 Binary files /dev/null and b/docs/ui-audit-screenshots/11_tool_build.png differ diff --git a/docs/ui-audit-screenshots/12_tool_gen.png b/docs/ui-audit-screenshots/12_tool_gen.png new file mode 100644 index 000000000..b2bbb977c Binary files /dev/null and b/docs/ui-audit-screenshots/12_tool_gen.png differ diff --git a/docs/ui-audit-screenshots/13_tool_swagger.png b/docs/ui-audit-screenshots/13_tool_swagger.png new file mode 100644 index 000000000..4a088675b Binary files /dev/null and b/docs/ui-audit-screenshots/13_tool_swagger.png differ diff --git a/docs/ui-audit-screenshots/14_self_equipment.png b/docs/ui-audit-screenshots/14_self_equipment.png new file mode 100644 index 000000000..aec8b5c78 Binary files /dev/null and b/docs/ui-audit-screenshots/14_self_equipment.png differ diff --git a/docs/ui-audit-screenshots/15_analysis_report.png b/docs/ui-audit-screenshots/15_analysis_report.png new file mode 100644 index 000000000..e8649447d Binary files /dev/null and b/docs/ui-audit-screenshots/15_analysis_report.png differ diff --git a/docs/ui-audit-screenshots/15_analysis_report_add_dialog.png b/docs/ui-audit-screenshots/15_analysis_report_add_dialog.png new file mode 100644 index 000000000..7769e01d7 Binary files /dev/null and b/docs/ui-audit-screenshots/15_analysis_report_add_dialog.png differ diff --git a/docs/ui-audit-screenshots/16_analysis_checkin.png b/docs/ui-audit-screenshots/16_analysis_checkin.png new file mode 100644 index 000000000..e13dbde7a Binary files /dev/null and b/docs/ui-audit-screenshots/16_analysis_checkin.png differ diff --git a/docs/ui-audit-screenshots/16_analysis_checkin_add_dialog.png b/docs/ui-audit-screenshots/16_analysis_checkin_add_dialog.png new file mode 100644 index 000000000..2e0801f26 Binary files /dev/null and b/docs/ui-audit-screenshots/16_analysis_checkin_add_dialog.png differ diff --git a/docs/ui-audit-screenshots/17_analysis_duration.png b/docs/ui-audit-screenshots/17_analysis_duration.png new file mode 100644 index 000000000..08d2c74e6 Binary files /dev/null and b/docs/ui-audit-screenshots/17_analysis_duration.png differ diff --git a/docs/ui-audit-screenshots/18_portrait.png b/docs/ui-audit-screenshots/18_portrait.png new file mode 100644 index 000000000..3bd6d1ff6 Binary files /dev/null and b/docs/ui-audit-screenshots/18_portrait.png differ diff --git a/docs/ui-audit-screenshots/19_system_dept.png b/docs/ui-audit-screenshots/19_system_dept.png new file mode 100644 index 000000000..a0defdf0f Binary files /dev/null and b/docs/ui-audit-screenshots/19_system_dept.png differ diff --git a/docs/ui-audit-screenshots/19_system_dict.png b/docs/ui-audit-screenshots/19_system_dict.png new file mode 100644 index 000000000..011bafb62 Binary files /dev/null and b/docs/ui-audit-screenshots/19_system_dict.png differ diff --git a/docs/ui-audit-screenshots/19_system_logininfor.png b/docs/ui-audit-screenshots/19_system_logininfor.png new file mode 100644 index 000000000..a734b56a4 Binary files /dev/null and b/docs/ui-audit-screenshots/19_system_logininfor.png differ diff --git a/docs/ui-audit-screenshots/19_system_menu.png b/docs/ui-audit-screenshots/19_system_menu.png new file mode 100644 index 000000000..c8237c96f Binary files /dev/null and b/docs/ui-audit-screenshots/19_system_menu.png differ diff --git a/docs/ui-audit-screenshots/19_system_operlog.png b/docs/ui-audit-screenshots/19_system_operlog.png new file mode 100644 index 000000000..086c3856a Binary files /dev/null and b/docs/ui-audit-screenshots/19_system_operlog.png differ diff --git a/docs/ui-audit-screenshots/19_system_role.png b/docs/ui-audit-screenshots/19_system_role.png new file mode 100644 index 000000000..a627a6f05 Binary files /dev/null and b/docs/ui-audit-screenshots/19_system_role.png differ diff --git a/docs/ui-audit-screenshots/19_system_user.png b/docs/ui-audit-screenshots/19_system_user.png new file mode 100644 index 000000000..91cfb2381 Binary files /dev/null and b/docs/ui-audit-screenshots/19_system_user.png differ diff --git a/docs/ui-audit-screenshots/20_train_auth.png b/docs/ui-audit-screenshots/20_train_auth.png new file mode 100644 index 000000000..3b243e22c Binary files /dev/null and b/docs/ui-audit-screenshots/20_train_auth.png differ diff --git a/docs/ui-audit-screenshots/21_monitor_job_manual.png b/docs/ui-audit-screenshots/21_monitor_job_manual.png new file mode 100644 index 000000000..7e3d91388 Binary files /dev/null and b/docs/ui-audit-screenshots/21_monitor_job_manual.png differ