AiVideo/docs/studio_rearchitecture.md

AiVideo Studio 重构方案（V2）

目标

• 实现与参考编辑器页面一致的工作台布局：顶部导航、中央预览舞台、底部时间线、右侧参数与日志面板。
• 保留并强化现有能力：自动分镜、单镜头润色、渲染、阶段日志、任务跟踪。
• 将前端代码从“流程散落”改造为“分层架构”，减少重复逻辑与状态不一致风险。

新架构

1. UI Shell 层

• TopNav：品牌、快捷操作、Play/Render 入口。
• ToolBar：上下文状态（task/mock）与工具位。
• PreviewStage：展示当前 Scene 预览或 final video。
• TimelineStrip：镜头缩略图时间线与进度条。
• SceneEditor：单镜头编辑与润色入口。

2. 状态层（StudioState）

• 统一使用 useReducer 管理工作台状态。
• 核心状态：
  • scenes
  • selectedSceneIndex
  • stageState
  • stageLogs
  • renderProgress
  • taskId
  • finalVideoUrl
  • toast
• 所有修改均通过 dispatch(action) 进入 reducer，避免多处 useState 导致的竞态和重复。

3. API/流处理层（StudioAPI）

• startScriptStream()：EventSource 流式接收 Script 阶段事件。
• postStream()：统一处理 Refine/Render 的 fetch + SSE 流。
• consumeFetchSSE()：抽象 SSE 分块解析，消除重复解析代码。

4. 事件编排层

• onStageEvent(sourceStage, event, data) 统一路由：
  • task
  • stage_update
  • line
  • error
  • done
• applyStageUpdate() 负责阶段状态、进度、scene upsert 的单点更新。

数据流

1. 用户修改 Prompt / Provider 参数。
2. 自动防抖触发 startScript()，进入 Script SSE。
3. stage_update.scene_json 持续更新 scenes，时间线和右侧编辑器同步刷新。
4. 用户可对当前 Scene 进行编辑与 refine。
5. 用户触发 render，进度与日志实时反馈，完成后挂载 final video URL。

兼容性说明

• 继续使用 babel-standalone@6，所以 JSX 不使用 <>...</>，统一为 React.Fragment。
• 保持现有后端接口契约不变：
  • GET /api/script
  • POST /api/refine
  • POST /api/render

后续建议

• 将当前单文件页面拆分为真正多文件前端工程（Vite + React），引入 TypeScript 与单元测试。
• 增加 Timeline 的拖拽排序与片段时长编辑。
• 增加右侧“资产库”与“模板库”，进一步贴近参考产品完整体验。