页面与组件详细文档

---

1. 页面文档 (Pages)

1.1 Dashboard（运行仪表盘）

文件：pages/Dashboard.tsx路由：/

职责：

• 展示所有运行记录的汇总列表
• 提供状态筛选（全部/运行中/已完成/失败）、场景筛选、策略筛选和搜索功能
• 支持从表格行直接启动/停止运行
• 顶部 HealthStrip 实时显示后端健康状态

State：

• runs: Run[] — 运行列表
• health: HealthResponse | null — 健康状态
• scenarios: ScenarioDbItem[] — 场景列表（用于筛选）
• strategies: StrategyItem[] — 策略列表（用于筛选）
• filterStatus / filterScenario / filterStrategy / search — 筛选条件

后端 API 映射：

• GET /health → HealthStrip 展示
• GET /runs?limit=200 → 运行列表
• GET /scenarios → 场景筛选下拉
• GET /strategies → 策略筛选下拉
• POST /runs/{id}/start → 启动按钮
• POST /runs/{id}/stop → 停止按钮

---

1.2 CreateRun（创建运行）

文件：pages/CreateRun.tsx路由：/create

职责：

• 选择场景和策略
• 配置运行参数（模式、步数、时间步长、随机种子）
• 创建并自动启动运行，完成后跳转到详情页

State：

• scenarios: ScenarioDbItem[] — 可选场景列表
• strategies: StrategyItem[] — 可选策略列表
• scenarioId / strategyId / mode / steps / dtSeconds / seed — 表单字段
• submitting: boolean — 提交状态
• error: string — 错误信息

后端 API 映射：

• GET /scenarios → 场景下拉
• GET /strategies → 策略下拉
• POST /runs → 创建运行
• POST /runs/{id}/start → 自动启动

内部组件：

• FormField — 表单字段包装器（局部组件）

---

1.3 RunDetail（运行详情）

文件：pages/RunDetail.tsx路由：/runs/:runId

职责：

• 展示运行元数据（场景、策略、进度、创建时间）
• 指标图表：吞吐量/丢包率/延迟三个维度的柱状图
• 通信追踪记录表格（支持分页）
• 产物文件列表（支持下载）

State：

• run: Run | null — 运行详情
• metrics: MetricItem[] — 指标数据
• traces: TraceItem[] — 追踪记录
• tracesTotal / tracesOffset — 分页状态
• activeTab: string — 当前图表维度
• artifacts: ArtifactFileItem[] — 产物列表

后端 API 映射：

• GET /runs/{id} → 运行详情 + 摘要
• GET /runs/{id}/metrics → 图表数据
• GET /runs/{id}/traces?limit=20&offset=N → 追踪记录
• GET /runs/{id}/artifacts → 产物列表

条件加载：只有运行处于终态（finished/stopped/failed）时才加载 metrics、traces、artifacts。

---

1.4 ABCompare（A/B 对比）

文件：pages/ABCompare.tsx路由：/compare

职责：

• 选择两个运行进行策略效果对比
• 展示 KPI 差异卡片（吞吐量、丢包率、P95 延迟）
• 叠加趋势柱状图
• 差异对照表

State：

• runs: Run[] — 全部运行列表
• runAId / runBId — 选中的 Run ID
• summaryA / summaryB — 运行摘要
• metricsA / metricsB — 指标序列

后端 API 映射：

• GET /runs?limit=200 → 选择器数据
• GET /runs/{runAId} + GET /runs/{runBId} → 摘要
• GET /runs/{runAId}/metrics + GET /runs/{runBId}/metrics → 趋势数据

URL 参数：支持 ?runA=xxx&runB=yyy 从 Dashboard 预填选择。

---

1.5 LiveMonitor（实时监控）

文件：pages/LiveMonitor.tsx路由：/monitor

职责：

• 选择一个 running/created 状态的运行进行实时监控
• 展示当前步数、运行状态
• 实时滚动指标（吞吐量、丢包率、P95 延迟）
• 同步误差与计算开销面板

State：

• runs: Run[] — 可选运行列表
• selectedRunId: string | null — 当前监控的 Run ID

数据源：useRunPolling hook（1 秒间隔 HTTP 轮询 GET /runs/{id}/status）

Hook 返回：

• run: Run | null
• currentStep / totalSteps
• latestMetrics: MetricItem | null
• loading / error

---

1.6 SystemConfig（系统配置）

文件：pages/SystemConfig.tsx路由：/config

职责：

• 展示后端健康状态和适配器信息
• Agent 端点连通性表格
• 场景拓扑 SVG 预览
• 位置初始化执行控制

State：

• health: HealthResponse | null
• config: ConfigResponse | null
• scenarios: ScenarioDbItem[]
• scenarioDetail: ScenarioFullResponse | null
• locInitRunning / locInitResult

后端 API 映射：

• GET /health → 状态卡片 + 端点表格
• GET /config → 配置信息 + 位置初始化参数
• GET /scenarios → 拓扑预览数据源
• GET /scenarios/{id} → 拓扑详情
• POST /config/location-init/run → 执行位置初始化

内部组件：

• TopoNode — 拓扑图节点（SVG 圆形）
• parseEndpoint() — TCP 端点解析函数
• topoPosition() — 节点布局计算

---

1.7 HealthCheck（节点健康检查）

文件：pages/HealthCheck.tsx路由：/health

职责：

• 全局健康状态 Banner（healthy/degraded/unhealthy）
• 摘要卡片（健康节点数、连接成功数、PHY 正常数、Agent 总数）
• 各节点详细状态表格

State：

• autoRefresh: boolean — 是否自动刷新

数据源：usePolling<NodeHealthResponse>(fetchNodeHealth, 15_000, autoRefresh)

后端 API 映射：

• GET /health/nodes → 15 秒自动刷新 + 手动刷新

内部组件：

• NodeRow — 节点表格行
• Badge — 状态标签（ok/fail）

---

1.8 ScenarioList（场景列表）

文件：pages/ScenarioList.tsx路由：/scenarios

职责：

• 展示所有场景（DB + YAML 合并）
• 操作：编辑、导出 YAML、删除（仅 DB 来源可删除）
• 新建场景入口

State：

• scenarios: ScenarioDbItem[]
• loading / error

后端 API 映射：

• GET /scenarios → 场景列表
• DELETE /scenarios/{id} → 删除
• POST /scenarios/{id}/export → 导出

---

1.9 + 1.10 ScenarioEditor（场景编辑器）

文件：pages/ScenarioEditor.tsx路由：/scenarios/new（新建）、/scenarios/:id/edit（编辑）

职责：

• 基本信息编辑（ID + 名称）
• 节点管理（添加/删除/编辑，支持从 config 端点自动填充）
• 流量配置管理（添加/删除/编辑）
• 运行参数设置（seed、dt_seconds、steps）
• 右侧实时拓扑预览

State：

• scenarioId / name — 基本信息
• nodes: ScenarioNodeItem[] — 节点列表
• traffic: ScenarioTrafficItem[] — 流量列表
• runConfig: ScenarioRunConfig — 运行参数
• nodeEndpoints: ConfigNodeEndpoint[] — 可用端点
• saving / error

后端 API 映射：

• GET /config → 加载可用端点
• GET /scenarios/{id} → 编辑模式加载数据
• POST /scenarios → 新建保存
• PUT /scenarios/{id} → 更新保存

---

2. 组件文档 (Components)

2.1 Layout

文件：components/Layout.tsx

职责：全局页面布局框架，左侧 Sidebar + 右侧主内容区域。

Props：

• children: React.ReactNode — 页面内容

结构：

┌─────────────────────────────────────────┐
│ Sidebar (240px) │ Content Area (flex-1) │
│                 │  ┌─────────────────┐  │
│  [Nav Items]    │  │  <Outlet />     │  │
│                 │  │                 │  │
│                 │  └─────────────────┘  │
└─────────────────────────────────────────┘

---

2.2 Sidebar

文件：components/Sidebar.tsx

职责：侧边导航栏，包含 8 个导航项。

导航项：

1. Dashboard (/)
2. 创建运行 (/create)
3. A/B 对比 (/compare)
4. 实时监控 (/monitor)
5. 系统配置 (/config)
6. 节点健康 (/health)
7. 场景管理 (/scenarios)

当前路由高亮通过 useLocation() 实现。

---

2.3 HealthStrip

文件：components/HealthStrip.tsx

职责：Dashboard 顶部的健康状态条，显示全局健康状态和关键指标。

Props：

• health: HealthResponse | null

显示内容：后端状态指示灯 + 适配器类型 + 节点在线数 + 数据库状态

---

2.4 PageHeader

文件：components/PageHeader.tsx

职责：每个页面顶部的标题区域。

Props：

• title: string — 页面标题
• subtitle?: string — 副标题
• action?: React.ReactNode — 右侧操作区域

---

2.5 Card

文件：components/Card.tsx

职责：通用卡片容器，统一卡片样式。

Props：

• title?: string — 卡片标题
• description?: string — 卡片描述
• apiHint?: string — API 端点提示（右上角灰色文字）
• headerRight?: React.ReactNode — 标题行右侧自定义内容
• footer?: React.ReactNode — 底部区域
• bodyPadding?: string — 内容区域内边距
• children: React.ReactNode — 卡片内容
• className?: string — 额外 CSS 类名

---

2.6 MetaCard

文件：components/MetaCard.tsx

职责：展示单个指标的摘要卡片。

Props：

• label: string — 指标标签
• value: React.ReactNode — 指标值
• subValue?: React.ReactNode — 副值/补充说明
• subValueColor?: string — 副值颜色

---

2.7 StatusBadge

文件：components/StatusBadge.tsx

职责：运行状态标签，根据状态显示不同颜色和文字。

Props：

• status: string — 运行状态值

状态颜色映射：

状态	颜色	显示文字
created	蓝色	已创建
running	绿色	运行中
stopping	橙色	停止中
finished	灰色	已完成
stopped	黄色	已停止
failed	红色	失败

---

2.8 RunsTable

文件：components/RunsTable.tsx

职责：运行列表表格，包含筛选、排序、分页和行操作。

Props：

• runs: Run[] — 运行数据
• scenarios: ScenarioDbItem[] — 场景列表（筛选用）
• strategies: StrategyItem[] — 策略列表（筛选用）
• onStart: (id: string) => void — 启动回调
• onStop: (id: string) => void — 停止回调

功能：

• 状态筛选（全部/运行中/已完成/失败）
• 场景/策略下拉筛选
• 关键字搜索
• 行操作：查看详情、启动、停止、对比

---

2.9 TabGroup

文件：components/TabGroup.tsx

职责：标签页切换组件。

Props：

• tabs: Array<{ key: string; label: string }> — 标签定义
• activeKey: string — 当前激活的标签
• onChange: (key: string) => void — 切换回调

---

2.10 BarChart

文件：components/BarChart.tsx

职责：柱状图组件（纯 CSS/SVG 实现，无第三方图表库依赖）。

Props：

• data: Array<{ label: string; value: number; color?: string; secondaryValue?: number; secondaryColor?: string }> — 数据
• height: number — 图表高度 (px)
• formatValue?: (v: number) => string — 值格式化函数

特性：支持双柱对比模式（A/B Compare 页使用）。

---

2.11 Pagination

文件：components/Pagination.tsx

职责：分页控件。

Props：

• total: number — 总记录数
• offset: number — 当前偏移
• pageSize: number — 每页数量
• onPrev: () => void — 上一页回调
• onNext: () => void — 下一页回调
• label?: string — 记录类型标签（如"条追踪记录"）