# 项目结构说明

## 📁 完整目录树

```
voicellmcloud/
│
├── 📄 README.md                          # 完整项目文档
├── 📄 QUICKSTART.md                      # 快速入门指南
├── 📄 STRUCTURE.md                       # 本文件
├── 📄 requirements.txt                   # Python 依赖清单
├── 📄 .env.example                       # 环境配置示例
├── 📄 .env                               # 环境配置 (git 忽略)
├── 📄 .gitignore                         # Git 忽略规则
│
├── 🚀 start.sh                           # Linux/macOS 启动脚本
├── 🚀 start.bat                          # Windows 启动脚本
│
├── 🧪 test_client.py                     # 测试客户端
├── 🔌 cloud_voice_client.py              # 香橙派客户端适配器
│
├── 📂 app/                               # 主应用代码
│   ├── __init__.py
│   ├── main.py                           # FastAPI 应用入口
│   ├── config.py                         # 配置管理
│   │
│   ├── 📂 protocols/                     # 协议层 (独立于业务)
│   │   ├── __init__.py
│   │   ├── models.py                     # 消息数据模型 (Pydantic)
│   │   └── validators.py                 # 协议验证逻辑
│   │
│   ├── 📂 websocket/                     # WebSocket 管理
│   │   ├── __init__.py
│   │   ├── session.py                    # 会话状态管理
│   │   └── handler.py                    # 消息路由与处理
│   │
│   ├── 📂 services/                      # 业务服务接口
│   │   ├── __init__.py
│   │   ├── llm_service.py                # LLM 服务接口定义
│   │   ├── tts_service.py                # TTS 服务接口定义
│   │   └── intent_service.py             # 意图识别服务
│   │
│   ├── 📂 providers/                     # 第三方服务实现
│   │   ├── __init__.py
│   │   ├── dashscope_llm.py              # 阿里云百炼 LLM 实现
│   │   └── piper_tts.py                  # Piper TTS 本地实现
│   │
│   └── 📂 utils/                         # 工具模块
│       ├── __init__.py
│       ├── audio.py                      # 音频处理工具
│       └── logger.py                     # 日志配置
│
├── 📂 models/                            # TTS 模型文件 (git 忽略)
│   └── README.txt                        # 模型下载说明
│
└── 📂 client/                            # 香橙派客户端参考代码
    └── voice_drone_assistant/            # (原有项目代码)
```

## 🎯 模块职责

### 应用核心 (`app/`)

| 模块 | 职责 | 关键文件 |
|------|------|---------|
| **入口** | FastAPI 应用、生命周期管理 | `main.py` |
| **配置** | 环境变量、配置验证 | `config.py` |

### 协议层 (`app/protocols/`)

| 模块 | 职责 | 设计原则 |
|------|------|---------|
| **models.py** | 定义所有消息的数据结构 | 严格遵循协议文档 |
| **validators.py** | 验证消息格式和合法性 | 独立于业务逻辑 |

**为什么独立协议层？**
- 协议变更不影响业务逻辑
- 便于版本管理和向后兼容
- 客户端开发可参考此规范

### WebSocket 层 (`app/websocket/`)

| 模块 | 职责 | 功能 |
|------|------|------|
| **session.py** | 管理所有活跃连接 | 创建/关闭/发送消息 |
| **handler.py** | 消息路由和业务编排 | 处理每种消息类型 |

### 服务层 (`app/services/`)

| 模块 | 类型 | 说明 |
|------|------|------|
| **llm_service.py** | 接口定义 | LLM 服务的抽象接口 |
| **tts_service.py** | 接口定义 | TTS 服务的抽象接口 |
| **intent_service.py** | 工具函数 | 意图识别和解析逻辑 |

**为什么用接口？**
- 支持多种实现（阿里云/本地/其他）
- 便于测试和 Mock
- 符合依赖倒置原则

### 提供者层 (`app/providers/`)

| 模块 | 实现 | 特点 |
|------|------|------|
| **dashscope_llm.py** | 阿里云百炼 | 云端 API 调用 |
| **piper_tts.py** | Piper 本地 | 高效本地推理 |

**扩展新的提供者：**
1. 实现对应接口
2. 在 `main.py` 注册
3. 更新配置枚举

### 工具层 (`app/utils/`)

| 模块 | 功能 |
|------|------|
| **audio.py** | 音频处理 (重采样/归一化/增益) |
| **logger.py** | 日志格式化和输出 |

## 🔄 数据流

```
香橙派客户端
    ↓ (WebSocket)
app/main.py (FastAPI 入口)
    ↓
app/websocket/session.py (连接管理)
    ↓
app/websocket/handler.py (消息处理)
    ├── 验证: app/protocols/validators.py
    ├── LLM: app/services/llm_service.py
    │         └→ app/providers/dashscope_llm.py
    ├── 意图: app/services/intent_service.py
    └── TTS: app/services/tts_service.py
              └→ app/providers/piper_tts.py
    ↓ (音频数据)
香橙派客户端
```

## 📊 调用时序

```
turn.text 消息处理流程:

1. handler._handle_turn_text()
   ├── 验证消息格式
   ├── 构建 LLM 消息
   ├── 调用 LLM (dashscope_llm.py)
   ├── 解析意图 (intent_service.py)
   ├── 发送 dialog_result
   ├── 流式 TTS (piper_tts.py)
   │    └→ 循环: 发送音频块
   └── 发送 turn.complete
```

## 🛠 扩展指南

### 添加新的 LLM 提供者

```python
# 1. 创建文件: app/providers/my_llm.py
from app.services.llm_service import LLMServiceInterface

class MyLLMService(LLMServiceInterface):
    async def chat(...): ...
    async def initialize(...): ...
    async def shutdown(...): ...

# 2. 在 app/config.py 添加枚举
# LLM_PROVIDER: str = "my_llm"

# 3. 在 app/main.py 注册
if settings.LLM_PROVIDER == "my_llm":
    llm_service = MyLLMService()
```

### 添加新的 TTS 提供者

同上，实现 `TTSServiceInterface` 接口即可。

### 添加新的消息类型

```python
# 1. 在 app/protocols/models.py 定义消息模型
class MyNewMessage(BaseModel):
    type: str = "my_new_message"
    # ... 其他字段

# 2. 在 app/protocols/validators.py 添加验证
def validate_my_new_message(data: dict): ...

# 3. 在 app/websocket/handler.py 处理消息
async def handle_my_new_message(...): ...
```

## 📝 开发规范

### 命名约定

- **文件名**: 小写下划线 `snake_case.py`
- **类名**: 大驼峰 `ClassName`
- **函数名**: 小写下划线 `function_name()`
- **常量**: 大写下划线 `CONSTANT_VALUE`

### 代码组织

- 每个模块单一职责
- 接口与实现分离
- 依赖注入 (通过 `main.py` 组装)

### 错误处理

- 使用 Pydantic 验证消息格式
- 捕获异常并返回协议定义的错误码
- 记录详细日志供调试

## 🚀 部署说明

### 开发环境
```bash
python -m uvicorn app.main:app --reload
```

### 生产环境
```bash
# 使用 gunicorn + uvicorn workers
gunicorn app.main:app \
    -w 4 \
    -k uvicorn.workers.UvicornWorker \
    --bind 0.0.0.0:8765
```

### Docker (未来规划)
```dockerfile
FROM python:3.10-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8765"]
```

## 📖 相关文档

- **协议规范**: `CLOUD_VOICE_PROTOCOL_v1_text_uplink.md`
- **完整文档**: `README.md`
- **快速入门**: `QUICKSTART.md`
- **香橙派客户端**: `client/voice_drone_assistant/`

---

**更新日期**: 2024-04-07  
**维护者**: 无人机云端语音服务团队