# 网络仿真可视化模块需求

## 1. 模块概述

网络仿真可视化模块用于接收网络配置阶段的平台节点运动信息，并在网络仿真结果回放阶段根据仿真事件重建动画。

## 2. 功能需求

### 2.1 场景配置

| 需求项 | 简要说明 |
| --- | --- |
| 可视化启动 | 用户选择可视化模块后，前端应启动 Unreal Engine 5.8 运行程序，并通过 Pixel Streaming 将其默认场景显示在主显示区域的 iframe 中。系统应将该选择写入 `scenarios.render_engine` 字段。进入平台轨迹或通信设备配置步骤时，应自动加载视频流，无需用户点击 `click to start`。 |
| 地形与原点 | 系统应根据用户提供的 URL 加载地形和高程数据，将配置存入 `scenarios.terrain` 字段，并每 0.5 秒将当前场景原点写入 `scenarios.origin_initialization` 字段。 |
| 平台放置与轨迹配置 | 选中的平台应在已捕获鼠标的 iframe 内以三维模型跟随鼠标移动，并显示当前经度、纬度和高度；高度计算方法待确认。单击鼠标左键应添加轨迹点，单击鼠标右键应添加终点并要求录入总到达时间。各点到达时间应根据路径长度和总运动时间计算。 |
| 轨迹撤销与恢复 | 轨迹完成前，向上滚动滚轮应撤销已配置的轨迹点，向下滚动滚轮应恢复已撤销的轨迹点。每次操作均应同步修改 `NetworkConfig/netclonex.kinematics` 字段。 |
| 平台数据写入 | 系统应通过 `nxDatabase\migrations\mongodb\001_network_configs.py` 持久化配置和平台运动数据。创建平台时，应新增一条 `NetworkConfig/netclonex` 记录，其中包含 `platformId`、`name`、`platformType`、`model3dRef` 和 `kinematics` 字段。 |
| 地图交互与漫游 | 进入通信设备配置步骤时，应自动加载已配置的地图。未选中设备时，iframe 应捕获鼠标，并通过 SpectatorPawn 模式提供摄像机漫游功能。禁止捕获时，鼠标位于页面任何区域均不得被 iframe 捕获。 |
| 通信设备配置 | 每个空平台应预置一个空的 `comNode`、`comModule` 和协议层，用户可从组件库中选择通信协议放入各协议层。将通信设备拖动至平台附近时，应显示红色吸附提示；释放鼠标后，应将设备安装至平台并更新 `NetworkConfig/netclonex.comNodes` 字段。 |
| 通信设备查看与修改 | 双击操作应依次展示 `platform` → `comNode` → `comModule` → `protocolLayer` → `protocol` → `parameters` 层级，供用户查看和修改。预定义设备应提供可调整的默认值；未定义设备应要求用户逐层配置。UE 应以不可再分、由基本数据和参数组成的基础网络构件为单位持久化通信配置。 |

### 2.2 仿真回放可视化

| 需求项 | 简要说明 |
| --- | --- |
| 场景加载 | 系统应读取地图配置信息以及平台和通信设备的二维、三维模型数据，并加载至地图场景中。 |
| 动画驱动 | 系统应读取 `nxDatabase\migrations\postgres\005_replay_truth.sql` 中的仿真事件，并据此驱动平台移动、平台姿态、天线波束指向、无线链路状态和传输层数据包动画。平台前端应对准当前航向。 |
| 前端推送与查看 | 系统应通过 Pixel Streaming 将动画推送至前端 iframe。SpectatorPawn 控制应支持摄像机和视口移动、观察角度调整、画面缩放及漫游。 |

#### 2.2.1 回放事件类型范围

本阶段仅支持以下回放事件类型：

| 可视化能力 | 事件类型 | 需求 |
| --- | --- | --- |
| 节点生命周期 | `platform-spawn`、`platform-despawn` | 创建和移除可见节点。`platform-spawn` 提供节点的初始模型、位置、姿态、接口及天线信息。 |
| 平台运动 | `platform-pose` | 更新平台的位置和姿态。第三个参数表示运动模式；`linear` 表示采用插值运动。 |
| 天线转动 | `antenna-state` | 根据事件参数更新天线姿态，并在播放时对按时间排序的姿态样本进行插值。 |
| 链路状态 | `link-spawn`、`link-state`、`link-despawn` | 创建、更新和移除链路。仅需在天线保持静止的时隙内显示链路状态。 |
| UDP 传输层数据包 | `pdu-spawn`、`pdu-receive`、`pdu-drop`、`pdu-despawn` | 显示 UDP 数据包的完整生命周期，并通过 `subject_id` 关联同一数据包的全部生命周期事件。 |

筛选 UDP 数据包时，仅保留第一个参数中包含 `layer: "transport"` 和 `protocol: "UDP"` 的 `pdu-spawn` 事件。源端口和目的端口应记录有效的 UDP 端口。后续 `pdu-receive`、`pdu-drop` 和 `pdu-despawn` 事件应通过相同的 `subject_id` 进行匹配；终止事件无需重复携带协议元数据。

本阶段不纳入以下事件族：`interface-*`、`route-*`、`flow-*`、`session-*`、`queue-*`、`buffer-*` 和 `radio-*`。除非回放过程中允许动态添加或移除天线，否则也不纳入 `antenna-spawn` 和 `antenna-despawn`。不得引入 `udp-send`、`antenna-rotate` 等新的事件名称。

`nxDatabase\migrations\postgres\005_replay_truth.sql` 中现有的 `replay_events.event_type` 字段和 JSONB 参数字段能够存储上述事件类型，本次需求变更无需新增数据库迁移。

### 2.3 播放控制

动画播放界面应支持：

- 实时播放。
- 逐条事件播放。
- 通过速度滑块进行慢速或快速播放。
- 启动、暂停和继续播放。

## 3. 开发环境与实现约束

- 操作系统：Windows 11。
- 引擎：Unreal Engine 5.8。
- 实现语言：纯 C++。
- 不使用蓝图。