# ViGent2 后端开发规范

本文档定义后端开发的结构规范、接口契约与实现习惯。目标是让新功能按统一范式落地，旧逻辑在修复时逐步抽离。

---

## 1. 模块化与分层原则

每个业务功能放入 `app/modules/<feature>/`，以“薄路由 + 厚服务/流程”组织代码。

- **router.py**：只做参数校验、权限校验、调用 service/workflow、返回统一响应。
- **schemas.py**：Pydantic 请求/响应模型。
- **service.py**：业务逻辑与集成逻辑（非长流程）。
- **workflow.py**：长流程/重任务编排（视频生成、渲染、异步任务）。
- **__init__.py**：模块标记。

其它层级职责：

- **repositories/**：数据读写（Supabase），不包含业务逻辑。
- **services/**：外部依赖与基础能力（TTS、Storage、Remotion 等）。
- **core/**：配置、安全、依赖注入、统一响应。

---

## 2. 目录结构（当前约定）

```
backend/
├── app/
│   ├── core/                # config、deps、security、response
│   ├── modules/             # 业务模块（路由 + 逻辑）
│   │   ├── videos/          # 视频生成任务
│   │   ├── materials/       # 素材管理
│   │   ├── publish/         # 多平台发布
│   │   ├── auth/            # 认证与会话
│   │   ├── ai/              # AI 功能（标题标签生成等）
│   │   ├── assets/          # 静态资源（字体/样式/BGM）
│   │   ├── ref_audios/      # 声音克隆参考音频
│   │   ├── login_helper/    # 扫码登录辅助
│   │   ├── tools/           # 工具接口
│   │   └── admin/           # 管理员功能
│   ├── repositories/        # Supabase 数据访问
│   ├── services/            # 外部服务集成
│   │   ├── uploader/        # 平台发布器（douyin/weixin）
│   │   ├── qr_login_service.py
│   │   ├── publish_service.py
│   │   ├── remotion_service.py
│   │   ├── storage.py
│   │   └── ...
│   └── tests/
├── assets/                  # 字体 / 样式 / bgm
├── user_data/               # 用户隔离数据（Cookie 等）
├── scripts/
└── requirements.txt
```

---

## 3. 接口契约规范（统一响应）

所有 JSON API 返回统一结构：

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

- 正常响应使用 `success_response`。
- 错误通过 `HTTPException` 抛出，统一由全局异常处理返回 `{success:false, message, code}`。
- 不再使用 `detail` 作为前端错误文案（前端已改为读 `message`）。

---

## 4. 认证与权限

- 认证方式：**HttpOnly Cookie** (`access_token`)。
- `get_current_user` / `get_current_user_optional` 位于 `core/deps.py`。
- Session 单设备校验使用 `repositories/sessions.py`。

---

## 5. 任务与状态

- 视频生成任务通过 `modules/videos/workflow.py` 统一编排。
- 任务状态通过 `modules/videos/task_store.py` 读写，**不要直接维护全局 dict**。
- 默认使用 Redis（`REDIS_URL`），不可用自动回退内存。

---

## 6. 文件与存储

- 所有文件上传/下载/删除/移动通过 `services/storage.py`。
- 需要重命名时使用 `move_file`，避免直接读写 Storage。

### Cookie 存储（用户隔离）

多平台扫码登录产生的 Cookie 按用户隔离存储：

```
backend/user_data/{user_uuid}/cookies/
├── douyin_cookies.json
├── weixin_cookies.json
└── ...
```

- `publish_service.py` 中通过 `_get_cookies_dir(user_id)` / `_get_cookie_path(user_id, platform)` 定位
- 会话 key 格式：`"{user_id}_{platform}"`，确保多用户并发登录互不干扰
- 登录成功后 Cookie 自动保存到对应路径，发布时自动加载

---

## 7. 代码约定

- 只在 router 做校验与响应拼装。
- 业务逻辑写在 service/workflow。
- 数据库访问写在 repositories。
- 统一使用 `loguru` 打日志。

---

## 8. 开发流程建议

- **新增功能**：先建模块，再写 router/service/workflow。
- **修复 Bug**：顺手把涉及的逻辑抽到对应 service/workflow。
- **核心流程变更**：必跑冒烟（登录/生成/发布）。

---

## 9. 常用环境变量

- `SUPABASE_URL` / `SUPABASE_KEY`
- `SUPABASE_PUBLIC_URL`
- `REDIS_URL`
- `GLM_API_KEY`
- `LATENTSYNC_*`
- `CORS_ORIGINS` (CORS 白名单，默认 *)

### 微信视频号
- `WEIXIN_HEADLESS_MODE` (headful/headless-new)
- `WEIXIN_CHROME_PATH` / `WEIXIN_BROWSER_CHANNEL`
- `WEIXIN_USER_AGENT` / `WEIXIN_LOCALE` / `WEIXIN_TIMEZONE_ID`
- `WEIXIN_FORCE_SWIFTSHADER`
- `WEIXIN_TRANSCODE_MODE` (reencode/faststart/off)

### 抖音
- `DOUYIN_HEADLESS_MODE` (headful/headless-new，默认 headless-new)
- `DOUYIN_CHROME_PATH` / `DOUYIN_BROWSER_CHANNEL`
- `DOUYIN_USER_AGENT` (默认 Chrome/144)
- `DOUYIN_LOCALE` / `DOUYIN_TIMEZONE_ID`
- `DOUYIN_FORCE_SWIFTSHADER`
- `DOUYIN_DEBUG_ARTIFACTS` / `DOUYIN_RECORD_VIDEO` / `DOUYIN_KEEP_SUCCESS_VIDEO`
- `DOUYIN_COOKIE` (抖音视频下载 Cookie)

---

## 10. Playwright 发布调试

- 诊断日志落盘：`backend/app/debug_screenshots/weixin_network.log` / `douyin_network.log`
- 关键失败截图：`backend/app/debug_screenshots/weixin_*.png` / `douyin_*.png`
- 视频号建议使用 headful + xvfb-run（避免 headless 解码/指纹问题）

---

## 11. 最小新增模块示例

```
app/modules/foo/
├── router.py
├── schemas.py
├── service.py
└── workflow.py
```

router 仅调用 service/workflow 并返回 `success_response`。