Tolan/.cursorrules

# Tolan AI 英语语音助手 - 开发规则

## 项目概述
- **后端**: FastAPI + Python 3.11+ + WebSocket
- **前端**: React 18 + TypeScript + Vite + Ant Design
- **AI服务**: 阿里云 DashScope (STT/LLM/TTS)
- **架构**: 实时语音对话流水线 (STT → LLM → TTS)

---

## 代码生成原则

### 文档规则
- ❌ 避免生成冗长的 Markdown 文档
- ✅ 代码优先，注释简洁
- ✅ 必要文档：配置说明、API定义（列表形式）
- ✅ 文档格式：表格 > 列表 > 段落
- ✅ **文档生成路径规则**：
  - 项目文档 → `项目文档/` 目录
  - 后端文档 → `backend/文档/` 目录
  - 前端文档 → `frontend/docs/` 目录（如需要）
  - 配置文档 → 对应模块根目录（如 `backend/ENV_CONFIG.md`）

### 代码风格
- **Python**: 类型提示、async/await、异常处理必需
- **TypeScript**: 严格类型、接口定义、错误边界
- **命名**: 英文、语义化、统一风格（snake_case/camelCase）
- **注释**: 仅对复杂逻辑、性能优化、临时方案添加

---

## 后端开发规则

### FastAPI 结构
```python
# 路由定义
@app.websocket("/ws")
async def endpoint(websocket: WebSocket): ...

# 类型定义（必需）
from pydantic import BaseModel
class Message(BaseModel):
    type: str
    data: dict
```

### 异步编程
- 所有 I/O 操作使用 `async/await`
- 使用 `asyncio.to_thread()` 包装同步库
- WebSocket 消息处理异步化

### 配置管理
- 所有配置从 `.env` 读取
- 使用 `pydantic-settings` 管理
- 必需项无默认值，可选项提供默认值

### AI 服务集成
```python
# DashScope API 调用模式
import dashscope
dashscope.api_key = settings.DASHSCOPE_API_KEY

# 流式处理
async for chunk in ai_service.generate_stream(text):
    await websocket.send_json(chunk)
```

### 错误处理
```python
try:
    result = await api_call()
except Exception as e:
    logger.error(f"Error: {e}")
    await send_error(request_id, str(e))
```

---

## 前端开发规则

### React + TypeScript
```typescript
// 类型定义（必需）
interface Message {
  type: string;
  requestId: string;
  data: unknown;
}

// 组件定义
export const Component: React.FC<Props> = ({ ... }) => {
  // Hooks
  const [state, setState] = useState<Type>(initial);
  
  // 处理函数
  const handleEvent = useCallback(() => { ... }, [deps]);
  
  return <UI />;
};
```

### WebSocket 通信
```typescript
// 发送消息
ws.send(JSON.stringify({ type, requestId, data }));

// 接收消息
ws.onmessage = (event) => {
  const message: Message = JSON.parse(event.data);
  handleMessage(message);
};
```

### 状态管理 (Zustand)
```typescript
export const useStore = create<State>((set) => ({
  value: initial,
  update: (newValue) => set({ value: newValue }),
}));
```

### 音频处理
```typescript
// 录音
const recorder = new Recorder({ sampleRate: 16000 });
recorder.start();

// Base64 编码
const base64 = btoa(String.fromCharCode(...audioData));
```

---

## API 集成规则

### DashScope STT
- 模型: `qwen3-asr-flash-realtime`
- 格式: PCM 16kHz mono
- 流式识别: WebSocket API

### DashScope LLM
- 模型: `qwen-turbo/qwen-plus`
- 模式: 流式输出 (stream=True)
- 提示词: 简化版优先

### DashScope TTS
- 模型: `qwen3-tts-flash`
- 音色: `Cherry` (女声)
- 输出: PCM 24kHz
- 速率控制: `TTS_MIN_INTERVAL` 避免限流

---

## WebSocket 消息协议

### 客户端 → 服务端
```typescript
{ type: "audio_chunk", requestId, data: base64, chunkIndex, sampleRate }
{ type: "audio_end", requestId, totalChunks }
{ type: "cancel", requestId }
```

### 服务端 → 客户端
```typescript
{ type: "text_result", requestId, text, isFinal }
{ type: "emotion", requestId, emotion }
{ type: "audio_response", requestId, data: base64, chunkIndex, isLast }
{ type: "error", requestId, code, message }
```

---

## 性能优化规则

### 后端优化
- TTS 连接预热（启动时）
- HTTP/2 连接池（httpx）
- 流式处理（LLM+TTS 并行）
- 动态超时（根据 STT 更新时间）

### 前端优化
- 音频流式播放（边接收边播放）
- WebSocket 断线重连
- 组件懒加载 (React.lazy)
- 防抖/节流（用户交互）

---

## 文档生成规范

### 文档类型与路径
| 文档类型 | 生成路径 | 示例 |
|---------|---------|------|
| 项目架构/设计文档 | `项目文档/` | `项目文档/系统架构设计.md` |
| API 文档 | `项目文档/` | `项目文档/前后端交互API文档.md` |
| 需求文档 | `需求/` | `需求/用户需求.md` |
| 后端技术文档 | `backend/文档/` | `backend/文档/数据库设计.md` |
| 后端配置说明 | `backend/` | `backend/ENV_CONFIG.md` |
| 前端技术文档 | `frontend/docs/` | `frontend/docs/组件设计.md` |
| 部署运维文档 | `项目文档/` | `项目文档/部署指南.md` |

### 文档命名规则
- 使用中文文件名（项目主要使用中文）
- 描述清晰、简洁
- 格式：`功能描述.md`

---

## 常见任务模板

### 添加新的 WebSocket 消息类型
1. `backend/models.py`: 定义 Pydantic 模型
2. `backend/websocket_handler.py`: 添加处理函数
3. `frontend/src/types/index.ts`: 定义 TypeScript 类型
4. `frontend/src/utils/websocket.ts`: 添加发送/接收逻辑

### 添加新的环境变量
1. `backend/.env`: 添加配置项
2. `backend/config.py`: 定义 Settings 字段
3. `backend/ENV_CONFIG.md`: 更新文档（仅列表）

### 添加新的 UI 页面
1. `frontend/src/pages/`: 创建页面组件
2. `frontend/src/router/`: 添加路由
3. 使用 Ant Design 组件，保持风格统一

### 生成技术文档
1. 确定文档类型（架构/API/配置/需求等）
2. 根据上表选择正确的生成路径
3. 使用表格格式（优先）
4. 内容控制在 100 行以内

---

## 禁止事项
- ❌ 生成超过 100 行的 Markdown 文档
- ❌ 在代码中使用 `any` 类型（TypeScript）
- ❌ 同步阻塞 I/O 操作（后端）
- ❌ 硬编码 API 密钥或敏感信息
- ❌ 未处理的 Promise rejection
- ❌ 未添加类型提示的函数（Python/TS）

---

## 调试技巧
```python
# 后端日志
print(f"[{request_id}] 🔍 Debug: {variable}")

# 性能测试
import time
start = time.time()
# ... code ...
print(f"⏱️ Duration: {(time.time() - start)*1000:.1f}ms")
```

```typescript
// 前端日志
console.log('[WebSocket] Received:', message.type);
console.time('Processing');
// ... code ...
console.timeEnd('Processing');
```