Architecture

System Overview

StormFlow 前端是基于 Nuxt 4 的单页应用，采用画布 + 节点编排交互方式。用户通过拖拽连接文本/图片/视频节点构建 AI 内容生产流水线，数据通过后端 HTTP API + WebSocket 实时同步。单仓单应用，无 monorepo。

Layer Diagram

依赖规则（严格单向）：

• L3 不直接调用 L1（不跳过 Store 实例化 Service）
• L1 不导入任何 Vue / Pinia / Vue Flow
• L0 不导入任何其他层（Nuxt 框架级强制：shared/ 内禁止导入 Vue / Nitro）

Components / Pages 消费 L3，自身不属于架构层。constants/ 存放 UI 专属配置（节点注册表、选项枚举），可被任意层读取。

Domain Model

See source: shared/types/

领域类型由 Nuxt 自动导入，无需手动 import。

文件	导出	用途
shared/types/node.ts	NodeType, NodeStatus, ContentOrigin, NodeBase, TextNodeData, ImageNodeData, VideoNodeData, NodeData, CanvasNode	节点辨别联合类型体系
shared/types/edge.ts	CanvasEdge	连线类型
shared/types/graph.ts	Graph, Viewport	画布图结构
shared/types/model.ts	ModelModality, AiModelInfo, AiModel, ModelAbility, AbilityType, AbilityRules	AI 模型类型

NodeData 使用辨别联合（discriminated union），data.type 作为辨别字段，TypeScript narrowing 自然消除类型断言。CanvasNode 为领域层自有类型，不依赖 Vue Flow，但与 Vue Flow 的 Node<NodeData> 结构兼容。

Data Flow

画布加载

节点/连线操作同步

多端同步（Push 事件）

AI 生成

Ownership Rules

Graph 唯一 mutable owner

flowStore 是 Graph 在前端内存中唯一的可变持有者。

• canvasStore 仅管理画布元数据（name 等），不持有 graph
• Vue Flow 的渲染状态由 flowStore 单向驱动

Transport 不直接改 graph

Vue Flow 状态边界

归属	内容
flowStore（持久化，同步服务端）	nodes、edges、viewport、节点数据
Vue Flow only（临时，不持久化）	选中态、hover、drag 预览、connection preview

Store → Composable 事件通道

flowStore 通过事件队列向 L3 传递需要 UI 反馈的信号。Store 不产生 UI 副作用（不调用 toast / router）。L3 负责消费事件并转化为用户可见反馈。

WS 协同状态机

后端契约（前置条件）

契约	说明
每次连接/重连后，服务端发送 CONNECT 快照	前端以此作为唯一权威 graph 初始化/恢复来源
accept 携带完整 VO 数据	前端用于 tmpId → serverId 替换
push 不发送给操作发起者	前端不做 echo 去重

Pending Mutations

flowStore 内部维护 pending mutations map（key 为 requestId），跟踪每个已发未确认的 WS command 的回滚函数和临时 ID。

事件处理规则

事件	处理
CONNECT	服务端快照覆盖本地 graph；所有 pending 回滚并清空
accept	以 requestId 匹配 pending；替换 tmpId → serverId；移除 pending
reject	以 requestId 匹配 pending；执行 rollback；推送事件；移除 pending
push	直接应用（服务端不向发起者推送，无需去重）
重连	WsClient / FlowService 持续存在，不重建；服务端主动发 CONNECT

冲突规则：服务端快照永远赢。CONNECT 到来时所有本地乐观状态回滚。

断线行为

WS 状态为 reconnecting 时，flowStore 拒绝所有 graph mutation。画布只读，L3 根据 wsStatus 显示提示。

重试策略

层面	行为
连接重试	WsClient 自动重连，CONNECT 快照恢复状态
命令重试	不自动重发；超时后 rollback；CONNECT 兜底

Session 生命周期

WsClient 和 FlowService 与 canvas 页面同生命周期，跨 reconnect 持续存在。

错误分类

类型	处理
业务失败（reject）	rollback + 事件队列
连接中断	自动重连 + 画布只读
命令超时	rollback，不重发，CONNECT 兜底
重连后快照覆盖	CONNECT 覆盖 + 警告事件

External Integrations

系统	用途	接口
StormFlow 后端 API	画布 CRUD、工作空间管理、AI 生成触发、模型列表	HTTP REST（NUXT_PUBLIC_API_BASE）
StormFlow WebSocket	节点/连线实时同步、AI 生成结果推送	WebSocket（Command/Accept/Reject/Push 协议）
腾讯云 COS	用户上传的图片/视频存储	STS 凭证 + cos-js-sdk-v5 直传，返回 CDN URL

Module Registry

模块	契约	主要源码
Workspace	workspace.md	app/pages/index.vue, stores/workspaceStore.ts
Canvas Editor	canvas-editor.md	app/pages/canvas/[id].vue, app/composables/useCanvasEditor.ts
Node System	node-system.md	app/components/nodes/
State Management	state-management.md	stores/
Services	services.md	services/
Shared Types	shared-types.md	shared/types/, shared/utils/