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

Appearance

后端开发指南（运行时 + 验收） ​

最后更新：2026-02-28

1) 运行时配置入口 ​

  • 配置模块：src/unet_dt/config/settings.py
  • 加载 API：load_runtime_settings() / RuntimeSettings.from_env()
  • 原则：环境变量优先（禁止硬编码凭据）

2) 本交付中使用的 MySQL 接线 ​

提供的数据库端点：

  • host：参见 .env.example 中的 UNET_DT_DB_HOST
  • port：参见 .env.example 中的 UNET_DT_DB_PORT
  • database：unet_dt

由于 unet_dt 已包含业务表，后端元数据通过以下表进行隔离：

  • dt_runs
  • dt_run_summary
  • dt_run_events

运行时使用的环境变量：

powershell
$env:UNET_DT_DB_HOST='<参见 .env.example>'
$env:UNET_DT_DB_PORT='<参见 .env.example>'
$env:UNET_DT_DB_USER='<参见 .env.example>'
$env:UNET_DT_DB_PASSWORD='<参见 .env.example>'
$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'

安全提示: 所有敏感凭据（数据库密码、网关地址等）均通过环境变量注入，禁止在代码或文档中硬编码。请参考项目根目录下的 .env.example 获取完整的环境变量清单。

3) 7 节点端点输入（A-G） ​

节点端点通过环境变量配置，支持两种注入方式：

  • UNET_DT_UNET_NODE_ENDPOINTS_JSON：JSON 格式的完整映射
  • UNET_DT_UNET_NODE_A_TCP ... UNET_DT_UNET_NODE_G_TCP：逐个指定

具体的节点地址和端口信息请参见 .env.example。

4) 位置初始化（A 方案） ​

  • 脚本：scripts/unet_test_location.py
  • 服务封装：src/unet_dt/service/location_initializer.py
  • 运行集成点：RunService.start_run()

行为模式：

  • fail_fast：初始化失败会阻止运行启动并标记运行失败
  • best_effort：运行继续并附带警告事件

试运行验证已执行：

powershell
$env:PYTHONPATH='src'
python scripts/unet_test_location.py --scenario scenarios/demo_line3.yaml --mode fail_fast --dry-run --json --node-endpoints-json '<参见 .env.example>'

结果：demo_line3 节点的 total=3、ok=3、failed=0。

5) 已执行的自动化验证 ​

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

结果：37 passed。

6) API + 运行端到端验收已执行 ​

验收运行 ID：acceptance-e2e-20260211090035

已验证的端点：

  • GET /health
  • GET /health/nodes
  • GET /config
  • GET /strategies
  • GET /scenarios
  • GET /scenarios/{scenario_id}
  • POST /scenarios
  • PUT /scenarios/{scenario_id}
  • DELETE /scenarios/{scenario_id}
  • POST /scenarios/import
  • POST /scenarios/{scenario_id}/export
  • POST /runs
  • POST /runs/{run_id}/start
  • GET /runs
  • GET /runs/{run_id}
  • GET /runs/{run_id}/status
  • GET /runs/{run_id}/metrics
  • GET /runs/{run_id}/traces
  • GET /runs/{run_id}/artifacts
  • GET /runs/{run_id}/events
  • POST /runs/{run_id}/stop
  • POST /config/location-init/run
  • WS /ws/runs/{run_id}

结果要点：

  • 运行成功完成（status=finished）
  • 产物目录：runs/acceptance-e2e-20260211090035
  • 摘要已持久化至数据库（dt_run_summary）
  • 指标合理性检查：吞吐量/丢包率/延迟值均在合理范围内

7) 前端开发指南 ​

技术栈 ​

  • React 19 + TypeScript + Vite 7
  • TailwindCSS v4 用于基础布局工具类
  • Lucide React 用于图标
  • React Router v7 用于客户端路由

本地开发 ​

bash
cd src/unet_dt/ui
npm install
npm run dev    # 启动 Vite dev server，默认端口 5173

Vite 已配置 /api 代理到 http://localhost:8000，开发时需同时启动后端 API。

构建与部署 ​

bash
npm run build   # 产物输出到 dist/

生产环境下需配置 Nginx/反向代理将 /api 转发到后端服务。

代码组织 ​

src/unet_dt/ui/src/
├── api/          # HTTP 客户端封装（client.ts）
├── components/   # 可复用 UI 组件
├── hooks/        # 自定义 React Hooks（轮询、WebSocket）
├── pages/        # 路由页面组件
└── types/        # TypeScript 类型定义

详细前端文档请参阅 docs/frontend/ 分区。

8) 当前剩余工作 ​

后端 API 和运行验收已在此步骤中完成。 前端 Dashboard 已全面实现，包含 10 个页面和 11 个可复用组件。 剩余范围：扩展实时网关验收场景和生产部署优化。