xiaoxia/xiaoxia-saas
1
0
Fork 0
Code Issues 16 Pull Requests 9 Actions 34.2k Packages Projects Releases 7 Wiki Activity

[P0][后端] 爆款视频v1.2 - DB模型+REST API+Celery编排器 #2039

New Issue
Open
opened 2026-09-25 21:30:12 +08:00 by xiaoxia · 1 comment
xiaoxia commented 2026-09-25 21:30:12 +08:00
Owner
Copy Link
Copy Source

父工单：#2038

概述

实现爆款视频v1.2的后端核心：数据库模型、REST API、Celery异步编排器。

数据库变更（Alembic migration）

新增 viral_video_jobs 表，字段：

字段 类型 说明
id UUID/BIGSERIAL 主键
user_id BIGINT FK users.id 用户
images JSONB 上传图片URL数组，含首图标记
industry VARCHAR 行业
target_customer VARCHAR 目标客户
persona_id VARCHAR 人设ID
viral_structure VARCHAR 爆款结构
marketing_purpose VARCHAR 营销目的
bgm_preference VARCHAR BGM偏好
duration INTEGER 目标时长秒
user_copy_text TEXT 【v1.2新增】 用户输入的不完整文案
fusion_level VARCHAR(20) 【v1.2新增】 融合强度：ai_full / ai_polish / user_primary
reference_audio_path VARCHAR 参考音频路径（可选）
voice_gender VARCHAR 音色性别
status VARCHAR(20) 任务状态 pending/analyzing/intent/fusion/storyboard/tts/rendering/uploading/done/failed
intent_result JSONB 【v1.2新增】 用户文案意图解析结果
result_video_url VARCHAR 成片OSS URL
credits_cost INTEGER 扣点
error_msg TEXT 错误信息
created_at/updated_at/started_at/finished_at TIMESTAMP 时间戳

REST API（apps/api/routes/viral_video.py）

  • POST /api/v1/viral-video/generate — 提交生成任务，参数含images/industry/.../user_copy_text/fusion_level
  • GET /api/v1/viral-video/{id} — 查询任务状态和结果
  • GET /api/v1/viral-video/history — 历史记录分页
  • POST /api/v1/viral-video/{id}/retry — 重试失败任务
  • 所有接口JWT鉴权复用现有 get_current_user
  • 参数校验Pydantic model

Celery编排器（apps/worker/viral_video/）

目录结构：

apps/worker/viral_video/
├── __init__.py
├── service.py      # ViralVideoOrchestrator 编排器
├── tasks.py        # Celery task定义
└── prompts.py      # Prompt模板（见子工单#2）

ViralVideoOrchestrator 9步流水线：

  1. 图片VLM分析 → 调用 ai_service.call_vision()，多图并行，结果合并
  2. 【v1.2新增】用户文案意图解析 → 若 user_copy_text 非空，调用LLM解析意图，通过WebSocket推送 intent_ready 事件，前端展示理解摘要卡片，等待用户确认/修改（前端确认后resume）
  3. 文案融合生成 → 调用LLM，根据fusion_level注入不同指令段（ai_full/ai_polish/user_primary）
  4. 分镜脚本生成 → 调用LLM生成storyboard
  5. 合规审核 → 调用LLM 6维度审核，不通过则rewrite_suggestions返回前端或自动重写1次
  6. CosyVoice配音 → 调用现有TTS服务，传script_segments和voice配置
  7. BGM选择 → 根据mood+marketing_purpose从预置表匹配BGM
  8. UnifiedRenderService渲染 → 组装渲染任务（图片序列+转场+Ken Burns+ASS字幕+BGM+配音）；若persona是数字人类型→渲染完成后调用MuseTalk口型同步worker
  9. OSS上传+通知 → 成片上传OSS→更新DB→WebSocket推送done→扣点确认

WebSocket进度事件

  • apps/api/websocket.py 注册新事件类型 viral_video:progress
  • 事件payload：{job_id, stage, progress(0-100), message, data:{...intent_result/preview/...}}
  • 9阶段stage枚举：image_analysis → intent_parsing → copy_fusion → storyboard → review → tts → rendering → musetalk → uploading

其他

  • packages/shared/constants.py 加 TASK_TYPE_VIRAL_VIDEO = "viral_video"
  • credits扣点复用 credits.deduct()，任务失败在finally中自动回滚（credits.refund()）
  • 用户意图确认机制：流水线在step2完成后进入 WAIT_USER_CONFIRM 状态，前端通过 POST /api/v1/viral-video/{id}/confirm-intent 接口确认（含可选修改后的user_copy_text），resume Celery任务继续step3

⚠️ 禁止重写

  • ❌ 不写新的TTS代码 → 调用现有CosyVoice服务
  • ❌ 不写新的FFmpeg/渲染代码 → 调用UnifiedRenderService
  • ❌ 不写新的OSS/Auth/WebSocket基础设施 → 全部复用
  • ❌ 不重写MuseTalk worker → 通过现有轮询队列提交任务

单元测试覆盖

  • 用户文案意图解析（有文案/无文案/空文案边界）
  • 文案融合三档（ai_full/ai_polish/user_primary）输出差异
  • 分镜clips[]结构正确（image_index索引合法、duration之和=总时长）
  • credits扣点+失败回滚
  • 意图确认resume流程
  • 数字人模式MuseTalk任务正确提交

验收标准

  1. Migration可正常upgrade/downgrade
  2. 4个API接口正常工作，鉴权通过
  3. Celery任务9步全流程跑通（Staging）
  4. WebSocket 9阶段进度实时推送
  5. 扣点成功，失败自动回滚
  6. 意图确认-重生成交互链路正常
  7. 单测覆盖率≥80%
父工单：#2038 ## 概述 实现爆款视频v1.2的后端核心：数据库模型、REST API、Celery异步编排器。 ## 数据库变更（Alembic migration） 新增 `viral_video_jobs` 表，字段： | 字段 | 类型 | 说明 | |------|------|------| | id | UUID/BIGSERIAL | 主键 | | user_id | BIGINT FK users.id | 用户 | | images | JSONB | 上传图片URL数组，含首图标记 | | industry | VARCHAR | 行业 | | target_customer | VARCHAR | 目标客户 | | persona_id | VARCHAR | 人设ID | | viral_structure | VARCHAR | 爆款结构 | | marketing_purpose | VARCHAR | 营销目的 | | bgm_preference | VARCHAR | BGM偏好 | | duration | INTEGER | 目标时长秒 | | user_copy_text | TEXT | **【v1.2新增】** 用户输入的不完整文案 | | fusion_level | VARCHAR(20) | **【v1.2新增】** 融合强度：`ai_full` / `ai_polish` / `user_primary` | | reference_audio_path | VARCHAR | 参考音频路径（可选） | | voice_gender | VARCHAR | 音色性别 | | status | VARCHAR(20) | 任务状态 pending/analyzing/intent/fusion/storyboard/tts/rendering/uploading/done/failed | | intent_result | JSONB | **【v1.2新增】** 用户文案意图解析结果 | | result_video_url | VARCHAR | 成片OSS URL | | credits_cost | INTEGER | 扣点 | | error_msg | TEXT | 错误信息 | | created_at/updated_at/started_at/finished_at | TIMESTAMP | 时间戳 | ## REST API（apps/api/routes/viral_video.py） - `POST /api/v1/viral-video/generate` — 提交生成任务，参数含images/industry/.../user_copy_text/fusion_level - `GET /api/v1/viral-video/{id}` — 查询任务状态和结果 - `GET /api/v1/viral-video/history` — 历史记录分页 - `POST /api/v1/viral-video/{id}/retry` — 重试失败任务 - 所有接口JWT鉴权复用现有 `get_current_user` - 参数校验Pydantic model ## Celery编排器（apps/worker/viral_video/） 目录结构： ``` apps/worker/viral_video/ ├── __init__.py ├── service.py # ViralVideoOrchestrator 编排器 ├── tasks.py # Celery task定义 └── prompts.py # Prompt模板（见子工单#2） ``` **ViralVideoOrchestrator 9步流水线**： 1. **图片VLM分析** → 调用 `ai_service.call_vision()`，多图并行，结果合并 2. **【v1.2新增】用户文案意图解析** → 若 user_copy_text 非空，调用LLM解析意图，通过WebSocket推送 `intent_ready` 事件，前端展示理解摘要卡片，等待用户确认/修改（前端确认后resume） 3. **文案融合生成** → 调用LLM，根据fusion_level注入不同指令段（ai_full/ai_polish/user_primary） 4. **分镜脚本生成** → 调用LLM生成storyboard 5. **合规审核** → 调用LLM 6维度审核，不通过则rewrite_suggestions返回前端或自动重写1次 6. **CosyVoice配音** → 调用现有TTS服务，传script_segments和voice配置 7. **BGM选择** → 根据mood+marketing_purpose从预置表匹配BGM 8. **UnifiedRenderService渲染** → 组装渲染任务（图片序列+转场+Ken Burns+ASS字幕+BGM+配音）；若persona是数字人类型→渲染完成后调用MuseTalk口型同步worker 9. **OSS上传+通知** → 成片上传OSS→更新DB→WebSocket推送done→扣点确认 ## WebSocket进度事件 - `apps/api/websocket.py` 注册新事件类型 `viral_video:progress` - 事件payload：`{job_id, stage, progress(0-100), message, data:{...intent_result/preview/...}}` - 9阶段stage枚举：`image_analysis` → `intent_parsing` → `copy_fusion` → `storyboard` → `review` → `tts` → `rendering` → `musetalk` → `uploading` ## 其他 - `packages/shared/constants.py` 加 `TASK_TYPE_VIRAL_VIDEO = "viral_video"` - credits扣点复用 `credits.deduct()`，任务失败在finally中自动回滚（`credits.refund()`） - 用户意图确认机制：流水线在step2完成后进入 `WAIT_USER_CONFIRM` 状态，前端通过 `POST /api/v1/viral-video/{id}/confirm-intent` 接口确认（含可选修改后的user_copy_text），resume Celery任务继续step3 ## ⚠️ 禁止重写 - ❌ 不写新的TTS代码 → 调用现有CosyVoice服务 - ❌ 不写新的FFmpeg/渲染代码 → 调用UnifiedRenderService - ❌ 不写新的OSS/Auth/WebSocket基础设施 → 全部复用 - ❌ 不重写MuseTalk worker → 通过现有轮询队列提交任务 ## 单元测试覆盖 - [ ] 用户文案意图解析（有文案/无文案/空文案边界） - [ ] 文案融合三档（ai_full/ai_polish/user_primary）输出差异 - [ ] 分镜clips[]结构正确（image_index索引合法、duration之和=总时长） - [ ] credits扣点+失败回滚 - [ ] 意图确认resume流程 - [ ] 数字人模式MuseTalk任务正确提交 ## 验收标准 1. Migration可正常upgrade/downgrade 2. 4个API接口正常工作，鉴权通过 3. Celery任务9步全流程跑通（Staging） 4. WebSocket 9阶段进度实时推送 5. 扣点成功，失败自动回滚 6. 意图确认-重生成交互链路正常 7. 单测覆盖率≥80%
xiaoxia added the backendP0feature labels 2026-09-25 21:30:12 +08:00
xiaoxia commented 2026-09-26 12:12:17 +08:00
Author
Owner
Copy Link
Copy Source

📌 v1.3升级补充（2026-09-26）

配合#2043 video_analyzer模块，本工单需额外完成：

  1. viral_video_jobs表migration增加：reference_video_url VARCHAR(500), style_strength VARCHAR(20), style_guide JSONB, style_template_id INTEGER（全部可选）
  2. 新建viral_video_style_templates配置表（id/name/description/style_guide JSONB/industry/category/cover_image_url/usage_count/created_at）
  3. POST /api/v1/viral-video/generate 请求体增加可选字段：reference_video_url/style_strength/style_template_id
  4. 新增接口：POST /api/v1/viral-video/analyze-style（预分析参考视频风格），GET /api/v1/viral-video/style-templates（预置风格列表）
  5. Celery编排器流水线增加步骤①.5：video_analysis（有参考视频时触发，调用video_analyzer.analyze_video_style）
  6. WS进度事件增加type=style_analyzed（payload含style_name/shot_count/pace/color_palette/camera_movements摘要）
  7. 分镜审核增加第5维度"风格一致性"（light豁免，medium/strict按PRD 4.4节校验）
  8. clips[]到UnifiedRenderService参数映射增加ken_burns/transition/video_filter按style_guide转换（转换规则见#2043）

注意：视频文件OSS上传签名URL逻辑复用图片上传的getSignedUploadUrl，不需要新写上传逻辑。

## 📌 v1.3升级补充（2026-09-26） 配合#2043 video_analyzer模块，本工单需额外完成： 1. viral_video_jobs表migration增加：reference_video_url VARCHAR(500), style_strength VARCHAR(20), style_guide JSONB, style_template_id INTEGER（全部可选） 2. 新建viral_video_style_templates配置表（id/name/description/style_guide JSONB/industry/category/cover_image_url/usage_count/created_at） 3. POST /api/v1/viral-video/generate 请求体增加可选字段：reference_video_url/style_strength/style_template_id 4. 新增接口：POST /api/v1/viral-video/analyze-style（预分析参考视频风格），GET /api/v1/viral-video/style-templates（预置风格列表） 5. Celery编排器流水线增加步骤①.5：video_analysis（有参考视频时触发，调用video_analyzer.analyze_video_style） 6. WS进度事件增加type=style_analyzed（payload含style_name/shot_count/pace/color_palette/camera_movements摘要） 7. 分镜审核增加第5维度"风格一致性"（light豁免，medium/strict按PRD 4.4节校验） 8. clips[]到UnifiedRenderService参数映射增加ken_burns/transition/video_filter按style_guide转换（转换规则见#2043） 注意：视频文件OSS上传签名URL逻辑复用图片上传的getSignedUploadUrl，不需要新写上传逻辑。
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
architecture
架构设计
 backend
后端相关
 blocked
阻塞中
 bug
Bug修复
 ci-bug
CI本身的bug
 ci-optimization
CI优化类任务
 ci-pipeline
CI流水线/workflow相关
 cleanup
代码清理
 devops
运维/部署/CI
 documentation
文档相关
 feature
新功能
 frontend
前端相关
 P0
阻塞性，必须立即处理
 P1
高优先级
 P2
中优先级
 P3
低优先级/后考虑
 question
需要讨论确认
 ready
PR CI通过，可合并
 refactor
代码重构
No Label backend feature P0
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
auto-approve-bot frontend-dev xiaoxia
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: xiaoxia/xiaoxia-saas#2039
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?