# ViGent2 后端开发指南

本文档提供后端架构概览与接口规范。开发规范与分层约定见 `Docs/BACKEND_DEV.md`。

---

## 🏗️ 架构概览

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

### 目录结构

```
backend/
├── app/
│   ├── core/             # 核心配置 (config.py, security.py, response.py)
│   ├── modules/          # 业务模块 (router/service/workflow/schemas)
│   │   ├── videos/       # 视频生成任务（router/schemas/service/workflow）
│   │   ├── materials/    # 素材管理（router/schemas/service）
│   │   ├── publish/      # 多平台发布
│   │   ├── auth/         # 认证与会话
│   │   ├── ai/           # AI 功能（标题标签生成）
│   │   ├── assets/       # 静态资源（字体/样式/BGM）
│   │   ├── ref_audios/   # 声音克隆参考音频（router/schemas/service）
│   │   ├── login_helper/ # 扫码登录辅助
│   │   ├── tools/        # 工具接口（router/schemas/service）
│   │   └── admin/        # 管理员功能
│   ├── repositories/     # Supabase 数据访问
│   ├── services/         # 外部服务集成 (TTS/Remotion/Storage/Uploader 等)
│   └── tests/            # 单元测试与集成测试
├── scripts/              # 运维脚本 (watchdog.py, init_db.py)
├── assets/               # 资源库 (fonts, bgm, styles)
├── user_data/            # 用户隔离数据 (Cookie 等)
└── requirements.txt      # 依赖清单
```

---

## 🔌 API 接口规范

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

- **文档地址**: `http://localhost:8006/docs` (Swagger UI)
- **认证方式**: HttpOnly Cookie (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/tasks`: 获取用户所有任务列表
    *   `GET /api/videos/generated`: 获取历史视频列表
    *   `DELETE /api/videos/generated/{video_id}`: 删除历史视频

3.  **素材管理 (Materials)**
    *   `POST /api/materials`: 上传素材
    *   `GET /api/materials`: 获取素材列表
    *   `PUT /api/materials/{material_id}`: 重命名素材

4.  **社交发布 (Publish)**
    *   `POST /api/publish`: 发布视频到 抖音/微信视频号/B站/小红书
    *   `POST /api/publish/login`: 扫码登录平台
    *   `GET /api/publish/login/status`: 查询登录状态（含刷脸验证二维码）
    *   `GET /api/publish/accounts`: 获取已登录账号列表

> 提示：视频号/抖音发布建议使用 headful + xvfb-run 运行后端。

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

6.  **声音克隆 (Ref Audios)**
    *   `POST /api/ref-audios`: 上传参考音频 (multipart/form-data)
    *   `GET /api/ref-audios`: 获取参考音频列表
    *   `PUT /api/ref-audios/{id}`: 重命名参考音频
    *   `DELETE /api/ref-audios/{id}`: 删除参考音频

7.  **AI 功能 (AI)**
    *   `POST /api/ai/generate-meta`: AI 生成标题和标签

8.  **工具 (Tools)**
    *   `POST /api/tools/extract-script`: 从视频链接提取文案

9.  **健康检查**
    *   `GET /api/lipsync/health`: LatentSync 服务健康状态
    *   `GET /api/voiceclone/health`: Qwen3-TTS 服务健康状态

### 统一响应结构

```json
{
  "success": true,
  "message": "ok",
  "data": { },
  "code": 0
}
```

---

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

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

- `material_path`: 视频素材路径（单素材模式）
- `material_paths`: 多素材路径数组（多机位模式，≥2 个素材时按句子自动切换）
- `tts_mode`: TTS 模式 (`edgetts` / `voiceclone`)
- `voice`: EdgeTTS 音色 ID（edgetts 模式）
- `ref_audio_id` / `ref_text`: 参考音频 ID 与文本（voiceclone 模式）
- `title`: 片头标题文字
- `subtitle_style_id`: 字幕样式 ID
- `title_style_id`: 标题样式 ID
- `subtitle_font_size`: 字幕字号（覆盖样式默认值）
- `title_font_size`: 标题字号（覆盖样式默认值）
- `title_top_margin`: 标题距顶部像素
- `subtitle_bottom_margin`: 字幕距底部像素
- `enable_subtitles`: 是否启用字幕
- `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/modules/` 下创建对应模块，添加 router/service/schemas，并在 `main.py` 注册路由。

### 添加定时任务

目前推荐使用 **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
```