# AI VideoAssistant Backend

Python 后端 API，配合前端 `web/` 模块使用。

## 快速开始

### 1. 安装依赖

```bash
cd api
pip install -r requirements.txt
```

### 2. 初始化数据库

```bash
python init_db.py
```

这会：
- 创建 `data/app.db` SQLite 数据库
- 初始化默认声音数据

### 3. 启动服务

```bash
# 开发模式 (热重载)
python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8100
```

服务运行在: http://localhost:8100

### 4. 测试 API

```bash
# 健康检查
curl http://localhost:8100/health

# 获取助手列表
curl http://localhost:8100/api/assistants

# 获取声音列表
curl http://localhost:8100/api/voices

# 获取通话历史
curl http://localhost:8100/api/history
```

---

## API 文档

完整 API 文档位于 [docs/](docs/) 目录：

| 模块 | 端点 | 方法 | 说明 |
|------|------|------|------|
| **Assistant** | `/api/assistants` | GET | 助手列表 |
| | | POST | 创建助手 |
| | `/api/assistants/{id}` | GET | 助手详情 |
| | | PUT | 更新助手 |
| | | DELETE | 删除助手 |
| **Voice** | `/api/voices` | GET | 声音库列表 |
| | | POST | 添加声音 |
| | `/api/voices/{id}` | GET | 声音详情 |
| | | PUT | 更新声音 |
| | | DELETE | 删除声音 |
| | `/api/voices/{id}/preview` | POST | 预览声音 |
| **LLM Models** | `/api/llm` | GET | LLM 模型列表 |
| | | POST | 添加模型 |
| | `/api/llm/{id}` | GET | 模型详情 |
| | | PUT | 更新模型 |
| | | DELETE | 删除模型 |
| | `/api/llm/{id}/test` | POST | 测试模型连接 |
| **ASR Models** | `/api/asr` | GET | ASR 模型列表 |
| | | POST | 添加模型 |
| | `/api/asr/{id}` | GET | 模型详情 |
| | | PUT | 更新模型 |
| | | DELETE | 删除模型 |
| | `/api/asr/{id}/test` | POST | 测试识别 |
| **History** | `/api/history` | GET | 通话历史列表 |
| | `/api/history/{id}` | GET | 通话详情 |
| | | PUT | 更新通话记录 |
| | | DELETE | 删除记录 |
| | `/api/history/{id}/transcripts` | POST | 添加转写 |
| | `/api/history/search` | GET | 搜索历史 |
| | `/api/history/stats` | GET | 统计数据 |
| **Knowledge** | `/api/knowledge/bases` | GET | 知识库列表 |
| | | POST | 创建知识库 |
| | `/api/knowledge/bases/{id}` | GET | 知识库详情 |
| | | PUT | 更新知识库 |
| | | DELETE | 删除知识库 |
| | `/api/knowledge/bases/{kb_id}/documents` | POST | 上传文档 |
| | `/api/knowledge/bases/{kb_id}/documents/{doc_id}` | DELETE | 删除文档 |
| | `/api/knowledge/bases/{kb_id}/documents/{doc_id}/index` | POST | 索引文档 |
| | `/api/knowledge/search` | POST | 知识搜索 |
| **Workflow** | `/api/workflows` | GET | 工作流列表 |
| | | POST | 创建工作流 |
| | `/api/workflows/{id}` | GET | 工作流详情 |
| | | PUT | 更新工作流 |
| | | DELETE | 删除工作流 |

---

## 数据模型

### Assistant (小助手)

| 字段 | 类型 | 说明 |
|------|------|------|
| id | string | 助手 ID |
| name | string | 助手名称 |
| opener | string | 开场白 |
| prompt | string | 系统提示词 |
| knowledgeBaseId | string | 关联知识库 ID |
| language | string | 语言: zh/en |
| voice | string | 声音 ID |
| speed | float | 语速 (0.5-2.0) |
| hotwords | array | 热词列表 |
| tools | array | 启用的工具列表 |
| llmModelId | string | LLM 模型 ID |
| asrModelId | string | ASR 模型 ID |
| embeddingModelId | string | Embedding 模型 ID |
| rerankModelId | string | Rerank 模型 ID |

### Voice (声音资源)

| 字段 | 类型 | 说明 |
|------|------|------|
| id | string | 声音 ID |
| name | string | 声音名称 |
| vendor | string | 厂商: Ali/Volcano/Minimax |
| gender | string | 性别: Male/Female |
| language | string | 语言: zh/en |
| model | string | 厂商模型标识 |
| voice_key | string | 厂商 voice_key |
| speed | float | 语速 |
| gain | int | 增益 (dB) |
| pitch | int | 音调 |

### LLMModel (模型接入)

| 字段 | 类型 | 说明 |
|------|------|------|
| id | string | 模型 ID |
| name | string | 模型名称 |
| vendor | string | 厂商 |
| type | string | 类型: text/embedding/rerank |
| base_url | string | API 地址 |
| api_key | string | API 密钥 |
| model_name | string | 模型名称 |
| temperature | float | 温度参数 |

### ASRModel (语音识别)

| 字段 | 类型 | 说明 |
|------|------|------|
| id | string | 模型 ID |
| name | string | 模型名称 |
| vendor | string | 厂商 |
| language | string | 语言: zh/en/Multi-lingual |
| base_url | string | API 地址 |
| api_key | string | API 密钥 |
| hotwords | array | 热词列表 |

### CallRecord (通话记录)

| 字段 | 类型 | 说明 |
|------|------|------|
| id | string | 记录 ID |
| assistant_id | string | 助手 ID |
| source | string | 来源: debug/external |
| status | string | 状态: connected/missed/failed |
| started_at | string | 开始时间 |
| duration_seconds | int | 通话时长 |
| summary | string | 通话摘要 |
| transcripts | array | 对话转写 |

---

## 使用 Docker 启动

```bash
cd api

# 启动所有服务
docker-compose up -d

# 查看日志
docker-compose logs -f backend
```

---

## 目录结构

```
api/
├── app/
│   ├── __init__.py
│   ├── main.py           # FastAPI 入口
│   ├── db.py             # SQLite 连接
│   ├── models.py         # SQLAlchemy 数据模型
│   ├── schemas.py        # Pydantic 模型
│   ├── storage.py        # MinIO 存储
│   ├── vector_store.py   # 向量存储
│   └── routers/
│       ├── __init__.py
│       ├── assistants.py # 助手 API
│       ├── history.py    # 通话记录 API
│       └── knowledge.py  # 知识库 API
├── data/                 # 数据库文件
├── docs/                 # API 文档
├── requirements.txt
├── .env
├── init_db.py
└── docker-compose.yml
```

---

## 环境变量

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `PORT` | `8100` | 服务端口 |
| `DATABASE_URL` | `sqlite:///./data/app.db` | 数据库连接 |
| `MINIO_ENDPOINT` | `localhost:9000` | MinIO 地址 |
| `MINIO_ACCESS_KEY` | `admin` | MinIO 密钥 |
| `MINIO_SECRET_KEY` | `password123` | MinIO 密码 |
| `MINIO_BUCKET` | `ai-audio` | 存储桶名称 |

---

## 数据库迁移

开发环境重新创建数据库：

```bash
rm -f api/data/app.db
python api/init_db.py
```

---

## 测试

### 安装测试依赖

```bash
cd api
pip install pytest pytest-cov -q
```

### 运行所有测试

```bash
# Windows
run_tests.bat

# 或使用 pytest
pytest tests/ -v
```

### 运行特定测试

```bash
# 只测试声音 API
pytest tests/test_voices.py -v

# 只测试助手 API
pytest tests/test_assistants.py -v

# 只测试历史记录 API
pytest tests/test_history.py -v

# 只测试知识库 API
pytest tests/test_knowledge.py -v
```

### 测试覆盖率

```bash
pytest tests/ --cov=app --cov-report=html
# 查看报告: open htmlcov/index.html
```

### 测试目录结构

```
tests/
├── __init__.py
├── conftest.py          # pytest fixtures
├── test_voices.py       # 声音 API 测试
├── test_assistants.py   # 助手 API 测试
├── test_history.py      # 历史记录 API 测试
└── test_knowledge.py    # 知识库 API 测试
```

### 测试用例统计

| 模块 | 测试用例数 |
|------|-----------|
| Voice | 13 |
| Assistant | 14 |
| History | 18 |
| Knowledge | 19 |
| **总计** | **64** |

### CI/CD 示例 (.github/workflows/test.yml)

```yaml
name: Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - name: Install dependencies
        run: |
          pip install -r api/requirements.txt
          pip install pytest pytest-cov
      - name: Run tests
        run: pytest api/tests/ -v --cov=app
```