# 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 与前端静态文件：<br>`cp ruoyi-admin.jar ruoyi-admin.jar.bak`<br>`cp -r frontend frontend.bak` | 检查备份文件生成成功 |
| **`DEPLOY_STEP_04`** | **CI 构建物拉取/生成** | 运行流水线或获取当前版本产物 `ruoyi-admin.jar` 与 `dist/` | 校验产物 MD5/SHA256 与构建日志 |
| **`DEPLOY_STEP_05`** | **前端静态资源更新** | 清理并覆盖部署：<br>`rm -rf /data2/wzb/deploy/frontend/*`<br>`cp -r build_ui/dist/* /data2/wzb/deploy/frontend/` | 确认 `frontend/index.html` 存在 |
| **`DEPLOY_STEP_06`** | **后端 Jar 包发布** | 将新构建 Jar 拷贝到发布目录：<br>`cp ruoyi-admin.jar /data2/wzb/deploy/backend/` | 确认物理文件更新且大小正常 |
| **`DEPLOY_STEP_07`** | **执行平滑重启调度** | 赋予权限并调用统一调度脚本：<br>`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/*`<br>`/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`**，以避免锁表与元数据不可逆破坏。