Appearance
功能性需求（FR）
本章按提交版 report.md 的编号口径列出功能性需求（FR-1 ~ FR-7）。每条 FR 均包含：功能描述/优先级/输入/操作序列/输出/补充说明。
3.0 功能性需求分类
| 功能性需求 | 功能模块 | 主要内容 |
|---|---|---|
| 功能性需求 1 | 场景与配置管理（FR-1） | 场景定义、校验、版本化 |
| 功能性需求 2 | UNET 接入与运行管理（FR-2） | 网关连接、启停、回退 |
| 功能性需求 3 | 调度策略（FR-3） | 轮询与自适应策略 |
| 功能性需求 4 | 同步与逻辑时间（FR-4） | 逻辑步进与 barrier |
| 功能性需求 5 | 数据采集与指标（FR-5） | Trace 记录与指标统计 |
| 功能性需求 6 | 可视化与控制（FR-6） | 前端展示与控制 |
| 功能性需求 7 | 实验对比与回放（FR-7） | A/B 对比与回放 |
3.1 功能性需求 1：场景与配置管理
3.1.1 场景加载与校验（FR-1.1）
- 功能描述：加载 YAML/JSON 场景文件并进行格式与字段校验。
- 优先级：高
- 输入：场景配置文件（路径或内容）
- 操作序列：读取 → 校验 → 解析 → 生成运行配置
- 输出：可执行场景对象 / 错误提示
- 补充说明：字段缺失应提示具体位置与修复方式；同一场景多次加载结果应一致。
3.1.2 场景版本化（FR-1.2）
- 功能描述：每次 run 创建时保存场景快照，确保可复现。
- 优先级：高
- 输入：run_id、解析后的场景对象（或原始场景文件路径）
- 操作序列：创建 run 目录 → 拷贝/序列化场景 → 记录校验信息（hash/版本）
- 输出：
runs/<run_id>/scenario.yaml（或等价的 JSON） - 补充说明：快照必须与当次运行实际使用的场景一致，且不可被后续修改覆盖。
3.1.3 业务流配置（FR-1.3）
- 功能描述：支持配置业务流（源节点、宿节点、发送周期、消息大小、持续步数等），用于生成可复现的发送负载。
- 优先级：高
- 输入：flows 列表（src、dst、period_ms/step、size_bytes、start_step、end_step 等）
- 操作序列：读取 flows → 校验字段/范围 → 编译为每 step 的待发任务（queue）
- 输出：可解析的业务流配置与编译后的待发队列（内部数据结构/落盘配置）
- 补充说明：若无法获取真实队列长度，可用“当步待发帧数”作为队列长度近似。
3.2 功能性需求 2：UNET 接入与运行管理
3.2.1 网关探测与连接（FR-2.1）
- 功能描述：探测 fjage gateway 并列出可见 agent/service，提供可用能力提示。
- 优先级：高
- 输入：host、port
- 操作序列：连接 → probe() → 输出 agent/service 列表或数量与能力建议
- 输出：探测结果（连接状态、版本信息、推荐 Tx/Rx 入口）
- 补充说明：必须支持自动探测 Python 侧依赖（arlpy 优先，fjagepy 备选）；若无法连接需给出明确排查提示并允许回退到 LogOnly。
3.2.2 运行启停控制（FR-2.2）
- 功能描述：支持启动/停止一次仿真 run，并管理运行目录与状态。
- 优先级：高
- 输入：scenario、strategy、seed、K、ΔT，UNET 启动命令（可选）
- 操作序列：创建 run 目录 → 写入 versions/scene/strategy → 启动 UNET（subprocess 或外部连接）→ 运行 → 停止与收尾
- 输出：run 状态、产物路径、错误信息
- 补充说明：启动失败需保留日志定位入口；支持“跑到结束”与“人工 stop”。
3.2.3 LogOnly 回退（FR-2.3）
- 功能描述：当无法网关控制时，支持仅通过日志/离线 trace 解析完成指标闭环。
- 优先级：中
- 输入：UNET 输出日志文件路径（或 traces 原始文件）
- 操作序列：解析日志/事件 → 标准化为 trace → 计算 metrics → 落盘/展示
- 输出：
traces.csv、metrics.csv、报告 - 补充说明：LogOnly 不阻塞交付；优先保证“能跑通 Demo-0”。
3.3 功能性需求 3：调度策略
3.3.1 轮询策略（FR-3.1）
- 功能描述：按固定顺序轮询选择节点发送，作为 baseline。
- 优先级：高
- 输入：节点列表、step_id、（可选）每步配额
- 操作序列：根据 step_id 计算当前节点 → 分配配额 → 输出决策
- 输出：ScheduleDecision（active_nodes、quota_frames）
- 补充说明：必须可复现（同 seed/同场景一致）。
3.3.2 自适应策略（FR-3.2）
- 功能描述：根据上一窗口丢包率/时延或队列长度，自适应调整 active_nodes 或 quota。
- 优先级：中
- 输入：last_window_metrics、queues（或待发帧数）
- 操作序列：读取指标 → 计算权重/优先级 → 选择节点与配额 → 输出决策
- 输出：ScheduleDecision
- 补充说明：策略必须可切换对比；需记录所用指标与决策依据。
3.3.3 调度决策记录（FR-3.3）
- 功能描述：记录每步调度决策与调度耗时，用于回放与分析。
- 优先级：高
- 输入：step_id、ScheduleDecision、调度耗时
- 操作序列：每步写入一行 CSV/JSON → 运行结束汇总
- 输出：
runs/<run_id>/schedule_decisions.csv - 补充说明：至少记录：step_id、active_nodes、quota_frames、schedule_overhead_ms、meta。
3.4 功能性需求 4：同步与逻辑时间
3.4.1 逻辑时间步进（FR-4.1）
- 功能描述：以固定步长 ΔT 推进 step（0..K-1），形成可复现实验节拍。
- 优先级：高
- 输入：K、ΔT
- 操作序列：step 开始 → 调度 → 执行/收集 → step 结束
- 输出：step_id、t_start/t_end（ms）
- 补充说明：MVP 可用 wall-clock 近似；能拿到仿真时间则优先使用。
3.4.2 Barrier 同步（FR-4.2）
- 功能描述：每步步末等待“事件收敛/确认”，再进入下一步，保证顺序一致。
- 优先级：高
- 输入：当步事件流/回执（或超时阈值）
- 操作序列：收集事件 → 判断收敛 → barrier 通过/超时处理
- 输出：barrier 结果（pass/timeout）
- 补充说明：超时应落盘并计入同步指标；乱序事件计数期望为 0。
3.4.3 同步质量指标（FR-4.3）
- 功能描述：输出 sync_error_ms 与 out_of_order 等同步质量指标。
- 优先级：中
- 输入：各节点/实例时间信息（或估计）
- 操作序列：计算差值/统计乱序 → 落盘与推送
- 输出：同步指标
- 补充说明：拿不到节点时钟时，可用“事件到达时间差”估计并注明估计方法。
3.5 功能性需求 5：数据采集与指标
3.5.1 Trace 采集（FR-5.1）
- 功能描述：采集每条消息的发送/接收事件，形成统一 trace 结构。
- 优先级：高
- 输入：Tx/Rx 事件（网关通知或日志解析）
- 操作序列：订阅/解析 → 标准化字段（src/dst/seq/t_ms/len）→ 写入 traces
- 输出：
runs/<run_id>/traces.csv - 补充说明：字段不齐时必须给出缺失原因与替代推断逻辑。
3.5.2 Payload Header 编解码（FR-5.2）
- 功能描述：发送 payload 前追加固定 24B header（run_id/step_id/seq/tx_time_ms/src/dst），接收时解析。
- 优先级：高
- 输入：user_data、run_id、step_id、seq、tx_time_ms、src、dst
- 操作序列：pack header → 拼接 payload → 发送；接收时 unpack header
- 输出：可解析 header 的 payload 与解析结果
- 补充说明：header 编码采用 little-endian
struct.pack('<IIIQHH', ...)。
3.5.3 指标计算（FR-5.3）
- 功能描述：从 traces 计算吞吐、时延分位数、丢包率等。
- 优先级：高
- 输入：
traces.csv - 操作序列：按窗口/step 聚合 → 计算 throughput/loss/delay(p50/p95) → 输出 metrics
- 输出：
runs/<run_id>/metrics.csv - 补充说明：丢包可通过 seq 缺口推断；需明确窗口大小与对齐方式。
3.5.4 结果落盘（FR-5.4）
- 功能描述：输出可复现实验的完整落盘目录。
- 优先级：高
- 输入：run 元信息、traces、metrics、schedule、版本信息
- 操作序列：写入 scenario/strategy/versions/traces/metrics/report
- 输出：
runs/<run_id>/...全套文件 - 补充说明：
versions.json必含 git_commit、python_version、deps、unet_cmd、unet_port/host。
3.6 功能性需求 6：可视化与控制
3.6.1 实时指标曲线（FR-6.1）
- 功能描述：展示吞吐、时延 p95、丢包率、sync_error 等实时曲线。
- 优先级：高
- 输入：metrics 实时数据（WebSocket 推送或轮询）
- 操作序列：订阅/拉取 → 更新曲线 → 显示当前值与历史趋势
- 输出：实时曲线与摘要卡片
- 补充说明：刷新周期建议 ≤ 1s；高延迟时需提示。
3.6.2 拓扑视图（FR-6.2）
- 功能描述：展示节点位置（2D）与状态（在线/发送/接收计数）。
- 优先级：中
- 输入：节点位置/轨迹（若可得）或固定布局
- 操作序列：加载节点信息 → 绘制点位/连线（可选）→ 更新状态
- 输出：拓扑视图
- 补充说明：若位置不可得，可使用固定布局或仅展示节点列表与连接关系。
3.6.3 运行控制（FR-6.3）
- 功能描述：选择场景与策略并启动/停止运行，支持查看当前运行状态。
- 优先级：高
- 输入：scenario_id、strategy_id、seed、K、ΔT、Start/Stop 操作
- 操作序列：前端调用 API → 后端创建 run 并启动 → 返回 run_id 与状态 → 停止时调用 stop
- 输出：运行状态、错误提示与 run 产物路径
- 补充说明：关键操作需要明确成功/失败提示；启动失败需给出日志定位入口。
3.6.4 历史列表与详情（FR-6.4）
- 功能描述：查看历史 run 列表与指标摘要，点击进入 run 详情。
- 优先级：中
- 输入：runs 目录或后端 runs API
- 操作序列：加载 runs 列表 → 按时间/策略筛选（可选）→ 查看单次 run 指标与文件
- 输出：run 列表页、run 详情页
- 补充说明：需展示 run_id、场景、策略、开始/结束时间、关键指标摘要。
3.6.5 WebSocket 实时推送（FR-6.5）
- 功能描述：通过 WebSocket 推送 step 更新、调度决策与当前窗口指标，支持实时展示。
- 优先级：高
- 输入：run 过程事件（step、schedule、metrics、sync）
- 操作序列：建立 WS 连接 → 按事件类型发送 JSON → 前端解析并更新 UI
- 输出：实时消息流（JSON）
- 补充说明：消息建议包含 type/run_id/step_id/t_ms 等统一字段；断线需支持重连与状态恢复。
3.7 功能性需求 7：实验对比与回放
3.7.1 A/B 对比（FR-7.1）
- 功能描述：选择两次 run（通常不同策略或不同参数）进行指标对比，输出对比曲线与差异统计。
- 优先级：中
- 输入：run_id_A、run_id_B、对比指标选择（throughput/loss/delay 等）
- 操作序列：加载两次 run 的 metrics → 对齐时间轴/step → 生成对比图与摘要表
- 输出：对比图表与差异统计结果
- 补充说明：建议提示相同 seed 对比；对齐失败需提示原因（K/ΔT 不一致等）。
3.7.2 回放（FR-7.2）
- 功能描述：按倍率回放历史 run 的关键指标与调度决策变化，支持教学演示与论文复现展示。
- 优先级：中
- 输入：run_id、回放倍率（1x/2x/...）、回放区间
- 操作序列：读取 metrics/schedule/traces → 按 step 或时间推进 → 更新曲线与当前决策显示
- 输出：回放过程与控制（播放/暂停/跳转）
- 补充说明：回放不要求与仿真实时一致，但需保证数据顺序一致、步边界清晰。
3.7.3 报告导出（FR-7.3）
- 功能描述：导出实验摘要与图表（用于提交/答辩展示），支持生成 Markdown/PDF（可选）。
- 优先级：中
- 输入：run_id、导出格式（md/png/pdf 可选）
- 操作序列：汇总关键指标 → 生成图表 → 写入 report.md（及图片）→ 输出导出路径
- 输出：
runs/<run_id>/report.md（以及对应图片/附件） - 补充说明：报告内容需包含：场景/策略/seed、关键指标（吞吐、时延 p95、丢包）、版本信息与结论简述。