对外接口与路由

本系统对外提供 REST API 与 WebSocket，用于脚本/界面控制与实时监控。

REST 路由表

健康检查 (routes/health.py)

方法	路径	说明
GET	/health	四层综合健康检查（DB + Adapter + TCP + PHY）
GET	/health/nodes	仅节点深度检查（gateway 连接 + probe + PHY）

系统配置 (routes/config.py)

方法	路径	说明
GET	/config	获取当前系统配置（节点端点、适配器、DB 等）
POST	/config/location-init/run	手动触发位置初始化脚本

场景管理 (routes/scenarios.py)

方法	路径	说明
GET	/scenarios	合并列表（DB + YAML）
GET	/scenarios/{scenario_id}	场景详情（先查 DB，再查 YAML）
POST	/scenarios	创建场景（写入 DB + 自动同步 YAML）
PUT	/scenarios/{scenario_id}	更新场景
DELETE	/scenarios/{scenario_id}	删除场景（含 YAML 清理）
POST	/scenarios/import	从 YAML 文件导入场景到 DB
POST	/scenarios/{scenario_id}/export	导出场景为 YAML 文件

策略发现 (routes/strategies.py)

方法	路径	说明
GET	/strategies	自动扫描 scheduler 包，返回所有 Strategy 子类

运行管理 (routes/runs.py)

方法	路径	说明
POST	/runs	创建运行（从场景加载默认参数）
GET	/runs	运行列表（分页：limit/offset）
GET	/runs/{run_id}	运行详情（含 summary）
GET	/runs/{run_id}/status	实时状态（含 current_step、latest_metrics，前端轮询用）
POST	/runs/{run_id}/start	启动运行（触发 ExecutionWorker）
POST	/runs/{run_id}/stop	停止运行
GET	/runs/{run_id}/metrics	聚合指标（先查 DB，再查 CSV）
GET	/runs/{run_id}/traces	原始 trace（分页，先查 DB，再查 CSV）
GET	/runs/{run_id}/artifacts	产物文件列表
GET	/runs/{run_id}/artifacts/{filename}	下载单个产物文件
GET	/runs/{run_id}/events	运行事件日志（分页）

WebSocket (ws.py)

协议	路径	说明
WS	/ws/runs/{run_id}	实时事件推送（step/schedule/metrics/sync/state/artifacts）

WebSocket 事件格式

所有 WebSocket 消息遵循统一信封格式：

{
  "type": "metrics",
  "run_id": "run-20260101-120000-abc12345",
  "ts_ms": 1735689600000,
  "payload": {
    "step_id": 12,
    "throughput_bps": 1234.5,
    "loss_rate": 0.1,
    "delay_p50_ms": 45.0,
    "delay_p95_ms": 900.0
  }
}

事件类型枚举：step | schedule | metrics | sync | state | artifacts

依赖注入

API 通过 deps.py 提供统一的依赖注入，所有路由函数通过 Depends() 获取：

依赖函数	返回类型	说明
get_settings	RuntimeSettings	运行时配置
get_db	Database	数据库引擎
get_repo	RunRepository	Run 仓库
get_run_service	RunService	运行业务服务
get_scenario_repo	ScenarioRepository	场景仓库
get_trace_repo	TraceRepository	Trace/Metrics 仓库
get_ws_broadcaster	RunEventBroadcaster	WebSocket 广播器
get_location_initializer	LocationInitializer	位置初始化器