# ViGent2 后端开发指南

本文档为后端开发人员提供架构概览、接口规范以及开发流程指南。

---

## 🏗️ 架构概览

后端采用 **FastAPI** 框架，基于 Python 3.10+ 构建，主要负责业务逻辑处理、AI 任务调度以及与各微服务组件的交互。

### 目录结构

```
backend/
├── app/
│   ├── api/              # API 路由定义 (endpoints)
│   ├── core/             # 核心配置 (config.py, security.py)
│   ├── models/           # Pydantic 数据模型 (schemas)
│   ├── services/         # 业务逻辑服务层
│   │   ├── auth_service.py       # 用户认证服务
│   │   ├── glm_service.py        # GLM-4 大模型服务
│   │   ├── lipsync_service.py    # LatentSync 唇形同步
│   │   ├── publish_service.py    # 社交媒体发布
│   │   └── voice_clone_service.py# Qwen3-TTS 声音克隆
│   └── tests/            # 单元测试与集成测试
├── scripts/              # 运维脚本 (watchdog.py, init_db.py)
├── assets/               # 资源库 (fonts, bgm, styles)
└── requirements.txt      # 依赖清单
```

---

## 🔌 API 接口规范

后端服务默认运行在 `8006` 端口。

- **文档地址**: `http://localhost:8006/docs` (Swagger UI)
- **认证方式**: Bearer Token (JWT)

### 核心模块

1.  **认证 (Auth)**
    *   `POST /api/auth/login`: 用户登录 (手机号)
    *   `POST /api/auth/register`: 用户注册
    *   `GET /api/auth/me`: 获取当前用户信息

2.  **视频生成 (Videos)**
    *   `POST /api/videos/generate`: 提交生成任务
    *   `GET /api/videos/tasks/{task_id}`: 查询任务状态
    *   `GET /api/videos/generated`: 获取历史视频列表
    *   `DELETE /api/videos/generated/{video_id}`: 删除历史视频

> **修正 (16:20)**：任务查询与历史列表接口已更新为 `/api/videos/tasks/{task_id}` 与 `/api/videos/generated`。

3.  **素材管理 (Materials)**
    *   `POST /api/materials/upload`: 上传素材 (Direct Upload to Supabase)
    *   `GET /api/materials`: 获取素材列表

4.  **社交发布 (Publish)**
    *   `POST /api/publish`: 发布视频到 B站/抖音/小红书

5.  **资源库 (Assets)**
    *   `GET /api/assets/subtitle-styles`: 字幕样式列表
    *   `GET /api/assets/title-styles`: 标题样式列表
    *   `GET /api/assets/bgm`: 背景音乐列表

---

## 🎛️ 视频生成扩展参数

`POST /api/videos/generate` 支持以下可选字段：

- `subtitle_style_id`: 字幕样式 ID
- `title_style_id`: 标题样式 ID
- `subtitle_font_size`: 字幕字号（覆盖样式默认值）
- `title_font_size`: 标题字号（覆盖样式默认值）
- `bgm_id`: 背景音乐 ID
- `bgm_volume`: 背景音乐音量（0-1，默认 0.2）

## 📦 资源库与静态资源

- 本地资源目录：`backend/assets/{fonts,bgm,styles}`
- 静态访问路径：`/assets`（用于前端样式预览与背景音乐试听）

## 🎵 背景音乐混音策略

- 混音发生在 **唇形对齐之后**，避免影响字幕/口型时间轴。
- 使用 FFmpeg `amix`，禁用归一化以保持配音音量稳定。

## 🛠️ 开发环境搭建

### 1. 虚拟环境

```bash
cd backend
python -m venv venv
source venv/bin/activate  # Linux/macOS
# .\venv\Scripts\activate # Windows
```

### 2. 依赖安装

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

### 3. 环境变量配置

复制 `.env.example` 到 `.env` 并配置必要的 Key：

```ini
# Supabase
SUPABASE_URL=http://localhost:8008
SUPABASE_KEY=your_service_role_key

# GLM API (用于 AI 标题生成)
GLM_API_KEY=your_glm_api_key

# LatentSync 配置
LATENTSYNC_GPU_ID=1
```

### 4. 启动服务

**开发模式 (热重载)**:
```bash
uvicorn app.main:app --host 0.0.0.0 --port 8006 --reload
```

---

## 🧩 服务集成指南

### 集成新模型

如果需要集成新的 AI 模型 (例如新的 TTS 引擎)：

1.  在 `app/services/` 下创建新的 Service 类 (如 `NewTTSService`)。
2.  实现 `generate` 方法，可以使用 subprocess 调用，也可以是 HTTP 请求。
3.  **重要**: 如果模型占用 GPU，请务必使用 `asyncio.Lock` 进行并发控制，防止 OOM。
4.  在 `app/api/` 中添加对应的路由调用。

### 添加定时任务

目前推荐使用 **APScheduler** 或 **Crontab** 来管理定时任务。
社交媒体的定时发布功能目前依赖 `playwright` 的延迟执行，未来计划迁移到 Celery 队列。

---

## 🛡️ 错误处理

全项目统一使用 `Loguru` 进行日志记录。

```python
from loguru import logger

try:
    # 业务逻辑
except Exception as e:
    logger.error(f"操作失败: {str(e)}")
    raise HTTPException(status_code=500, detail="服务器内部错误")
```

---

## 🧪 测试

运行测试套件：

```bash
pytest
```