前端架构

技术栈

技术	版本	用途
React	19.2	UI 框架
Vite	7.3	构建工具 + 开发服务器
TypeScript	5.9	类型系统
Tailwind CSS	4.1	原子化 CSS 框架
React Router	7.13	客户端路由
Lucide React	0.563	图标库

路由结构

定义于 App.tsx，所有页面共享 Layout 组件（含侧边栏）：

路径	组件	说明
/	Dashboard	运行列表仪表盘（首页）
/create	CreateRun	创建新运行
/runs/:runId	RunDetail	运行详情（指标/trace/产物）
/compare	ABCompare	A/B 运行对比
/monitor	LiveMonitor	实时运行监控
/config	SystemConfig	系统配置查看
/health	HealthCheck	节点健康检查
/scenarios	ScenarioList	场景列表
/scenarios/new	ScenarioEditor	新建场景
/scenarios/:id/edit	ScenarioEditor	编辑场景

组件架构

共享组件（11 个）

组件	文件	职责
Layout	Layout.tsx	页面布局骨架（Sidebar + Outlet）
Sidebar	Sidebar.tsx	侧边导航栏
PageHeader	PageHeader.tsx	页面标题与操作区
Card	Card.tsx	通用卡片容器
MetaCard	MetaCard.tsx	带标签的指标卡片
StatusBadge	StatusBadge.tsx	运行状态徽章（颜色编码）
RunsTable	RunsTable.tsx	运行列表表格
BarChart	BarChart.tsx	柱状图组件
Pagination	Pagination.tsx	分页控件
TabGroup	TabGroup.tsx	标签页切换
HealthStrip	HealthStrip.tsx	健康状态条

页面组件（10 个）

组件	文件	数据来源
Dashboard	Dashboard.tsx	fetchRuns()
CreateRun	CreateRun.tsx	fetchScenariosMerged() + fetchStrategies() + createRun()
RunDetail	RunDetail.tsx	fetchRunDetail() + fetchRunMetrics() + fetchRunTraces() + fetchRunArtifacts()
LiveMonitor	LiveMonitor.tsx	useRunPolling() + useWebSocket()
ABCompare	ABCompare.tsx	fetchRuns() + fetchRunMetrics()
SystemConfig	SystemConfig.tsx	fetchConfig()
HealthCheck	HealthCheck.tsx	usePolling(fetchNodeHealth, 15000)
ScenarioList	ScenarioList.tsx	fetchScenariosMerged()
ScenarioEditor	ScenarioEditor.tsx	fetchScenarioFull() + createScenario() / updateScenario()

API 层 (api/client.ts)

统一的 HTTP 客户端封装，所有请求以 /api 为 base path：

const BASE = "/api";

// REST 示例
export async function fetchRuns(params?): Promise<RunListResponse> { ... }
export async function createRun(body): Promise<Run> { ... }
export async function startRun(runId): Promise<Run> { ... }

// WebSocket
export function connectRunWebSocket(runId: string): WebSocket {
  const protocol = location.protocol === "https:" ? "wss:" : "ws:";
  return new WebSocket(`${protocol}//${host}/api/ws/runs/${runId}`);
}

完整 API 函数清单：

函数	方法	路径
fetchHealth()	GET	/health
fetchNodeHealth()	GET	/health/nodes
fetchConfig()	GET	/config
fetchStrategies()	GET	/strategies
fetchRuns()	GET	/runs
createRun()	POST	/runs
startRun()	POST	/runs/{id}/start
stopRun()	POST	/runs/{id}/stop
fetchRunDetail()	GET	/runs/{id}
fetchRunStatus()	GET	/runs/{id}/status
fetchRunMetrics()	GET	/runs/{id}/metrics
fetchRunTraces()	GET	/runs/{id}/traces
fetchRunArtifacts()	GET	/runs/{id}/artifacts
fetchScenariosMerged()	GET	/scenarios
fetchScenarioFull()	GET	/scenarios/{id}
createScenario()	POST	/scenarios
updateScenario()	PUT	/scenarios/{id}
deleteScenario()	DELETE	/scenarios/{id}
exportScenario()	POST	/scenarios/{id}/export
importScenario()	POST	/scenarios/import
runLocationInit()	POST	/config/location-init/run
connectRunWebSocket()	WS	/ws/runs/{id}

Hooks

usePolling

通用轮询 hook，支持自动刷新开关和手动刷新：

const { data, loading, error, refetch } = usePolling<T>(fetcher, intervalMs, enabled);

useRunPolling

运行状态专用轮询，调用 GET /runs/{id}/status：

const { run, summary, currentStep, totalSteps, latestMetrics, loading, error }
  = useRunPolling({ runId, interval: 1000, enabled: true });

• 默认 1 秒轮询间隔
• 运行进入终态（finished/stopped/failed）后自动停止轮询

useWebSocket

WebSocket 连接管理：

const { connected, lastEvent } = useWebSocket({
  runId,
  onEvent: (event) => { ... },
});

• 自动建立/断开连接（跟随 runId 变化）
• 消息解析为 WsEvent 类型

Vite Proxy 配置

开发模式下 Vite 代理配置（vite.config.ts）：

浏览器 → http://localhost:5173/api/runs
         ↓ Vite proxy rewrite: /api → /
         http://localhost:8000/runs

浏览器 → ws://localhost:5173/api/ws/runs/{id}
         ↓ Vite proxy rewrite
         ws://localhost:8000/ws/runs/{id}

后端端口通过 VITE_API_PORT 环境变量配置，默认 8000。