TraceStudio-dev/docs/web1.1/v2_api_and_architecture.md

# 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` 头控制。

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

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

```json
{
  "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 组件。

2) `/api/graph/execute` — 提交图以执行

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

```json
{
  "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}
}
```

响应示例：

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

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

```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" }
```

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

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

请求示例：

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

响应示例：

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

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

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

## 三、前端 TypeScript 接口草案

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

```ts
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）。