@szjy/workflow 0.1.29 → 0.1.31

package/README.md

@@ -2,34 +2,299 @@
 
 [![Publish to NPM](https://github.com/szjy-work/workflow/actions/workflows/release.yml/badge.svg)](https://github.com/szjy-work/workflow/actions/workflows/release.yml)
 
-基于 vite + vue3 + typescript 的组件
+## 项目概述
 
+@szjy/workflow 是基于 Vue 3、TypeScript 和 BPMN.js 开发的工作流设计器组件库，提供了完整的工作流程设计、表单权限配置和电子签章管理能力。该组件库适用于需要实现业务流程设计与管理的企业应用系统，特别是在建筑信息化领域。
 
-## 使用
+## 目录结构
 
-先安装：
-```shell
-npm i @szjy/workflow
 ```
+workflow/
+├── examples/                # 示例代码
+│   ├── App.vue             # 示例应用
+│   └── ui/                 # 示例UI组件
+├── packages/
+│   ├── components/         # 核心组件
+│   │   ├── Hello/          # Hello组件(示例)
+│   │   └── Workflow/       # 工作流组件
+│   │       ├── activiti/   # Activiti引擎配置
+│   │       ├── biz-logic/  # 业务逻辑实现
+│   │       ├── components/ # 子组件
+│   │       ├── palette/    # 自定义画板
+│   │       ├── store/      # 状态管理
+│   │       └── utils/      # 工具函数
+│   └── i18n/               # 国际化资源
+│       ├── en_US/          # 英文
+│       └── zh_CN/          # 中文
+├── public/                 # 静态资源
+└── index.ts                # 入口文件
+```
+
+## 环境要求
+
+- Node.js >= 16
+- Vue 3
+- TypeScript >= 4.8
+- Vite >= 5.0.0
+
+## 安装
+
+```bash
+# npm
+npm install @szjy/workflow
 
-本地开发：
-```shell
-npm run dev
+# yarn
+yarn add @szjy/workflow
+
+# pnpm
+pnpm add @szjy/workflow
 ```
 
-然后在项目中引入：
+## 快速开始
+
+### 全局注册
 
 ```typescript
-import SWorkflow from '@szjy/workflow';
-import '@szjy/workflow/dist/style.css';
+// main.ts
+import { createApp } from 'vue'
+import App from './App.vue'
+import SWorkflow from '@szjy/workflow'
+import '@szjy/workflow/dist/style.css'
 
+const app = createApp(App)
 app.use(SWorkflow).mount('#app')
 ```
 
-这样就可以在项目中使用组件了：
+### 组件使用
+
+```vue
+<template>
+  <sz-workflow ref="workflowRef" @init="onInitWorkflow">
+    <!-- 自定义工具栏插槽 -->
+    <template #TOOLBAR_SUFFIX>
+      <button>导入模板</button>
+    </template>
+    
+    <!-- 自定义用户选择器插槽 -->
+    <template #USER_CHOOSER_SUFFIX="userProps">
+      <user-chooser :user-id="userProps.userId" :on-change="userProps.onChange"></user-chooser>
+    </template>
+  </sz-workflow>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+
+const workflowRef = ref()
+
+// 初始化回调
+const onInitWorkflow = (modeler) => {
+  console.log('工作流编辑器初始化完成', modeler)
+}
+
+// 获取工作流XML
+const getXml = async () => {
+  const xml = await workflowRef.value?.getWorkflowXml()
+  console.log(xml)
+}
+
+// 导入工作流XML
+const importXml = (xml) => {
+  workflowRef.value?.initXmlToStore(xml)
+}
+</script>
+```
+
+## 核心功能
+
+### 工作流设计器
+
+提供基于BPMN.js的可视化流程设计器，支持拖拽式流程设计。
+
+### 表单权限配置
+
+支持为工作流各节点配置表单字段的权限（编辑、只读、隐藏）。
+
+### 电子签章管理
+
+支持配置电子签章的位置、样式和触发条件。
+
+### 国际化支持
+
+内置中文和英文语言包，支持多语言配置。
+
+## API文档
+
+### 属性
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|-------|------|-------|------|
+| mode  | string | 'normal' | 工作流模式，可选值：'normal'(编辑模式)、'preview'(预览模式) |
+| height | string | '' | 工作流设计器高度，为空时自动计算 |
+
+### 事件
+
+| 事件名 | 参数 | 说明 |
+|-------|------|------|
+| init | modeler | 工作流编辑器初始化完成时触发 |
+
+### 方法
+
+| 方法名 | 参数 | 返回值 | 说明 |
+|-------|------|-------|------|
+| getWorkflowXml | - | Promise\<string\> | 获取当前工作流的XML定义 |
+| initXmlToStore | xml: string | Promise\<void\> | 导入工作流XML定义 |
+| updateProcessId | processId: string | void | 更新流程ID |
+| getPermissionJSON | - | PermissionJSONLike | 获取表单权限配置 |
+| setPermissionByFields | permissonJSON: PermissionJSONLike, fields: FieldItemType[] | void | 设置表单权限配置 |
+| updatePermFields | fields: FieldItemType[] | void | 更新表单字段列表 |
+| getEsignJSON | - | EsignJSONLike | 获取电子签章配置 |
+| setEsignConfig | esignJSON: EsignJSONLike | void | 设置电子签章配置 |
+
+### 插槽
+
+| 插槽名 | 参数 | 说明 |
+|-------|------|------|
+| TOOLBAR_PREFIX | - | 工具栏前置内容 |
+| TOOLBAR_SUFFIX | - | 工具栏后置内容 |
+| USER_CHOOSER_SUFFIX | { userId, onChange } | 用户选择器自定义渲染 |
+| FORMID_CHOOSER_SUFFIX | { formFieldId, onChange } | 表单字段选择器自定义渲染 |
+
+## 工作流架构
+
+```mermaid
+flowchart TD
+  A[工作流组件] --> B[BPMN编辑器]
+  A --> C[属性面板]
+  A --> D[工具栏]
+  
+  B --> E[Activiti引擎]
+  B --> F[自定义画板]
+  
+  C --> G[节点属性]
+  C --> H[表单权限]
+  C --> I[电子签章]
+  
+  G --> J[基础属性]
+  G --> K[监听器]
+  
+  H --> L[字段权限]
+  H --> M[条件配置]
+  
+  D --> N[保存/导出]
+  D --> O[放大/缩小]
+  D --> P[对齐工具]
+```
+
+## 使用示例
+
+### 基础工作流设计
+
+```vue
+<template>
+  <sz-workflow ref="workflowRef"></sz-workflow>
+  <button @click="saveWorkflow">保存流程</button>
+</template>
 
-```html
-<sz-workflow></sz-workflow>
+<script setup>
+import { ref } from 'vue'
+
+const workflowRef = ref()
+
+const saveWorkflow = async () => {
+  const xml = await workflowRef.value?.getWorkflowXml()
+  console.log('流程定义XML:', xml)
+  // 保存到服务器的代码
+}
+</script>
 ```
 
+### 表单权限配置
+
+```typescript
+// 字段列表
+const fields = [
+  { id: 'field1', name: '姓名' },
+  { id: 'field2', name: '部门' },
+  { id: 'field3', name: '职位' }
+]
+
+// 权限配置
+const permissions = {
+  createFieldPermission: {
+    assigneeFieldPermissionMap: [
+      { key: 'field1', fieldId: 'field1', fieldName: '姓名', permission: 'EDITABLE' },
+      { key: 'field2', fieldId: 'field2', fieldName: '部门', permission: 'EDITABLE' },
+      { key: 'field3', fieldId: 'field3', fieldName: '职位', permission: 'EDITABLE' }
+    ],
+    othersFieldPermissionMap: [
+      { key: 'field1', fieldId: 'field1', fieldName: '姓名', permission: 'ALL_READ_ONLY' },
+      { key: 'field2', fieldId: 'field2', fieldName: '部门', permission: 'ALL_READ_ONLY' },
+      { key: 'field3', fieldId: 'field3', fieldName: '职位', permission: 'HIDDEN' }
+    ]
+  },
+  taskToFieldPermissionMap: {
+    'Activity_1': {
+      assigneeFieldPermissionMap: [
+        { key: 'field1', fieldId: 'field1', fieldName: '姓名', permission: 'EDITABLE' }
+      ],
+      othersFieldPermissionMap: [
+        { key: 'field1', fieldId: 'field1', fieldName: '姓名', permission: 'ALL_READ_ONLY' }
+      ]
+    }
+  }
+}
+
+// 设置权限
+workflowRef.value?.setPermissionByFields(permissions, fields)
+```
+
+## 项目开发
+
+### 本地开发
+
+```bash
+# 安装依赖
+pnpm install
+
+# 启动开发服务器
+pnpm dev
+
+# 构建
+pnpm build
+
+# 发布
+pnpm release
+```
+
+### 代码规范
+
+项目使用 TypeScript 强类型检查，请确保所有代码通过类型检查。
+
+### 提交流程
+
+使用 commit-and-tag-version 进行版本管理，提交前请确保代码已通过测试。
+
+## 常见问题
+
+### Q: 为什么工作流编辑器无法保存？
+
+A: 请检查是否调用了 `getWorkflowXml()` 方法获取XML内容，该方法返回Promise，需要使用 `await` 或 `.then()` 处理。
+
+### Q: 如何自定义节点图标？
+
+A: 可以通过扩展 BPMN.js 的 PaletteProvider 来添加自定义节点。具体可参考 `packages/components/Workflow/palette/` 下的实现。
+
+### Q: 如何处理表单权限与后端的交互？
+
+A: 可通过 `getPermissionJSON()` 获取权限配置JSON，然后发送至后端保存。加载时通过 `setPermissionByFields()` 方法恢复配置。
+
+## 参考文档
+
+1. [BPMN.js 官方文档](https://bpmn.io/toolkit/bpmn-js/)
+2. [Vue 3 组件开发指南](https://v3.vuejs.org/guide/component-basics.html)
+3. [Activiti 工作流引擎文档](https://www.activiti.org/documentation)
+4. [Vue 3 组合式 API 参考](https://v3.vuejs.org/api/composition-api.html)
+5. [Vite 构建工具文档](https://vitejs.dev/guide/)
+