17 KiB
17 KiB
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
- 领先提交清单：
e2d7e63d8e157417c5aa83fba536834951a2ea25-fix(db): 补齐Kingbase操作日志耗时字段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 - 变更目标：
为若依系统核心日志表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 执行，严格比对本地驱动与授权 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 顺序
[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 脚本； - 若目标库为全新库或历史旧库：按受控初始化手册逐步升级。
- 若目标库已经是 V2 基线：仅执行当前 Release Delta migration（即
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/boardAPI: /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 脚本进行回滚；
- 采用上一个已归档稳定制品进行平滑回退：
# 恢复后端稳定 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 (发布产物清单)
- 后端 Jar 包：
RuoYi-Vue/ruoyi-admin/target/ruoyi-admin.jar - 前端静态制品：
build_ui/dist/ - 当前发布 Delta Migration：
RuoYi-Vue/sql/system/kingbase/001_sys_oper_log_cost_time.sql - 历史引导/升级/验收资产包：
RuoYi-Vue/sql/train/v2/*,RuoYi-Vue/sql/generator/kingbase/* - 部署配置与运维脚本：
deploy/restart-all.sh,deploy/nginx.conf.example,scripts/bootstrap/check-kingbase-jdbc.sh,.gitlab-ci.yml - 版本基线 HEAD：
FINAL_HEAD_PENDING(当前开发基线d162954cd1e26c6948408a8304ca333ba9fe7a40) - 测试与准备报告：
docs/_meta/final-release-readiness.md,docs/_meta/deployment-gate-checklist.md - Browser 审计报告：
docs/ui-audit-screenshots/