fix(shadow): respect queue phases and compress input evidence

docs/runbooks/ft546-shadow-20260908-phase-storage-repair.md

@@ -0,0 +1,58 @@
+# 2026-09-08 影子阶段与存储修复
+
+适用：现场源码基线 `414b3bf`，分支 `optimize/wcs`，目录 `C:\project\FT546-WCS-SHANDOW`，Windows CMD + IDEA + Java 8 + Maven 3.6.0。
+
+本次更新仅用于继续影子测试。正式调度、PLC 通讯和生产数据库写入路径不变。本次没有现场 SQL 迁移、权限调整、清理历史数据、扩大容量上限或远程进程操作。
+
+## 修复后的行为
+
+1. 从现有只读视图增加采集 `issued`、`execution_status`。只有明确的 `0 / 1` 待下发阶段可产生新预测。已下发、已完成、生命周期不明、已到终点及无移动阶段记录为 `OBSERVATION_ONLY`，不产生虚拟寄存器写入，也不计入算法不一致。
+2. 保留队列已绑定的车辆；忙碌、禁止发送、低电量和故障门槛不放宽。绑定阶段按正式程序的发送规则，从车辆当前位置到当前终点预测，不再回到旧队列起点折返。跨楼层及两阶段交接当前只观察，仍需专门的状态机证据才能评价其新调度行为。
+3. 旧结果还原遵循 PLC 发送规则：`tsj` 的 `default02=1/2` 终点为 `09050<楼层>`，`8` 为 `07050<楼层>`。路径可在提升机入口结束，而实际发送端点会被改写，不能直接用路径末点当作发送末点。与本阶段终点不符的旧路径，以及待下发阶段起点已漂移的路径，记录为旧结果不可用。
+4. 新输入采用无损 gzip；同一次证据保存中的相同输入只存一份压缩正文，其余记录引用本批首条输入。原始 JSON 的哈希保持不变。使用现有表、同一事务，不增加生产访问权限。
+5. 安全等待/避让点只能通过 `shadow.traffic.safe-wait-sites`、`shadow.traffic.safe-yield-sites` 显式配置。默认空列表，状态显示 `UNCONFIGURED`。配置点必须是可通行数字站点且至少有两个相邻出口；这个校验不能代替现场人员确认物理安全。未取得现场确认前保持空列表。
+6. `/shadow/status` 和运行心跳新增 `runtimeIdentity`。本次 `buildId` 为 `ft546-shadow-20260908-phase-storage-v2`。`effectiveSettingsSha256` 自动计算，覆盖返回的非秘密调度、存储、端口及安全点配置；不包含数据库连接凭据、外部配置文件或已编译类的完整指纹。
+
+## 现场更新顺序
+
+与操作人员逐步进行，每一步确认结果后再进入下一步。只停止 `Ft546ShadowApplication`；不要停止 `RuoYiApplication`，不要使用 Stop All，也不要批量结束 Java 进程。
+
+1. 在 IDEA 中选中影子程序 `Ft546ShadowApplication` 的运行窗口，点红色停止按钮，确认这个影子进程退出。
+2. CMD 进入 `C:\project\FT546-WCS-SHANDOW`，先执行 `git status --short` 和 `git fetch origin optimize/wcs`。保留现场配置、忽略文件和 `shadow-evidence`。若有与本次源码重叠的本地修改，先备份并核对；不要 reset、clean 或强制覆盖。
+3. 使用交付消息指定的准确提交执行 `git merge --ff-only <提交号>`，再执行 `git log -1 --oneline` 核对。不要无条件更新到将来的其他提交。
+4. IDEA 刷新 Maven，保持原有 Java 8 和 Maven 3.6.0，编译 `ruoyi-wcs-shadow` 及其依赖。沿用此前已验证的离线依赖，不需要部署脚本或 JAR 包。
+5. 核对影子运行配置：主类仍为 `com.ruoyi.shadow.Ft546ShadowApplication`；数据库账号、生产只读库、证据库、18091 本机端口和存储上限沿用现场设置。新增安全点列表保持空，直到现场确认。
+6. 修正运行元数据后，仅启动这个影子配置。浏览器访问 `http://127.0.0.1:18091/shadow/status`。核对 `READY`、全部启动检查 PASS、上述 buildId，以及 `cycleDiagnostics.dispatch` 内各项计数。只观察时 `eligiblePhases=0` 可以是正常状态，不代表算法完成验证。
+
+## IDEA 中两个人工哈希字段
+
+历史运行的元数据不修改。审计发现此前配置哈希填入了源码归档哈希；新运行不要照抄或互换这两个值。
+
+- `shadow.evidence.run.artifact-sha256`：记录本次交付物的 SHA-256。源码运行时，可以使用当前准确提交的源码归档哈希，并在现场记录中注明 `source archive`，不能称为运行中 JAR 或编译类的校验值。
+- `shadow.evidence.run.configuration-sha256`：记录本次现场运行配置快照文件的 SHA-256。配置快照保留在现场受控目录，不提交到 Git，不发送含密码的文件。
+- 在 CMD 中可以使用 `certutil -hashfile "文件完整路径" SHA256` 计算实际文件的哈希。若用源码归档，可先运行 `git archive --format=tar -o "%TEMP%\ft546-shadow-source.tar" HEAD`，再对这个文件运行 certutil。归档仅用于现场计算元数据，不是额外的部署包。
+- 状态中的 `operatorArtifactSha256` / `operatorConfigurationSha256` 是上述人工输入，程序没有将其认证为实际运行产物。`buildId` 是代码内版本标签；`effectiveSettingsSha256` 是程序自动计算的配置摘要，两者与人工哈希分开显示。
+
+## 证据导出兼容性
+
+`shadow_input_batch.captured_json` 现在允许三种形式：旧版原始 JSON、`ft546-input-gzip-v1` 压缩信封、`ft546-input-ref-v1` 同批引用。`content_hash` 始终校验原始 JSON，不能对压缩信封直接算哈希后判定损坏。
+
+推荐从生产服务器本机浏览器或可访问本机 HTTP 的 AI 工具读取：
+
+```text
+http://127.0.0.1:18091/shadow/inputs/<cycle_id>
+```
+
+每次返回一条输入：`cycleId`、`runId`、`contentHash`、`hashVerified=true`、`capturedJson`（原始 JSON 字符串）。接口只查询证据库；拒绝非本机连接、缺失/跨运行/循环/多层引用、损坏哈希和超限解压。单份原始输入最多 8 MiB。
+
+如果 AI 只能查询 SQL，应同时导出引用记录和所指向的根记录，保留原样交给分析程序解码。仅按尾部时间窗口导出可能遗漏根记录。不要再假定 `captured_json` 始终直接包含 `maps/queues/vehicles`。
+
+同批根输入与引用在同一事务中写入，任一子表失败整批回滚。压缩格式不影响原始输入哈希、决定哈希和逻辑证据哈希。旧程序回退运行仍可新增旧格式输入；分析工具必须继续理解新旧两种物理存储形式。不要逐条删除某个根输入而保留引用。
+
+## 验证与剩余边界
+
+- 最终本地验证命令：`mvn -o -pl ruoyi-wcs-shadow -am test -Dshadow.replay.audit-directory=<本地审计导出目录>`。覆盖 WCS 核心、FT546 协议和影子模块；现场样本留在 Git 之外。旧 300 条归档已不在原附件路径，本次使用仍可读取的 2026-09-08 审计导出回放，未编造或补填其生命周期。
+- 新增回归覆盖生命周期隔离、已到终点、绑定车辆不可重分配、忙碌车辆保护、提升机端点改写、旧阶段路径、显式安全点、压缩还原、篡改/解压上限/引用校验和事务回滚。
+- 2026-09-08 审计导出的 25 条样本包含 17 份不同输入，离线回放保持 JSON 与哈希原样。输入字段按 SQL Server nvarchar 字节估算，从 3,294,254 字节降至 604,048 字节（18.34%）；此数字不包括其他表、索引、页开销、事务日志，也不代表数据库文件自动缩小。
+- 当日最后一次容量检查为 14.39 GiB / 16 GiB。压缩只降低后续增长；旧空间不释放，容量上限不变。再次达到保护上限仍会停止影子采集，需要另行评估归档方案，不能只调大阈值。
+- `READY` 只说明影子采集链路健康。正式版接管前还需本次新运行的有效待下发样本、路线与协议差异、拥堵/避让及特殊交接阶段证据；本修复不构成正式版上线批准。