railwaysystem/docs/_meta/final-release-readiness.md

# 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:** 课程管理 → 开班计划<br>**API:** `/train/plan/*` | **PENDING_FINAL_GATE** | Safe UI Polish 涉及页面，待最终发版门禁运行时验证 |
| **RTC-07** | Enrollment (参训人员) | **UI:** 课程管理 → 开班计划 → 参训人员 (Tab)<br>**API:** `POST/GET /train/plans/{planId}/enrollments...` | **PENDING_FINAL_GATE** | 内部 Tab 视图，Safe UI Polish 涉及页面，待最终门禁验证 |
| **RTC-08** | Scheduling (智能排课) | **UI:** 课程管理 → 开班计划 → 排课课表 (Tab)<br>**API:** `/train/lessons/*` 及 `/train/plans/{planId}/timetable` | **PENDING_FINAL_GATE** | 内部 Tab 视图，冲突 Soft Warning，待最终门禁验证 |
| **RTC-09** | Board (电子班牌) | **UI:** 设施设备 → 电子班牌<br>**正式路由:** `/train/board`<br>**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/`