Studio 系统架构：从状态机到端到端流程

一个图像编辑应用的复杂度不在于 UI 的绚丽，而在于状态流动的清晰性。Studio 系统的核心设计围绕一个问题展开：如何让状态变化可预测、可追溯、可扩展。

状态机：系统的心脏

useStudioStore.ts 不是一个简单的状态容器，而是整个 Studio 功能的真相源（Single Source of Truth）。没有组件持有关键状态，所有交互都通过 store actions 处理。

interface StudioState {
  currentStage: number           // UI 流程控制
  layoutSlots: LayoutSlot[]     // 画布的权威数据结构
  assets: Asset[]               // 所有可用资产
  selectedSlotId: string | null // 驱动上下文切换
  layout: LayoutType
  backgroundColor: string
  isUploading: boolean
}

这个设计的核心思想是：状态变化应该是单向的、可预测的。用户交互触发 action，action 更新状态，状态变化触发组件重渲染。没有组件可以绕过 store 直接修改数据。

组件协调：上下文驱动的 UI

ControlPanel 的 UI 完全由 store 状态驱动。它根据 currentStage 和 selectedSlotId 渲染不同的控制界面：

Stage 1 (准备阶段): 文件上传、相机拍摄、AI 生成表单 Stage 2 (装饰阶段): 上下文敏感的调整面板 Stage 3 (导出阶段): 导出和分享控件

关键的条件渲染逻辑：

{selectedSlotId && selectedSlot?.content ? (
  <ImageAdjustmentPanel selectedSlot={selectedSlot} />
) : (
  <LayoutControls />
)}

当没有选中插槽时，显示布局模板和背景色控件。选中插槽后，这些通用工具隐藏，显示针对该插槽的调整面板。

这种设计让 UI 始终保持上下文相关性。用户不需要在一堆不相关的选项中寻找需要的功能。

画布：DOM 的创新使用

Studio 的画布基于 DOM 而非 Canvas API。这个决定有其合理性，但也有代价。

DOM 提供了现成的响应式布局能力。Flexbox 和 Grid 让画布可以自适应不同屏幕尺寸。事件处理也更简单，每个元素都是独立的事件目标。

但性能上限确实不如 Canvas。当元素数量多或需要频繁重绘时，DOM 会开始卡顿。

AI 生成的端到端流程

AI 图像生成是一个完全异步、解耦的多服务协作流程。

这个流程体现了几个关键设计决策：

1. 乐观更新 立即显示 pending 状态的占位符，提升感知性能。

2. 队列解耦 API 请求立即返回，处理异步进行。队列确保任务不丢失。

3. 实时同步 通过 WebSocket 接收状态更新，避免轮询的低效。

创作保存的混合云策略

这个流程展现了 DOM-to-Image 导出和混合云存储的结合：

DOM-to-Image 导出 基于当前 DOM 状态生成图像，支持高分辨率输出，跨浏览器兼容。

混合存储策略 R2 永久存储（成本优化），CDN 全球分发（性能优化），数据库索引（快速检索）。

关于导出系统的更多细节，参见 dual-export-pipeline-architecture。

性能优化的实践

性能优化不是追求绝对速度，而是减少无用操作。

选择性重渲染 使用 Zustand 的选择器减少不必要的更新。组件只订阅需要的状态片段。

图像懒加载 资产预览按需加载，不在视口内的图像不会请求。

内存管理 组件卸载时清理资源，及时释放不再使用的图像缓存。

错误处理的层次

错误处理分为三个层次：

网络层 重试机制（指数退避），WebSocket 失败时降级到轮询。

状态层 事务性更新确保原子性，乐观锁处理并发修改。

UI 层 清晰的错误状态和恢复指导，不只是"出错了"，而是"什么地方出错了、为什么、怎么解决"。

开发体验

调试工具集成 Zustand DevTools 可视化状态变化，React DevTools 调试组件层次。

类型安全保障 TypeScript 全覆盖，Zustand 状态的类型推导，运行时验证。

架构的本质

Studio 系统的架构不是一次性的完美规划，而是在约束条件下持续调整的过程。

核心设计原则：

• 状态机驱动：所有交互通过状态变化表达
• 单向数据流：可预测、可追溯的状态变化
• 异步解耦：长时间操作不阻塞用户交互
• 清晰边界：前后端、组件间的契约明确

这些原则不是提前规划的，而是从问题中涌现的。当你理解了系统的本质需求，架构就会自然显现。

关于从意图到架构的思考过程，参见 from-intent-to-architecture。

架构设计没有银弹。每个选择都是在特定约束下的权衡。重要的不是追求完美，而是理解权衡的逻辑，并随着条件变化持续调整。

最后更新：2025-11-06