hn-workflow-components 1.0.4 → 1.0.5

package/README.md

@@ -1 +1,259 @@
-# Simple Workflow
+# hn-workflow-components
+
+一个基于 React + TypeScript 的可视化工作流编排组件库，提供工作流编辑器与执行进度查看器两种模式。
+
+[![React](https://img.shields.io/badge/React-%5E17.0.0%20%7C%20%5E18.0.0-blue)](https://react.dev/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-%5E5.7.0-blue)](https://www.typescriptlang.org/)
+[![License](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)
+
+---
+
+## ✨ 功能特性
+
+- 🎨 **可视化编排** — 拖拽式节点编辑，支持画布缩放与拖拽浏览
+- 🔄 **撤销/重做** — 完整的操作历史栈（undo/redo）
+- 🌲 **分支支持** — 条件分支、并行分支、包容分支三种分支类型
+- 📊 **执行追踪** — 独立的进度查看器，支持节点状态着色与图例
+- 🧩 **物料扩展** — 可自定义节点类型、属性面板与校验规则
+- 🎭 **主题适配** — 支持 Ant Design 主题 token 注入与暗黑模式
+- 📱 **响应式画布** — 自适应缩放，支持鼠标拖拽平移
+
+---
+
+## 📦 安装
+
+```bash
+npm install hn-workflow-components
+# 或
+yarn add hn-workflow-components
+# 或
+pnpm add hn-workflow-components
+```
+
+### 对等依赖
+
+请确保项目中已安装以下依赖：
+
+```bash
+npm install react react-dom antd styled-components @ant-design/icons
+```
+
+> React 版本要求：>=17 <19
+
+---
+
+## 🚀 快速开始
+
+### 1. 工作流编辑器
+
+用于设计流程图，支持节点增删改、分支配置与保存发布。
+
+```tsx
+import { WorkflowComponents } from 'hn-workflow-components'
+
+function App() {
+  return (
+    <WorkflowComponents
+      processKey="leave-approval"
+      processName="请假审批流程"
+      baseUrl="https://api.example.com"
+      customHeaders={{
+        Authorization: 'Bearer xxx',
+      }}
+    />
+  )
+}
+```
+
+### 2. 工作流查看器
+
+用于展示流程执行进度，节点按状态着色。
+
+```tsx
+import { WorkflowViewerComponents } from 'hn-workflow-components'
+
+function App() {
+  return (
+    <WorkflowViewerComponents
+      processKey="instance-123"
+      baseUrl="https://api.example.com"
+      statusColors={{
+        completed: '#52c41a',
+        processing: '#faad14',
+        pending: '#d9d9d9',
+      }}
+    />
+  )
+}
+```
+
+---
+
+## 📖 API 文档
+
+### WorkflowComponents（编辑器）
+
+| 属性 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `processKey` | `string` | ✅ | 流程定义唯一标识 |
+| `processName` | `string` | ✅ | 流程显示名称 |
+| `baseUrl` | `string` | ✅ | 后端 API 基础地址 |
+| `customHeaders` | `Record<string, string>` | ❌ | 自定义请求头 |
+
+### WorkflowViewerComponents（查看器）
+
+| 属性 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `processKey` | `string` | ✅ | 流程实例标识（用于查询执行状态） |
+| `baseUrl` | `string` | ✅ | 后端 API 基础地址 |
+| `customHeaders` | `Record<string, string>` | ❌ | 自定义请求头 |
+| `statusColors` | `StatusColors` | ❌ | 自定义状态颜色 |
+
+### StatusColors
+
+```ts
+interface StatusColors {
+  completed?: string   // 已处理（默认 #52c41a）
+  processing?: string  // 处理中（默认 #faad14）
+  pending?: string     // 待处理（默认 #d9d9d9）
+}
+```
+
+---
+
+## 🧩 内置节点类型
+
+| 节点类型 | 说明 | 在物料板显示 |
+|----------|------|--------------|
+| `start` | 发起人节点 | ❌ |
+| `approver` | 审批人 | ✅ |
+| `notifier` | 抄送人 | ✅ |
+| `exclusive` | 条件分支 | ✅ |
+| `parallel` | 并行分支 | ✅ |
+| `inclusive` | 包容分支 | ❌ |
+| `subProcess` | 子流程 | ✅ |
+| `dispatcher` | 分发节点 | ✅ |
+| `message` | 消息通知 | ❌ |
+| `service` | 服务节点 | ❌ |
+| `asyncSubProcess` | 异步子流程 | ❌ |
+| `trigger` | 触发器 | ❌ |
+
+---
+
+## 🏗️ 自定义物料与 UI
+
+如需自定义节点内容或属性面板，可通过 `materialUis` 传入：
+
+```tsx
+import type { IMaterialUIs } from 'hn-workflow-components'
+
+const myMaterialUis: IMaterialUIs = {
+  approver: {
+    // 节点卡片内容渲染
+    viewContent: (node) => (
+      <div>{node.config?.approverType === 'countersign' ? '会签' : '或签'}</div>
+    ),
+    // 校验规则
+    validate: (node, { t }) => {
+      if (!node.config?.groupType) {
+        return t('请选择审批人')
+      }
+      return true
+    },
+  },
+}
+
+// 在业务层封装中使用
+<WorkflowComponents
+  processKey="xxx"
+  processName="xxx"
+  baseUrl="xxx"
+/>
+```
+
+---
+
+## 🔌 后端接口约定
+
+组件库内置调用以下接口，请确保后端按约定实现：
+
+| 接口 | 方法 | 路径 | 说明 |
+|------|------|------|------|
+| 查询用户与角色 | POST | `/bpmn/approval/action/queryUserAndRoleData` | 获取可选审批人数据 |
+| 获取流程定义 | POST | `/bpmn/json/getBpmnJson` | 根据 processKey 获取 JSON 流程图 |
+| 获取执行状态 | POST | `/bpmn/process/queryBpmnJsonAndNodeStatus` | 获取节点执行状态 |
+| 获取业务表单字段 | POST | `/bpmn/json/bizForm` | 用于条件配置 |
+| 保存流程图 | POST | `/bpmn/json/saveBpmnJson` | 保存 JSON 流程定义 |
+| 发布流程图 | POST | `/bpmn/json/bpmnJsonToXml` | 转换为 XML 并发布 |
+| 查询版本历史 | POST | `/bpmn/json/queryBpmnJsonVersion` | 获取历史版本 |
+
+---
+
+## 🛠️ 本地开发
+
+```bash
+# 克隆仓库
+git clone <repo-url>
+cd simple-workflow
+
+# 安装依赖
+pnpm install
+
+# 启动开发服务器
+pnpm dev
+
+# 构建库
+pnpm build:lib
+
+# ESLint 检查
+pnpm lint
+```
+
+---
+
+## 📁 目录结构
+
+```
+src/
+├── core/workflow-editor/    # 核心编辑器引擎
+│   ├── classes/             # EditorEngine 状态管理类
+│   ├── components/          # 通用 UI 组件（工具栏、表达式输入等）
+│   ├── FlowEditor/          # 编辑器画布、物料板、设置面板
+│   ├── ProgressViewer/      # 只读进度查看器
+│   ├── nodes/               # 节点渲染组件（普通节点、分支节点等）
+│   ├── interfaces/          # TypeScript 类型定义
+│   ├── reducers/            # Redux 状态切片
+│   ├── hooks/               # React Hooks
+│   └── utils/               # 工具函数（API、UUID、颜色等）
+├── demo/                    # 业务层封装（可直接使用的高阶组件）
+│   ├── WorkflowEditor/      # 编辑器业务封装
+│   ├── WorkflowViwer/       # 查看器业务封装
+│   └── ShellContainer.tsx   # 外壳容器
+├── index.ts                 # 库入口，导出 WorkflowComponents / WorkflowViewerComponents
+└── App.tsx / main.tsx       # 本地调试入口
+```
+
+---
+
+## ⚠️ 已知限制
+
+- 当前仅支持 React 17/18，尚未适配 React 19
+- 全局配置（`baseUrl`、`headers`）通过模块级变量存储，多实例场景下可能互相影响
+- 分支节点标题硬编码截取前两个字符（如"添加条件分支" → "条件分支"），需确保 `getRouteNodeName` 返回格式一致
+- 进度查看器尚未实现路由节点（`exclusive`/`parallel`/`inclusive`）的状态徽章展示
+
+---
+
+## 🤝 贡献
+
+欢迎提交 Issue 与 PR。提交前请确保：
+
+1. 代码通过 `pnpm lint` 检查
+2. 保持与现有代码风格一致
+3. 如涉及 UI 变动，请在 PR 中附截图
+
+---
+
+## 📄 License
+
+[MIT](./LICENSE)