# TraceStudio 开发环境设置指南

## 前置要求

- **Python 3.11+**（推荐使用 Conda）
- **Node.js 18+**
- **npm 或 yarn**

## 快速启动（推荐）

### Windows PowerShell

```powershell
# 1. 安装后端依赖
cd server
pip install -r requirements.txt

# 2. 安装前端依赖
cd ../web
npm install

# 3. 返回根目录，使用启动脚本
cd ..
.\start.ps1
```

启动脚本会同时启动前后端服务。

## 手动启动

### 1. 启动后端

```powershell
cd server
python main.py
```

后端服务将在 `http://127.0.0.1:8000` 启动。

### 2. 启动前端

在**新的终端窗口**中：

```powershell
cd web
npm run dev
```

前端服务将在 `http://localhost:5173` 启动。

## 访问应用

- **前端界面**: http://localhost:5173
- **后端 API**: http://127.0.0.1:8000
- **API 文档**: http://127.0.0.1:8000/docs

## 开发工具

### 推荐的 VS Code 插件

- **ESLint** - JavaScript/TypeScript 代码检查
- **Prettier** - 代码格式化
- **Tailwind CSS IntelliSense** - Tailwind 智能提示
- **Python** - Python 语言支持
- **Pylance** - Python 类型检查

### 热重载

- **前端**: Vite 自动热重载，修改文件后立即生效
- **后端**: Uvicorn 自动重载，修改 Python 文件后自动重启

## 常见问题

### 前端无法连接后端

确保后端服务已启动在 `http://127.0.0.1:8000`。

### 端口被占用

如果端口 8000 或 5173 被占用，可以修改：
- **后端端口**: 在 `server/main.py` 的 `uvicorn.run()` 中修改 `port` 参数
- **前端端口**: 在 `web/vite.config.ts` 中添加 `server.port` 配置

### Python 依赖安装失败

推荐使用 Conda 环境：

```powershell
conda create -n tracestudio python=3.11
conda activate tracestudio
pip install -r server/requirements.txt
```

### Node 依赖安装失败

尝试清除缓存后重新安装：

```powershell
cd web
rm -r node_modules
rm package-lock.json
npm install
```

## 项目结构

```
TraceStudio/
├── web/              # React 前端
│   ├── src/
│   ├── public/
│   └── package.json
├── server/           # FastAPI 后端
│   ├── main.py
│   └── requirements.txt
├── start.ps1         # 启动脚本
└── SETUP.md          # 本文档
```

## 下一步

查看 [PHASE1_COMPLETE.md](PHASE1_COMPLETE.md) 了解已完成的功能和测试用例。