TraceStudio-dev/web/README.md

TraceStudio Web Frontend

基于 React 19 + TypeScript + Vite 的现代化前端应用。

🚀 快速开始

1. 安装依赖

npm install
# 或
pnpm install

2. 配置环境变量（可选）

复制 .env.example 为 .env.local 并修改配置：

cp .env.example .env.local

编辑 .env.local：

# API 服务器地址（可选，默认自动检测）
VITE_API_BASE_URL=http://127.0.0.1:8000

注意：如果不设置环境变量，前端会自动检测：

• 开发环境：使用 http://127.0.0.1:8000
• 生产环境：使用当前域名的 8000 端口或相对路径

3. 启动开发服务器

npm run dev

访问 http://localhost:5173

4. 构建生产版本

npm run build

构建产物在 dist/ 目录。

🔧 环境变量

变量名	说明	默认值
VITE_API_BASE_URL	后端API地址	开发: http://127.0.0.1:8000 生产: 自动检测

📡 API 配置

API 基础地址的优先级：

1. 环境变量 VITE_API_BASE_URL（最高优先级）
2. 开发模式 import.meta.env.DEV → http://127.0.0.1:8000
3. 生产模式 根据 window.location 动态生成

示例场景：

// 开发环境
http://127.0.0.1:8000

// 生产环境（同域部署）
https://tracestudio.com:8000

// 生产环境（自定义域名）
VITE_API_BASE_URL=https://api.tracestudio.com

🛠️ 开发

项目结构

src/
├── components/       # React 组件
│   ├── AppShell.tsx
│   ├── HeaderBar.tsx
│   ├── Inspector.tsx
│   ├── NodePalette.tsx
│   ├── Workspace.tsx
│   └── FileExplorer.tsx
├── stores/          # Zustand 状态管理
│   └── useStore.ts
├── utils/           # 工具函数
│   ├── api.ts       # API 通讯层
│   └── nodeRegistry.ts
└── i18n.ts          # 国际化

API 通讯层

所有后端请求统一通过 src/utils/api.ts 管理：

import { getPlugins, executeGraph, listFiles } from './utils/api'

// 获取节点列表
const result = await getPlugins()

// 执行图
const result = await executeGraph({ nodes, edges })

// 列出文件
const result = await listFiles('path/to/dir')

🌐 部署

部署到服务器

1. 构建生产版本：

   npm run build
   

2. 配置环境变量（如果需要）：

   echo "VITE_API_BASE_URL=https://api.your-domain.com" > .env.production
   npm run build
   

3. 将 dist/ 目录部署到服务器

Nginx 配置示例

server {
    listen 80;
    server_name tracestudio.com;
    
    root /var/www/tracestudio/dist;
    index index.html;
    
    # 前端路由
    location / {
        try_files $uri $uri/ /index.html;
    }
    
    # 代理后端API
    location /api {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

📝 技术栈

• 框架: React 19
• 语言: TypeScript 5
• 构建: Vite 6
• 状态管理: Zustand 5
• 流程图: React Flow 11
• 国际化: 自定义 i18n
• 样式: CSS + Tailwind CSS

---

React + Vite 模板说明

Currently, two official plugins are available:

• @vitejs/plugin-react uses Babel (or oxc when used in rolldown-vite) for Fast Refresh
• @vitejs/plugin-react-swc uses SWC for Fast Refresh

React Compiler

The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see this documentation.

Expanding the ESLint configuration

If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:

export default defineConfig([
  globalIgnores(['dist']),
  {
    files: ['**/*.{ts,tsx}'],
    extends: [
      // Other configs...

      // Remove tseslint.configs.recommended and replace with this
      tseslint.configs.recommendedTypeChecked,
      // Alternatively, use this for stricter rules
      tseslint.configs.strictTypeChecked,
      // Optionally, add this for stylistic rules
      tseslint.configs.stylisticTypeChecked,

      // Other configs...
    ],
    languageOptions: {
      parserOptions: {
        project: ['./tsconfig.node.json', './tsconfig.app.json'],
        tsconfigRootDir: import.meta.dirname,
      },
      // other options...
    },
  },
])

You can also install eslint-plugin-react-x and eslint-plugin-react-dom for React-specific lint rules:

// eslint.config.js
import reactX from 'eslint-plugin-react-x'
import reactDom from 'eslint-plugin-react-dom'

export default defineConfig([
  globalIgnores(['dist']),
  {
    files: ['**/*.{ts,tsx}'],
    extends: [
      // Other configs...
      // Enable lint rules for React
      reactX.configs['recommended-typescript'],
      // Enable lint rules for React DOM
      reactDom.configs.recommended,
    ],
    languageOptions: {
      parserOptions: {
        project: ['./tsconfig.node.json', './tsconfig.app.json'],
        tsconfigRootDir: import.meta.dirname,
      },
      // other options...
    },
  },
])