feat(viral-video): 三步独立流程接入真实后端API（替换mock，对接analyze-images/generate-copy/confirm-copy） #2122

Merged

xiaoxia merged 1 commits from feat/2041-real-3step-api into develop 2026-10-01 12:25:04 +08:00

Conversation 4 Commits 1 Files Changed 1

+140 -60

xiaoxia commented 2026-10-01 12:24:31 +08:00

Owner

Copy Link

Copy Source

改动：三步独立流程接入真实后端 API（替换前端 mock）

后端 PR#2117（d390d7c）已在 staging 上线三个新端点，前端把之前的 mockImageAnalysis/mockGenerateCopy 替换成真实调用：

1. STEP1「🔍 分析图片」→ POST /api/v1/viral-video/analyze-images

• 入参：images（OSS URL[]，必填）、reference_video_url?、style_template_id?、style_strength?
• 返回：ViralVideoJob，状态=running，完成后 status=image_analyzed，job.image_analysis.products[] 包含 category/name/brand/colors/material_or_texture/key_features/visual_style/scene/target_audience_hint/text_on_image
• 前端改动：拿到 job 后立即保存 jobId 并启动轮询（之前轮询只在视频生成阶段启用，现在从 STEP1 开始贯穿三步）；轮询到 image_analyzed 时自动把 job.image_analysis 同步进 imageAnalysis state 并切到 step1_done
• 删除 mockImageAnalysis 客户端假数据调用

2. STEP2「✍️ 生成文案」→ POST /api/v1/viral-video/{id}/generate-copy

• 入参：industry/target_customer/viral_structure/marketing_purpose/bgm_preference/duration/fusion_level/user_copy_text/style_strength
  • AI 全写/AI 润色档位：不传 user_copy_text
  • 「按我写的来」档位：传 textarea 中 task.userCopy
• 返回：ViralVideoJob，完成后 status=copy_generated，job.copy_result = {title, final_copy, suggested_copy, scenes:[{shot,narration,duration?}]}
• 前端改动：轮询到 copy_generated 时自动把 copy_result.final_copy/title 同步进 generatedCopy/generatedTitle 并切到 step2_copy_ready，textarea 直接显示真实文案
• 删除 mockGenerateCopy 客户端假数据调用

3. STEP2「🎬 确认文案并生成视频」→ POST /api/v1/viral-video/{id}/confirm-copy（一步触发）

• 入参：edited_copy?（用户编辑后的文案；未编辑不传，后端用 AI 原文案）
• 返回：ViralVideoJob，后端跑 TTS→Seedance→ffmpeg→upload 全流程，完成后 status=completed，result_video_url 为成片
• 前端改动：
  • handleConfirmCopy 不再只切本地 state，直接调 confirmViralCopy，切到 step3_generating 显示「AI 正在生成视频中…」
  • 轮询到 completed 自动切到 step3_done，视频播放器用 job.output_url || job.result_video_url
  • 用户不需要再点一次 STEP3「开始生成视频」，但该按钮保留作为重试/兜底入口：有 jobId+文案时重走 confirm-copy，否则降级到旧 /generate 接口

4. 轮询升级

onPollUpdate 现在识别所有新状态和阶段：

• image_analyzed → step1_done
• copy_generated → step2_copy_ready
• running 态按 progress_stage 细分：
  • image_analysis/video_analysis → step1_analyzing
  • intent_parsing/copy_fusion/storyboard/review → step2_generating
  • tts/bgm_select/rendering/musetalk/uploading → step3_generating
• wait_user_confirm 兼容旧链路（停留在 step2_copy_ready）
• failed 按阶段区分 copyError/videoError
• 自动把 job.image_analysis/job.copy_result 同步到本地 state，避免本地假数据与服务端不同步
• 轮询终止条件仍为 completed/failed/cancelled（image_analyzed/copy_generated 是非终态，继续轮询等待下一步触发）

5. 旧链路兼容

• /generate 和 /{id}/confirm-intent 端点保留不删，handleGenerateVideo（STEP3 兜底按钮）继续使用旧 /generate 作为降级路径
• retryViralVideo 逻辑不变
• GET /viral-video/{id} 类型定义已包含 image_analysis/copy_result 字段，与后端对齐

6. 类型清理

• 移除未使用的 CopyResult 类型导入（现在通过 job.copy_result 访问，不需要本地类型声明的实例）
• 补充 isCopyStage/isImageAnalysisStage 导入（用于轮询阶段判断）
• 删除 mock 函数导入

测试

• tsc --noEmit 通过
• eslint 通过
• prettier --write 通过
• vite build 通过

未改动

• 旧的 /generate 和 /{id}/confirm-intent 接口代码路径保留，未删除
• WS 事件 viral_video:image_analyzed/viral_video:copy_generated：当前轮询已能覆盖状态推进，WS 事件可在后续迭代作为实时加速优化（非阻塞）
• 音色参数（voice_id/voice_source）：当前三步 API 的 AnalyzeImagesRequest/GenerateCopyRequest/ConfirmCopyRequest 类型里没有 voice 字段，音色选择 state 保留在前端，待后端补充音色设置端点（或在 confirm-copy 中扩展）后再打通

## 改动：三步独立流程接入真实后端 API（替换前端 mock） 后端 PR#2117（d390d7c）已在 staging 上线三个新端点，前端把之前的 mockImageAnalysis/mockGenerateCopy 替换成真实调用： ### 1. STEP1「🔍 分析图片」→ `POST /api/v1/viral-video/analyze-images` - 入参：`images`（OSS URL[]，必填）、`reference_video_url?`、`style_template_id?`、`style_strength?` - 返回：`ViralVideoJob`，状态=running，完成后 status=`image_analyzed`，`job.image_analysis.products[]` 包含 category/name/brand/colors/material_or_texture/key_features/visual_style/scene/target_audience_hint/text_on_image - 前端改动：拿到 job 后立即保存 `jobId` 并启动轮询（之前轮询只在视频生成阶段启用，现在从 STEP1 开始贯穿三步）；轮询到 `image_analyzed` 时自动把 `job.image_analysis` 同步进 `imageAnalysis` state 并切到 `step1_done` - 删除 `mockImageAnalysis` 客户端假数据调用 ### 2. STEP2「✍️ 生成文案」→ `POST /api/v1/viral-video/{id}/generate-copy` - 入参：`industry/target_customer/viral_structure/marketing_purpose/bgm_preference/duration/fusion_level/user_copy_text/style_strength` - AI 全写/AI 润色档位：不传 `user_copy_text` - 「按我写的来」档位：传 textarea 中 `task.userCopy` - 返回：`ViralVideoJob`，完成后 status=`copy_generated`，`job.copy_result = {title, final_copy, suggested_copy, scenes:[{shot,narration,duration?}]}` - 前端改动：轮询到 `copy_generated` 时自动把 `copy_result.final_copy`/`title` 同步进 `generatedCopy`/`generatedTitle` 并切到 `step2_copy_ready`，textarea 直接显示真实文案 - 删除 `mockGenerateCopy` 客户端假数据调用 ### 3. STEP2「🎬 确认文案并生成视频」→ `POST /api/v1/viral-video/{id}/confirm-copy`（一步触发） - 入参：`edited_copy?`（用户编辑后的文案；未编辑不传，后端用 AI 原文案） - 返回：`ViralVideoJob`，后端跑 TTS→Seedance→ffmpeg→upload 全流程，完成后 status=`completed`，`result_video_url` 为成片 - 前端改动： - `handleConfirmCopy` 不再只切本地 state，直接调 `confirmViralCopy`，切到 `step3_generating` 显示「AI 正在生成视频中…」 - 轮询到 `completed` 自动切到 `step3_done`，视频播放器用 `job.output_url || job.result_video_url` - 用户不需要再点一次 STEP3「开始生成视频」，但该按钮保留作为重试/兜底入口：有 jobId+文案时重走 confirm-copy，否则降级到旧 `/generate` 接口 ### 4. 轮询升级 `onPollUpdate` 现在识别所有新状态和阶段： - `image_analyzed` → `step1_done` - `copy_generated` → `step2_copy_ready` - `running` 态按 `progress_stage` 细分： - `image_analysis`/`video_analysis` → `step1_analyzing` - `intent_parsing`/`copy_fusion`/`storyboard`/`review` → `step2_generating` - `tts`/`bgm_select`/`rendering`/`musetalk`/`uploading` → `step3_generating` - `wait_user_confirm` 兼容旧链路（停留在 step2_copy_ready） - `failed` 按阶段区分 `copyError`/`videoError` - 自动把 `job.image_analysis`/`job.copy_result` 同步到本地 state，避免本地假数据与服务端不同步 - 轮询终止条件仍为 `completed/failed/cancelled`（`image_analyzed`/`copy_generated` 是非终态，继续轮询等待下一步触发） ### 5. 旧链路兼容 - `/generate` 和 `/{id}/confirm-intent` 端点保留不删，`handleGenerateVideo`（STEP3 兜底按钮）继续使用旧 `/generate` 作为降级路径 - `retryViralVideo` 逻辑不变 - `GET /viral-video/{id}` 类型定义已包含 `image_analysis`/`copy_result` 字段，与后端对齐 ### 6. 类型清理 - 移除未使用的 `CopyResult` 类型导入（现在通过 `job.copy_result` 访问，不需要本地类型声明的实例） - 补充 `isCopyStage`/`isImageAnalysisStage` 导入（用于轮询阶段判断） - 删除 mock 函数导入 ## 测试 - [x] tsc --noEmit 通过 - [x] eslint 通过 - [x] prettier --write 通过 - [x] vite build 通过 ## 未改动 - 旧的 `/generate` 和 `/{id}/confirm-intent` 接口代码路径保留，未删除 - WS 事件 `viral_video:image_analyzed`/`viral_video:copy_generated`：当前轮询已能覆盖状态推进，WS 事件可在后续迭代作为实时加速优化（非阻塞） - 音色参数（voice_id/voice_source）：当前三步 API 的 AnalyzeImagesRequest/GenerateCopyRequest/ConfirmCopyRequest 类型里没有 voice 字段，音色选择 state 保留在前端，待后端补充音色设置端点（或在 confirm-copy 中扩展）后再打通

xiaoxia added 1 commit 2026-10-01 12:24:37 +08:00

feat(viral-video): 三步独立流程接入真实后端API（替换mock） ... 235d3685c6

后端PR#2117已上线三步独立端点，前端替换原先的mockImageAnalysis/mockGenerateCopy：

1. STEP1「🔍 分析图片」：
   - 改为调用 POST /viral-video/analyze-images，入参 images/reference_video_url/style_strength
   - 返回 ViralVideoJob，立刻保存 jobId 并启动轮询（之前轮询只在视频生成阶段启用，现在从STEP1开始贯穿三步）
   - 删除 mockImageAnalysis 客户端假数据

2. STEP2「✍️ 生成文案」：
   - 改为调用 POST /viral-video/{id}/generate-copy，入参 industry/target_customer/viral_structure/marketing_purpose/bgm_preference/duration/fusion_level/user_copy_text/style_strength
   - AI全写/AI润色档位不传user_copy_text；按我的话来档位传textarea内容
   - 返回 job 包含 copy_result，轮询到 status=copy_generated 时自动把 copy_result.final_copy/title 同步进generatedCopy/generatedTitle并切换到step2_copy_ready
   - 删除 mockGenerateCopy 客户端假数据

3. STEP2「🎬 确认文案并生成视频」→ 合并触发：
   - handleConfirmCopy 不再只切本地状态，改为调用 POST /viral-video/{id}/confirm-copy
   - 用户未修改文案时不传 edited_copy（后端用AI生成的final_copy）；用户编辑过则传 edited_copy
   - 接口返回后job进入running→TTS→Seedance→ffmpeg→upload全流程，轮询到status=completed自动切换step3_done
   - 不再需要单独再点「开始生成视频」按钮，但保留STEP3的按钮作为重试/兜底入口（有jobId+文案时走confirm-copy，否则降级到旧/generate接口）

4. 轮询 onPollUpdate 升级：
   - 识别新状态 image_analyzed→step1_done、copy_generated→step2_copy_ready
   - running态按progress_stage细分：image/video_analysis→step1_analyzing、intent/copy/storyboard/review→step2_generating、tts/bgm/rendering/musetalk/uploading→step3_generating
   - 自动同步 job.image_analysis 和 job.copy_result 到本地imageAnalysis/generatedCopy/generatedTitle，避免本地state与服务端不同步
   - failed态按阶段区分copyError/videoError

5. 旧链路兼容：
   - /generate 和 /{id}/confirm-intent 端点保留不删，handleGenerateVideo 兜底路径继续使用旧/generate（兼容旧任务/失败重试/没有jobId的降级场景）
   - retryViralVideo 逻辑不变
   - GET /{id} 已返回image_analysis/copy_result字段，类型定义已在types.ts对齐

tsc/eslint/prettier/vite build 全绿。

xiaoxia reviewed 2026-10-01 12:24:47 +08:00

xiaoxia left a comment

Author

Owner

Copy Link

Copy Source

LGTM

LGTM

xiaoxia merged commit 033c4a2eab into develop 2026-10-01 12:25:04 +08:00

gitea-actions bot commented 2026-10-01 12:26:46 +08:00

Copy Link

Copy Source

🗑️ 预览环境已清理

PR #2122 已关闭或合并，对应的预览环境已被清理。

如有需要，可以重新打开 PR 来重新生成预览环境。

🗑️ **预览环境已清理** PR #2122 已关闭或合并，对应的预览环境已被清理。 > 如有需要，可以重新打开 PR 来重新生成预览环境。

gitea-actions bot commented 2026-10-01 12:27:16 +08:00

Copy Link

Copy Source

🚀 预览环境已部署

项目	详情
PR号	#2122
预览链接	https://pr-2122.preview.xiaoxiajianji.com
API环境	staging

💡 预览环境使用 staging API 数据，请勿在预览环境中操作重要数据。

🔄 每次提交新代码后预览环境会自动更新。

🗑️ PR 关闭或合并后，预览环境会自动清理。

🚀 **预览环境已部署** | 项目 | 详情 | |------|------| | PR号 | #2122 | | 预览链接 | [https://pr-2122.preview.xiaoxiajianji.com](https://pr-2122.preview.xiaoxiajianji.com) | | API环境 | staging | > 💡 预览环境使用 staging API 数据，请勿在预览环境中操作重要数据。 > > 🔄 每次提交新代码后预览环境会自动更新。 > > 🗑️ PR 关闭或合并后，预览环境会自动清理。

auto-approve-bot reviewed 2026-10-01 12:27:33 +08:00

auto-approve-bot left a comment

Collaborator

Copy Link

Copy Source

CI全绿，自动审批通过。

CI全绿，自动审批通过。

xiaoxia referenced this issue from a commit 2026-10-01 12:31:21 +08:00

fix(viral-video): #2122 三阶段 pipeline 补齐 voice_id/voice_source/video_ratio 字段

xiaoxia referenced this issue from a commit 2026-10-01 12:40:51 +08:00

fix(viral-video): #2122 三阶段 pipeline 补齐 voice_id/voice_source/video_ratio 字段

xiaoxia referenced this issue from a commit 2026-10-01 12:49:37 +08:00

fix(viral-video): #2122 三阶段 pipeline 补齐 voice_id/voice_source/video_ratio 字段

Sign in to join this conversation.

Reviewers

No Reviewers

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

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

auto-approve-bot frontend-dev xiaoxia

No Assignees

3 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: xiaoxia/xiaoxia-saas#2122