railwaysystem/DEMO_RUNBOOK.md

# SYFJGYD 学员管理系统 — Java 21 / Spring Boot 4 隔离 QA 运行手册

本手册仅对应 `boot4-iot-fusion-archive` 的 `fix/iot-safety-hardening` 本地候选版本。
原 RailwaySystem 和历史实验工程只读；不执行 Push、Merge、共享部署或硬件操作。

## 当前验收边界

Round 5V-2 用户已明确批准仅对目标QA库执行005增量迁移，但备份/隔离恢复前提
尚未满足，当前状态为 `MIGRATION_AUTHORIZED_BLOCKED_RESTORE`，005未执行。
不能将 H2/替身测试、构建成功或登录页显示称为
Kingbase 事务/浏览器业务闭环验收。真实硬件验收始终未进行。
迁移前置、失败回滚和核验清单见 [迁移计划](docs/iot/ROUND5V_KINGBASE_MIGRATION_PLAN.md)。
**不要执行 qa-bootstrap 全量初始化、清空测试数据、重建库、重置已有账号或序列。**

## 1. 构建前提

- Java 21（本机验证 21.0.2）、Maven 3.9.x；全部模块统一 release 21。
- Node 22.23.2、npm 10.9.8（`build_ui/.nvmrc` / packageManager / lockfile）。
- Python 3.9+、本机 `redis-server`（新实例只监听 loopback 的独立端口）。
- 合法取得当前商业 JDBC 9.0.0；不向 Git 或公共 Maven 上传二进制。

从本工作树根目录执行（路径以实际 checkout 为准，不引用 RuoYi-Vue-master）：

```bash
java -version
mvn -version
export KINGBASE_JDBC_JAR='/absolute/path/to/authorized/kingbase8-9.0.0.jar'
bash scripts/bootstrap/install-kingbase-jdbc.sh
bash scripts/bootstrap/check-kingbase-jdbc.sh
mvn -B -f RuoYi-Vue/pom.xml -pl ruoyi-admin -am '-Dtest=Round5s*,Round5vAccommodationAtomicityTest,RealIotSecurityGateTest,FaceExtractClientMockTest,CommandRespHandlerMockTest,DmsHttpClientTest,DmsTokenManagerTest,TrainIotLockAuthBridgeMockTest' -Dsurefire.failIfNoSpecifiedTests=false package
python3 -m unittest discover -s scripts/qa -p test_qa_tools.py -v
```

驱动私有坐标：`cn.com.kingbase:kingbase8:9.0.0`；SHA256：
`e439bd1c48ce654748c4f333b874a61465702ceb18f29ee017c3f9bc47738c23`。
安装脚本先校验供应商文件，再用固定版本 Maven install plugin 安装到本机私有仓库。
`ruoyi-admin/lib` 不再是构建依赖来源。CI 由管理员合规预置同一私有依赖，缺失即失败。

```bash
cd build_ui
node --version
npm --version
npm ci --ignore-scripts --no-audit --no-fund
npm run build:prod
cd ..
```

不得用实验工程/node_modules1/node_modules2、服务器 symlink 或临时依赖目录替代
lockfile 安装。Quill 2 的转译配置与实验工程一致。Vue 2/CLI 4 的废弃依赖及旧版
node-ipc engine/ESLint peer 警告仍存在：本轮不做整套前端框架迁移，不声称无漏洞。

## 2. 凭据和只读身份检查

将 `qa-bootstrap/round5v.env.example` 的键名交给管理员，在 Git 外受保护文件中
填写真实 QA 配置并设置 owner-only 权限 0600。不要把密码放命令行、截图或报告。
脚本也兼容本机已有 `~/.railwaysystem-qa.env` 中的 `FUSION_QA_APP_PASSWORD` 和
身份加密键，但**不会复用其中可能指向旧库的 QA_DB_URL**。

```bash
python3 scripts/qa/qa.py inspect --config /protected/round5v.env
python3 scripts/qa/qa.py snapshot --config /protected/round5v.env
python3 scripts/qa/qa.py verify-snapshot --snapshot-dir .qa-runtime/snapshot-REPLACE_WITH_ACTUAL_ID
```

固定目标：`railwaysystem_fusion_qa_20261013`；固定运行账号：`fusion_qa_app`。
检查使用只读 repeatable-read 事务并 rollback，记录版本、schema、列、索引和计数；
不打印业务行。快照含两张受影响表的敏感内容，仅存 `.qa-runtime/`（目录0700，
数据0600）；其 XML 解析和 SHA 验证不等同于原生全库备份或数据库恢复演练。
在本轮已检查范围中未找到匹配的原生备份客户端，本机Docker守护进程不可用，
也未发现或取得可用的独立恢复实例。仅有两表快照不能通过恢复门禁。
需要提供已有且获准使用的恢复环境、匹配版本工具和受保护的QA库DDL管理配置；
不要创建数据库、猜测密码、提权或把业务账号当成迁移账号。

## 3. 启停隔离 QA（迁移批准并完成后）

```bash
python3 scripts/qa/qa.py start --config /protected/round5v.env
python3 scripts/qa/qa.py frontend
```

默认端口：后端18096、前端18088、独立 Redis16389，仅监听127.0.0.1；端口占用即
失败，不杀旧进程、不改共享 Redis。启动器先确认目标数据库和16列/4索引存在，
缺迁移拒绝启动；列/索引的完整定义仍须按迁移计划人工核验。PID 输出不代表就绪。

安全值强制为 MQTT Mock=true / enabled=false / real-device-write-enabled=false /
whitelist空 / protocol-verified=false / retry-task-enabled=false；人脸 HTTP关闭；
OpenAPI、QA危险接口、Druid控制台和Quartz自动启动关闭；旧DMS关闭。
继承环境中的 Spring/IoT/DMS/JVM 注入覆盖被过滤，数据库 URL/账号由命令行固定。
JWT和独立Redis密钥由安全随机数首次生成至 `.qa-runtime/runtime-secrets.env`，0600，
以进程环境注入，不写源码/命令行；数据库及身份密钥仅取受保护配置文件。
不得为演示去打开真实门禁或危险接口。

```bash
curl --noproxy '*' --fail http://127.0.0.1:18096/captchaImage
# 真实 Chrome 访问 http://127.0.0.1:18088 ，使用管理员单独提供的 QA 账号。
python3 scripts/qa/qa.py stop
```

stop只处理本脚本账本中且进程命令身份仍匹配的PID；不会清端口、杀其他Chrome、
停止实验工程或修改系统网络。JWT、访问日志、快照、浏览器证据均不进入Git。

## 4. 迁移后验收清单（未完成项不得标 PASS）

1. 管理员真实登录、getInfo/getRouters、原品牌菜单和首页图表；培训核心查询。
2. IoT九页：group/gateway/device/face/auth/command/accesslog/mqttlog/config，
   必须验证组件渲染及实际QA查询，不能把SPA fallback HTTP200当作无404证明。
3. 为本轮创建可追踪的合成业务样本，不复用/覆盖既有培训测试记录：报名、
   住宿预分配、入住、调宿、退宿、授权意图与`iotlocks.lock_command`流水。
4. 用实际Kingbase Mapper/Service/事务管理器覆盖迁移计划中的崩溃、并发、晚到ACK、
   提交/回滚场景；外部MQTT和人脸只能是可控替身。危险Mock HTTP端点保持关闭，
   ACK由隔离的Service测试驱动，不通过开放生产式控制接口来换取通过。
5. 受控Mock ACK成功只能证明软件闭环，不能证明真实门锁已授权或撤权。

现有 `Round5sExecutionIntegrationTest` 的文件型H2证据不是第4项的替代品；
`Round5vAccommodationAtomicityTest`证明异常传播/事务声明，不证明Kingbase回滚。

## 5. CI与当前阻塞

`.gitlab-ci.yml` 已改为显式web+RUN_FUSION_VALIDATION=true才允许的验证流水线；
Java21、私有JDBC预检及npm ci，**无部署job**。本轮未Push，也未触发/验证远程Runner。
005授权已明确；当前仍缺可用的原生备份/隔离恢复条件、已配置的授权DDL管理账号、真实Kingbase生命周期验证和
依托新QA后端的完整Chrome验收。迁移安全前提未满足时，单独前端会明确返回502，
不得用旧实验后端或伪造API响应冒充新版本验收。