TraceStudio-dev/docs/server/api.md

# TraceStudio — 后端 API 文档（server 视角）

本文件以实现代码为准，汇总了当前后端提供的 HTTP API（可用于生成 OpenAPI 或 mock server）。所有路径以服务器根地址为前缀，路由通常被挂载在 `/api` 下（例如最终完整路径为 `/api/files/list`）。

**概览**
- **Backend stack**: FastAPI（Python 3.11+）、Polars、自定义节点加载/执行框架。
- **安全约定**: 所有文件路径会经过 `sanitize_path` / `is_safe_path` 校验以防目录遍历；自定义节点文件名通过 `NodeValidator.is_safe_filename` 验证。

**DataFrame 序列化说明**
- **字段约定**: 后端在返回计算结果中会将 `polars.DataFrame` 序列化为一个带 `__type: DataFrame` 的对象以便前端预览与分页请求。
- **结构示例**:

```json
{
  "__type": "DataFrame",
  "columns": ["col1", "col2"],
  "preview": [{"col1": 1, "col2": "a"}, ...],
  "rows": 1234
}
```

此格式用于 `/node/preview` 返回和 `/graph/execute` 中每个节点 outputs 的预览。`preview` 的长度受服务端限制（通常为 10 或 20）。

**全局错误处理约定**
- 成功返回一般为 JSON 对象并包含 `success` 或 `status: "success"`。
- 失败时使用 HTTP 错误码（400/403/404/500）并在 body 中提供 `detail` 字段；`/graph/execute` 在 500 时会返回更详细的 `traceback` 对象。

--

**1) 文件与文件管理（Files）**

说明: 文件相关接口分布在 `server/file_manager.py`（router prefix `/api/files`）与 `server/app/api/endpoints_upload.py`（被挂载到 `/api`，内部路径为 `/files/*`），两套接口在功能上有重叠，前端可以任选其一，推荐使用 `/api/files/*` 族。

- `GET /api/files/list` — 列出目录
  - Query: `path`（string, 可空，空或 `/` 表示根），`username`（可选，用于确保用户目录存在）
  - Response: `{ "path": "...", "items": [ {name,path,type,size,modified,extension}, ... ] }
  - Errors: 400（路径不是目录）、403（路径非法）、404（路径不存在）、500（读取失败）

- `POST /api/files/upload` — 上传文件（multipart）
  - Form: `file` (multipart file)
  - Query: `path`（目标目录）、`username`（可选）
  - Response: `{ "success": true, "file": FileInfo, "message": "..." }`
  - Notes: 如果同名文件已存在会自动加后缀避免覆盖（除非使用专门的 save/force 接口）。

- `POST /api/files/action` — 文件基本操作
  - Body: `FileAction` 模型 `{ action, path, target?, new_name? }`
  - 支持操作: `move`, `delete`, `mkdir`, `rename`
  - Response: 视操作返回 `{ success: true, ... }` 或详细信息

- `GET /api/files/download` — 下载
  - Query: `path`（必需）
  - Response: 返回 `FileResponse` (streamed)

- `GET /api/files/info` — 获取文件/文件夹信息
  - Query: `path`（必需）
  - Response: `FileInfo`（或 `{ exists: false }`）

模型参考 (`FileInfo`, `FileAction`)

```py
class FileInfo(BaseModel):
    name: str
    path: str
    type: str  # 'file' | 'folder'
    size: Optional[int]
    modified: Optional[str]
    extension: Optional[str]

class FileAction(BaseModel):
    action: str  # 'move'|'delete'|'mkdir'|'rename'
    path: str
    target: Optional[str]
    new_name: Optional[str]
```

实现状态: 已实现（路径清理、权限检查、用户目录创建、重命名/删除/移动、下载流）。

--

**2) 图/节点（Graph & Node）**

- `GET /api/plugins` — 获取可用节点插件
  - Response: `{ "plugins": { class_name: metadata }, "total": N, "categories": [...] }`
  - Notes: metadata 包含 `display_name`, `category`, `description`, `inputs`, `outputs`, `param_schema`, `class_name` 等。

- `POST /api/node/preview` — 预览单个节点执行结果
  - Body: `NodePreviewRequest` `{ node: NodeSchema, limit: int = 10 }`
  - NodeSchema 支持 `data` 或 `params` 两种字段（兼容历史 payload）
  - Response 示例:

```json
{
  "class_name": "MyNode",
  "status": "success",
  "columns": ["a","b"],
  "preview": [{"a":1,"b":2}],
  "context": {...}
}
```

- `POST /api/graph/execute` — 执行完整图
  - Body: `GraphExecuteRequest` `{ nodes: [NodeSchema], edges: [EdgeSchema], settings?: {} }`
  - Response (成功示例):

```json
{
  "status": "success",
  "message": "成功执行 3 个节点",
  "execution_time": 0.123,
  "results": {
    "node1": { "status": "ok", "outputs": {"out": {"__type":"DataFrame", ...}}, "error": null }
  },
  "stats": { "total_nodes": 3, "total_edges": 2, "execution_order": ["node1","node2"] }
}
```

 - 返回格式说明: `results` 为 node_id 映射；每个节点包含 `status`, `outputs`, `error`。如果输出为 DataFrame，按上文序列化规则返回。

模型摘要 (`NodeSchema`, `EdgeSchema`, `GraphExecuteRequest`)

```py
class NodeSchema(BaseModel):
    id: str
    type: str
    class_name: Optional[str]
    function: Optional[str]
    data: Optional[Dict[str,Any]]
    params: Optional[Dict[str,Any]]

class EdgeSchema(BaseModel):
    id: Optional[str]
    source: str
    target: str
    dimension_mode: str
    source_port: Optional[str]
    target_port: Optional[str]

class GraphExecuteRequest(BaseModel):
    nodes: List[NodeSchema]
    edges: List[EdgeSchema]
    settings: Optional[Dict[str,Any]]
```

实现状态: 已实现。注意：后端兼容旧/新 executor 返回格式（可能是 `node_infos/node_results` 或 node_id->info 映射）。`/nodes/save` 接口为占位，尚需实现持久化策略。

--

**3) 自定义节点管理（Custom Nodes）**

- 前缀: `/api/custom-nodes/*`

- `GET /api/custom-nodes/list` — 列出自定义节点文件（含验证状态）

- `POST /api/custom-nodes/validate` — 验证节点代码（不保存）
  - Body: `{ code: str, filename?: str }`
  - Response: `{ success: true, validation: { valid: bool, errors: [...] } }`

- `GET /api/custom-nodes/read/{filename}` — 读取节点源码
  - Response: `{ success: true, filename, code, size, modified }`

- `POST /api/custom-nodes/save` — 保存并加载节点
  - Body: `{ filename, code, force?: bool }`
  - 行为: 验证代码后保存，支持备份与强制覆盖，保存后调用 loader 加载节点并返回 `load_result`。

- `POST /api/custom-nodes/action` — 对节点执行 `load`/`unload`/`delete`/`rename`

- `GET /api/custom-nodes/download/{filename}` — 下载节点文件

- `POST /api/custom-nodes/upload` — 上传节点文件（会验证并加载）

- `GET /api/custom-nodes/loaded` — 返回运行时已加载类及其 metadata

- `POST /api/custom-nodes/reload-all` — 重新加载所有自定义节点

- `GET /api/custom-nodes/example` — 返回示例节点代码（供编辑器使用）

模型参考 (`NodeValidateRequest`, `NodeSaveRequest`, `NodeActionRequest`)

实现状态: 功能齐全（验证、保存、备份、加载/卸载、列出、下载）。注意：保存/上传过程会在保存前使用 `validate_node_code` 做静态验证并在失败时阻止加载。

--

**4) 用户管理相关（简要）**

- `GET /api/users/list` — 返回 `{ users: [...], count: N }`
- `POST /api/users/add` — 接受 `{ username, display_name? }`，会验证用户名格式、写入 users DB 并创建用户工作区。

实现状态: 已实现（基础用户 CRUD 含创建与列表）。

--

**5) 其他/占位接口**

- `POST /api/nodes/save` — 当前仅作占位，返回 success: true；需要后续实现节点保存到文件或 DB 的策略。

--

**对前端/集成测试的建议**
- 使用 `NodeSchema` 中的 `class_name` 作为后端加载的实现类标识；如果客户端只提供 `data/params` 中的 `meta.class_name`，后端也会兼容读取。
- 推荐按 `__type: DataFrame` 约定解析节点输出并在前端提供 DataFrame 视图组件（columns + preview + rows）。
- 自定义节点上传必须在后端验证通过后才加载，前端应展示 `validation` 结果并要求用户确认覆盖。

--

如需我把上述模型转换为可直接导入的 OpenAPI spec（`openapi.json`）以便一键生成 mock server 或 SDK，请回复确认，我会在下一步生成并附上简化 schema 片段。

---

引用实现: [server/file_manager.py](server/file_manager.py#L1-L400)
参考实现: [server/app/api/endpoints_upload.py](server/app/api/endpoints_upload.py#L1-L400), [server/app/api/endpoints_graph.py](server/app/api/endpoints_graph.py#L1-L400), [server/app/api/endpoints_custom_nodes.py](server/app/api/endpoints_custom_nodes.py#L1-L400)