# Tolan 前端快速启动指南

## 📋 前置要求

- Node.js >= 18.0.0
- npm >= 9.0.0
- 后端服务已启动（`backend/`目录）

## 🚀 快速启动

### 1. 安装依赖

```bash
cd /Users/wuzilong/work/00code/Tolan/frontend
npm install
```

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

创建 `.env.local` 文件：

```bash
# 如果后端在本地运行
VITE_WS_URL=ws://localhost:8000/ws/realtime

# 如果后端使用HTTPS
VITE_WS_URL=wss://localhost:8443/ws/realtime
```

如果不配置，默认使用 `ws://localhost:8000/ws/realtime`

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

```bash
npm run dev
```

应用将在 http://localhost:5173 启动

### 4. 在浏览器中打开

访问：http://localhost:5173

## 📱 使用步骤

1. **等待初始化**
   - 页面加载时会自动连接WebSocket服务器
   - 初始化录音器和播放器
   - 看到"连接成功"提示

2. **开始对话**
   - 按住录音按钮开始说话
   - 动画IP会切换到"倾听"状态
   - 说完后松开按钮

3. **接收回复**
   - AI处理语音并返回音频
   - 动画IP切换到"说话"状态
   - 自动播放AI回复

4. **继续对话**
   - 播放完成后，动画IP回到"待机"状态
   - 可以再次按住按钮继续对话

## 🔧 故障排查

### 问题1: 连接失败

**症状**: 显示"连接中..."但一直无法连接

**解决方案**:
1. 确认后端服务已启动
2. 检查WebSocket URL配置
3. 查看浏览器控制台错误信息

```bash
# 检查后端是否运行
curl http://localhost:8000/docs
```

### 问题2: 麦克风权限被拒绝

**症状**: 点击录音按钮没有反应

**解决方案**:
1. 浏览器会弹出权限请求，点击"允许"
2. 如果已拒绝，在浏览器设置中重新授权
3. 确保使用HTTPS或localhost

### 问题3: 无法播放音频

**症状**: 收到回复但没有声音

**解决方案**:
1. 检查浏览器是否静音
2. 检查系统音量设置
3. 确认浏览器支持OGG/Opus格式
4. 查看控制台是否有错误

### 问题4: 延迟过高

**症状**: 响应时间超过1秒

**解决方案**:
1. 检查网络连接
2. 确认后端连接池已启动
3. 查看控制台中显示的延迟数据
4. 检查后端日志

## 📊 性能监控

应用会在控制台输出性能指标：

```
端到端延迟: 285ms
收到音频数据: 2048 bytes
音频播放状态: playing
```

目标延迟: < 300ms

## 🌐 浏览器兼容性

### 推荐浏览器
- ✅ Chrome 90+（最佳体验）
- ✅ Edge 90+
- ✅ Safari 14+
- ✅ Firefox 88+

### 移动端
- ✅ iOS Safari 14+
- ✅ Android Chrome 90+

### 已知问题
- iOS需要在用户交互中激活录音
- 某些Android浏览器不支持所有音频参数

## 🛠 开发命令

```bash
# 安装依赖
npm install

# 启动开发服务器（热更新）
npm run dev

# 生产构建
npm run build

# 预览生产构建
npm run preview

# 代码检查
npm run lint
```

## 📂 项目结构

```
frontend/
├── src/
│   ├── components/       # React组件
│   ├── stores/          # 状态管理
│   ├── utils/           # 工具模块
│   ├── config.ts        # 配置
│   └── main.tsx         # 入口
├── public/              # 静态资源
└── package.json
```

## 🔗 相关文档

- [完整README](./README.md)
- [API文档](../项目文档/API文档.md)
- [项目开发重点和难点](../项目文档/项目开发重点和难点分析.md)

## 💡 提示

1. **首次使用**: 浏览器会请求麦克风权限，务必允许
2. **iOS设备**: 首次点击需要激活音频上下文
3. **网络环境**: 建议在良好的网络环境下使用
4. **HTTPS**: 生产环境必须使用HTTPS

## 📞 获取帮助

遇到问题？

1. 查看浏览器控制台（F12）的错误信息
2. 检查后端日志
3. 参考完整文档
4. 查看GitHub Issues

---

**祝您使用愉快！🎉**