89 lines
4.2 KiB
Markdown
89 lines
4.2 KiB
Markdown
# Web 前端结构说明
|
||
|
||
本文件记录 `web/` 目录下的主要文件与子目录，并对每个文件/目录给出简短职责说明，便于快速理解前端代码组织与接口契约。
|
||
|
||
说明：请在对前端结构进行修改或新增文件时同步更新本文件。
|
||
|
||
---
|
||
|
||
## 顶层文件
|
||
|
||
- `index.html` — Vite 应用入口 HTML 模板，挂载 React 根节点和必要 meta/脚本。
|
||
- `package.json` — 前端依赖与 npm 脚本配置（`dev`、`build`、`preview` 等）。
|
||
- `vite.config.ts` — Vite 构建与开发服务器配置（别名、环境变量、插件）。
|
||
- `tsconfig.json` / `tsconfig.app.json` / `tsconfig.node.json` — TypeScript 编译配置与项目范围划分。
|
||
- `postcss.config.cjs` / `tailwind.config.cjs` — CSS/ Tailwind 配置。
|
||
- `README.md` / `SETUP.md` — 前端开发与启动说明。
|
||
|
||
## 目录：public
|
||
|
||
- `public/` — 静态资源文件夹，直接由 Vite 拷贝到输出目录（favicon、静态图片等）。
|
||
|
||
## 目录：src
|
||
|
||
- `src/main.tsx` — 应用入口文件，初始化 i18n、state provider，并挂载 `App`。
|
||
- `src/App.tsx` — 顶层 React 组件，通常负责路由或全局布局占位。
|
||
- `src/i18n.ts` — 国际化初始化与语言资源配置。
|
||
- `src/index.css` / `src/App.css` — 全局样式与组件级样式入口（Tailwind/CSS 组合）。
|
||
|
||
### 子目录：assets
|
||
|
||
- `src/assets/` — 图片、图标及其他静态前端资源。
|
||
|
||
### 子目录：components
|
||
|
||
- `src/components/AppShell.tsx` — 应用主壳，组合 `HeaderBar`、侧边栏、画布和 `Inspector`。
|
||
- `src/components/HeaderBar.tsx` — 顶部控制栏，包含 Run/Save、用户/环境切换等操作入口。
|
||
- `src/components/BreadcrumbNav.tsx` — 面包屑导航组件，用于目录/文件路径导航。
|
||
- `src/components/NodePalette.tsx` — 节点库面板，显示可用节点并实现拖拽到画布。
|
||
- `src/components/FileExplorer.tsx` — 文件资源管理器，支持文件操作与拖拽到画布。
|
||
- `src/components/FileViewer.tsx` — 文件内容预览与编辑模态。
|
||
- `src/components/Inspector.tsx` — 右侧参数面板，展示所选节点的参数与预览。
|
||
- `src/components/CustomNodeEditor.tsx` — 自定义节点编辑器，编辑 Python 自定义节点元数据并与后端交互。
|
||
- `src/components/Workspace.tsx` — 中央画布容器（React Flow 封装），处理节点渲染、连线、交互与缩放。
|
||
- `src/components/SettingsModal.tsx` — 系统设置弹窗，管理 API 地址与运行时选项。
|
||
|
||
#### 子目录：components/nodes
|
||
|
||
- `src/components/nodes/UniversalNode.tsx` — 通用节点渲染组件，负责节点头部、handles、参数摘要与状态灯。
|
||
|
||
#### 子目录：components/graph
|
||
|
||
- `src/components/graph/GraphCanvas.tsx` — 画布渲染组件（迁移目标），仅负责 React Flow 渲染与低层事件转发。
|
||
- `src/components/graph/GraphControls.tsx` — 画布控制按钮（缩放/视图重置等）。
|
||
|
||
#### 子目录：components/_layouts
|
||
|
||
- `src/components/_layouts/PanelContainer.tsx` — 侧边栏/面板容器通用布局组件。
|
||
|
||
### 子目录：hooks
|
||
|
||
- `src/hooks/useCanvasDrop.ts` — 处理拖拽到画布的 DataTransfer，解析并调用 store 的 `addNodeFromSchema`。
|
||
|
||
### 子目录：stores
|
||
|
||
- `src/stores/` — 状态管理目录（可能包含 Zustand/Redux store），管理节点集合、选择状态与界面首级数据。
|
||
|
||
### 子目录：utils
|
||
|
||
- `src/utils/api.ts` — 所有后端 API 调用的封装函数（例如构造 `graph/execute` payload 的辅助函数）。
|
||
- `src/utils/` — 其他工具函数集合（格式化、解析等）。
|
||
|
||
### 子目录：components/request
|
||
|
||
- `src/components/request/graphRequest.ts` — 将前端的 nodes/edges/globalSettings 转换为后端 `/api/graph/execute` 所需的 payload 的适配器函数。
|
||
|
||
## 目录：tests
|
||
|
||
- `web/tests/TEST_INTEGRATION.js` — 前端集成测试（占位/示例），用于验证关键 UI 交互或端到端路径。
|
||
|
||
---
|
||
|
||
## 维护建议
|
||
|
||
- 在每次对 `src/components` 做结构性变动时，同时更新本文件与 `docs/web/components_structure.md`。
|
||
- 为 `stores`、`core/model` 提供清晰的类型定义文件，便于组件与服务之间的契约校验。
|
||
|
||
文档生成时间: 2026-01-10
|
||
生成者: Copilot（自动化脚本）
|