TraceStudio-dev/docs/web/api.md

# TraceStudio 后端 API 规范（前端视角）

目标：为前端与 AI 提供一份完整、可机器读取的后端 API 规范文档，使第三方或 AI 能基于此快速生成 mock server 或直接对接后端。

说明：本文件以 `server/app/api/*.py` 中实现的接口为准，列出每个端点的 URL、方法、请求字段、响应示例以及用于 mock 服务的 JSON schema。

---

## 目录
- 文件管理 API (`/api/files/*`)
- 插件与节点 API (`/api/plugins`, `/api/node/preview`, `/api/graph/execute`, `/api/nodes/save`)
- 用户管理 (`/api/users/*`)
- 自定义节点管理 (`/api/custom-nodes/*`)

---

## 公共响应格式
- 成功响应通常包含 `data` 或直接返回对象（习惯差异），建议 mock server 使用下面两种可互换格式：

1) 标准包裹格式：
```json
{ "data": { ... }, "error": null }
```

2) 直接对象格式（FastAPI 端点常用）：
```json
{ "success": true, "message": "...", "...": ... }
```

为兼容前端接入，mock server 可以默认返回 `{"data":..., "error": null}`，同时支持返回原始端点返回的直出格式。

---

## 文件管理 API

### GET /api/files/list
- 描述：列出目录内容
- 参数（query）：
  - `path` (string) 相对路径，默认 ""
- 成功响应示例：
```json
{
  "path": "users/guest/data",
  "items": [
    { "name": "护送30.utrace", "path": "users/guest/data/护送30.utrace", "type": "file", "size": 12345, "extension": ".utrace" },
    { "name": "sample.csv", "path": "users/guest/data/sample.csv", "type": "file", "size": 1024, "extension": ".csv" }
  ]
}
```
- Mock schema (JSON Schema simplified):
```json
{
  "type": "object",
  "properties": {
    "path": {"type":"string"},
    "items": {"type":"array","items": {"type":"object","properties": {"name":{"type":"string"},"path":{"type":"string"},"type":{"type":"string"},"size":{"type":"number"},"extension":{"type":"string"}}}}
  }
}
```

### POST /api/files/upload
- 描述：上传文件（multipart/form-data）
- 请求：multipart 表单，`file` 字段为文件，query 可带 `path` 与 `username`
- 成功响应示例：
```json
{
  "success": true,
  "file": { "name": "sample.csv", "path": "users/guest/data/sample.csv", "size": 1024 }
}
```
- 注意：mock server 可模拟写入并返回路径与 size

### GET /api/files/download
- 描述：下载文件
- 参数（query）：`path` (string) 必需
- 响应：文件二进制（mock server 可返回静态文本或固定二进制）

### GET /api/files/info
- 描述：获取文件元信息
- 参数：`path` (string)
- 成功示例：
```json
{ "exists": true, "name": "sample.csv", "path": "users/guest/data/sample.csv", "type": "file", "size": 1024, "modified": 1670000000.0, "extension": ".csv" }
```

### POST /api/files/action
- 描述：文件操作（delete/mkdir/rename）
- 请求体：JSON
```json
{ "action": "delete|mkdir|rename", "path": "users/guest/data", "new_name": "new_folder" }
```
- 成功示例：
```json
{ "success": true, "message": "Deleted" }
```

---

## 插件与图执行 API

### GET /api/plugins
- 描述：获取可用节点插件元数据
- 成功示例（精简）：
```json
{
  "plugins": {
    "CSVLoader": { "display_name":"CSV 数据加载器", "category":"Loader/CSV", "class_name":"CSVLoader", "param_schema": [{"name":"file_path","type":"string","default":""}], "inputs": [], "outputs": [{"name":"table","type":"DataTable"}] }
  },
  "total": 1,
  "categories": ["Loader","Transform","Visualizer"]
}
```
- Mock schema：插件对象映射，键为 `class_name`

### POST /api/node/preview
- 描述：预览单个节点（返回列与 preview 数据）
- 请求 JSON：
```json
{ "node": { "id": "n1", "type": "universal", "class_name": "CSVLoader", "data": { "file_path": "users/guest/data/sample.csv" } }, "limit": 10 }
```
- 成功示例：
```json
{ "class_name":"CSVLoader", "status":"success", "columns":["col1","col2"], "preview":[{"col1":1,"col2":2}], "context": {} }
```
- 说明：如果节点输出为 DataFrame，会返回 `columns` 与 `preview` 列表

### POST /api/graph/execute
- 描述：执行完整计算图
- 请求 JSON（精简）：
```json
{ "nodes": [{"id":"n1","type":"universal","class_name":"CSVLoader","params":{...}}], "edges": [{"source":"n1","target":"n2"}], "settings": {} }
```
- 成功示例（精简）：
```json
{
  "status":"success",
  "message":"成功执行 2 个节点",
  "execution_time": 0.123,
  "results": {
    "n1": { "status":"success", "outputs": {"table": {"__type":"DataFrame","columns":["a","b"],"preview":[{"a":1,"b":2}],"rows":100} }, "error": null }
  },
  "stats": { "total_nodes":2, "total_edges":1 }
}
```
- Mock server应实现 DataFrame preview 序列化结构（`__type: DataFrame`）以便前端渲染

### POST /api/nodes/save
- 描述：保存节点配置
- 请求 JSON：
```json
{ "nodeId": "n_xxx", "nodeData": {...} }
```
- 成功示例：
```json
{ "success": true, "message": "节点 n_xxx 配置已保存", "nodeId": "n_xxx" }
```

---

## 用户 API

### GET /api/users/list
- 描述：返回用户列表
- 成功示例：
```json
{ "users": ["guest","ouczbs"], "count": 2 }
```

### POST /api/users/add
- 描述：添加用户
- 请求 JSON：
```json
{ "username":"newuser", "display_name":"New User" }
```
- 成功示例：
```json
{ "success": true, "message": "用户 newuser 创建成功" }
```

---

## 自定义节点管理 API（/api/custom-nodes/*）

说明：此命名空间包含上传、验证、保存、加载自定义节点的完整流程，mock server 可实现下列端点的简化版本。

### GET /api/custom-nodes/list
- 示例响应：
```json
{ "success": true, "total": 1, "nodes": [{"filename":"example.py","valid":true,"loaded":true}] }
```

### POST /api/custom-nodes/validate
- 请求：{ "code": "<python code>" }
- 返回：{ "success": true, "validation": {"valid":true, "errors": [] } }

### POST /api/custom-nodes/save
- 请求：{ "filename":"my_node.py","code":"...","force":false }
- 返回：{ "success": true, "message":"节点已保存并加载", "filename":"my_node.py" }

### POST /api/custom-nodes/action
- 请求：{ "filename":"my_node.py","action":"load|unload|delete|rename","new_filename":"..." }
- 返回：{ "success": true, "message":"..." }

### POST /api/custom-nodes/upload
- multipart 文件上传，返回 `success`/`validation`/`load_result`

### GET /api/custom-nodes/loaded
- 返回当前已加载节点列表（class_name + metadata）

---

## Mock Server 指南（快速上手）

1. 推荐使用 `json-server` 或用 Node.js + Express 快速 mock（可返回静态 JSON 或根据请求构造回复）。
2. 必须支持：
   - `/api/plugins` 返回插件元数据
   - `/api/node/preview` 接受 `node` + `limit`，返回 `columns` + `preview`
   - `/api/graph/execute` 返回 `results`，DataFrame 用 `__type: DataFrame` 标记
   - `/api/files/*` 支持 list/upload/download/info/action
   - `/api/custom-nodes/*` 简单实现文件列表、validate、upload、loaded
3. 示例：使用 Express 的伪代码快速实现 `/api/node/preview`：

```js
app.post('/api/node/preview', (req, res) => {
  const { node, limit } = req.body
  // 根据 node.class_name 返回不同的 preview
  if (node.class_name === 'CSVLoader') {
    return res.json({ class_name: 'CSVLoader', status: 'success', columns: ['a','b'], preview: [{a:1,b:2}] })
  }
  res.status(500).json({ error: 'Unknown node' })
})
```

---