61 lines
3.9 KiB
Markdown
61 lines
3.9 KiB
Markdown
# Components 结构说明
|
||
|
||
本文件由 Copilot 自动生成，记录 `web/src/components` 及其子目录下的所有组件文件与简短职责说明，便于快速理解前端 UI 组织与接口契约。
|
||
|
||
说明：每一项均为实现现状的简短说明，若实现细节变更，请人工批准并同步更新本文件与 `docs/ai/copilot.md` 的导航部分。
|
||
|
||
---
|
||
|
||
## 根组件目录 (web/src/components)
|
||
|
||
- AppShell.tsx — 应用主壳组件，负责总体布局（HeaderBar、左侧面板、画布、Inspector、底部 RunBar）和全局显示逻辑。
|
||
- HeaderBar.tsx — 顶部导航栏与控制面板，包含 Run/Save、工作流标题编辑、用户切换、触发图执行逻辑。
|
||
- BreadcrumbNav.tsx — 面包屑导航，用于文件路径/目录导航展示和跳转。
|
||
- NodePalette.tsx — 节点库面板，展示可用算子/节点，提供搜索、分类与拖拽到画布功能。
|
||
- FileExplorer.tsx — 文件管理器，提供文件列表、上传、下载、重命名、删除、拖拽到画布和在新窗口预览等功能。
|
||
- FileViewer.tsx — 文件预览器模态，支持文本/代码/图片预览与在线编辑保存。
|
||
- Inspector.tsx — 右侧属性面板，展示选择节点的参数、上下文变量、预览与单节点预览触发逻辑。
|
||
- CustomNodeEditor.tsx — 自定义节点编辑器，支持查看/编辑/验证/保存 Python 自定义节点文件并与后端交互。
|
||
- Workspace.tsx — 中央画布容器，封装 React Flow，负责节点/连线渲染、拖放逻辑、缩放与选区等交互。
|
||
- SettingsModal.tsx — 系统设置模态，提供修改 API 地址、缓存策略、日志等级等配置项的 UI。
|
||
|
||
|
||
## 子目录：nodes (web/src/components/nodes)
|
||
|
||
- UniversalNode.tsx — 通用节点渲染组件（React Flow 节点），负责渲染节点头部、状态灯、输入/输出端口（Handle）、参数摘要与预览区域；为大多数节点类型提供一致的视觉和交互呈现。
|
||
|
||
(注：如果需要，可在此处继续扩展每个自定义节点具体文件的职责说明。)
|
||
|
||
|
||
## 子目录：request (web/src/components/request)
|
||
|
||
- graphRequest.ts — 将前端的 nodes/edges/globalSettings 等转换为后端执行器 (`/api/graph/execute`) 期望的 payload 的适配器/构造器函数。
|
||
|
||
|
||
## 新增（重构骨架）
|
||
|
||
为支持 Logic/UI 分离与迁移，已在项目中新增以下骨架目录与文件（初步实现，需人工补全错误处理与细节）：
|
||
|
||
- `web/src/core/services/ExecutionService.ts` — 执行服务：负责将前端节点与连线构建为后端 payload 并调用 `/api/graph/execute`。
|
||
- `web/src/core/model/NodeModel.ts` — 节点模型：封装节点行为与转为 React Flow 对象的函数。
|
||
- `web/src/core/model/GraphModel.ts` — 图模型：管理节点集合、连线与连接规则（类型安全检查）。
|
||
|
||
- `web/src/components/graph/GraphCanvas.tsx` — 画布渲染占位：拆解自 `Workspace.tsx`，仅负责渲染 React Flow（事件委托给 store / hooks）。
|
||
- `web/src/components/graph/GraphControls.tsx` — 画布控制按钮集合（缩放、视图整合等占位）。
|
||
- `web/src/components/_layouts/PanelContainer.tsx` — 侧边/面板容器通用组件。
|
||
|
||
- `web/src/hooks/useCanvasDrop.ts` — 拖拽处理 Hook：解析 `dataTransfer` 并调用 store 的 `addNodeFromSchema`（初始实现）。
|
||
|
||
这些文件用于逐步迁移 `Workspace.tsx` 的职责到更清晰的 Core / UI 分层。请在迁移过程中逐步替换原始实现并运行测试验证行为一致性。
|
||
|
||
|
||
## 其他说明与建议
|
||
|
||
- 文档维护：任何在 `web/src/components` 下新增/删除文件时，请在本文件中同步变更并在 PR 描述中提醒文档更新。
|
||
- 进一步增强：可为每个组件补充 `Props` 类型、主要方法、依赖的 `store` 或 API 端点，便于自动化生成接口契约。
|
||
|
||
---
|
||
|
||
文档生成时间: 2026-01-10
|
||
生成者: Copilot（自动化脚本）
|