# 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 的拖拽排序与片段时长编辑。
- 增加右侧“资产库”与“模板库”，进一步贴近参考产品完整体验。