united-workforce/packages/workflow-dashboard/context.md

# Workflow UI — 开发上下文文档

## 1. 项目定位

workflow-dashboard 是一个 Web 图形编辑器，用于可视化展示和编辑工作流（Workflow）的结构。

**核心场景**：
- 用户本地执行 `uwf connect` 命令，通过 WebSocket 连接到此 Web 服务
- CLI 将本地 YAML 工作流文件发送到 server
- Server 解析后，提供图形化界面展示工作流的节点拓扑，允许用户进行逻辑编排和节点编辑
- 编辑完成后，数据可回传给 CLI 或持久化

## 2. 技术栈

| 层 | 技术 | 说明 |
|---|------|------|
| 图编辑器 | @xyflow/react v12 | 节点/边渲染、拖拽、连线（strict 连接模式） |
| 前端框架 | React 19 | UI 组件 |
| 路由 | react-router v7 | Hash 模式路由 |
| 状态管理 | 自研 (context.tsx) | 基于 useSyncExternalStore + Immer |
| 样式 | Tailwind CSS v4 | 原子化 CSS |
| 图标 | lucide-react | 图标库 |
| 构建工具 | Vite 8 | Dev server + 打包 |
| 后端框架 | Elysia | 轻量 REST API（当前为 stub） |

## 3. 目录结构

```
workflow-dashboard/
├── server.ts                 # Vite dev server 入口 (port 3000)
├── vite.config.ts            # Vite 配置（react + tailwind + elysia 插件 + @ 别名）
├── vite-dev.ts               # 自定义 Vite 插件
├── components.json           # shadcn 配置
├── server/
│   ├── api.ts                # Elysia REST API (health + workflow CRUD)
│   └── workflow.ts           # Workflow 文件读写 + 格式转换
├── tmp/workflow/             # Workflow YAML 存储目录（开发阶段）
├── src/
│   ├── main.tsx              # React DOM 入口
│   ├── router.tsx            # React Router 配置
│   ├── app.tsx               # 根布局组件
│   ├── lib/utils.ts          # Tailwind cn() 工具
│   ├── components/ui/        # shadcn 组件（button, card, dialog, input, textarea）
│   ├── pages/
│   │   ├── home.tsx          # Home 列表页（workflow 管理）
│   │   └── detail.tsx        # Workflow 详情/编辑页
│   └── editor/               # ★ 核心编辑器
│       ├── flow.tsx          # FlowEditor 组件 + 公开 API 导出
│       ├── type.ts           # 内部类型定义
│       ├── context.tsx       # 自研状态管理框架
│       ├── injection.ts      # DI 容器（FlowModel / Injection）
│       ├── model/            # 状态模型层
│       ├── nodes/            # 节点渲染组件
│       ├── edges/            # 边渲染组件
│       ├── panel/            # UI 面板（工具栏、添加/编辑面板）
│       ├── trans/            # 数据转换层（内外格式互转）
│       ├── layout/           # 自动布局算法
│       └── utils/            # 工具函数
```

## 4. 数据模型

### 4.1 外部格式 — WorkFlowSteps（与 CLI 交换的数据）

`WorkFlowSteps` 是 `WorkFlowStep[]`，每个 step 描述一个角色节点及其转移关系：

```typescript
type WorkFlowRole = {
  name: string;          // 角色名称（唯一标识）
  description: string;   // 角色描述
  identity: string;      // 身份定义（system prompt）
  prepare: string;       // 执行前准备指令
  execute: string;       // 核心执行指令
  report: string;        // 输出格式指令
};

type WorkFlowTransition = {
  target: string;           // 目标角色名 或 'END'
  condition: string | null; // 条件表达式，null 为 else（无条件兜底）
};

type WorkFlowStep = {
  role: WorkFlowRole;
  transitions: WorkFlowTransition[];
};
```

### 4.2 内部格式 — ReactFlow Nodes & Edges

编辑器内部使用 ReactFlow 的 Node/Edge 模型：

**节点类型**：
- `start` → 起始节点（右侧 1 个 source handle）
- `end` → 结束节点（左侧 1 个 target handle）
- `role` → 角色节点（6 个 handle，见下方）

**Role 节点 Handle 布局**：

| 位置 | 类型 | ID | 颜色 |
|------|------|----|------|
| 左侧 | target (in) | `input` | 蓝色 |
| 上方 30% | target (in) | `input-top` | 蓝色 |
| 下方 30% | target (in) | `input-bottom` | 蓝色 |
| 右侧 | source (out) | `output` | 绿色 |
| 上方 70% | source (out) | `output-top` | 绿色 |
| 下方 70% | source (out) | `output-bottom` | 绿色 |

- target handle 设置了 `isConnectableStart`，可以从 in 拖向 out 发起连线（`onConnect` 自动纠正方向）
- source handle 设置了 `isConnectableEnd`

**RoleNodeData** 对齐上游 `RoleDefinition`：
```typescript
type RoleNodeData = {
  name: string;
  description: string;
  identity: string;
  prepare: string;
  execute: string;
  report: string;
};
```

**边类型**：
- `default`（GradientEdge）→ 渐变色边（绿→蓝），节点仅有一条出边时使用
- `status`（StatusEdge）→ 带 status 标签的渐变色边，节点有多条出边时使用

**边渲染特性**：
- 渐变色：SVG linearGradient，从 source 端绿色（#10b981）到 target 端蓝色（#3b82f6）
- 选中时：变为琥珀色（#f59e0b）单色，方便识别
- 缺少条件时：红色（#ff5252）
- 交互区域：20px 宽透明路径用于点击

### 4.3 Else 分支机制

当一个节点有多条 conditional 出边时：
- **edges 数组中排第一个的 conditional 边自动成为 else**（兜底分支）
- else 边显示灰色 `else` badge（不可点击，无需设置条件）
- 其余边显示 `if` badge（需要设置条件，可点击编辑）
- 只有一条 conditional 出边时不显示 else 标签
- else 边在有 if 兄弟存在时不能被删除（`onBeforeDelete` 保护）
- 序列化时 else 边输出 `condition: null`
- 反序列化时 `condition: null` 的 transition 排序到第一个

### 4.4 条件边自动升级与降级

- **升级**：当用户从某节点拖出第二条边时，`edgesModel.onConnect` 自动将该节点所有出边升级为 `conditional` 类型。
- **降级**：当删除 conditional 边后，若该 source 仅剩一条 conditional 出边，`handlers.onDelete` 自动将其降级回 `default` 类型。

### 4.5 连线约束

`onConnect` 中的校验逻辑：
1. 禁止自连（source === target）
2. 禁止同一对节点之间的重复边（source+target 去重）
3. 方向归一化：从 input handle 拖到 output handle 时自动反转 source/target
4. Handle 类型校验：source 端必须是 output handle，target 端必须是 input handle

### 4.6 数据转换层（trans/）

```
WorkFlowSteps  ──transIn()──→  { nodes, edges }  ──transOut()──→  WorkFlowSteps
                 （反序列化）                           （序列化）
```

- `transIn(steps)`: 外部步骤列表 → ReactFlow 节点和边
- `transOut(nodes, edges)`: ReactFlow 节点和边 → 外部步骤列表
- `validate(nodes, edges)`: 校验图结构合法性

三个函数都是**纯函数**。

### 4.7 验证规则

1. start 恰好 1 个，输出恰好 1 条
2. end 恰好 1 个，输入 ≥1 条，输出 0 条
3. role 节点：输入 ≥1、输出 ≥1
4. 多输出时：第一条 conditional 边为 else（跳过 condition 检查），其余必须有非空 condition
5. role 节点总数 ≥2
6. 无孤立节点（正向 BFS 从 start 可达 + 反向 BFS 从 end 可达）

## 5. 架构分层

### 5.1 状态管理框架（context.tsx）

自研的轻量响应式系统，核心概念：

| 概念 | 说明 |
|------|------|
| `generate<T>()` | 创建响应式 store（get/set/use/listen） |
| `SubModel<T, A>` | 状态切片模板（name + make() + create()） |
| `Model` | 事务管理器 + undo/redo 栈 |
| `define.model()` | 定义有状态有 actions 的模型 |
| `define.view()` | 定义只读视图模型 |
| `define.memoize()` | 定义缓存计算模型 |
| `define.compute()` | 定义响应式依赖计算（自动追踪） |

使用 `useSyncExternalStore` 桥接 React 渲染。

### 5.2 模型层（model/）

| 模型 | 文件 | 职责 |
|------|------|------|
| `nodesModel` | nodes.ts | 节点数组状态 + CRUD 操作 |
| `edgesModel` | edges.ts | 边数组状态 + 连线 + conditional 自动升级 + 连线约束 |
| `addNodeViewModel` | add-node-view.ts | 添加节点面板的 UI 状态 |
| `editNodeViewModel` | edit-node-view.ts | 编辑节点面板的 UI 状态 |
| `injection` | inject.ts | DI 实例视图模型 |
| `handlers` | handlers.ts | 事件处理器集合（拖拽、连线、删除保护、快捷键、布局、加载/保存） |

### 5.3 DI 容器（injection.ts）

```
FlowModel（公开 API）          Injection（内部实现）
  ├─ load(steps)  ──emit──→     emit('load', steps)  → handlers.loadSteps()
  ├─ on('save', cb)              emit('save', steps)  ← handlers.saveData()
  └─ 持有 Injection 实例
```

- `FlowModel` 是外部消费者唯一接触的类，提供 `load()` 和 `on('save')` 接口
- 构造函数接受可选的 `inital_steps` 参数，用于加载默认工作流
- `Injection` 是内部事件总线，解耦 server 通信与 UI 状态

### 5.4 事务与 Undo/Redo

Model 提供事务机制：
- `startTransaction()` 快照当前状态
- `endTransaction()` 将快照推入 undo 栈
- Ctrl+Z / Ctrl+Y 触发撤销/重做
- 拖拽、添加节点、删除等操作自动包裹在事务中

## 6. 节点体系

### 6.1 渲染组件

```
ReactFlow
  ├─ nodeTypes: { start: NodeStart, end: NodeEnd, role: NodeRole }
  └─ edgeTypes: { default: GradientEdge, status: StatusEdge }
```

`NodeRole` 显示角色名（data.name），使用 teal 色系图标和标签。Handle 分蓝色（in）和绿色（out）两种颜色。

### 6.2 节点编辑

角色节点的编辑器直接内联在 AddNodePanel 和 EditNodePanel 中，可编辑字段：
- name（必填）
- description、identity、prepare、execute、report（textarea）

## 7. UI 面板

| 面板 | 位置 | 内容 |
|------|------|------|
| Toolbar | 顶部居中 | Undo/Redo、添加角色、自动布局、保存 |
| AddNodePanel | 右下角 | 角色节点创建表单（name + 6 字段 → 确认） |
| EditNodePanel | 右下角 | 角色节点编辑表单（预填当前数据 → 确认） |

AddNodePanel 和 EditNodePanel 互斥显示，点击外部自动关闭。

## 8. 自动布局（layout/）

`LayoutLR(nodes, edges)` 算法：
1. 拓扑排序分层（BFS，start → layer 0，end → max+1）
2. 按层分组
3. 计算 X/Y 坐标（水平间距 80px，垂直间距 40px）
4. 无变化时返回原数组（避免无效重渲染）

## 9. 核心数据流

### 加载工作流

```
FlowModel.load(steps) / FlowModel(initialSteps)
  → Injection.emit('load', steps)
  → handlers.loadSteps()
  → transIn(steps) → { nodes, edges }
    （condition: null 的 transition 排序到第一个，成为 else）
  → nodesModel.set(nodes)
  → edgesModel.set(edges)
  → autoLayoutLR()
  → model.reset()（清空 undo/redo）
```

### 保存工作流

```
用户点击 Save
  → handlers.saveData()
  → validate(nodes, edges)
  → 校验失败 → Toast 提示错误
  → 校验通过 → transOut(nodes, edges) → WorkFlowSteps
    （第一条 conditional 边序列化为 condition: null）
  → Injection.emit('save', steps)
  → FlowModel.emit('save', steps)
  → 外部消费者（server/CLI）接收
```

### 连线与条件边升级

```
用户拖线连接两个节点
  → edgesModel.onConnect(params)
  → normalizeConnection（方向纠正）
  → 校验（自连、重复、handle 类型）
  → 检查 source 已有出边数量
  → 已有出边 → 新边 + 已有边全部升级为 conditional
  → 首条出边 → 创建普通边
```

### 删除保护

```
用户选中节点/边按 Delete
  → handlers.onBeforeDelete({ nodes, edges })
  → start/end 节点 → 阻止
  → else 边（有 if 兄弟时）→ 阻止
  → 其他 → 允许
```

## 10. 上游数据模型参考

workflow-dashboard 消费的 YAML 工作流最终映射自 `WorkflowPayload`（定义在 workflow-protocol）：

```typescript
type WorkflowPayload = {
  name: string;
  description: string;
  roles: Record<string, RoleDefinition>;       // 角色定义（4 段式：identity/prepare/execute/report）
  graph: Record<string, Record<string, Target>>;   // status-based 路由图
};
```

workflow-dashboard 使用 `WorkFlowSteps` 格式作为交换数据，其中 `WorkFlowRole` 的字段与 `RoleDefinition` 对齐（description/identity/prepare/execute/report），`WorkFlowTransition` 对应 graph 中的 `Target`。外部（CLI/server）负责 `WorkflowPayload` ↔ `WorkFlowSteps` 的转换。

## 11. 当前状态与待完善项

- **WebSocket 集成**: 尚未实现，CLI connect 的 WebSocket 通信待开发
- **验证**: 图结构校验 + 可达性检测 + else 分支规则已实现
- **只读模式**: Detail 页面有"编辑/预览"切换按钮，但编辑器尚未实现真正的只读模式（禁止交互）

## 12. 业务系统

### 12.1 路由

| 路由 | 页面 | 文件 |
|------|------|------|
| `/` | Home — Workflow 列表 | `src/pages/home.tsx` |
| `/workflow/:name` | Detail — 预览/编辑 | `src/pages/detail.tsx` |

### 12.2 后端 API

Elysia REST API（`server/api.ts`），通过 Vite 插件（`vite-dev.ts`）集成到 dev server。

| Method | Path | 说明 |
|--------|------|------|
| GET | `/api/workflows` | 列出所有 workflow（name + description） |
| GET | `/api/workflows/:name` | 获取单个 workflow（返回 WorkFlowSteps JSON） |
| POST | `/api/workflows` | 新建 workflow（body: `{name, description}`） |
| PUT | `/api/workflows/:name` | 保存 workflow（body: WorkFlowSteps JSON） |
| DELETE | `/api/workflows/:name` | 删除 workflow |

### 12.3 数据存储

- 存储目录：`tmp/workflow/`，文件名 `{name}.yaml`
- 存储格式：WorkflowPayload YAML（与上游 workflow-protocol 一致）
- Server 端负责 WorkflowPayload ↔ WorkFlowSteps 转换（`server/workflow.ts`）

字段映射：
| WorkFlowRole | RoleDefinition |
|--------------|---------------|
| name | roles map key |
| description | description |
| identity | goal |
| prepare | capabilities (join/split by `\n`) |
| execute | procedure |
| report | output |

条件映射：WorkFlowTransition.condition 存储表达式字符串，保存时提取为 named conditions map。

### 12.4 shadcn/ui

已初始化 shadcn（`components.json`），使用 `@` 路径别名。已安装组件：
- button、card、dialog、input、textarea
- 组件位于 `src/components/ui/`

### 12.5 目录结构更新

```
workflow-dashboard/
├── server/
│   ├── api.ts                # Elysia REST API（health + workflow CRUD）
│   └── workflow.ts           # Workflow 文件读写 + 格式转换
├── src/
│   ├── components/ui/        # shadcn 组件
│   ├── pages/
│   │   ├── home.tsx          # Home 列表页
│   │   └── detail.tsx        # Workflow 详情/编辑页
│   └── ...
├── tmp/workflow/             # Workflow YAML 存储目录（开发阶段）
└── components.json           # shadcn 配置
```