@leadal/flowstream-ui-plus 0.0.1 → 0.0.3

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

@@ -28,7 +28,7 @@ pnpm link --global @leadal/flowstream-ui-plus
 
 ## 3. 公共组件清单
 
-只公开以下 5 个主组件和 1 个子组件：
+公开以下流程组件：
 
 | 按需导出名 | 全局标签 | 说明 |
 | --- | --- | --- |
@@ -45,15 +45,12 @@ pnpm link --global @leadal/flowstream-ui-plus
 
 ```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,
@@ -63,6 +60,8 @@ app.use(FlowstreamUIPlus, {
 app.mount('#app')
 ```
 
+流程组件使用的 Element Plus 控件及样式由组件库统一注册和携带，业务项目无需额外执行 `app.use(ElementPlus)`。
+
 `baseURL` 是接口前缀。传入地址时组件库会按原值使用（仅移除末尾 `/`）：
 
 - 留空：生产构建不添加前缀；测试/开发源码模式默认添加 `/api`。
@@ -172,12 +171,15 @@ const diagramRef = ref<InstanceType<typeof FlowDiagram>>()
 
 ## 8. ui-flow-buttons 与 ui-flow-button
 
-`FlowButtons` 根据 `workId` 请求当前可用操作。发送、保存、启动和跳转等需要业务页面参与的动作通过 `execute-action` 交给宿主处理，其中发送动作名为 `taskSend`。
+`FlowButtons` 根据当前工作项请求可用操作。可直接传 `workId`；如果业务详情只有流程实例，则传 `processInstanceId + dealUserId`，组件会自行查询该用户在该实例中的待办。发送和跳转默认在组件内部打开完整弹窗；保存、启动等业务表单相关动作通过 `execute-action` 交给宿主处理。任务拾取在传入 `dealUserId` 后由组件完成；前/后加签内置机构人员单选弹窗，`taskId` 可显式传入或由待办自动解析。
 
 ```vue
 <ui-flow-buttons
-  :work-id="task.workId"
   :process-instance-id="task.processInstanceId"
+  :process-definition-id="task.processDefinitionId"
+  :deal-user-id="loginUser.id"
+  :deal-user-name="loginUser.name"
+  force-single-assignee
   :before-action="validateBeforeAction"
   :after-action="reloadAfterAction"
   @after-action="handleAfterAction"
@@ -186,7 +188,7 @@ const diagramRef = ref<InstanceType<typeof FlowDiagram>>()
 />
 ```
 
-内部操作（如办毕、退回、撤回、收回、挂起、恢复和终止）成功后会触发 `after-action(action, result)`；也兼容 `afterAction` 函数型 prop。宿主可在该事件中提示成功并刷新列表。
+流程操作成功后会触发 `after-action(action, result, context)`；也兼容 `afterAction` 函数型 prop。`context` 包含当前待办字段，发送和跳转完成后还包含实际请求数据 `requestData`，宿主可据此同步业务状态并刷新列表。加签人员树只允许选择 `ntype=user` 的机构人员，部门节点仅用于展开。
 
 单按钮子组件可按需使用：
 
@@ -196,7 +198,7 @@ const diagramRef = ref<InstanceType<typeof FlowDiagram>>()
 
 ## 9. ui-flow-send
 
-`FlowSend` 是完整的发送办理组件，内置下一环节解析、办理人选择、流程变量、审批意见和确认发送弹窗。直接使用时点击组件按钮即可打开；与 `FlowButtons` 配合时可隐藏自身按钮，由 `taskSend` 操作调用实例的 `open()`。
+`FlowSend` 是完整的发送办理组件，内置下一环节解析、办理人选择、流程变量、审批意见和确认发送弹窗。`FlowButtons` 已默认集成该弹窗；只有需要自定义编排时，才单独使用 FlowSend，并给 FlowButtons 设置 `:auto-handle-dialogs="false"`。
 
 ```vue
 <script setup lang="ts">
@@ -227,7 +229,7 @@ function handleAction(action: string) {
 </template>
 ```
 
-推荐通过 `v-model` 控制弹窗，避免宿主依赖组件实例；实例仍公开 `open()`、`close()`、`getNextNode()`、`assembleData()` 和 `send()`。组件请求 `nodeAssistant` 加载下一节点候选人，并在确认时直接提交 `/flowstream/server/task/event/send`。
+推荐通过 `v-model` 控制弹窗，避免宿主依赖组件实例；实例仍公开 `open()`、`close()`、`getNextNode()`、`assembleData()` 和 `send()`。组件通过 `nodeAssistant` 请求 `POST /flowstream/server/assignment/event/query` 加载下一节点候选人，并在确认时直接提交 `/flowstream/server/task/event/send`。
 
 ## 10. ui-flow-jump
 
@@ -263,3 +265,111 @@ const jumpVisible = ref(false)
 组件请求只将服务端 `code` 为 `0` 或 `200` 的响应视为成功。建议统一监听 `error` 事件，并在入口通过 `getToken` 配置认证信息。
 
 流程图空白时，优先检查父容器高度、流程定义 ID、流程实例 ID 以及 BPMN 下载接口。
+
+## 12. 获取第一个办理节点
+
+已知流程定义 ID 时，查询第一个人工办理节点：
+
+```ts
+import { getFirstHandleNodes } from '@leadal/flowstream-ui-plus'
+
+const result = await getFirstHandleNodes({
+  processDefinitionId,
+})
+const firstHandleNodes = result.data || []
+```
+
+- 接口为 `POST /flowstream/server/model/event/get/firsthandle`。
+- 返回的是跳过 StartEvent、网关和中间事件后，各分支上第一个 `USER_TASK` 的集合，可能有多个。
+- 纯自动流程返回 `data: []`，不是错误。
+- `flowStartNodeList(args)` 作为兼容别名保留并调用新接口。`startNodes(args)` 仍用于跳转组件查询全部用户任务，不受本次变更影响。
+
+## 13. 命令式流程发起服务
+
+业务项目不再放置 `FlowStart`，提交业务数据后调用默认导出的运行时服务：
+
+```ts
+import flowstream from '@leadal/flowstream-ui-plus'
+
+async function submit() {
+  const result = await flowstream.getRuntimeService().start({
+    processDefinitionId,
+    draftUserId: currentUser.id,
+    draftUserName: currentUser.name,
+    business: { key: businessId, name: businessName },
+    variables,
+    async onBeforeStart(startArgs) {
+      const formData = await openBusinessForm()
+      if (!formData) return false
+      startArgs.variables = { ...startArgs.variables, ...formData }
+      return true
+    },
+    async onBeforeSend(context) {
+      return validateBeforeSend(context)
+    },
+    onStarted(result) {
+      saveFlowRelation(result.processInstanceId)
+    },
+    onAfterSend({ sendData }) {
+      syncNextAssignee(sendData.flowNodeAssignees)
+      refreshBusinessList()
+    },
+    onClose() {
+      console.log('发送弹窗已关闭；未发送时流程实例会被撤销')
+    },
+    onError(error) {
+      console.error(error.phase, error.message)
+    },
+  })
+  if (result === false) return
+}
+```
+
+- `onBeforeStart(args)` 在任何流程查询和启动接口之前执行，支持 `boolean | Promise<boolean>`；返回 `false` 时不会创建流程实例，`start()` 返回 `false`。
+- `start()` 通过启动校验后，内部依次完成首办节点解析、`quickStart`、发送弹窗初始化、下一节点和候选办理人查询。
+- `onBeforeSend(context)` 在实例创建成功后、审批人选择弹窗打开前执行，也支持 Promise；返回 `false` 时保留流程实例和当前会话，但不打开弹窗。
+- 条件稍后满足时调用 `await flowstream.getRuntimeService().open()`，组件会重新执行 `onBeforeSend`；决定放弃时调用 `close()` 撤销实例并释放会话。
+- 调用成功后直接打开选择弹窗，业务模板不需要挂载隐藏组件。
+- 候选办理人可以有多个；`singleAssignee` 默认开启，每个下一节点只能选择一人。
+- 用户确认后由内部发送组件调用 `sendTask()`；`onAfterSend` 参数中的 `sendData.flowNodeAssignees` 是实际发送的下一节点和办理人。
+- 用户未发送就关闭弹窗时会撤销刚创建的流程实例并释放会话；只有 `onBeforeSend` 返回 `false`、弹窗尚未打开时，才能调用 `open()` 在条件满足后继续。
+- `processDefinitionId`、`draftUserId`、`draftUserName` 均为必填；快速启动不支持多个首办节点或多个起草人待办。
+
+业务表单弹窗应由接入项目实现，并将用户操作转换为 Promise：确认且校验成功时 `resolve(true)`，取消、关闭或组件卸载时 `resolve(false)`。不要只修改一个响应式布尔变量而不结束 Promise，否则 `start()` 会一直等待。
+
+## 14. 获取应用与流程
+
+业务页面需要「选应用 → 选流程 → 发起」级联场景时，可查询应用列表和流程定义列表。
+
+方式一：函数式调用（`flowApi` 已聚合全部接口，也可直接导入单个函数）：
+
+```ts
+import { flowApi } from '@leadal/flowstream-ui-plus'
+
+// 获取应用列表
+const apps = (await flowApi.getAppList()).data || []
+
+// 获取流程定义列表（可按应用过滤）
+const flows = (await flowApi.getFlowList({ appId })).data || []
+```
+
+方式二：`runtimeService` 便捷方法（已自动解包 `data`）：
+
+```ts
+import flowstream from '@leadal/flowstream-ui-plus'
+
+const apps = await flowstream.getRuntimeService().getApps()
+const flows = await flowstream.getRuntimeService().getFlows({ appId })
+```
+
+典型级联发起示例：
+
+```vue
+<ui-select v-model="appId" :options="apps" label-key="name" value-key="id" @change="loadFlows" />
+<ui-select v-model="processDefinitionId" :options="flows" label-key="name" value-key="id" />
+<ui-button @click="submit">发起流程</ui-button>
+```
+
+- 接口约定（路径待后端确认）：`POST /flowstream/server/repository/app/event/list`、`POST /flowstream/server/repository/flowdef/event/list`。
+- `FlowApp`、`FlowDefinition` 类型已从库中导出，字段以后端实际返回为准。
+- 拿到流程定义后，将 `flow.id` 作为 `processDefinitionId` 传给 `runtimeService.start()` 即可完成发起。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leadal/flowstream-ui-plus",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "FlowStream workflow components for Vue 3",
   "type": "module",
   "main": "dist/flowstream-ui-plus.umd.cjs",