初始化系统融合软件代码仓库

docs/图片直传协商与准备取图.md

@@ -0,0 +1,69 @@
+# 图片直传协商与准备取图
+
+PXHJ 仍负责操作，采集网关负责传递协商，接收节点负责收原图。准备阶段不需要先启动正式试验，也能从接收节点取图做配置和标定。真实融合算法另行实现。
+
+```mermaid
+sequenceDiagram
+    participant D as 嵌入式采集器
+    participant G as 采集网关
+    participant P as PXHJ 后端
+    participant C as 总控服务
+    participant N as 接收节点
+    D->>G: 请求图片上传地址（加密协商）
+    G->>P: 原字节转发
+    P->>P: 按原登记来源和密钥认证
+    P->>C: 登记短期原图接入任务
+    C->>N: 心跳计划下发接收许可
+    N->>C: 图片入口已就绪
+    C-->>P: 接收节点的 IP、UDP 端口和许可期限
+    P-->>G: 加密地址回复
+    G-->>D: 回到专用协商套接字
+    D->>N: 原有加密 JPG 分片直接上传
+    P->>N: 准备页面查询原图（内部签名请求）
+    N-->>P: 原图元数据、JPEG
+    P->>P: 缓存完整验签 JPEG 后发布图片编号
+    P-->>P: 沿原 image-frames 接口供页面使用
+```
+
+## 使用流程
+
+1. 主服务、网关和节点按现有方式部署。节点自动注册时同时上报图片入口，总控的主电脑也可以接收。
+2. PXHJ 保存采集器来源和原密钥，现有 UDP 网关映射继续负责数据、心跳与协商。采集器的专用协商套接字发送地址请求。
+3. 总控把原图接入算作一路任务，和其他任务一起受每台机器配置路数限制。没有空位时回复等待，采集器继续用原图片地址。
+4. 节点准备好端口和认证许可后，下一次协商返回上传目标。采集器直接向节点上传，完整图片不经过网关。
+5. PXHJ 的准备页面继续使用原图片查询入口。后端先向当前节点取齐精确帧并验签，再发布临时图片编号；后续按编号返回同一份快照。页面不接触内部服务凭证或设备密钥。
+6. 路数调整触发迁移时，短暂给采集器两个上传目标。PXHJ 继续读旧节点；新节点收到首帧后切换，旧目标撤销。
+
+原图接入与正式试验启停独立。后续融合任务可读取这份原图接入结果，避免为准备页面再上传完整的第二份视频。目前演示任务与原图接入是两类任务，各自占用配置路数；未实现跨任务复用融合处理槽位。
+
+## 配置与端口
+
+| 项目 | 默认值 | 用途 |
+|---|---:|---|
+| 网关 UDP | 19002 | 数据转发及短小协商报文 |
+| PXHJ 采集 UDP | 19001 | 原协议解析与协商认证 |
+| PXHJ 图片 UDP | 6020 | 原图片接收、协商失败回退 |
+| 主节点图片 UDP | 19100 | 主节点 HTTP 18100 + 1000 |
+| 子节点图片 UDP | HTTP 端口 + 1000 | 各实例独立原图接收 |
+
+节点可用 `fusion.image-port` 或安装参数 `-ImagePort` 单独指定图片端口。`fusion.image-port=0` 为自动化测试的系统分配端口。多网卡环境使用 `-AdvertisedHost` 指定采集器和 PXHJ 均可访问的 IPv4，不能发布仅本机可见的地址。需要允许对应 UDP 和节点 HTTP 端口。
+
+嵌入式新增 `[image_negotiation]`：`enabled`、`gateway_host`、`gateway_port`。默认关闭，已有设备保持原上传方式；启用前确认网关映射、节点地址和网络连通。关闭或协商失败时回到 `[image_upload]` 的原上传目标。
+
+如果固定采集数据的 `fixed_json.udp_host` 改为网关，必须单独把 `image_upload.udp_host` 设置为 PXHJ 图片接收机器的 IP。它不能继续继承固定数据的网关地址，否则回退图片会投向网关的 6020，而该入口并不接收图片。
+
+## 协议与边界
+
+- 在原 PXHJ-FND/1 中加入 `0x14` 地址请求、`0x15` 地址回复；沿用原 SM4、HMAC-SM3、CRC 与采集器编号。图片 `0x12` 分片格式不变。
+- 请求携带协议版本、设备启动号、递增序号、请求号与时间；回复回显本次请求并附总控身份、代次、任务版本、有效期和最多两个目标。
+- 地址许可 8 秒，采集器约每 1.5 秒请求续期；有效 WAITING 立即回退，没有许可或旧许可到期时使用原图片上传地址。无效回复被忽略，不能延长既有许可。连续 30 秒没有认证协商释放来源任务。
+- 节点只接受当前任务许可的来源 IP、采集器编号和密钥。先验签解密，再组装图片；不完整、过期、CRC 或 JPEG 校验失败的帧不供页面使用。
+- 原密钥只在经过签名认证的后端请求和执行计划中传递，不写总控快照、数据库或浏览器响应。
+- UDP 缺片仍会丢帧；本阶段没有图片分片重传。直接上传分散了网关压力，但节点和链路的实际容量仍需用现场画面进行压测。
+- 当前每个登记采集器对应一路原图。原协议没有独立相机通道号，多相机标识需要后续明确协议扩展。
+- PXHJ 原图快照最长保存 30 秒，总计不超过 4096 张或 64 MiB，达到预算时可提前淘汰。快照权限沿用原图片入口；旧编号不会被替换成新图片。节点私有接口仍在任务撤销后拒绝旧版本。
+- 准备取图的路由查询、元数据、精确 JPEG 和一次允许的重试共享 1800 ms 预算，完整 HTTP 正文也受超时限制。仅已验签的精确帧 404 可刷新元数据重取一次。
+
+## 验证范围
+
+本机验证覆盖真实加密分片、节点收图、准备取图代理、容量和迁移、认证失败与许可撤销。2026-10-15 已在实际 RK3588 构建完整 ARM 程序、部署并开启协商，通过现有 PXHJ 准备页面取到直传原图；视频输入为已有文件经 RTP 送入真实板卡。当前结果见 [开发板图片协商联调记录](开发板图片协商联调记录.md)。真实摄像机、真实融合和多台物理电脑性能验收另行进行。

docs/开发板图片协商联调记录.md

@@ -0,0 +1,86 @@
+# 开发板图片协商联调记录
+
+日期：2026-10-15。本文记录实际 RK3588 开发板与现有 PXHJ 的联调。
+
+## 实际部署
+
+| 位置 | 服务 | 入口或配置 |
+|---|---|---|
+| 开发板 192.168.7.165 | ARM64 `px_JKGL` 完整程序 | 原有 RTP 视频入口 UDP 9200 |
+| 电脑 192.168.7.222 | 总控兼执行节点 | HTTP 18100 / 图片 UDP 19100，容量 2 |
+| 同一电脑 | 子节点 A | HTTP 18120 / 图片 UDP 19120，容量 3 |
+| 同一电脑 | 子节点 B | HTTP 18121 / 图片 UDP 19121，容量 3 |
+| 同一电脑 | 网关 | HTTP 18110 / 协商 UDP 19002 |
+| 同一电脑 | 原 PXHJ | 前端 5178、后端 8088、采集 UDP 19001、备用图片 UDP 6020 |
+
+板上已开启 `image_negotiation.enabled=true`，协商指向 `192.168.7.222:19002`；图片回退地址明确为 `192.168.7.222:6020`。固定数据和心跳继续使用原来的 `19001`。完整原图经协商后直接发给接收节点，网关只中转短协商报文。
+
+三个 Java 执行实例运行在同一台电脑，使用原稳定身份和数据目录；实际路数配置是 2/3/3。开发板是真实硬件，本次视频输入是已有 `1.mp4` 经 FFmpeg/RTP 送入开发板，经过板上程序解码、压缩、加密和分片。尚未进行物理摄像机、多台物理电脑、带宽容量或真实融合验收。
+
+## 程序部署与回退材料
+
+ARM 程序在目标板隔离目录构建后才激活，保留原有串口、RTP、启动器和程序内 1 GiB 日志保留功能。ARM 日志测试 9 项通过；图片协商测试 8 项通过，1 项可选 Java 互通夹具跳过。Windows 的 Java/C++ 互通验证已另行通过，板上实际协商和原图链路也已跑通。
+
+- 当前 ARM 二进制 SHA256：`6d28db56f9cf20cde843d432dcf148e7a72a3d54e91c37996a18463b0dc00972`。
+- 板上构建、候选和原文件备份目录：`/home/Tronlong/SY26-PX-Collect/runtime/image-route-stage-20261015-013802-b11a5ace`。
+- 本机状态证据：`runtime/board-image-route/deployment-state.json`、`live-board-check.json`、`arm-artifacts/activation-result.json`。
+- 激活与回退工具见 [嵌入式部署步骤](../scripts/嵌入式图片协商部署步骤.md)。回退需要显式运行工具，未因验证通过而自动回退。
+
+没有更改设备密钥、重置节点身份或删除采集数据。PXHJ 网关登记通过已登录的正式配置接口加入当前板卡，保留原选项。
+
+## 准备阶段取图
+
+使用现有试验 `SY_20261012_000005` 的第一轮准备页，轮次仍为 `PENDING`，无需启动正式试验。现有视频采集模块为 `03`。
+
+首次主节点收图后，真实页面取得 `remote-` 图片编号，原图接口返回 JPEG 200，页面解码尺寸为 **480 × 853**。已核对来源连接、采样时间、接收时间、长度和 SHA256，排除了旧 6020 历史图片。证据在 `runtime/board-image-real-verification/preparation-main.json` 及同名截图。
+
+本次只观察准备页，没有保存视频确认、标定、试验配置或开始/结束试验。现有另一轮 `RUNNING` 保持原状态。
+
+## 主节点切换到 A
+
+通过临时调整各节点容量触发正常迁移，没有直接修改任务归属；完成后恢复 2/3/3。
+
+北京时间 **09:49:44—09:50:09** 的节点观测记录了 110 张不同新帧：主节点版本 1 为 17 张，A 节点版本 2 为 93 张。A 的第一帧接收时间为 **09:49:48.389**。新旧节点交接的两条成功帧记录相隔 232 ms，全窗口成功新帧记录最大间隔 438 ms；这是观察间隔，不是端到端延迟指标。
+
+切换后旧主节点/版本 1 的私有图片接口返回经过签名核验的 404，证明旧许可已撤销。另一个三分钟基线窗口记录了 345 张主节点与 A 的原图。两组共 455 张记录已独立核对 JPEG 解码、尺寸、字节数和 SHA256，全部通过。独立审计见 `runtime/board-image-observation/audit-first-migration.json`。
+
+首次页面 30 秒检查启动于这次切换完成之后，30/30 取得新图，只作为 A 稳定期证据；不把它当成覆盖主节点到 A 全过程的页面证据。节点观察工具会重查短暂无帧，记录并未保存每一次 HTTP 尝试，因此也不以工具退出 0 声称所有尝试都返回 200。
+
+## 联调发现的取图窗口
+
+后续 A 稳定期精确取图检查出现过 **1/30 次 404**：页面刚取得帧号，节点仅保留的最近三帧就已淘汰那一帧。该时段没有发生 A 到 B 迁移；旧文件名中含 `a-to-b` 的记录不代表第二次迁移通过。
+
+PXHJ 已改为先取得完整、验签通过的原图快照，再公布这个图片编号。缓存中的每个编号对应固定字节，节点淘汰和任务切换不再影响这份快照。缓存最长保存 30 秒，同时限制 4096 张和 64 MiB，达到预算时可以提前淘汰；权限沿用原图片入口。完整 HTTP 正文受查询预算限制；批量取图结束时也会去掉本批已被预算淘汰的编号，避免公布悬空地址。
+
+修复相关 24 项测试全部通过；全后端 **411 项，失败 0、错误 0、跳过 30 项**，已以达梦依赖打包并替换实际 PXHJ 后端。跳过项仍是原有外部环境测试，不能视为现场验收通过。构建日志为 `runtime/board-image-route/pxhj-snapshot-package.log`，测试报告在 `runtime/pxhj-image-build/surefire-reports`。修改仍位于原 `fusion.service` / `fusion.client` 分层，XTRH Java 注释占比 21.53%，PXHJ fusion 业务 28.83%。
+
+重启后重新经正式登录恢复准备页。北京时间 **10:13:52—10:14:22**，30/30 次取得新鲜远程原图及精确 JPEG 200，30 个不同 SHA；601 次 DOM 采样均有已解码图片，浏览器 HTTP 错误、页面 JS 错误和试验业务写入均为 0。20 秒前的同一公开编号重取返回 200，SHA 与当时完全相同。证据为 `preparation-snapshot-stable-a*`，旧失败窗口原样保留。
+
+## 修复后复测与 A 到 B
+
+使用随机请求号和数字 Unix 毫秒门闩联动浏览器采样与正常容量操作，避免人工启动先后差使页面漏掉切换瞬间。实际页面窗口为北京时间 **10:16:18.043—10:17:03.051**，包含以下完整交接：
+
+| 事件 | 北京时间 | 结果 |
+|---|---|---|
+| 浏览器先确认 A 原图，再启动门闩 | 10:16:18.043 | A / 版本 2；随后执行已授权容量调整 |
+| B 收到完整首帧 | 10:16:21.255 | B / 实际版本 4，图片已就绪 |
+| 观察到 B 已接管 | 10:16:21.306 | 当前原图路由切到 B |
+| 旧 A 私有接口核验 | 10:16:21.530 | 版本 2 返回已验签 404，旧许可撤销 |
+| 重新读取切换前公开图片编号 | 10:16:30.058 | 200，SHA 与切换前字节完全相同 |
+| 浏览器窗口结束 | 10:17:03.051 | 持续取得 B 新图 |
+
+45 次页面检查均为新鲜远程原图、精确 JPEG 200，45 个不同 SHA，接收时间距检查最大 357 ms。899 次 DOM 采样没有观察到空图或未解码图片，实际最大采样间隔 197 ms；浏览器 HTTP 错误为 0。这是该观察窗口的结果，不承诺任意负载和网络条件下绝对不丢帧。新证据前缀为 `runtime/board-image-real-verification/preparation-snapshot-migration-a-to-b`，包含数字门闩、逐次数据、DOM、HTTP、旧图重取及汇总。
+
+同时节点 35 秒窗口保存 157 张不同新帧：A 13 张、B 144 张。全部独立完成 JPEG 解码、尺寸、长度和 SHA256 核对；交接两条成功帧记录相隔 227 ms，全窗口最大成功新帧记录间隔 644 ms。接收和采样时间存在板卡/电脑钟差，不能用这些数值宣称网络延迟。节点证据为 `runtime/board-image-observation/real-a-to-b/summary.json`、`frames.jsonl` 和逐帧 JPG。
+
+## 最终状态
+
+- 板上协商保持开启，当前原图由 **B：192.168.7.222:19121** 接收，原图任务状态 `READY`、版本 4。
+- 主节点、A、B 和网关全部在线；容量恢复 **2/3/3**，B 占用 1 路，其他占用 0，预留为 0；没有为验证创建额外正式视频任务。
+- PXHJ 仍在现有第一轮准备页，截图见 [preparation-b.png](../runtime/board-image-real-verification/preparation-b.png)。页面原图 480 × 853，正式图片接口 200，已解码。
+- 达梦只读前后比较确认：当前准备轮次及冻结装备/采集模块绑定未变，原运行中轮次及绑定未变，仍有 1 轮运行中。正式网关路由保留为当前板卡的 31001 转发源端口，没有清除采集记录。
+- 板上程序与当前 FFmpeg 文件输入保持运行，便于继续从 PXHJ 查看；真实融合、仿真目标叠加和录像仍未实现。
+
+轮次和绑定终检在 `runtime/board-image-real-verification/trial-integrity-final.json` 与 `trial-business-invariants.json`。旧帧私有接口的 404 是许可撤销验证，和此前已修复的公开原图偶发 404 含义不同。
+
+网关最后约 73 秒只读增量检查中，接收、转发和回包各增加 48，错误增量、队列丢弃和未知来源均为 0；整个进程累计错误为 5，记录未给出逐条原因，因此不声称全程网关零错误。B 最终图片接收拒绝和队列丢弃均为 0。详细计数见 `real-a-to-b/gateway-post-migration-delta.json` 与 `node-final.json`，没有重置计数来隐藏历史记录。

docs/本机验证记录.md

@@ -0,0 +1,155 @@
+# Java 后台服务本机验证记录
+
+## 图片直传协商版本：2026-10-15
+
+本次增加采集器地址协商、节点直接认证接收原 JPG 分片，以及 PXHJ 原图片 API 的私有回源代理。正式试验未开始时原图任务也可用。网关仅转发短小协商报文，图片直接上传当前接收节点；动态迁移在候选端口就绪后短暂双发，候选收到完整首帧后切换取图。
+
+| 验证 | 结果及范围 |
+|---|---|
+| XTRH 全部 Java 测试与打包 | 38 项，失败 0、错误 0、跳过 0 |
+| PXHJ 后端全回归与达梦配置打包 | 403 项，失败 0、错误 0、跳过 30；产物在 `runtime/pxhj-image-build`，测试数据使用隔离 H2 |
+| 节点原图集成 | 随机 HTTP/UDP 端口的真实主服务；未启动正式试验即可接收独立 PXHJ WireCodec oracle 生成的加密分片，HTTP JPEG 与原字节一致；匿名 401、无帧或旧版本为签名 404 |
+| PXHJ 协商和准备取图 | 新增 11 项；真实 UDP、原设备密钥及来源认证、可信中转、防重放、会话权限和 opaque 原图回源；总控/节点使用随机端口签名 HTTP 替身，此项属于分段验证 |
+| Windows 嵌入式独立组件 | Qt 5.15.2 / MSVC / OpenSSL，7 个业务用例，另含 init/cleanup 共 9 项通过；C++ 与实际 PXHJ Java WireCodec 双向互操作 |
+| 前端 | 构建和既有 `fusion-operations-ui.mjs` 回归通过；使用正式组件及 API 拦截，原图与演示预览按类型显示 |
+| 中文注释统计 | XTRH 主 Java 21.53%（594/2759）；PXHJ fusion 主 Java 29.46%（476/1616） |
+
+安装脚本还在两个未启动的隔离目录验证：HTTP 18900 默认生成图片端口 19900；worker 显式 `-ImagePort 29920` 正确写入配置。部署产物 SHA256 已与本次构建逐一核对，四个 XTRH 实例及 PXHJ 均一致；匿名图片 API 返回 401，后端会话入口和前端页面返回 200。
+
+已按原稳定身份、数据目录及配置升级本机总控 18100、网关 18110/19002、节点 18120/18121 与 PXHJ 8088 后端。图片 UDP 实际绑定 19100、19120、19121。只读签名状态确认三个执行节点、一个网关在线；升级后 PXHJ 达梦缓存年龄核对值为 955 ms，在线节点 3、网关 1。原有 RUNNING 轮次升级前后都是 1；前端进程 5178 持续运行。
+
+当前节点配置容量实际为主节点 2、A 3、B 3，合计 8；这是核对时保存的管理员配置，升级没有用安装默认值覆盖。当前原图和视频运行任务为 0，设备上传路径尚未切换。实际端口和容量可以随后续操作变化。
+
+没有连接或部署 ARM 板子，也没有进行物理多机、真实图片并发容量或融合算法验收。嵌入式协商默认 disabled；启用前必须独立保留 PXHJ 原图片回退地址。Windows 独立组件及本机分段协议验证不能替代目标板和现场整链联调。
+
+变更前 XTRH 源码、原前端文件、部署前 JAR 和发布脚本备份在 `E:\CodexHome\backups\xtrh-image-negotiation-20261015`；PXHJ 本次实施后源码快照标记为 `pxhj-image-implementation`，不能当作实施前源码备份。
+
+以下为 2026-10-14 阶段的历史记录，测试数量和进程状态以本节新版本为准。
+
+验证日期：2026-10-14。工作空间：`E:\Codex\xtrh`。
+
+这份记录覆盖本项目后台服务和部署脚本。验证使用一台 Windows 电脑上的多个独立 Java 进程，以及本机 UDP 套接字。真实采集器、多台物理电脑、仿真系统和真实视频融合不在这份记录的验收范围内。
+
+当前正式视频融合、仿真数据协议与录制未实现。播放信息由节点先提交对外地址和任务就绪结果，总控登记有效播放地址，再由 PXHJ 后台通过签名轮询同步登记；主动推送回调未实现。真实 PXHJ 业务服务与实际总控、节点的业务串联使用隔离 H2 验证；经用户确认，主达梦后端现已加载新版并接通总控，但真实采集来源未切换。
+
+## 自动化测试
+
+使用 Java 25.0.2 执行 Maven，项目按 Java 17 目标编译。增加主节点执行能力后完整 `test` 共 24 项通过，失败 0、错误 0；新版已经打包并升级正式本机总控，部署结果见文末。
+
+| 测试类 | 数量 | 主要验证 |
+|---|---:|---|
+| `CoordinatorTest` | 10 | 容量预留、超额排队、准备完成后切换、容量不足保留输出、迁移目标掉线、旧会话/版本拒绝、轮次结束与 UDP 解耦、租约到期、系统时间回退、持久化恢复和上下文重确认、未确认的空路由不作为清空指令 |
+| `GatewayTest` | 3 | 1～60000 字节不透明二进制 UDP 转发、独立转发源端口、反向回执、未知来源丢弃、总控失联继续转发、重启恢复路由、未确认路由不覆盖缓存、同版本号但明确确认的空路由仍撤销原转发 |
+| `ServiceSecurityTest` | 3 | 完整请求/响应签名、一次性随机数防重放、方法/地址/参数/正文篡改拒绝、过期请求拒绝 |
+| `PeerClientTest` | 1 | HTTP 头不发送明文凭证，拒绝无签名、错误密钥、错误随机数、正文和状态不匹配的响应 |
+| `WorkerTest` | 2 | 准备转为运行后播放连接读取当前任务，延迟到达的计划不能延长过期授权 |
+| `WorkerCapabilityTest` | 4 | 总控默认有执行能力、可关闭执行能力及媒体接口/线程池、独立 worker 不受总控开关影响、gateway 无执行能力 |
+| `CoordinatorWorkerIntegrationTest` | 1 | 随机端口主进程签名自注册、唯一主身份、任务 READY、同端口实际 JPEG 解码、结束撤销、拒绝伪造主身份 |
+
+测试报告保存在构建目录 `target/surefire-reports`，该目录不提交仓库。
+
+代码已按业务及 controller / service / dao 分层，原 `Coordinator`、`Gateway`、`Worker` 对应当前的 `control.service.CoordinatorService`、`gateway.service.GatewayService`、`node.service.WorkerService`。测试放在对应 service、config、security 或 client 包内。当前报告已确认原 19 项与新增 5 项全部通过。
+
+## 主总控兼任执行节点
+
+新增集成测试在随机 HTTP 端口启动真实 Spring Boot 总控，容量 1，关闭 mDNS，使用独立临时目录和测试凭证。总控进程自身自动通过签名请求注册为唯一 `COORDINATOR` 执行节点，节点 ID 等于总控服务 ID，不需要额外执行进程。下发一条隔离的 PENDING 上下文后任务进入 READY，播放地址使用同一个实际随机端口，实际 HTTP MJPEG 首帧能由 ImageIO 解码；结束上下文后播放地址撤销。主身份冒充普通 WORKER、另一个身份登记 COORDINATOR 均被拒绝。
+
+四项能力条件测试确认：总控默认同时有执行服务、媒体控制器和媒体线程池；关闭 `fusion.coordinator-worker-enabled` 后这些组件都不加载，控制服务保留；普通 worker 即使该开关为 false 也保持执行能力；gateway 始终无视频执行组件。
+
+安装脚本在独立、未启动的测试安装目录中验证：默认总控输出执行开关 true，`-CoordinatorOnly` 输出 false，worker 使用该参数被拒绝。未启动这些安装目录的进程，也未修改正式节点容量、任务或路由。
+
+PXHJ 新增业务已按 controller / service / dao / config / security 分层，针对性验证如下：
+
+| 测试类 | 数量 | 结果与范围 |
+|---|---:|---|
+| `FusionServiceTest` | 10 | 通过；权威试验配置、节点容量、状态同步和恢复等业务规则 |
+| `FusionAccessTest` | 5 | 通过；正式接口权限、会话、CSRF 与允许访问的范围 |
+| `FusionRelayUdpIntegrationTest` | 2 | 通过；真实 UDP 接收中的加密采集报文与心跳认证，以及动态配置的中转回程地址 |
+| `FusionBusinessIntegrationTest` | 1 | 通过；真实 PXHJ 业务服务和正式接口层连接实际总控、节点的业务串联 |
+
+前三类合计 17 项，业务串联另 1 项。业务串联以显式启用方式运行，与默认常规回归分开核对。
+
+PXHJ 全后端回归和打包已在独立目录 `runtime/pxhj-build` 完成。已读取该目录的 Surefire XML 汇总：392 项测试，失败 0、错误 0、跳过 30 项。常规回归默认跳过实时外部服务和达梦等 opt-in 测试；不能把跳过项算成已验证的真实环境能力。新版产物 [pxhj-server-0.1.0.jar](E:/Codex/xtrh/runtime/pxhj-build/pxhj-server-0.1.0.jar) 已生成。
+
+回归过程中修正了已有报告测试的比较对象：对比 DAO 的原始报告事件，而不是执行 DTO 派生的 `eventParameters`；产品业务代码没有因此改动。修正后完整回归通过。
+
+## PXHJ 真实业务串联
+
+`FusionBusinessIntegrationTest` 显式连接隔离验证总控及两个独立 Java 节点。PXHJ 使用实际 Spring 业务服务与 MockMvc 正式接口层，执行登录、会话及 CSRF 校验；业务数据写入独立 H2，正式试验由既有业务服务创建，使用保存的固定方案、装备和冻结绑定。
+
+验证过程通过：按已绑定装备配置五路演示视频，准备阶段由 A 处理两路、B 处理三路；各路返回实际 MJPEG 流，读到完整 JPEG 首帧并确认首尾标记。通过正式轮次开始接口后五路进入运行状态；在 PXHJ 接口中调整为 A 一路、B 四路，一路自动迁移，版本递增，迁移后各路仍能读取 JPEG。正式结束轮次后撤销旧播放地址，远端任务也结束。清理时恢复验证节点容量和路由。
+
+这验证了真实业务实现到后台节点的链路，未启动浏览器走人工页面流程，不属于物理多机或真实视频融合验收。
+
+## 结构与注释核对
+
+节点身份文件操作已下沉到 `common.dao.NodeIdentityDao`；H2 文件地址由 `common.dao.StateStore.open(Path, ObjectMapper)` 组装。`common` 和 `discovery` 已整理格式与关键中文注释，解释身份与启动会话、持久化失败、未认证广播、多网卡地址选择、认证后总控去重以及服务根地址校验。本项为源码与统计核对，不等同于重构后的运行回归。
+
+按 `scripts/Measure-Comments.ps1 -SourceRoots @(...) -MinimumPercent 20` 运行，当前统计如下：
+
+| 目录 | 完整注释行 | 非空源码行 | 比例 |
+|---|---:|---:|---:|
+| `common` | 69 | 290 | 23.79% |
+| `discovery` | 80 | 374 | 21.39% |
+| 全部 XTRH 主 Java | 429 | 1964 | 21.84% |
+| 当前 PXHJ 新增 fusion 业务 | 370 | 1101 | 33.61% |
+
+统计包含以注释标记开头的整行注释、Javadoc 及块注释边界，不包含空行或代码末尾的行内注释。XTRH 全部主 Java 和 PXHJ 新增 fusion 业务均达到约 20% 的要求；这些数字不包含两项目的测试文件和前端文件。
+
+## 独立进程与自动发现
+
+通过部署脚本启动以下四个真实 Java 进程：
+
+| 实例 | 角色 | HTTP 端口 | 其他配置 |
+|---|---|---:|---|
+| coordinator | 总控 | 18200 | 隔离验证集群 |
+| gateway | 采集网关 | 18210 | UDP 接收入口 19202 |
+| worker-a | 节点 A | 18220 | 初始容量 2 路 |
+| worker-b | 节点 B | 18221 | 初始容量 3 路 |
+
+网关和两个节点配置中均没有 `fusion.coordinator-url`。通过 mDNS 自动发现总控，完成带签名的身份校验和自动注册；总控快照确认两个节点、一个网关在线。中文节点名称保存与上报正确。
+
+在隔离验证集群中下发五路后台演示视频任务，节点 A 处理两路、节点 B 处理三路。通过实际 HTTP 播放连接读取到 MJPEG 帧。运行中将 B 容量修改为四路、A 修改为一路，总控自动迁移任务，最终保持五路可播放，无需重启 Java 进程。
+
+上述初始验证使用明确标记的本机测试上下文；后续已由前述 PXHJ 真实业务串联补充正式权限、保存绑定和轮次关联的验证，业务数据仍限于隔离 H2。
+
+## UDP 与轮次结束
+
+在隔离网关中配置一条本机验证路由，目的端为临时 UDP 套接字，未向 PXHJ 正式采集入口发送测试报文。
+
+- 实际网关进程转发 4096 字节随机二进制报文，目的端收到的字节完全一致。
+- 目的端看到固定的独立转发源端口。
+- 目的端回复的二进制字节返回原发送套接字，返回源端口为网关入口 19202。
+- 将该测试轮次同步为 `SAVED` 后，五路媒体任务均结束；同一采集路由继续正常转发。
+
+另外，`FusionRelayUdpIntegrationTest` 在隔离 PXHJ 应用中开启真实 UDP 套接字，使用正式 `WireCodec` 生成加密采集报文与加密心跳。未登记中转来源先被拒绝；登记映射后报文被接受、样本落入 H2，原采集器连接记录与密钥关联保持不变；未知来源和错误密钥被拒绝，加密心跳独立确认在线。该类第二项验证动态配置目的地址使用已登记的中转回程，原设备地址不被修改。此处验证的是实际协议实现和本机测试套接字，未使用真实硬件采集器。
+
+## 新版本本机角色启动后的只读确认
+
+新版本已部署到本机默认端口：总控 18100、网关 HTTP 18110 / UDP 19002、节点 A 18120 / 容量 2、节点 B 18121 / 容量 3。在主后端升级前，只读签名请求 `/control/snapshot` 的响应验证通过，两个节点和一个网关在线；网关与节点配置中均没有固定总控 URL。当时节点没有运行任务，网关路由状态为等待，尚未接管真实采集来源。主后端后续接通结果见下一节。
+
+本次确认只读取状态，不下发任务、路由，不修改试验、采集器或服务进程。该默认端口集群与 `runtime/validation` 隔离验证集群使用不同私有凭证。
+
+## 达梦主实例实际接通
+
+用户明确允许立即重启后，仅重启 PXHJ 主后端并加载新版 JAR，前端进程保持运行。实际主后端 PID 为 38344，前端 PID 为 33616；后端 8088 的 `/api/auth/csrf` 与前端 5178 页面 HTTP 检查均返回 200，未登录 `/api/fusion/status` 返回 401。PXHJ UDP 19001 和图片 UDP 6020 恢复，网关 UDP 19002 继续运行。
+
+只读查询实际达梦 `biz_fusion_cache`，检查时缓存年龄 1104 毫秒，内容包含两个在线节点和一个在线网关，证明主实例已实际签名同步总控状态。原有 `RUNNING` 轮次数仍为 1，没有自动结束或修改现有试验；原端点上传和采集接收路径未切换，也没有为正在运行的正式试验新增演示视频配置。
+
+用户从 PXHJ 融合节点管理和试验组织中的节点/视频区域统一操作。主实例连接已经接通，隔离 H2 中的正式业务流程和演示视频串联已验证；真实硬件迁移、真实融合和多台物理电脑验收仍未完成。
+
+## 主总控执行能力正式部署
+
+本次仅重启总控 18100，新 PID 为 41276，保留原稳定身份、H2 状态和私有配置。PXHJ 后端 PID 38344、前端 PID 33616、网关及两个子节点均未再次重启。总控健康信息确认执行能力已开启。
+
+实际签名快照复核通过：主节点 `nodeRole=COORDINATOR`，节点 ID 等于总控服务 ID，仅有一条主记录；主节点播放基础地址为 `http://192.168.8.237:18100`，在线、容量 2。A/B 保持 `WORKER`、容量 2/3。当前合计三个在线执行节点和一个在线网关，总容量 7，运行任务和等待任务均为 0。
+
+只读达梦缓存检查时年龄 64 毫秒，在线执行节点数 3、在线网关数 1，证明 PXHJ 未重启也能同步新的主节点记录。原正式 `RUNNING` 轮次数仍为 1，未新增或变更正式试验视频任务，未调整 A/B 容量，未切换采集器上传或路由。本机主端口实际 JPEG 播放使用随机端口集成测试验证，生产总控当前没有新视频任务运行。
+
+前述两节点和 1104 毫秒缓存记录属于加入主执行能力之前的阶段；当前运行状态以本节三个执行节点为准。
+
+## 部署脚本
+
+PowerShell 脚本语法解析通过。集群凭证生成、私有文件访问限制、已有实例重新安装、四个实例启动及健康身份校验、中文 properties 转义、按进程身份停止均已实际执行。
+
+隔离验证目录 `runtime/validation` 中保留本机身份、数据库、日志与私有配置，便于复查；该目录被 `.gitignore` 排除。业务联调结束后，四个 182xx 验证实例已按身份停止；只读端口查询确认 18100、18110、18120、18121 继续监听，182xx 验证端口已释放。未验证注册登录自启任务的实际重登录行为。

docs/系统融合软件原型阶段建设范围及完成标准.md

@@ -0,0 +1,110 @@
+# 系统融合软件原型阶段建设范围及完成标准
+
+## 1 原型建设目标
+
+本阶段在尚未与外部设备建立通信的条件下，围绕合同提出的外部数据处理、虚拟同步、视景融合及显示要求，建设基于模拟数据和本地视频素材的交互演示原型。原型重点完成主要功能页面、示例信息展示、基本操作流程和视频播放，用于确认界面布局、信息组织及显示方式，为后续设备接入和功能开发提供依据。
+
+原型以“页面可操作、模拟信息可查看、本地视频可播放、展示流程可演示”为阶段目标。演示不依赖外部设备连接：装备、定位、姿态、动作及状态信息使用预置样例，视频使用本地录制或测试素材，页面明确标识“原型演示”“模拟数据”或“演示视频”。
+
+本阶段范围限定为页面与本地视频展示，不包含设备通信、真实数据采集、实时视频流接入、三维场景、三维模型展示及模型动画，也不包含多传感器位姿融合、真实数据驱动的虚拟模型同步、实装与仿真画面的自动对齐及融合渲染。相关能力列入后续建设范围。
+
+## 2 原型建设内容
+
+### 2.1 外部数据处理页面演示
+
+建设装备及数据来源展示页面，以预置样例体现无人装备定位、姿态，车载探测设备姿态，以及侦察、打击设备动作状态等信息的展示位置和关联关系。
+
+页面支持选择示例装备，查看对应的模拟参数和状态。需要说明正常、异常或未接入等显示效果时，通过预设演示状态切换呈现；这些状态不来源于设备检测。数据来源显示为“模拟数据”，设备接入情况显示为“未接入”。
+
+**完成程度：** 可以选择示例装备、查看对应信息并切换预设状态；展示内容有明确的模拟标识，不依赖设备通信。
+
+### 2.2 虚拟同步功能展示
+
+建设虚拟同步相关信息的展示区域，以列表、表格和状态标签演示装备与虚拟实体对应关系，以及同步延迟、数据丢包率、实体映射状态等监控信息的页面布局。对应关系使用示例名称和关联信息，不加载或渲染三维模型。
+
+同步延迟、数据丢包率等指标默认显示“待接入”或“—”；为展示界面效果使用样例数值时，应在该区域明确标注“模拟数据”。本阶段不进行真实指标计算，也不完成统一时间基准构建、跨节点时空同步及模型实时驱动。
+
+**完成程度：** 可以演示装备选择、示例映射关系查看和监控信息查看流程，且不会将样例数值呈现为实际监测结果。
+
+### 2.3 视景与视频播放
+
+建设视景展示页面，将预置本地视频素材与示例通道关联，提供通道列表、播放、暂停、通道切换、播放状态提示及全屏查看功能，演示从选择通道到画面呈现的基本流程。
+
+页面标注“演示视频”或“本地回放”，播放状态仅反映本地素材是否正常播放。本阶段不连接摄像机或操控终端，不将本地视频播放表述为实时视频流接入或视景融合。
+
+**完成程度：** 在未连接外部设备的演示环境中，可以播放和暂停预置视频、切换示例通道并全屏查看；素材缺失或无法播放时有明确提示。
+
+### 2.4 操控席与综合态势展示
+
+操控席视景以单路演示视频为主，显示示例装备、通道及播放状态，支持全屏查看。综合态势页面采用示例装备列表、模拟状态信息和视频区域组合布局，支持选择装备后查看对应信息与本地视频。
+
+两个显示场景可复用同一本地视频素材，在演示计算机上切换布局，体现后续使用方式。本阶段不要求连接真实操控席或综合态势显示设备，其专用接口与现场显示联调列入后续建设。
+
+**完成程度：** 能够分别演示操控席视景布局和综合态势布局，选中装备与展示内容对应一致。
+
+## 3 页面及基本交互
+
+管理页面纳入现有 PXHJ 操作入口。原型拟设置以下四类页面或视图，可根据现有页面合并组织。
+
+| 页面或视图 | 主要展示内容 | 基本交互 |
+|---|---|---|
+| 运行总览 | 示例任务、装备概况、未接入标识、本地视频可用状态 | 进入装备详情或视频页面 |
+| 数据与同步状态 | 模拟定位姿态、示例实体关系、监控信息展示区域 | 选择示例装备、查看详情、切换预设状态 |
+| 视景展示 | 示例通道、本地视频画面、演示标识、播放状态 | 选择通道、播放、暂停、切换、全屏；全屏布局用于操控席演示 |
+| 综合态势展示 | 示例装备列表、模拟状态、选中装备关联的本地视频 | 选择装备、联动查看对应信息与视频、全屏展示 |
+
+页面重点展示业务信息，不要求填写真实设备地址或通信参数。各页面持续保留原型演示标识，避免切换页面或全屏后丢失素材来源说明。
+
+本阶段所有展示均采用常规页面、列表、表格、状态标签和视频区域。综合态势页面以装备信息与视频的组合展示为完成范围，三维场景、三维模型及模型动画均不纳入本阶段交付和演示。
+
+## 4 与合同功能的阶段对应关系
+
+| 合同功能 | 本阶段做到的程度 | 后续建设内容 |
+|---|---|---|
+| 外部数据处理 | 采用预置样例完成装备、定位姿态及动作状态的页面演示 | 设备通信、真实数据接收、协议适配、校验及标准化处理 |
+| 虚拟同步 | 展示示例实体关系及监控信息布局，演示查看与切换流程 | 统一时间基准、模型实时驱动、节点时空同步、真实延迟和丢包统计 |
+| 视景融合 | 使用本地视频素材完成播放和视景页面演示 | 实时视频流接入、多传感器位姿融合、仿真相机绑定、画面配准及融合渲染 |
+| 操控席及综合态势显示 | 在演示计算机上完成两类页面布局及本地视频呈现 | 正式融合结果输出、目标显示设备接口联调及显示性能验证 |
+
+上述对应关系用于明确原型阶段的建设深度。页面和播放流程的完成情况，与合同全部功能的最终实现情况分别记录。
+
+## 5 原型演示流程
+
+1. 在未连接外部设备的环境中打开原型，查看示例任务、装备和演示标识。
+2. 选择示例装备，查看模拟数据及示例实体对应关系。
+3. 切换预设状态，查看监控区域的信息布局和异常提示样式。
+4. 进入视景页面，选择关联本地素材的示例通道，演示播放、暂停、切换及全屏查看。
+5. 切换到综合态势页面，选择装备，查看对应模拟状态与演示视频。
+6. 使用素材不可用的测试通道展示播放异常提示，再切换到有效素材恢复播放。
+
+演示以页面操作和视频展示为主，不安排尚未实现的融合算法或虚实自动配准演示。
+
+## 6 阶段完成标准
+
+| 检查项 | 完成标准 |
+|---|---|
+| 页面完整性 | 约定页面或视图均可打开，主要展示区域与导航可用 |
+| 演示条件 | 未连接外部设备时，仍可完成约定的页面操作和本地视频播放 |
+| 操作流程 | 示例装备选择、详情查看、预设状态切换、视频播放与暂停、通道切换和全屏显示可以完成 |
+| 信息对应 | 所选示例装备、模拟数据和本地视频的关联一致 |
+| 数据来源标识 | 页面及全屏视图明确标识模拟数据和演示视频；真实设备接入状态为未接入 |
+| 视频播放 | 指定本地素材可播放，切换后显示对应素材；不可用时显示原因或状态 |
+| 两类显示 | 可以分别展示操控席视景布局及综合态势布局 |
+| 范围说明 | 原型功能清单明确已完成、演示展示和后续建设内容 |
+
+检查记录应注明模拟数据范围、本地视频素材、演示环境和操作结果。本阶段的完成依据为界面与交互验证，不包含设备连通性、实时采集、融合精度、同步延迟或多节点处理能力验证。
+
+## 7 原型交付内容
+
+- 原型阶段设计说明，明确建设内容及完成程度。
+- 可运行的交互演示页面和本地视频播放功能。
+- 预置模拟数据及演示视频素材清单。
+- 页面截图及基本操作说明。
+- 原型演示记录，注明模拟数据和本地视频来源。
+- 后续功能建设清单，列明完整数据处理、虚拟同步和真实视景融合等尚未实现的内容。
+
+## 8 后续建设衔接
+
+后续在已确认的页面、示例关系和显示方式基础上，先开展设备通信、真实数据与实时视频流接入，再逐步实现数据处理、统一时间基准、仿真模型驱动、传感器位姿融合、仿真相机绑定以及画面对齐和融合渲染，形成合同要求的完整功能链路。
+
+本阶段仅明确后续功能需要展示的信息项和操作入口。设备协议、接口实现及联调结果列为后续建设内容，不将页面预留位置表述为已经完成接口对接。

docs/系统融合软件页面与采集接入.md

@@ -0,0 +1,38 @@
+# 系统融合软件页面与采集接入
+
+本次将已确认的六页设计实现为原生系统融合软件控制台。页面源码位于 `frontend/`，构建产物放入 `src/main/resources/static/console/`，随 `xtrh-services` JAR 一起部署。
+
+## 页面
+
+| 页面 | 当前数据行为 |
+|---|---|
+| 数据接收 | 按试验冻结的实装选择，查看真实采集参数、来源、采样和接收时间及质量 |
+| 同步质量监控 | 装备列表与查看框架已实现，尚未接入同步质量指标时显示空状态 |
+| 虚拟数据下发 | 虚拟装备血量、位置等只读框架；尚无虚拟装备源时为空 |
+| 融合视频展示 | 按实装选择，画面右上角保留六项融合指标；尚无真正融合源时为空 |
+| 融合指标展示 | 按实装逐行展示，未接入指标为 `—` |
+| 主从控制 | 展示已注册节点的身份、角色、心跳在线状态；未上报 CPU、内存、网络速率为 `—` |
+
+页面不会将原图、演示视频或采集参数推测成融合输出，不内置示例装备、位置、血量或曲线。
+
+## 真实采集链路
+
+`采集器 → 既有网关/采集入口 → PXHJ 认证、解密、协议解析 → 冻结装备与采集模块绑定 → 实时质量判定 → 签名快照推送 → 系统融合软件页面`
+
+PXHJ 的 `TrialFusionCollectionSnapshot` 只读取未完成的正式试验及冻结绑定。`TrialCollectionService.realLiveForFusion` 沿用原采集服务，在计算质量前排除模拟报文，固定读取实时 60 秒窗口；公开用户采集接口原有权限检查保持不变。
+
+每两秒由独立单线程 `FusionCollectionPublisher` 复用 `FusionImageClient` 和原 `app.fusion.*` 私有配置，调用签名 `POST /control/collection/sync`。共享凭证只保留在后台。新快照整体替换内存中的旧快照，空列表也同步，因此结束试验后不会残留装备。
+
+接收端使用大小、数量、字段、标量值及时间边界校验，保留真实零值，缺失使用 null。保留 `GOOD/MISSING/STALE/INVALID_TIME/INVALID_VALUE/AMBIGUOUS` 等质量；超过 15 秒无有效推送，最后值标记为过期。断开时不将旧值显示成正常接收。
+
+## 构建和使用
+
+1. 在 `frontend` 安装依赖：`pnpm install` 或 `npm install`。
+2. 运行 `scripts/Build-Xtrh.ps1`，将先测试并构建页面，再执行 Java 测试和打包。已有前端构建产物时可使用 `-SkipFrontend`。
+3. 将新 JAR 部署到既有总控，保留身份、数据和私有配置。
+4. PXHJ 桥接源码已按基线校验应用；重新打包并加载 PXHJ 后端，既有 `app.fusion.enabled` 和总控配置生效后自动推送。
+5. 从总控所在电脑打开 `http://127.0.0.1:18100/console/`。页面每两秒刷新，可搜索和选择装备；存在多个试验时可在页头切换。
+
+浏览器 API 只有同源本机 GET/HEAD 查看能力。原 `/control/*` 仍需 HMAC 签名；页面没有节点容量修改、试验控制或采集器重配置操作。
+
+PXHJ 桥接补丁与原文件校验清单保存在 `runtime/console-pxhj-staging/`；应用前会核对基线并备份原文件，避免覆盖其他改动。源码修改不会自动更新运行中的进程。

docs/系统融合软件页面接入验证.md

@@ -0,0 +1,31 @@
+# 系统融合软件页面接入验证
+
+日期：2026-10-16。
+
+原生页面已实现并启用，地址为 `http://127.0.0.1:18100/console/`。六页为数据接收、同步质量监控、虚拟数据下发、融合视频展示、融合指标展示、主从控制。
+
+## 软件验证
+
+- XTRH 完整回归 48 项通过，失败、错误和跳过均为 0。
+- PXHJ 完整回归 445 项，失败 0、错误 0、跳过 30 项外部环境测试。
+- 前端数据规则 3 项通过，生产构建通过。
+- 独立测试集群的真实 HTTP 签名同步、响应验签及页面联动检查 13 项通过。测试数据已清空，测试实例已关闭，没有向正式系统写入测试样本。
+- 六页的 1586px 和 1024px 桌面布局、导航、搜索、选择及空状态通过；不使用原图、DEMO 或生成图冒充融合视频。
+
+## 已加载程序
+
+获得用户“现在重启并启用”的明确授权后，PXHJ 后端 8088 与融合总控 18100 已重新加载；原有 5178 前端未停止。替换前的 JAR 保存在 `runtime/console-activation-backup-20261016-193802/`，身份、H2 状态及达梦数据保留。
+
+启动前错误地使用了 PXHJ 不提供的 `/health` 地址；部署脚本的端口保护阻止了替换。随后以 `/api/auth/csrf` 和进程 JAR 路径确认真实服务并取得明确重启授权，没有在未获准时停止 PXHJ。
+
+PXHJ 采集桥接源码已按基线哈希保护应用，原修改文件备份在 `runtime/console-bridge-backup-20261016-192330/`。部署后的两个 JAR 与已验证构建产物进行 SHA-256 一致性核对。
+
+## 正式只读观察
+
+正式 `/console/api/snapshot` 中 collection.state 为 CONNECTED，识别 5 个试验、6 台绑定装备、286 个参数，SIMULATED 数量为 0。显示的装备和参数来自正式冻结绑定，没有添加示例数据。
+
+原采集网关原先未运行，现已启动；HTTP 18110 / UDP 19002，唯一既有登记路由的目标仍为 PXHJ UDP 19001，路由状态 APPLIED。不修改采集器配置或来源匹配。
+
+检查窗口内网关未收到新报文，全部参数为 MISSING。软件链路已启用，新的有效采集样本到达后会经原解密与绑定流程刷新页面；当前没有把空值补成零或其他装备的数据。此记录不替代真实采集器运行、物理多机或真实融合视频验收。
+
+其他五页仅保留查看功能。真实节点身份与心跳可见，CPU、内存、网络速率和未接入的虚拟/融合数据均为 `—` 或空列表。