TraceStudio-dev/docs/web/web_structure.md

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（自动化脚本）