158 lines
7.0 KiB
Markdown
158 lines
7.0 KiB
Markdown
# 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）。
|