blp/railwaysystem
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
29ce31f00efff3dae2b1b06b57fec95ff6a5e58a
railwaysystem/docs/_meta/final-release-readiness.md
T

17 KiB
Raw Blame History

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
  • 变更目标：
    为若依系统核心日志表 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 脚本；
    • 若目标库为全新库或历史旧库：按受控初始化手册逐步升级。
  • 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 脚本进行回滚；
  • 采用上一个已归档稳定制品进行平滑回退： 
    # 恢复后端稳定 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/
Reference in new issue View Git Blame Copy Permalink