Update backend schema

2026-02-08 14:26:19 +08:00
parent b9a315177a
commit 727fe8a997
16 changed files with 1532 additions and 94 deletions
--- a/api/README.md
+++ b/api/README.md
@@ -1,13 +1,13 @@
 # AI VideoAssistant Backend

-Python 后端 API，配合前端 `ai-videoassistant-frontend` 使用。
+Python 后端 API，配合前端 `web/` 模块使用。

 ## 快速开始

 ### 1. 安装依赖

 ```bash
-cd ~/Code/ai-videoassistant-backend
+cd api
 pip install -r requirements.txt
 ```

@@ -25,44 +25,162 @@ python init_db.py

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

+服务运行在: http://localhost:8100
+
 ### 4. 测试 API

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

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

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

 # 获取通话历史
-curl http://localhost:8000/api/history
+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/models/llm` | GET | LLM 模型列表 |
+| | | POST | 添加模型 |
+| | `/api/models/llm/{id}` | GET | 模型详情 |
+| | | PUT | 更新模型 |
+| | | DELETE | 删除模型 |
+| | `/api/models/llm/{id}/test` | POST | 测试模型连接 |
+| **ASR Models** | `/api/models/asr` | GET | ASR 模型列表 |
+| | | POST | 添加模型 |
+| | `/api/models/asr/{id}` | GET | 模型详情 |
+| | | PUT | 更新模型 |
+| | | DELETE | 删除模型 |
+| | `/api/models/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 (小助手)
+
+| 字段 | 类型 | 说明 |
 |------|------|------|
-| `/api/assistants` | GET | 助手列表 |
-| `/api/assistants` | POST | 创建助手 |
-| `/api/assistants/{id}` | GET | 助手详情 |
-| `/api/assistants/{id}` | PUT | 更新助手 |
-| `/api/assistants/{id}` | DELETE | 删除助手 |
-| `/api/voices` | GET | 声音库列表 |
-| `/api/history` | GET | 通话历史列表 |
-| `/api/history/{id}` | GET | 通话详情 |
-| `/api/history/{id}/transcripts` | POST | 添加转写 |
-| `/api/history/{id}/audio/{turn}` | GET | 获取音频 |
+| 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 ~/Code/ai-videoassistant-backend
+cd api

 # 启动所有服务
 docker-compose up -d
@@ -71,33 +189,144 @@ docker-compose up -d
 docker-compose logs -f backend
 ```

+---
+
 ## 目录结构

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