TraceStudio V2 前端框架与关键 API 协议草案

重要说明：本文件包含针对 V2 架构的一套 API 草案与实现建议，但最终所有 API 路径、字段、响应格式以及行为以用户/后端方实际提供的接口规范为准。在开始任何前端实现之前，请将你的 API 规范（OpenAPI / JSON Schema / 示例请求响应）附上或指向可访问的接口文档，前端团队将严格按该规范实现对接。

本文档基于 V2 架构白皮书（TraceStudio V2 架构规范白皮书），梳理前端 `Core / View` 分层设计要点以及一组建议性的 API 协议（示例：`/api/schema`、`/api/graph/execute`、WebSocket 执行事件等），用于与后端就契约达成一致并快速落地 PoC。

目标受众：前端工程师、后端工程师、架构评审者。

一、前端架构快照

Core（纯 TypeScript，无 React）：
- 目录：web/src/core/
- 职责：模型（GraphModel, NodeModel, PortModel）、服务（ApiService, SchemaService, ExecutionService）、store（Zustand ViewModel）。
View（纯 React）：
- 目录：web/src/components/
- 职责：渲染、事件转发，仅通过 Core 的 ViewModel 读取/修改数据。
协议优先：所有节点参数/控件/验证逻辑由后端通过 /api/schema 提供 JSON Schema，前端根据 schema 动态渲染 Inspector 中的控件。

二、关键 API 协议草案

说明：下列 HTTP 路径与消息格式为示例/草案，将被用户提供的 API 定义覆盖。如果你已准备好接口文档（OpenAPI / Swagger / 示例 JSON），把文档路径或文件上传到仓库（建议放在 server/api_spec/），我会根据该规范自动生成 TypeScript 接口并调整前端实现。

（示例草案）约定：所有路径以 /api/ 前缀，版本采用 v1 或者通过 Accept / X-Api-Version 头控制。

/api/schema — 获取节点定义与 UI 控件描述

方法：GET /api/schema 或 GET /api/schema/{node_type}
功能：返回后端注册的节点类型列表，及每个节点的 JSON Schema 描述（包括参数、输入/输出端口、默认值、控件类型）。
示例响应：

{
  "version": "1.0",
  "nodes": [
    {
      "type": "UTraceLoader",
      "title": "UTrace Loader",
      "inputs": [],
      "outputs": ["trace"],
      "parameters": [
        {"name":"path","type":"string","widget":"FilePicker","default":""},
        {"name":"sampleRate","type":"number","widget":"Slider","min":1,"max":100,"default":10}
      ]
    }
  ]
}

字段说明：

parameters[].widget：由后端建议的控件类型（Slider, Toggle, FilePicker, CodeEditor, 等），前端通过 WidgetRegistry 映射到具体 React 组件。

/api/graph/execute — 提交图以执行

方法：POST /api/graph/execute
功能：接收序列化后的图（节点列表、连线、参数），后端返回一个 execution_id 并异步执行。
示例请求体：

{
  "graph": {
    "nodes": [
      {"id":"n1","type":"UTraceLoader","params":{"path":"/data/trace.utrace","sampleRate":5}},
      {"id":"n2","type":"FrameTimeChart","params":{}}
    ],
    "edges": [
      {"from":"n1","out":"trace","to":"n2","in":"input"}
    ]
  },
  "runOptions": {"preview":true}
}

响应示例：

{ "execution_id": "exec_20260110_0001", "status": "accepted" }

执行结果与事件机制：

后端应提供 WebSocket 或 SSE 路径（例如 ws://host/api/graph/exec/ws?execution_id=...）用于实时推送节点状态、日志与输出引用。
推送事件示例（JSON）:

{ "type":"node_status", "execution_id":"exec_...", "node_id":"n1", "status":"running" }
{ "type":"node_status", "execution_id":"exec_...", "node_id":"n1", "status":"success", "outputs": {"trace":"/cloud/users/guest/results/trace.parquet"} }
{ "type":"log", "execution_id":"exec_...", "level":"info", "message":"Node n1 parsed 1000 frames" }

/api/schema/validate — 参数验证（可选，后端或前端都可做）

方法：POST /api/schema/validate
功能：接收单个节点类型与参数，返回验证结果和改进建议（例如值超出范围）。

请求示例：

{ "type":"UTraceLoader","params": {"sampleRate": 0} }

响应示例：

{ "valid": false, "errors": [{"field":"sampleRate","message":"must be >= 1"}] }

/api/nodes/list & /api/node/{id} — 节点元数据与详情（可选）

用于前端在节点库展示可用节点的说明、示例与快速文档。

三、前端 TypeScript 接口草案

下面是前端用于与后端交互的主要类型草案（可放在 web/src/core/model/types.ts）。注意：这些类型为建议草案，将在接收到用户提供的 API / OpenAPI spec 后自动调整并严格对齐。

export interface ParameterSchema {
  name: string;
  type: 'string' | 'number' | 'boolean' | 'object' | 'array';
  widget?: string;
  default?: unknown;
  // 额外字段将根据后端 schema 扩展
  [k: string]: unknown;
}

export interface NodeSchema {
  type: string;
  title?: string;
  inputs: string[];
  outputs: string[];
  parameters: ParameterSchema[];
}

export interface GraphPayload {
  nodes: Array<{id: string; type: string; params: Record<string, unknown>}>
  edges: Array<{from:string; out:string; to:string; in:string}>;
}

四、错误处理、版本与安全建议

版本控制：在 /api/schema 返回中包含 version 字段；前端在不兼容时应提示用户升级后端或降级前端。
错误语义化：所有错误响应统一返回 {code:int, message:string, details?:any}。
权限与隔离：所有执行生成的输出应写入用户隔离路径（例如 cloud/users/{username}/results/{execution_id}/），响应中只返回可访问引用。

五、下一步交付（我可以为你做的）

Draft A: 基于你提供的 API 规范（OpenAPI / JSON Schema）生成 web/src/core/model/types.ts、web/src/core/services/ApiService.ts、web/src/core/services/SchemaService.ts 的初始实现与类型定义。
Draft B: 如果需要，我可以生成后端 Mock 层（server/app/api/schema.py 或 server/api_spec/mock_server.py），用于本地开发与前端联调；该 Mock 将严格基于你提供的示例或 OpenAPI 进行生成。
Draft C: 生成一个小型 end-to-end 示例：前端请求 （以你提供的 schema 路径为准），渲染一个 UniversalNode，并通过 POST /api/graph/execute 提交图然后通过 WebSocket 接收模拟事件；示例会以用户接口为真实来源。

请把你的 API 规范以 OpenAPI/Swagger 文件、或至少包含以下内容的示例 JSON 文件上传到仓库（建议路径：server/api_spec/）：

/api/schema 或 /api/schema/manifest 的响应示例
/api/execution/queue 的请求/响应示例
WebSocket 事件格式示例（或事件类型文档）

我会先根据你提供的 API 规范生成 TypeScript 类型与服务骨架，然后再继续实现前端的 registry 与 Inspector。请选择要我先做的 Draft（推荐 Draft A）。

7.0 KiB Raw Blame History Unescape Escape