# TraceStudio — Server 核心功能与组件说明

本文档概述 `server/` 目录的核心功能、模块职责、执行流程以及可扩展点，便于新贡献者快速理解后端体系与关键逻辑。

**目标**
- 将 Unreal Insights 导出的数据通过可编程节点图进行二次加工与可视化。
- 后端职责: 解析/存储数据、管理用户文件、加载/验证/执行节点、调度工作流、并提供可供前端调用的 REST API。

--

**一、核心模块（按目录）**

- `server/main.py`
  - FastAPI 应用入口，负责应用初始化、路由挂载、CORS 配置与 startup 事件（例如 reload custom nodes、初始化 cache）。

- `server/app/api/` — HTTP 路由集合
  - `endpoints_upload.py` / `server/file_manager.py` — 文件浏览、上传、下载、文件操作 API。
  - `endpoints_graph.py` — Graph/Node 相关 API：插件列表、节点预览、图执行、用户管理等。
  - `endpoints_custom_nodes.py` — 自定义节点的验证/上传/保存/加载/列表/下载接口。

- `server/app/core/` — 后端核心逻辑
  - `node_base.py` — 节点基类 (`TraceNode`) 与常用接口（`get_metadata()`, `execute()` / `wrap_process()` 等）。
  - `node_loader.py`、`node_registry.py` — 自定义节点扫描、动态加载与注册。
  - `node_validator.py` — 节点代码静态校验与安全审查。
  - `workflow_executor.py` — 工作流执行器，负责节点调度、依赖解析与运行时上下文管理。
  - `cache_manager.py` — 缓存层，用于缓存节点结果或插件元数据以提升性能。
  - `user_manager.py` — 用户路径、profile 与基本用户 CRUD。

- `server/custom_nodes/` — 用户可编辑节点代码（非核心但受支持）

--

**二、主要功能点（Feature List）**

1. 文件管理
   - 多用户文件根 (`cloud/`)，支持 `shared`, `users/{username}/workflows`, `data`, `results`。
   - 安全路径校验、上传去重、文件操作（move/rename/delete/mkdir）、下载流式返回。

2. 自定义节点生命周期
   - 上传/验证: `validate_node_code` 进行静态分析，阻止可疑代码。
   - 保存/备份: 保存前备份旧版本，支持 `force` 覆盖。
   - 加载/卸载: `node_loader` 动态导入并注册节点类到 `NodeRegistry`。
   - 运行时已加载查询与批量重载。

3. 节点图执行引擎
   - 接受 `GraphExecuteRequest`（nodes/edges/settings），将前端节点映射为内部执行单元。
   - 支持参数兼容（`data` / `params`），并统一传入 `params` 给执行器。
   - 执行器返回多种格式（兼容旧版 node_infos/node_results 或新的报告结构），后端负责序列化输出并将 DataFrame 转为预览格式。

4. 节点预览（快速迭代）
   - 允许前端在编辑器中对单个节点做即时预览（限制行数），返回 columns + preview。

5. 用户与权限（基础）
   - 用户列表与新增用户接口；为新用户创建工作目录结构。

--

**三、核心执行流程（文本流程图）**

1. 用户发起 `POST /api/graph/execute` 请求。
2. `endpoints_graph.execute_graph` 做入参校验、将 `NodeSchema/EdgeSchema` 转换为内部执行单元。
3. 创建 `WorkflowExecutor`（含用户上下文），并调用 `executor.execute(nodes, edges, global_context)`。
4. `WorkflowExecutor` 根据 DAG 拓扑计算执行序列，按节点调用对应 `TraceNode.wrap_process()`。
5. 各节点运行时可读写缓存（`CacheManager`），并可以访问 `context`（例如 user_id、preview_mode）。
6. 执行完成后，执行器返回 `node_infos/node_results` 或早期格式，`execute_graph` 对输出进行兼容处理并将复杂对象（DataFrame）序列化为预览对象。
7. 返回给客户端完整 `results` 映射与执行统计信息。

--

**四、关键实现要点与注意事项**

- DataFrame 处理: 使用 Polars（或兼容 pandas 的转换），但在 API 层返回 preview 而非完整表，避免大 payload。
- 自定义代码安全: 目前实现为保存后加载，强烈建议在生产环境中添加沙箱隔离或手动审查流程。
- 兼容性: executor 的返回格式存在历史差异，API 层做了兼容处理。新增 executor 功能时应保持向后兼容或更新文档并通知前端。
- 缓存失效策略: 对于依赖外部数据的节点，cache key 需要包含数据版本与节点参数，避免脏数据复用。

--

**五、扩展点（供后续开发）**

- 提供 OpenAPI 完整 schema 并在 CI 中自动校验前后端契约。
- 增加节点运行时沙箱（例如使用 Subprocess + seccomp 或 Wasm 运行自定义代码）。
- 支持异步/分布式执行器，利用外部任务队列（例如 Celery / RabbitMQ / Redis）以支持长耗时任务与横向扩展。
- 为自定义节点提供版本化（metadata 中含 `version` 字段）与回滚机制。

--

引用文件与快速查阅:
- [server/main.py](server/main.py#L1-L1)
- [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)