分布式水声通信数字孪生调度引擎

Appearance

验收与演示脚本（Demo-0 ~ Demo-2） ​

本章给出可直接用于答辩的“分段式演示脚本”。验收以“输入步骤 / 预期产物 / 关键指标”描述，保证可检查、可复现。

对外 Demo 版本固定 3 个：

  • Demo-0：离线闭环（mock traces，兜底可交付）
  • Demo-1：接入 UNET 实时通信（Gateway 采集真实 traces）
  • Demo-2：Dashboard 可视化 + 运行控制（答辩整合版本，尚未交付）

环境准备（一次性） ​

  • Python：>= 3.10
  • 安装（建议，含测试依赖）：
powershell
python -m pip install -e ".[dev]"
  • Demo-1（UNET 网关接入）建议额外安装：
powershell
python -m pip install -e ".[unet]"

说明：代码会按 arlpy -> fjagepy -> LogOnly 自动探测后端；Demo-1 需要至少一个网关后端可用（arlpy 或 fjagepy）。

Demo-0：离线跑完出指标（必做，mock traces） ​

输入：

  • 场景：scenarios/demo_line3.yaml
  • 策略：round_robin
  • 参数：K=60 steps，ΔT=1s，seed 固定

步骤（复制执行）：

powershell
$env:PYTHONPATH='src'
python -m unet_dt.orchestrator.runner --scenario scenarios/demo_line3.yaml --strategy round_robin --steps 60 --dt 1 --seed 42

预期产物（runs/<run_id>/ 必须齐全）：

  • scenario.yaml
  • strategy.json
  • versions.json
  • traces.csv（数据来源=mock/logonly）
  • metrics.csv
  • report.md

关键指标：至少能在 metrics.csv/report.md 看到 throughput / loss / delay_p95。

想观察每步数据变化可加 --debug，详见 运行流程说明。

Demo-1：UNET Gateway 端到端链路（必做，真实 traces） ​

目标：证明“能连、能发、能收、能解析 header、能落盘 traces”。

1) 启动 UNET（Windows handbook 2-node 示例） ​

在新终端启动 UNET：

powershell
cd C:\Users\80428\Downloads\unet-community-3.4.4\unet-3.4.4
bin\unet samples\2-node-network.groovy

预期：终端输出类似：

  • Node A: tcp://localhost:1101
  • Node B: tcp://localhost:1102

对应场景文件：scenarios/demo_2node_handbook.yaml（已内置上述 tcp/http 地址与最小 traffic）。

2) Probe：证明网关可连、列出可见 agent/service ​

powershell
python scripts\unet_probe_gateway.py --scenario scenarios\demo_2node_handbook.yaml --all

预期：能看到 backend 类型（arlpy/fjagepy/logonly）、连接成功与 agent/service 列表（或数量摘要）。

3) Subscribe RX：证明能收到消息并解析 DT header ​

在另一个终端运行（订阅 Node B）：

powershell
python scripts\unet_subscribe_rx.py --scenario scenarios\demo_2node_handbook.yaml --node-id 2 --seconds 30 --debug

预期：脚本打印收到的消息 key/type 摘要；若 payload 内含 DT header，会打印 unpack 后的 run_id/step_id/seq/tx_time_ms/src/dst。

4) Send TX：从 Node A 向 Node B 发 1 包（包含 DT header） ​

再开一个终端执行：

powershell
python scripts\unet_send_ping_or_tx.py --scenario scenarios\demo_2node_handbook.yaml --node-id 1 --to 2 --payload-bytes 32

说明：当使用 --scenario 时，脚本把 --to 视为“场景 node_id”（例如 2），并会 best-effort 通过 ARP 解析到运行时 UNET address（2-node sample 中地址通常是动态分配的）。

  • 建议：先用 --json 看 dst_unet_addr 是否解析成功。
  • 注意：该 sample 的 Datagram MTU 常见为 56 bytes，因此 --payload-bytes（不含 24-byte header）建议 <= 32。

5) 跑一次 gateway-backed run：生成真实 traces + 指标 ​

powershell
$env:PYTHONPATH='src'
python -m unet_dt.orchestrator.runner --scenario scenarios/demo_2node_handbook.yaml --mode gateway --strategy round_robin --steps 10 --dt 1 --seed 42 --rx-grace 15

预期产物（runs/<run_id>/）：

  • versions.json 包含 gateway 后端/host/port 与 run_u32 等信息
  • traces.csv：source=gateway；能看到至少 1 行 received=true
  • metrics.csv / report.md：指标可用

验收点：

  • 端到端链路成立：Tx 成功发出 + Rx 能收到 + header 能解析 + traces 能落盘
  • 核心逻辑不写死 UNET agent 名称/消息类名：通过 probe 与调试信息定位，必要时由 scenario 注入 hint

想观察每步数据变化可加 --debug，详见 运行流程说明。

常见问题排查（现场用） ​

  • Probe 失败：先确认 UNET 进程在跑、端口（1101/1102）可达。
  • Rx 一直收不到：
    • 先用 --debug 看脚本观察到的字段；
    • 检查 --to 是否为正确的 UNET address；
    • 必要时先只做“能收到任意消息”的证明（脚本会打印 raw/key 摘要）。

Demo-2：React Dashboard 全流程验收（答辩版本） ​

目标：在 React + Vite SPA Dashboard 中完成"创建 run → 启动 → 实时监控 → 查看结果"全流程，并验证 A/B 对比与健康检查功能。

1) 环境启动 ​

启动后端 API 服务器：

powershell
$env:PYTHONPATH='src'
python -m uvicorn unet_dt.api.main:app --host 0.0.0.0 --port 8000

启动前端开发服务器：

powershell
cd src/unet_dt/ui
npm run dev

2) 健康检查验收 ​

  • 访问 Dashboard 健康检查页面
  • 验证 GET /health 返回 status: healthy（或 degraded，视 UNET 节点可用性）
  • 验证数据库连接正常（db.ok: true）
  • 验证各节点的 PHY 状态、agent/service 数量、UNet 地址显示正确

3) 场景管理验收 ​

  • 查看场景列表（GET /scenarios），确认 YAML 文件与数据库场景均展示
  • 通过 API 创建新场景（POST /api/scenarios），验证创建成功
  • 导入 YAML 场景到数据库（POST /api/scenarios/import），验证导入成功

4) 创建并启动 Run ​

  • 在 Dashboard 选择场景（如 demo_line3）与策略（round_robin）
  • 配置参数：K=30, ΔT=1s, seed=42, mode=mock
  • 点击 Start → 验证 run 进入 running 状态

5) 实时监控验收 ​

  • WebSocket 连接 /ws/runs/{run_id} 成功
  • 实时曲线更新（throughput_bps / loss_rate / delay_p95_ms / sync_error_ms）
  • current_step 逐步递增直到 K

6) 完成后查看结果 ​

  • 运行结束后 run 状态为 finished
  • 查看 run 详情页：摘要指标、traces 表格、metrics 曲线
  • 查看产物文件列表（GET /runs/{run_id}/artifacts）

7) A/B 对比 ​

  • 再创建一次使用 adaptive 策略的 run
  • 选择两次 run 进行对比，验证对比曲线与差异统计可用

验收 checklist ​

  • [ ] 健康检查页：数据库/适配器/节点状态正常展示
  • [ ] 场景列表：YAML + DB 场景合并展示
  • [ ] 创建 run：参数正确、状态 created
  • [ ] 启动 run：状态 running、current_step 递增
  • [ ] WebSocket：连接成功、实时数据推送
  • [ ] 完成 run：状态 finished、摘要指标正确
  • [ ] 详情页：曲线/traces/产物可访问
  • [ ] A/B 对比：双 run 对比图可用

2026-02-11 后端 API 验收报告（本次完成） ​

A. 环境验证 ​

powershell
$env:PYTHONPATH='src'
python -m compileall src
pytest -q tests

预期：37 passed。

B. MySQL 配置确认 ​

powershell
$env:UNET_DT_DB_HOST='usw-cynosdbmysql-grp-rj8i8a3n.sql.tencentcdb.com'
$env:UNET_DT_DB_PORT='25567'
$env:UNET_DT_DB_USER='xiaokai'
$env:UNET_DT_DB_PASSWORD='***'
$env:UNET_DT_DB_NAME='unet_dt'
$env:UNET_DT_DB_TABLE_RUNS='dt_runs'
$env:UNET_DT_DB_TABLE_RUN_SUMMARY='dt_run_summary'
$env:UNET_DT_DB_TABLE_RUN_EVENTS='dt_run_events'
$env:UNET_DT_DB_AUTO_CREATE='false'

C. 端到端流程执行 ​

验收 run_id: acceptance-e2e-20260211090035

  • GET /health -> 200
  • GET /scenarios -> 200
  • POST /runs -> 201
  • POST /runs/{run_id}/start -> 200
  • GET /runs/{run_id} -> 200（最终状态 finished）
  • GET /runs -> 200
  • GET /runs/{run_id}/metrics -> 200
  • GET /runs/{run_id}/traces -> 200
  • POST /runs/{run_id}/stop -> 200（终态幂等返回）
  • WS /ws/runs/{run_id} -> 连接成功，首帧包含 state、metrics

D. 结果 sanity 检查 ​

  • throughput_bps：均值约 853.33
  • loss_rate：区间 [0, 1]（均值约 0.0833）
  • delay_p95_ms：均值约 182.35
  • DB 状态：dt_runs.status=finished，dt_run_summary 已写入摘要

E. 位置初始化（A 方案）核验 ​

  • 命令：python scripts/unet_test_location.py --scenario scenarios/demo_line3.yaml --mode fail_fast --dry-run --json --node-endpoints-json ...
  • 结果：total=3，ok=3，failed=0

F. 下一步计划 ​

  • 开始前端 Dashboard 开发
  • 对接上述 API 接口
  • 实现 run 列表与详情页
  • 接入 WebSocket 实时数据