TraceStudio-dev/web/README.md

# TraceStudio Web Frontend

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

## 🚀 快速开始

### 1. 安装依赖

```bash
npm install
# 或
pnpm install
```

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

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

```bash
cp .env.example .env.local
```

编辑 `.env.local`：

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

**注意**：如果不设置环境变量，前端会自动检测：
- **开发环境**：使用 `http://127.0.0.1:8000`
- **生产环境**：使用当前域名的 8000 端口或相对路径

### 3. 启动开发服务器

```bash
npm run dev
```

访问 http://localhost:5173

### 4. 构建生产版本

```bash
npm run build
```

构建产物在 `dist/` 目录。

## 🔧 环境变量

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

## 📡 API 配置

API 基础地址的优先级：

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

示例场景：

```typescript
// 开发环境
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` 管理：

```typescript
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. 构建生产版本：
   ```bash
   npm run build
   ```

2. 配置环境变量（如果需要）：
   ```bash
   echo "VITE_API_BASE_URL=https://api.your-domain.com" > .env.production
   npm run build
   ```

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

### Nginx 配置示例

```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](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) (or [oxc](https://oxc.rs) when used in [rolldown-vite](https://vite.dev/guide/rolldown)) for Fast Refresh
- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) 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](https://react.dev/learn/react-compiler/installation).

## Expanding the ESLint configuration

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

```js
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](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:

```js
// 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...
    },
  },
])
```