refactor: GeneratePage Phase 2 — 7个Step组件化 + 自定义Hook（2682→485行） #803

Merged

xiaoxia merged 12 commits from refactor/generate-page-phase2 into develop 2026-07-24 17:20:59 +08:00

Conversation 5 Commits 12 Files Changed 17

+3336 -2350

xiaoxia commented 2026-07-24 00:58:44 +08:00

Owner

Copy Link

Copy Source

背景

GeneratePage 巨无霸拆分 Phase 2，将 7 个 Step 全部组件化并抽离对应自定义 Hook。

改动

• 7 个 Step 组件：Step1TemplateSelect ~ Step7ConfirmGenerate
• 7 个 Step Hook：useStep1Template ~ useStep7Generate
• 额外抽取：useGenerateVideo（生成核心逻辑，371行）
• 主组件精简：GeneratePage.tsx 从 2682 行 → 485 行（-81.9%）

行数统计

文件	行数
GeneratePage.tsx	485
Step1TemplateSelect	86
Step2MaterialSelect	310
Step3GeneratePreview	57
Step4TitleSettings	298
Step5VoiceSelect	533
Step6CoverSettings	191
Step7ConfirmGenerate	198
useStep1Template	44
useStep2Materials	205
useStep3Preview	47
useStep4Title	251
useStep5Voice	397
useStep6Cover	77
useStep7Generate	121
useGenerateVideo	371

状态划分

• 共享状态（保留主组件）：currentStep、selectedTemplate、titleSettings、coverSettings、materialMode/selectedMaterials、selectedVoice/voiceMode、generateCount 等跨 Step 使用的状态
• Step 特有状态（下放 Hook）：各 Step 内部的 UI 状态、数据请求、交互处理

原则

• 纯结构重构，功能完全不变
• TypeScript 类型完整，无新增 any
• 无新增第三方依赖
• 常量/类型从 constants.ts / types.ts 统一导入

Commits (4个)

1. feat(generate): add Step1-3 components and hooks
2. feat(generate): add Step4-7 components and hooks
3. refactor(generate): simplify GeneratePage with step components
4. refactor(generate): extract useGenerateVideo hook for core generation logic

## 背景 GeneratePage 巨无霸拆分 Phase 2，将 7 个 Step 全部组件化并抽离对应自定义 Hook。 ## 改动 - **7 个 Step 组件**：Step1TemplateSelect ~ Step7ConfirmGenerate - **7 个 Step Hook**：useStep1Template ~ useStep7Generate - **额外抽取**：useGenerateVideo（生成核心逻辑，371行） - **主组件精简**：GeneratePage.tsx 从 2682 行 → 485 行（-81.9%） ## 行数统计 | 文件 | 行数 | |------|------| | GeneratePage.tsx | 485 | | Step1TemplateSelect | 86 | | Step2MaterialSelect | 310 | | Step3GeneratePreview | 57 | | Step4TitleSettings | 298 | | Step5VoiceSelect | 533 | | Step6CoverSettings | 191 | | Step7ConfirmGenerate | 198 | | useStep1Template | 44 | | useStep2Materials | 205 | | useStep3Preview | 47 | | useStep4Title | 251 | | useStep5Voice | 397 | | useStep6Cover | 77 | | useStep7Generate | 121 | | useGenerateVideo | 371 | ## 状态划分 - **共享状态（保留主组件）**：currentStep、selectedTemplate、titleSettings、coverSettings、materialMode/selectedMaterials、selectedVoice/voiceMode、generateCount 等跨 Step 使用的状态 - **Step 特有状态（下放 Hook）**：各 Step 内部的 UI 状态、数据请求、交互处理 ## 原则 - 纯结构重构，功能完全不变 - TypeScript 类型完整，无新增 any - 无新增第三方依赖 - 常量/类型从 constants.ts / types.ts 统一导入 ## Commits (4个) 1. feat(generate): add Step1-3 components and hooks 2. feat(generate): add Step4-7 components and hooks 3. refactor(generate): simplify GeneratePage with step components 4. refactor(generate): extract useGenerateVideo hook for core generation logic

xiaoxia added 6 commits 2026-07-24 00:58:44 +08:00

docs(#780): 补齐.env.example缺失的30+配置项 ... 9a852a4a12

梳理所有配置文件（shared/api/worker），完整列出全部环境变量：
- 新增：数据库连接池配置（pool_size/max_overflow/timeout/recycle）
- 新增：Celery broker/backend 配置
- 新增：Worker 并发/子进程数 配置
- 新增：OSS 直传大小/过期时间 配置
- 新增：豆包大模型（Doubao）配置
- 新增：CosyVoice 克隆模型配置
- 新增：渲染引擎选择（RENDER_ENGINE）
- 新增：邮件投递开关 / SMTP TLS / API 端口等零散配置
- 每个配置补充用途注释和默认值说明
- 顶部增加配置读取优先级说明

refactor: GeneratePage Phase 1 - 抽取常量/类型/UI组件 ... e9d4885f7a

将 3036 行的 GeneratePage.tsx 按 Phase 1 计划拆分：

新增文件：
- constants.ts — 12组常量（STEPS/TITLE_PRESETS/AI标题模板/智能匹配理由/渐变色/图标等）
- types.ts — TitleSettings/SmartMatchResult/AiTitleResult 等类型定义
- components/GenerateHeader.tsx — 页头组件
- components/GenerateStepsBar.tsx — 步骤条组件
- components/GenerateResultPanel.tsx — 右侧生成结果面板

GeneratePage.tsx 从 3036 行 → 2682 行（-354行）
纯结构重构，业务逻辑零改动

feat(generate): add Step1-3 components and hooks ... fe62730401

- Step1TemplateSelect + useStep1Template: template selection UI and logic
- Step2MaterialSelect + useStep2Materials: material selection with manual/auto modes
- Step3GeneratePreview + useStep3Preview: generation preview summary

Part of GeneratePage Phase 2 refactoring.

feat(generate): add Step4-7 components and hooks ... b50cdb5943

- Step4TitleSettings + useStep4Title: title settings with AI generation and styling
- Step5VoiceSelect + useStep5Voice: voice selection with preset/TTS/clone modes
- Step6CoverSettings + useStep6Cover: cover settings with auto/frame/upload modes
- Step7ConfirmGenerate + useStep7Generate: generation confirmation and progress

Part of GeneratePage Phase 2 refactoring.

refactor(generate): simplify GeneratePage with step components ... 13452491a8

- Replace renderStep1~renderStep7 with standalone Step components
- Move step-specific state and logic into corresponding custom hooks
- Keep shared state (currentStep, selectedTemplate, titleSettings, etc.) in main component
- Keep core business logic (handleGenerate, URL params, step navigation) in main component
- Reduce main component from 2681 lines to ~765 lines

GeneratePage Phase 2: 7-step componentization complete.

refactor(generate): extract useGenerateVideo hook for core generation logic ... f42908b758

- Move handleGenerate, handleRetry, download, share to useGenerateVideo hook
- Move generation state (generating, progress, generated, etc.) to the hook
- Main component now focuses on state management, step navigation, and layout
- Reduce GeneratePage from 765 to ~420 lines

GeneratePage Phase 2: final optimization.

xiaoxia added 1 commit 2026-07-24 01:19:17 +08:00

fix(generate): fix ESLint errors in Phase 2 split ... 4fb68e8ba9

- rename useStep5Voice.ts -> .tsx (JSX in hook file)
- remove unused variables (presetVoicesLoading, cloneModalOpen, handleCloneSuccess)
- remove unused type imports (TitleConfig, PresetVoiceItem)

xiaoxia added 1 commit 2026-07-24 09:47:02 +08:00

style: format with prettier 045295283f

xiaoxia added 1 commit 2026-07-24 09:54:25 +08:00

test: add GenerateHeader component smoke test caa4ad23ed

xiaoxia added 1 commit 2026-07-24 10:09:34 +08:00

style: fix GenerateHeader test prettier formatting 0a33fdc3e0

xiaoxia added 1 commit 2026-07-24 11:32:49 +08:00

merge: resolve conflicts with develop (rebase Phase 2 onto latest develop) 4ab94fb051

auto-approve-bot approved these changes 2026-07-24 11:56:18 +08:00

auto-approve-bot left a comment

Collaborator

Copy Link

Copy Source

CI全绿，自动审批通过。

CI全绿，自动审批通过。

auto-approve-bot approved these changes 2026-07-24 11:56:18 +08:00

auto-approve-bot left a comment

Collaborator

Copy Link

Copy Source

CI全绿，自动审批通过。

CI全绿，自动审批通过。

auto-approve-bot commented 2026-07-24 12:12:03 +08:00

Collaborator

Copy Link

Copy Source

Auto merge skipped after multiple 405 errors: PR may have conflicts or unresolved checks. Please review manually. This is not a CI failure.

Auto merge skipped after multiple 405 errors: PR may have conflicts or unresolved checks. Please review manually. This is not a CI failure.

xiaoxia added 1 commit 2026-07-24 16:58:44 +08:00

test: add GeneratePage import to extend vitest related coverage 8c62033101

xiaoxia force-pushed refactor/generate-page-phase2 from 172f90ee41 to 8c62033101 2026-07-24 16:58:44 +08:00 Compare

auto-approve-bot commented 2026-07-24 17:11:19 +08:00

Collaborator

Copy Link

Copy Source

📊 审查概览

• 整体评价：需修改
• 严重问题数量：2 个
• 一般建议数量：1 个

❌ 需修改的问题（严重）

1. [apps/web/src/pages/generate/GeneratePage.tsx: ~131行] 性能回归：handleCloneSuccess 未使用 useCallback 包裹

   • 问题描述：在旧代码中，handleCloneSuccess 使用了 useCallback 进行包裹，依赖项为 [addClone]。在重构后的新代码中，该回调函数被定义为普通函数 const handleCloneSuccess = ...。由于该函数会被传递给子组件（如 CloneModal），每次 GeneratePage 重新渲染时都会创建一个新的函数引用，导致接收该 prop 的子组件发生不必要的重渲染。
   • 修改建议：恢复 useCallback 包裹，确保函数引用稳定。

     const handleCloneSuccess = useCallback((voice: VoiceClone) => {
       addClone(voice)
       setCloneModalOpen(false)
       message.success("音色克隆成功！")
     }, [addClone]) // 确保依赖项正确
     

2. [apps/web/src/pages/generate/GeneratePage.tsx: ~13行] 未使用的导入：getEditPlan

   • 问题描述：代码中保留了 import { getEditPlan } from "@/api/template-editor"，但在当前 diff 展示的代码中，getEditPlan 原本调用的位置（已被移除的 handleGenerate 函数）已被删除。loadPlanConfig 函数仅解析 URL 参数中的 JSON，并未调用该 API。保留未使用的导入会增加打包体积并降低代码整洁度。
   • 修改建议：确认 getEditPlan 是否在其他未展示的代码（如 JSX 或其他 hook）中使用。如果该逻辑已完全迁移至 useGenerateVideo hook 中，请从 GeneratePage.tsx 中移除此导入。

💡 改进建议（一般）

1. [apps/web/src/pages/generate/GeneratePage.tsx: ~131行] loadPlanConfig 依赖项可能导致重复执行
   • 具体内容：useEffect 依赖了 [editPlanId, planConfigStr]，而 loadPlanConfig 内部也依赖这两个值。通常建议将 loadPlanConfig 放在 useEffect 内部，或者确保 useEffect 的依赖项与 loadPlanConfig 的 useCallback 依赖项完全一致。当前写法虽然逻辑上正确，但若 loadPlanConfig 被其他地方复用或依赖项变化，可能存在闭包陷阱风险。建议将 loadPlanConfig 直接定义在 useEffect 内部以简化逻辑，除非它需要被复用。

✅ 良好实践

• 状态解耦：成功将大量业务逻辑（智能匹配、标题生成、TTS合成等）从主组件中剥离，主组件职责更清晰，专注于状态管理和流程编排。
• 类型安全：保留了 useState 的泛型定义（如 useState<"manual" | "auto">("manual")），有助于类型检查。
• Hook 复用：引入 useGenerateVideo 和 useCloneProgress 等自定义 Hook，提高了代码的可维护性和复用性。

---

✅ 格式检查通过 | ❌ 逻辑审查需修改 | ⚠️ 建议关注性能

---

_{🤖 由 AI 代码审查机器人自动生成 | 2026-07-24 09:11:19 | 模型:}

### 📊 审查概览 - **整体评价**：需修改 - **严重问题数量**：2 个 - **一般建议数量**：1 个 ### ❌ 需修改的问题（严重） 1. **[apps/web/src/pages/generate/GeneratePage.tsx: ~131行] 性能回归：`handleCloneSuccess` 未使用 `useCallback` 包裹** - **问题描述**：在旧代码中，`handleCloneSuccess` 使用了 `useCallback` 进行包裹，依赖项为 `[addClone]`。在重构后的新代码中，该回调函数被定义为普通函数 `const handleCloneSuccess = ...`。由于该函数会被传递给子组件（如 `CloneModal`），每次 `GeneratePage` 重新渲染时都会创建一个新的函数引用，导致接收该 prop 的子组件发生不必要的重渲染。 - **修改建议**：恢复 `useCallback` 包裹，确保函数引用稳定。 ```typescript const handleCloneSuccess = useCallback((voice: VoiceClone) => { addClone(voice) setCloneModalOpen(false) message.success("音色克隆成功！") }, [addClone]) // 确保依赖项正确 ``` 2. **[apps/web/src/pages/generate/GeneratePage.tsx: ~13行] 未使用的导入：`getEditPlan`** - **问题描述**：代码中保留了 `import { getEditPlan } from "@/api/template-editor"`，但在当前 diff 展示的代码中，`getEditPlan` 原本调用的位置（已被移除的 `handleGenerate` 函数）已被删除。`loadPlanConfig` 函数仅解析 URL 参数中的 JSON，并未调用该 API。保留未使用的导入会增加打包体积并降低代码整洁度。 - **修改建议**：确认 `getEditPlan` 是否在其他未展示的代码（如 JSX 或其他 hook）中使用。如果该逻辑已完全迁移至 `useGenerateVideo` hook 中，请从 `GeneratePage.tsx` 中移除此导入。 ### 💡 改进建议（一般） 1. **[apps/web/src/pages/generate/GeneratePage.tsx: ~131行] `loadPlanConfig` 依赖项可能导致重复执行** - **具体内容**：`useEffect` 依赖了 `[editPlanId, planConfigStr]`，而 `loadPlanConfig` 内部也依赖这两个值。通常建议将 `loadPlanConfig` 放在 `useEffect` 内部，或者确保 `useEffect` 的依赖项与 `loadPlanConfig` 的 `useCallback` 依赖项完全一致。当前写法虽然逻辑上正确，但若 `loadPlanConfig` 被其他地方复用或依赖项变化，可能存在闭包陷阱风险。建议将 `loadPlanConfig` 直接定义在 `useEffect` 内部以简化逻辑，除非它需要被复用。 ### ✅ 良好实践 - **状态解耦**：成功将大量业务逻辑（智能匹配、标题生成、TTS合成等）从主组件中剥离，主组件职责更清晰，专注于状态管理和流程编排。 - **类型安全**：保留了 `useState` 的泛型定义（如 `useState<"manual" | "auto">("manual")`），有助于类型检查。 - **Hook 复用**：引入 `useGenerateVideo` 和 `useCloneProgress` 等自定义 Hook，提高了代码的可维护性和复用性。 --- ✅ 格式检查通过 | ❌ 逻辑审查需修改 | ⚠️ 建议关注性能 --- _{🤖 由 AI 代码审查机器人自动生成 | 2026-07-24 09:11:19 | 模型:} <!-- AI_CODE_REVIEW_AUTO_COMMENT -->

xiaoxia merged commit 9a51cad137 into develop 2026-07-24 17:20:59 +08:00

xiaoxia deleted branch refactor/generate-page-phase2 2026-07-24 17:20:59 +08:00

gitea-actions bot commented 2026-07-24 17:21:13 +08:00

Copy Link

Copy Source

🗑️ 预览环境已清理

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

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

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

Sign in to join this conversation.

Reviewers

No Reviewers

auto-approve-bot

Labels

Clear labels

P0

阻塞性，必须立即处理

P1

高优先级

P2

中优先级

P3

低优先级/后考虑

architecture

架构设计

backend

后端相关

blocked

阻塞中

bug

Bug修复

ci-bug

CI本身的bug

ci-optimization

CI优化类任务

ci-pipeline

CI流水线/workflow相关

cleanup

代码清理

devops

运维/部署/CI

documentation

文档相关

feature

新功能

frontend

前端相关

question

需要讨论确认

ready

PR CI通过，可合并

refactor

代码重构

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

auto-approve-bot xiaoxia

No Assignees

3 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: xiaoxia/xiaoxia-saas#803