ViGent2/Docs/BACKEND_DEV.md

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/：配置、安全、依赖注入、统一响应。
• api/：仅做 router 透传，保持 /api/* 路由稳定。

---

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

backend/
├── app/
│   ├── api/                 # 兼容路由入口，透传到 modules
│   ├── core/                # config、deps、security、response
│   ├── modules/             # 业务模块
│   │   ├── videos/
│   │   ├── materials/
│   │   ├── publish/
│   │   ├── auth/
│   │   └── ...
│   ├── repositories/        # Supabase 数据访问
│   ├── services/            # 外部服务集成
│   └── tests/
├── assets/                  # 字体 / 样式 / bgm
├── scripts/
└── requirements.txt

---

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

所有 JSON API 返回统一结构：

{
  "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。

---

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_*
• 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)

---

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。