@luckzz/vue-logicflow-designer 0.0.0-stage → 0.0.1

package/README.md

@@ -1,3 +1,415 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# LiteFlow Designer
+
+> 基于 **Vue 3 + LogicFlow + ElementPlus** 的独立流程编排拖拽设计器组件，对标 [LiteFlow](https://liteflow.cc/) 规则引擎，支持可视化编排、XML / DSL / EL 格式转换、流程模拟执行，可作为 Vue3 组件库独立打包被其他项目引用。
+
+---
+
+## 目录
+
+- [快速开始](#快速开始)
+- [功能特性](#功能特性)
+- [节点类型参考](#节点类型参考)
+- [技术栈](#技术栈)
+- [对外接口](#对外接口)
+- [外部引用集成](#外部引用集成)
+- [项目结构](#项目结构)
+- [架构说明](#架构说明)
+- [开发指南](#开发指南)
+- [构建打包](#构建打包)
+- [开发阶段](#开发阶段)
+
+---
+
+## 快速开始
+
+### 环境要求
+
+- **Node.js** >= 18
+- **npm** >= 9
+
+### 安装依赖并启动
+
+```bash
+npm install
+npm run dev
+```
+
+浏览器自动打开 `http://localhost:3000`，进入流程设计器预览页。
+
+> 开发模式下 [`views/Designer.vue`](src/views/Designer.vue) 引用 [`DesignerPanel.vue`](src/components/designer/DesignerPanel.vue)，可在此页面调试所有功能。
+
+---
+
+## 功能特性
+
+### 画布操作
+
+| 功能 | 说明 |
+|------|------|
+| ✅ 自动布局 | dagre LR 层次布局，节点增删后自动触发 |
+| ✅ 缩放滑块 | 画布右侧纵向滑块，范围 25% ~ 200% |
+| ✅ 滚轮缩放 / 平移 | 画布拖拽平移 + 鼠标滚轮缩放 |
+| ✅ 网格 / 对齐线 | 背景网格 + 拖拽对齐辅助线 |
+| ✅ 撤销 / 重做 | Ctrl+Z / Ctrl+Y |
+| ✅ 小地图 | 画布工具栏一键开关 |
+| ✅ 自适应画布 | 工具栏 fit 按钮 / 窗口尺寸变化自适应 |
+
+### 节点操作
+
+| 功能 | 说明 |
+|------|------|
+| ✅ 连线添加节点 | 边线中点 `+` 按钮追加，**唯一添加方式** |
+| ✅ 选中 / 删除 | 点选高亮，Delete 键删除，自动重连上下游 |
+| ✅ 复制粘贴 | Ctrl+C / Ctrl+V |
+| ✅ 左侧面板 | SidePanel 展示脚本节点与流程链，InsertNodeDialog 按分类展示可插入节点 |
+| ❌ 禁止拖拽 | 节点不可拖拽移动 |
+| ❌ 禁止删除 | START / END 节点不可删除 |
+
+### 边线与分支
+
+| 功能 | 说明 |
+|------|------|
+| ✅ polyline 折线 | 直角折线连线，中点带 `+` 添加按钮 |
+| ✅ 边线选中 | 高亮显示 + 条件表达式显示 |
+| ✅ 自动聚合 | WHEN/SWITCH/IF/FOR/WHILE/ITERATOR 创建时自动生成 AND 聚合节点 |
+| ✅ IF 分支 | 支持 true / false 双分支，属性面板可管理 |
+| ✅ PRE / FINALLY | 前置/后置容器，仅允许在 THEN 容器内创建 |
+| ✅ 递归清理 | 分支删除时递归清理到 AND 节点并重连 |
+| ❌ 禁止删除边线 | 边线仅随节点删除而连带删除 |
+| ❌ AND 节点受限 | AND 不可手动创建/删除 |
+
+### 数据导入导出
+
+| 格式 | 说明 |
+|------|------|
+| ✅ XML | 顶层数据模型（脚本 + 流程链），TopToolbar 导入/查看 |
+| ✅ DSL | 画布工具栏导入/查看 LiteFlow 规则 DSL |
+| ✅ EL | 画布工具栏导入 LiteFlow EL 表达式（链式风格） |
+| ✅ JSON | FlowData 内部格式，@save / @change 事件传出 |
+
+### 流程模拟
+
+| 功能 | 说明 |
+|------|------|
+| ✅ 模拟面板 | 画布工具栏「播放」按钮打开 SimulatePanel |
+| ✅ 执行模式 | 单步执行 / 自动执行（可调速度） |
+| ✅ 路径高亮 | 执行路径实时高亮显示 |
+| ✅ 模拟日志 | 实时模拟日志输出 |
+
+### 对外能力
+
+| 能力 | 说明 |
+|------|------|
+| ✅ `@save` 事件 | 保存时传出当前流程 XML 数据 |
+| ✅ `@change` 事件 | 流程变更时实时传出最新 XML |
+| ✅ `getSnapshot()` | 获取画布截图（base64 PNG） |
+
+---
+
+## 节点类型参考
+
+### 流程控制 (control)
+
+| 类型 | 名称 | 形状 | 颜色 | 说明 |
+|------|------|------|------|------|
+| `THEN` | 串行 | ▬ 矩形 | `#1890FF` | 顺序执行后续节点 |
+| `PRE` | 前置 | ▬ 矩形 | `#1890FF` | 流程开始前串行执行 |
+| `FINALLY` | 后置 | ▬ 矩形 | `#1890FF` | 流程结束后串行执行（不受异常影响） |
+| `WHEN` | 并行 | ◇ 菱形 | `#1890FF` | 并行执行多个分支，需聚合 |
+| `SWITCH` | 选择 | ◇ 菱形 | `#2F54EB` | 条件分支选择，需聚合 |
+| `IF` | 条件 | ◇ 菱形 | `#2F54EB` | 条件判断，支持 true/false 分支 |
+| `FOR` | 循环 | ⬡ 六边形 | `#531DAB` | 固定次数循环，需聚合 |
+| `WHILE` | 条件循环 | ⬡ 六边形 | `#531DAB` | 条件循环，需聚合 |
+| `ITERATOR` | 迭代器 | ⬡ 六边形 | `#531DAB` | 遍历集合，需聚合 |
+
+### 业务组件 (component)
+
+| 类型 | 名称 | 形状 | 颜色 | 说明 |
+|------|------|------|------|------|
+| `CMP` | 组件 | ▬ 矩形 | `#52C41A` | 普通业务组件 |
+| `SCRIPT` | 脚本 | ▬ 矩形 | `#52C41A` | Groovy / JavaScript 脚本节点 |
+| `SUB_FLOW` | 子流程 | ▬ 矩形 | `#52C41A` | 子流程引用节点 |
+
+### 特殊节点 (special)
+
+| 类型 | 名称 | 形状 | 颜色 | 说明 |
+|------|------|------|------|------|
+| `START` | 开始 | ● 圆形 | `#722ED1` | 流程起点（唯一，不可删除） |
+| `END` | 结束 | ● 圆形 | `#FF4D4F` | 流程终点（唯一，不可删除） |
+| `AND` | 聚合 | ● 圆形 | `#FAAD14` | 自动生成，不可手动操作 |
+
+---
+
+## 技术栈
+
+| 技术 | 版本 | 用途 |
+|------|------|------|
+| Vue 3 | ^3.5 | 前端框架 (Composition API) |
+| Vite | ^6.0 | 构建工具 + 组件库打包 |
+| ElementPlus | ^2.9 | UI 组件库 |
+| @logicflow/core | ^2.0 | 流程图画布核心引擎（内置 Preact） |
+| @logicflow/extension | ^2.0 | 扩展（Snapshot / MiniMap 等） |
+| dagre | ^0.8 | 自动布局算法（LR 层次布局，LogicFlow 内置） |
+| CodeMirror 6 | ^6.0 | 脚本编辑器 |
+| highlight.js | ^11.11 | DSL/XML 语法高亮 |
+
+---
+
+## 对外接口
+
+### Props
+
+| Prop | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `data` | `string \| object` | 否 | `null` | 流程 XML 字符串或 FlowModel 对象 |
+| `readonly` | `boolean` | 否 | `false` | 只读模式 |
+| `defaultLanguage` | `string` | 否 | `'java'` | 脚本默认语言 |
+
+### Events
+
+| Event | 参数 | 说明 |
+|-------|------|------|
+| `@save` | `(xml: string)` | 用户点击保存时触发，传出当前 XML |
+| `@change` | `(xml: string)` | 流程数据变更时触发，传出最新 XML |
+
+### Expose
+
+| 方法 | 返回值 | 说明 |
+|------|--------|------|
+| `getSnapshot()` | `Promise<string>` | 获取当前画布截图（base64 PNG） |
+
+---
+
+## 外部引用集成
+
+### 安装
+
+```bash
+npm install liteflow-designer
+```
+
+### 按需引入（推荐）
+
+```vue
+<template>
+  <DesignerPanel
+    ref="designerRef"
+    :data="flowXml"
+    :readonly="false"
+    @save="handleSave"
+    @change="handleChange"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+import { DesignerPanel } from 'liteflow-designer'
+import 'liteflow-designer/dist/style.css'
+
+const designerRef = ref(null)
+const flowXml = ref('<flow>...</flow>')
+
+function handleSave(xml) {
+  console.log('保存流程:', xml)
+}
+
+function handleChange(xml) {
+  console.log('变更:', xml)
+}
+
+async function exportImage() {
+  const base64 = await designerRef.value.getSnapshot()
+}
+</script>
+```
+
+### 全局注册
+
+```js
+import { createApp } from 'vue'
+import LiteFlowDesigner from 'liteflow-designer'
+import 'liteflow-designer/dist/style.css'
+
+const app = createApp(App)
+app.use(LiteFlowDesigner)       // 注册为 <lite-flow-designer />
+app.mount('#app')
+```
+
+### FlowModel / XML 数据模型
+
+```js
+import { FlowModel, xmlToFlowModel, flowModelToXML } from 'liteflow-designer'
+
+const model = xmlToFlowModel('<flow>...</flow>')
+const xml = flowModelToXML(model)
+```
+
+---
+
+## 项目结构
+
+```
+liteflow/
+├── index.html
+├── package.json
+├── vite.config.js
+├── README.md
+├── ARCHITECTURE.md                    # 详细架构设计文档
+│
+├── src/
+│   ├── main.js                        # 开发预览入口
+│   ├── index.js                       # 组件库对外导出
+│   ├── App.vue
+│   │
+│   ├── views/
+│   │   └── Designer.vue               # 本地开发预览页
+│   │
+│   ├── components/designer/           # 设计器组件包 ⭐
+│   │   ├── DesignerPanel.vue          # 对外顶层容器
+│   │   ├── TopToolbar.vue             # 顶部 XML 工具栏
+│   │   ├── SidePanel.vue              # 左侧脚本/链列表面板
+│   │   ├── FlowCanvas.vue             # 中央画布
+│   │   ├── CanvasToolbar.vue          # 画布悬浮工具栏（DSL/缩放/模拟）
+│   │   ├── PropsPanel.vue             # 右侧属性面板
+│   │   ├── SimulatePanel.vue          # 流程模拟浮动面板
+│   │   ├── InsertNodeDialog.vue       # 插入/追加节点弹窗
+│   │   ├── ScriptDialog.vue           # 脚本编辑弹窗
+│   │   ├── ScriptEditor.vue           # CodeMirror 编辑器
+│   │   ├── ChainDialog.vue            # 流程链编辑弹窗
+│   │   ├── nodes/                     # LogicFlow 自定义 Preact 节点/边
+│   │   │   ├── EdgePlusButton.jsx
+│   │   │   └── LiteFlow*Node.jsx
+│   │   ├── props/                     # 节点类型属性编辑子组件
+│   │   └── sub-keywords/              # 子关键字表单控件
+│   │
+│   ├── composables/
+│   │   ├── useFlowDesigner.js         # 画布核心逻辑
+│   │   └── useFlowManager.js          # XML/链/脚本管理
+│   │
+│   ├── config/
+│   │   ├── NodeEnum.js                # 节点类型枚举
+│   │   ├── KeywordEnum.js             # 子关键字枚举
+│   │   ├── EdgeEnum.js                # 边类型枚举
+│   │   └── nodes.js                   # 节点视觉配置
+│   │
+│   ├── core/
+│   │   ├── FlowData.js                # 单链图数据 + DSL/EL 转换
+│   │   ├── FlowModel.js               # XML 顶层数据模型
+│   │   ├── DSLParser.js / ELParser.js / XMLParser.js
+│   │   ├── Simulator.js               # 流程模拟引擎
+│   │   ├── ELNode.js                  # AST 转换管道（graph↔tree↔text）
+│   │   ├── FlowParserBase.js          # 解析共用工具
+│   │   ├── utils/                     # 画布辅助工具
+│   │   │   ├── containerUtils.js      # THEN/PRE/FINALLY 容器约束
+│   │   │   └── ifBranchUtils.js       # IF 分支边管理
+│   │   └── ast/                       # AST 节点类 + 子关键字注册表
+│   │
+│   ├── router/
+│   ├── styles/
+│   │   └── global.css
+│   └── views/
+│
+└── dist/                              # 构建产物
+    ├── liteflow-designer.es.js
+    ├── liteflow-designer.umd.js
+    └── style.css
+```
+
+---
+
+## 架构说明
+
+详细分层设计、数据流、AST 管道说明见 [ARCHITECTURE.md](./ARCHITECTURE.md)。
+
+**核心要点：**
+
+- **双模式**：开发预览应用 + 可发布组件库
+- **双数据模型**：对外 XML（FlowModel），链内 JSON 图（FlowData）
+- **连线驱动**：仅通过边线 `+` 追加节点
+- **Preact ↔ Vue**：LogicFlow 自定义组件用 JSX，经 eventCenter 通信
+
+---
+
+## 开发指南
+
+### 核心设计理念
+
+| 理念 | 说明 |
+|------|------|
+| **连线驱动** | 所有节点通过边线上的 `+` 按钮追加，禁止自由拖拽 |
+| **分支即聚合** | 分支节点创建时自动生成 AND 聚合节点，删除时递归清理 |
+| **内部封装** | FlowData 完全内部化，外部只需关心 XML / `@save` / `@change` |
+| **独立打包** | 整体可作为 Vue3 组件库被其他项目引用 |
+
+### 开发约定
+
+- **Preact ↔ Vue 通信**：LogicFlow 自定义节点/边用 Preact 编写（`.jsx`），通过 `eventCenter` 与 Vue 侧通信
+- **节点类型策略**：通过 `properties.nodeType` 区分业务类型，自定义视图在 `nodes/` 目录
+- **自动布局**：dagre（`rankdir: 'LR'`）计算坐标，防抖 300ms 自动触发
+- **状态注入**：`provideDesigner()` / `injectDesigner()` 向子组件注入画布状态
+
+### 添加新节点类型
+
+1. 在 [`src/config/NodeEnum.js`](src/config/NodeEnum.js) 添加类型常量
+2. 在 [`src/config/nodes.js`](src/config/nodes.js) 添加视觉配置
+3. 如需分支行为，更新 `BRANCH_NODE_TYPES` 等集合
+4. 在 [`src/components/designer/props/`](src/components/designer/props/) 添加属性编辑组件
+5. 在 [`src/core/ast/`](src/core/ast/) 添加 AST 节点类并 `ELNode.register()`
+
+### 手动测试
+
+1. **开发预览**：`npm run dev`，操作所有功能
+2. **构建验证**：`npm run build:lib`，在外部项目引用打包产物
+
+> 后续建议引入 **Vitest** + **@vue/test-utils** 进行组件单元测试。
+
+---
+
+## 构建打包
+
+### 组件库打包
+
+```bash
+npm run build:lib
+```
+
+| 文件 | 格式 | 说明 |
+|------|------|------|
+| `liteflow-designer.es.js` | ES Module | 支持 `import` 按需引入 |
+| `liteflow-designer.umd.js` | UMD | 支持 `<script>` 标签或 CommonJS |
+| `style.css` | CSS | 组件样式 |
+
+### External 依赖
+
+以下依赖设为 **external**，不打包进组件库，由使用方提供：
+
+`vue` · `element-plus` · `@logicflow/core` · `@logicflow/extension` · `preact` · `@codemirror/*`
+
+### 普通构建
+
+```bash
+npm run build
+npm run preview
+```
+
+---
+
+## 开发阶段
+
+| 阶段 | 内容 | 状态 |
+|------|------|------|
+| Phase 1 | 项目骨架：DesignerPanel 布局、FlowCanvas 封装、禁止拖拽 | ✅ |
+| Phase 2 | 边线 + 按钮：EdgePlusButton、InsertNodeDialog | ✅ |
+| Phase 3 | 节点删除重连、分支递归删除 + AND 管理 | ✅ |
+| Phase 4 | 自动布局：dagre LR 层次布局 | ✅ |
+| Phase 5 | FlowData + DSL/EL + XML 数据模型 | ✅ |
+| Phase 6 | 工具栏 + 属性面板 + 缩放 + getSnapshot | ✅ |
+| Phase 7 | 流程模拟：Simulator + SimulatePanel | ✅ |
+| Phase 8 | 组件打包：library mode | ✅ |
+| Phase 9 | PRE/FINALLY 容器 + IF 双分支 | ✅ |
+
+---
+
+## License
+
+[Apache-2.0](LICENSE)