@leadal/flowstream-ui-plus 0.0.1

package/docs//346/216/245/345/205/245/346/226/207/346/241/243.md

@@ -0,0 +1,265 @@
+# FlowStream UI Plus 接入文档
+
+`@leadal/flowstream-ui-plus` 提供 FlowStream 业务工程需要的 Vue 3 运行时组件。流程设计与编辑由工作流程引擎内部完成，组件库不导出 Editor。
+
+## 1. 环境要求
+
+- Node.js `>= 18`
+- pnpm `>= 8`
+- Vue `>= 3.4`
+- Element Plus `>= 2.8`
+
+```bash
+pnpm add @leadal/flowstream-ui-plus vue element-plus
+```
+
+## 2. 本地 link
+
+```bash
+cd workflow-components-vue3
+pnpm run build
+pnpm link --global
+
+cd /path/to/components-demo-vue3-web
+pnpm link --global @leadal/flowstream-ui-plus
+```
+
+重新修改组件库后需要再次执行 `pnpm run build`；如果开发服务器没有感知 link 包变化，请重启开发服务器。
+
+## 3. 公共组件清单
+
+只公开以下 5 个主组件和 1 个子组件：
+
+| 按需导出名 | 全局标签 | 说明 |
+| --- | --- | --- |
+| `FlowButtons` | `ui-flow-buttons` | 流程操作按钮组 |
+| `FlowButton` | `ui-flow-button` | 单个流程按钮，作为按钮组子组件使用 |
+| `FlowDiagram` | `ui-flow-diagram` | BPMN 流程图和办理轨迹 |
+| `FlowSend` | `ui-flow-send` | 发送任务 |
+| `FlowJump` | `ui-flow-jump` | 跳转任务 |
+| `FlowGrid` | `ui-flow-grid` | 待办、已办、草稿统一列表 |
+
+`SvgIcon`、轨迹表格、基础表格等仍可作为上述组件的内部实现，但不属于公共导出。
+
+## 4. 全量注册
+
+```ts
+import { createApp } from 'vue'
+import ElementPlus from 'element-plus'
+import 'element-plus/dist/index.css'
+import FlowstreamUIPlus from '@leadal/flowstream-ui-plus'
+import '@leadal/flowstream-ui-plus/style.css'
+import App from './App.vue'
+
+const app = createApp(App)
+
+app.use(ElementPlus)
+app.use(FlowstreamUIPlus, {
+  baseURL: import.meta.env.VITE_FLOWSTREAM_ORIGIN,
+  timeout: 60_000,
+  getToken: () => localStorage.getItem('access_token') || undefined,
+})
+
+app.mount('#app')
+```
+
+`baseURL` 是接口前缀。传入地址时组件库会按原值使用（仅移除末尾 `/`）：
+
+- 留空：生产构建不添加前缀；测试/开发源码模式默认添加 `/api`。
+- `/api`：显式使用测试环境代理。通过 npm/pnpm link 消费构建产物时，应使用这种配置。
+- `http://127.0.0.1:19090`：直连 FlowStream，最终请求为 `http://127.0.0.1:19090/flowstream/...`。
+- `https://example.com/api`：使用已有 `/api` 网关前缀。
+
+本地前端代理应将 `/api` 转发到 FlowStream 服务，并移除 `/api` 前缀。
+
+## 5. 按需注册
+
+```ts
+import {
+  FlowButton,
+  FlowButtons,
+  FlowDiagram,
+  FlowGrid,
+  FlowJump,
+  FlowSend,
+  configureWorkflow,
+} from '@leadal/flowstream-ui-plus'
+import '@leadal/flowstream-ui-plus/style.css'
+
+configureWorkflow({
+  baseURL: import.meta.env.VITE_FLOWSTREAM_ORIGIN,
+  getToken: () => localStorage.getItem('access_token') || undefined,
+})
+```
+
+## 6. ui-flow-grid
+
+`type` 为必传属性，支持：
+
+- `todo`：待办，操作事件的 `action` 为 `view`。
+- `done`：已办，操作事件的 `action` 为 `handle`。
+- `draft`：草稿，操作事件的 `action` 为 `view`；调用 `create()` 时为 `create`。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { FlowGrid } from '@leadal/flowstream-ui-plus'
+
+const gridRef = ref<InstanceType<typeof FlowGrid>>()
+
+function createDraft() {
+  gridRef.value?.create({
+    name: '请假流程',
+    processDefinitionId: 'Process_leave:1:xxxx',
+  })
+}
+
+function handleWork(payload: {
+  action: 'view' | 'handle' | 'create'
+  workData: Record<string, unknown>
+}) {
+  console.log(payload)
+}
+</script>
+
+<template>
+  <div class="flow-grid-page">
+    <ui-flow-grid
+      ref="gridRef"
+      type="draft"
+      :deal-user-id="currentUserId"
+      :app-id="appId"
+      :app-module-id="appModuleId"
+      @on-handle="handleWork"
+      @error="console.error"
+    />
+  </div>
+</template>
+
+<style scoped>
+.flow-grid-page { height: 100%; min-height: 500px; }
+</style>
+```
+
+实例公开 `loadTableData()`、`create(flow)`、`data`、`loading` 和 `pageConfig`。
+
+## 7. ui-flow-diagram
+
+父容器必须设置明确高度。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { FlowDiagram } from '@leadal/flowstream-ui-plus'
+
+const diagramRef = ref<InstanceType<typeof FlowDiagram>>()
+</script>
+
+<template>
+  <div style="height: 700px">
+    <ui-flow-diagram
+      ref="diagramRef"
+      :process-definition-id="processDefinitionId"
+      :process-instance-id="processInstanceId"
+      @loaded="handleLoaded"
+      @error="handleError"
+    />
+  </div>
+</template>
+```
+
+调用 `diagramRef.value?.refresh()` 可以刷新流程图和办理轨迹。
+
+## 8. ui-flow-buttons 与 ui-flow-button
+
+`FlowButtons` 根据 `workId` 请求当前可用操作。发送、保存、启动和跳转等需要业务页面参与的动作通过 `execute-action` 交给宿主处理，其中发送动作名为 `taskSend`。
+
+```vue
+<ui-flow-buttons
+  :work-id="task.workId"
+  :process-instance-id="task.processInstanceId"
+  :before-action="validateBeforeAction"
+  :after-action="reloadAfterAction"
+  @after-action="handleAfterAction"
+  @execute-action="handleAction"
+  @error="handleError"
+/>
+```
+
+内部操作（如办毕、退回、撤回、收回、挂起、恢复和终止）成功后会触发 `after-action(action, result)`；也兼容 `afterAction` 函数型 prop。宿主可在该事件中提示成功并刷新列表。
+
+单按钮子组件可按需使用：
+
+```vue
+<ui-flow-button type="save" @click="saveForm" />
+```
+
+## 9. ui-flow-send
+
+`FlowSend` 是完整的发送办理组件，内置下一环节解析、办理人选择、流程变量、审批意见和确认发送弹窗。直接使用时点击组件按钮即可打开；与 `FlowButtons` 配合时可隐藏自身按钮，由 `taskSend` 操作调用实例的 `open()`。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { FlowSend } from '@leadal/flowstream-ui-plus'
+
+const sendVisible = ref(false)
+
+function handleAction(action: string) {
+  if (action === 'taskSend') sendVisible.value = true
+}
+</script>
+
+<template>
+  <ui-flow-send
+    v-model="sendVisible"
+    :process-definition-id="task.processDefinitionId"
+    :process-instance-id="task.processInstanceId"
+    :activity="task"
+    :work-id="task.workId"
+    :deal-user="currentUser"
+    :show-trigger="false"
+    :variables="variables"
+    @before-send="handleBeforeSend"
+    @after-send="handleAfterSend"
+    @error="handleError"
+  />
+</template>
+```
+
+推荐通过 `v-model` 控制弹窗，避免宿主依赖组件实例；实例仍公开 `open()`、`close()`、`getNextNode()`、`assembleData()` 和 `send()`。组件请求 `nodeAssistant` 加载下一节点候选人，并在确认时直接提交 `/flowstream/server/task/event/send`。
+
+## 10. ui-flow-jump
+
+`FlowJump` 内置“开始节点 + 办理人”选择弹窗。办理人支持组织树懒加载；如果节点没有配置办理人，组件会回填当前用户。跳转不编辑业务变量，请求中固定提交 `variables: {}`。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { FlowJump } from '@leadal/flowstream-ui-plus'
+
+const jumpVisible = ref(false)
+</script>
+
+<template>
+  <ui-flow-jump
+    v-model="jumpVisible"
+    :process-definition-id="task.processDefinitionId"
+    :process-instance-id="task.processInstanceId"
+    :work-id="task.workId"
+    :deal-user="{ id: currentUserId, name: currentUserName }"
+    :show-trigger="false"
+    @before-jump="handleBeforeJump"
+    @after-jump="handleAfterJump"
+    @error="handleError"
+  />
+</template>
+```
+
+`showTrigger` 默认是 `true`，此时组件自身显示“跳转”按钮并负责打开弹窗；与 `FlowButtons` 配合时设为 `false`，在按钮组触发 `taskJump`/`jump` 后执行 `jumpVisible.value = true`。实例同时公开 `open()`、`close()`、`getStartNodes()`、`assembleData()` 和 `jump()`。
+
+## 11. 错误处理
+
+组件请求只将服务端 `code` 为 `0` 或 `200` 的响应视为成功。建议统一监听 `error` 事件，并在入口通过 `getToken` 配置认证信息。
+
+流程图空白时，优先检查父容器高度、流程定义 ID、流程实例 ID 以及 BPMN 下载接口。

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@leadal/flowstream-ui-plus",
+  "version": "0.0.1",
+  "description": "FlowStream workflow components for Vue 3",
+  "type": "module",
+  "main": "dist/flowstream-ui-plus.umd.cjs",
+  "module": "dist/flowstream-ui-plus.js",
+  "types": "dist/index.d.ts",
+  "style": "dist/style.css",
+  "files": [
+    "dist",
+    "README.md",
+    "docs"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/flowstream-ui-plus.js",
+      "require": "./dist/flowstream-ui-plus.umd.cjs"
+    },
+    "./style.css": "./dist/style.css"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "vue-tsc --noEmit && vite build",
+    "typecheck": "vue-tsc --noEmit",
+    "pack:lib": "pnpm run build && pnpm pack"
+  },
+  "peerDependencies": {
+    "element-plus": "^2.8.0",
+    "vue": "^3.4.0"
+  },
+  "dependencies": {
+    "@leadal/netiler-ui3-plus": "^0.0.5",
+    "axios": "^1.9.0",
+    "bpmn-js": "^18.6.2",
+    "camunda-bpmn-moddle": "^7.0.1",
+    "dayjs": "^1.11.13",
+    "diagram-js": "^15.23.2"
+  },
+  "devDependencies": {
+    "@element-plus/icons-vue": "^2.3.1",
+    "@types/node": "^22.10.0",
+    "@vitejs/plugin-vue": "^5.2.0",
+    "element-plus": "^2.8.0",
+    "sass": "^1.83.0",
+    "typescript": "^5.7.0",
+    "vite": "^6.0.0",
+    "vite-plugin-dts": "^4.5.0",
+    "vue": "^3.5.0",
+    "vue-tsc": "^2.2.0"
+  },
+  "engines": {
+    "node": ">=18",
+    "pnpm": ">=8"
+  },
+  "license": "UNLICENSED"
+}