# flow_engine

**Repository Path**: fjxylin/flow_engine

## Basic Information

- **Project Name**: flow_engine
- **Description**: vue3+ts的流程引擎demo
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-06-29
- **Last Updated**: 2025-10-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 流程引擎 (Flow Engine)

基于 Vue3 + TypeScript 开发的流程设计引擎，参考 bpmn.js 的设计思路，支持可视化流程建模。

## 🚀 功能特性

### 核心功能
- **拖拽式节点创建**: 从左侧节点库拖拽节点到画布
- **可视化连线**: 点击节点连接点创建连线
- **历史记录系统**: 完整的撤销(Ctrl+Z)/重做(Ctrl+Y)功能，支持50步历史记录
- **节点类型支持**:
  - 开始节点 (圆形，绿色)
  - 结束节点 (圆形，红色) 
  - 任务节点 (矩形，蓝色)
  - 判断节点 (菱形，橙色)
  - 并行节点 (矩形，灰色)
  - 合并节点 (矩形，深灰色)

### 交互功能
- **节点操作**:
  - **网格对齐拖拽**: 节点移动自动吸附到网格点
  - 单击选择节点
  - **双击编辑节点名称** (内联编辑器)
  - **右键菜单**: 编辑、删除选项
  - **Delete键删除**: 选中后按Delete/Backspace键删除
- **连线操作**:
  - 点击连接点开始连线
  - **直线连接**: 简洁的直线连接，端点自动对齐网格
  - **连线实时预览**: 跟随鼠标移动的直线预览
  - **右键或ESC键取消连线** (带视觉提示)
  - **双击编辑连线标签** (内联编辑器)
  - **右键菜单**: 编辑标签、删除连线
  - **Delete键删除**: 选中后按Delete/Backspace键删除
  - 设置连线条件和标签
- **画布操作**:
  - **智能网格**: 20px网格系统，所有元素自动对齐
  - 鼠标滚轮缩放
  - 中键拖拽平移画布
  - 框选多个元素
  - **点击空白区域取消选中**: 点击画布空白处取消所有选中状态

### 工具功能
- **文件操作**:
  - 保存流程为JSON文件
  - 导入流程文件
  - 清空画布
- **视图控制**:
  - 缩放控制 (10% - 300%)
  - 视图重置
- **属性编辑**:
  - 节点属性编辑
  - 连线条件设置
  - 实时属性面板

## 🛠 技术栈

- **前端框架**: Vue 3 + TypeScript
- **状态管理**: Pinia
- **UI组件库**: Element Plus
- **样式预处理**: SCSS
- **构建工具**: Vue CLI
- **图形渲染**: SVG + HTML Canvas

## 📦 项目结构

```
src/
├── components/
│   └── FlowEngine/          # 流程引擎组件
│       ├── index.vue        # 主容器组件
│       ├── FlowCanvas.vue   # 画布组件
│       ├── FlowNode.vue     # 节点组件
│       ├── FlowEdge.vue     # 连线组件
│       └── NodePalette.vue  # 节点面板
├── stores/
│   └── flowStore.ts         # 流程状态管理
├── types/
│   └── flow.ts              # 类型定义
└── main.ts                  # 应用入口
```

## 🚀 快速开始

### 环境要求
- Node.js >= 16
- npm >= 7

### 安装依赖
```bash
npm install
```

### 启动开发服务器
```bash
npm run serve
```

### 构建生产版本
```bash
npm run build
```

## 📖 使用指南

### 1. 创建节点
- 从左侧节点库拖拽节点到画布
- **网格对齐**: 节点自动吸附到20px网格点，确保整齐排列
- 节点会自动生成唯一ID
- 可通过右侧属性面板编辑节点属性

### 2. 连接节点
- 将鼠标悬停在节点上显示连接点
- 点击源节点的连接点开始连线
- **直线连接**: 简洁的直线连接，无多余弯曲
- **网格对齐**: 连线端点对齐到网格，线条更整齐
- **实时预览**: 连线跟随鼠标移动，显示直线预览
- **右键点击或按ESC键可以取消连线操作** ✨
- 点击目标节点的连接点完成连线
- 支持设置连线条件和标签

### 3. 编辑属性
- **快速编辑**: 双击节点或连线可直接编辑名称/标签
- **内联编辑器**: 支持实时编辑，Enter键保存，ESC键取消
- **失焦保存**: 点击其他地方自动保存编辑内容
- **属性面板**: 单击选择节点或连线，在右侧面板编辑详细属性

### 4. 删除操作
- **键盘删除**: 选中节点或连线后按Delete或Backspace键删除
- **右键删除**: 右键点击节点或连线，选择"删除"选项
- **多选删除**: 可同时选中多个元素后批量删除
- **取消选中**: 点击画布空白区域取消所有选中状态

### 5. 画布操作
- **缩放**: 鼠标滚轮
- **平移**: 中键拖拽
- **选择**: 左键点击或框选
- **清空**: 工具栏清空按钮

### 6. 历史记录操作
- **撤销**: Ctrl+Z 或点击工具栏撤销按钮
- **重做**: Ctrl+Y 或 Ctrl+Shift+Z 或点击工具栏重做按钮
- **历史状态**: 工具栏显示当前步骤数和总步骤数
- **智能记录**: 只记录有意义的操作，选择状态变化不会产生历史记录
- **防抖优化**: 拖动过程中不会产生大量历史记录，只在开始和结束时记录

### 7. 文件操作
- **保存**: 导出为JSON格式流程文件
- **导入**: 支持导入之前保存的流程文件
- **格式**: 标准JSON格式，便于集成

## 📊 系统架构

### 操作步骤流程图

以下流程图展示了用户与流程引擎的完整交互流程：

```mermaid
flowchart TD
    A["启动应用"] --> B["初始化FlowStore"]
    B --> C["初始化历史记录"]
    C --> D["显示空白画布"]
    
    D --> E{"用户操作选择"}
    
    E -->|拖拽节点面板| F["创建新节点"]
    E -->|点击节点/连线| G["选择元素"]
    E -->|拖拽节点| H["移动节点位置"]
    E -->|双击元素| I["编辑标签"]
    E -->|连接点拖拽| J["创建连线"]
    E -->|右键菜单| K["删除元素"]
    E -->|Ctrl+Z| L["撤销操作"]
    E -->|Ctrl+Y| M["重做操作"]
    E -->|保存按钮| N["导出流程文件"]
    E -->|导入按钮| O["加载流程文件"]
    E -->|清空按钮| P["清空画布"]
    E -->|缩放操作| Q["调整视图"]
    
    F --> R["保存到历史记录"]
    G --> S["更新选择状态"]
    H --> T["网格吸附<br/>显示辅助线"]
    I --> U["保存标签更改"]
    J --> V["验证连接有效性"]
    K --> W["确认删除对话框"]
    
    R --> X["更新画布显示"]
    S --> X
    T --> R
    U --> R
    V --> R
    W --> R
    L --> Y["恢复历史状态"]
    M --> Y
    N --> Z["下载JSON文件"]
    O --> AA["解析并导入数据"]
    P --> BB["清空所有数据"]
    Q --> CC["更新视口参数"]
    
    X --> E
    Y --> X
    Z --> E
    AA --> X
    BB --> X
    CC --> X
```

### 数据流向架构图

以下流程图展示了数据在整个应用架构中的流动：

```mermaid
flowchart TD
    A["用户界面层<br/>FlowEngine/index.vue"] --> B["工具栏组件"]
    A --> C["画布容器<br/>FlowCanvas.vue"]
    A --> D["属性面板"]
    A --> E["节点面板<br/>NodePalette.vue"]
    
    E -->|拖拽事件| F["创建节点数据"]
    C -->|包含| G["FlowNode组件"]
    C -->|包含| H["FlowEdge组件"]
    C -->|包含| I["ContextMenu组件"]
    
    G -->|节点操作| J["FlowStore<br/>状态管理中心"]
    H -->|连线操作| J
    I -->|菜单操作| J
    F --> J
    
    J --> K["核心状态数据"]
    K --> L["nodes: FlowNode[]<br/>节点数组"]
    K --> M["edges: FlowEdge[]<br/>连线数组"]
    K --> N["selectedNodes: string[]<br/>选中节点ID"]
    K --> O["selectedEdges: string[]<br/>选中连线ID"]
    K --> P["viewport: Viewport<br/>视口信息"]
    K --> Q["history: HistoryState[]<br/>历史记录"]
    K --> R["guideLines: GuideLine[]<br/>辅助线数据"]
    
    J -->|响应式更新| S["计算属性Getters"]
    S --> T["getSelectedNodes<br/>获取选中节点"]
    S --> U["getSelectedEdges<br/>获取选中连线"]
    S --> V["canUndo/canRedo<br/>历史记录状态"]
    S --> W["historyInfo<br/>历史信息"]
    
    J -->|状态变更| X["Actions方法"]
    X --> Y["addNode/updateNode/deleteNode<br/>节点操作"]
    X --> Z["addEdge/updateEdge/deleteEdge<br/>连线操作"]
    X --> AA["saveToHistory<br/>历史记录管理"]
    X --> BB["undo/redo<br/>撤销重做"]
    X --> CC["selectNode/selectEdge<br/>选择管理"]
    
    J -->|数据持久化| DD["外部存储"]
    DD --> EE["导出JSON文件<br/>saveFlow()"]
    DD --> FF["导入JSON文件<br/>loadFlow()"]
    DD --> GG["浏览器本地存储<br/>(可扩展)"]
    
    S -->|数据绑定| A
    X -->|触发更新| A
    
    style J fill:#e1f5fe
    style K fill:#f3e5f5
    style DD fill:#e8f5e8
```

### 架构特点

- **🔄 响应式数据流**: Vue3 + Pinia实现的响应式状态管理
- **📝 历史记录系统**: 完整的撤销/重做功能支持，带防抖优化
- **🧩 组件化架构**: 清晰的组件分工和数据传递，高内聚低耦合
- **✨ 用户体验优化**: 网格吸附、辅助线、实时预览等细节优化
- **🎯 TypeScript支持**: 完整的类型安全保障
- **📊 状态管理**: 集中式状态管理，便于维护和调试

## 🔧 自定义开发

### 添加新节点类型
1. 在 `types/flow.ts` 中定义新的节点类型
2. 在 `FlowNode.vue` 中添加节点样式和图标
3. 在 `NodePalette.vue` 中添加到节点库

### 扩展连线功能
1. 在 `FlowEdge.vue` 中修改连线渲染逻辑
2. 在 `flowStore.ts` 中扩展连线数据结构
3. 添加新的连线类型和样式

### 集成到现有项目
```javascript
// 安装依赖
npm install pinia element-plus uuid

// 引入组件
import FlowEngine from './components/FlowEngine/index.vue'
import { useFlowStore } from './stores/flowStore'

// 使用
<FlowEngine />
```

## 🎯 设计理念

本流程引擎参考了 bpmn.js 的设计思路，但从零开始构建，具有以下特点：

- **轻量级**: 无重度依赖，核心代码简洁
- **可定制**: 组件化设计，易于扩展
- **现代化**: 基于Vue3 + TypeScript，类型安全
- **响应式**: 良好的移动端适配
- **易集成**: 可独立使用或集成到现有项目

## 📄 License

MIT License