总体架构（面向需求）

四层结构

• 仿真底座层：UNET / UnetStack / UnetSim（Java/Agent-based）
• 调度与一致性层：Python（Orchestrator + Scheduler + Barrier/Clock + Gateway Preflight）
• 服务与持久化层：Python（FastAPI REST/WS + SQLAlchemy ORM + MySQL）
• 观测与可视化层：React + Vite SPA（Dashboard、场景管理、健康检查、运行监控）

组件关系（逻辑视图）

+---------------------+        +----------------------------------+
|  UNET/UnetSim       | <----> | UnetAdapter (Gateway/LogOnly)    |
|  (multiple nodes)   |        +----------------------------------+
+---------------------+                      |
                                             v
                        +-----------------------------------------+
                        | Orchestrator (run/step/barrier)         |
                        |  - Gateway Preflight (PHY 健康预检)      |
                        |  - step loop (ΔT, K)                     |
                        |  - 调度策略 + 决策记录                    |
                        +-----------------------------------------+
                                             |
                                             v
                        +-----------------------------------------+
                        | Persistence (持久化层)                   |
                        |  - RunRepository (runs/summary/events)  |
                        |  - TraceRepository (traces/metrics)     |
                        |  - ScenarioRepository (场景 CRUD)        |
                        |  - 文件落盘 (CSV/JSON/Markdown)          |
                        +-----------------------------------------+
                                             |
                           +-----------------+-----------------+
                           v                                   v
                 +------------------+            +---------------------------+
                 | FastAPI REST/WS  |            | React + Vite SPA          |
                 | (API + Config +  |  <-------> | (Dashboard / 场景管理 /   |
                 |  Health routes)  |    HTTP/WS | 健康检查 / 运行监控)       |
                 +------------------+            +---------------------------+

新增架构层说明

Persistence 持久化层

• RunRepository：管理 runs / run_summary / run_events 三张表，负责 run 生命周期状态机转换
• TraceRepository：管理 run_traces / run_metrics 两张表，支持批量写入与分页查询
• ScenarioRepository：管理 scenarios 表，提供场景 CRUD + YAML 导入/导出
• 文件落盘：每次 run 仍输出 runs/<run_id>/ 目录，作为数据库的补充备份

Config 配置层

• RuntimeSettings：集中管理数据库连接、UNET 节点端点、表名映射等运行时配置
• Scenario / NodeConfig / TrafficFlow：Pydantic 模型，定义场景配置的类型安全结构

Protocol 协议层

• Payload Header 24B 编解码（run_id/step_id/seq/tx_time_ms/src/dst）
• UNet 地址解析（通过 NODE_INFO service 查询节点运行时地址）

两条集成路径（必须保留）

• Path-1（优先）：Python 通过 fjage gateway 连接 UNET，订阅通知、下发发送/控制指令。
• Path-2（兜底）：无法直接控制时，通过日志解析采集指标（控制简化为启动/停止/跑到结束）。

关键要求：UNET 相关操作必须封装为 UnetAdapter，主流程不写死 agent 名称/消息类名。

可复现与一致性设计

• seed 固定：影响随机流量、策略选择、（可选）仿真参数随机扰动
• 逻辑时间步进：step_id = 0..K-1，每步窗口 [t_start, t_end)
• barrier：每步收敛“当步事件/统计”后才进入下一步
• 落盘：每次 run 输出 runs/<run_id>/，保存场景/策略/版本/trace/metrics/report