@leadal/flowstream-ui-plus 0.0.2 → 0.0.4

package/README.md

@@ -146,6 +146,7 @@ configureWorkflow({
 | `dealUserId`          | 当前用户 ID；自动解析待办和拾取任务时使用        | `string`                                          | 条件 | —      |
 | `dealUserName`        | 当前用户名称                                     | `string`                                          | 否   | —      |
 | `variables`           | 发送、办毕时提交的流程变量                       | `Record<string, unknown>`                         | 否   | `{}`   |
+| `assignmentQueryParams` | 内置发送弹窗查询候选办理人时附加的自定义路由参数 | `Record<string, unknown>`                       | 否   | `{}`   |
 | `autoResolveWork`     | 未传 `workId` 时自动查询当前用户待办             | `boolean`                                         | 否   | `true` |
 | `autoHandleDialogs`   | 在组件内部处理发送和跳转弹窗                     | `boolean`                                         | 否   | `true` |
 | `forceSingleAssignee` | 每个下一节点仅允许选择一名办理人                 | `boolean`                                         | 否   | `false`|
@@ -347,7 +348,7 @@ function handleWork({ action, workData }: {
 - 填写审批意见；
 - 确认后调用任务发送接口，成功后关闭弹窗并提示“发送成功”。
 
-办理人候选数据通过 `POST /flowstream/server/assignment/event/query` 加载。
+办理人候选数据通过 `POST /flowstream/server/assignment/event/query` 加载。业务路由需要额外上下文时，可通过 `assignmentQueryParams` 追加任意数量的请求字段，也可以不传。组件维护的 `processDefinitionId`、`activityId`、`userId` 和懒加载 `parentId` 优先级更高，不能被扩展参数覆盖。
 
 #### 1) 属性定义（Properties）
 
@@ -359,6 +360,7 @@ function handleWork({ action, workData }: {
 | `workId`              | 当前工作项 ID                                        | `string \| number`        | 是   | —          |
 | `processInstanceId`   | 流程实例 ID                                          | `string \| number`        | 否   | `''`       |
 | `variables`           | 当前业务流程变量                                     | `Record<string, unknown>` | 否   | `{}`       |
+| `assignmentQueryParams` | 查询候选办理人时附加的自定义路由参数               | `Record<string, unknown>` | 否   | `{}`       |
 | `dealUser`            | 当前用户，可传 `id` 或 `userId`                      | `object`                  | 否   | `{}`       |
 | `bpmnXml`             | BPMN XML；用于辅助判断下一节点是单人还是多人办理     | `string`                  | 否   | `''`       |
 | `showTrigger`         | 是否显示组件自身的发送按钮                           | `boolean`                 | 否   | `true`     |
@@ -406,6 +408,10 @@ import { ref } from 'vue'
 import { FlowButtons, FlowSend } from '@leadal/flowstream-ui-plus'
 
 const sendVisible = ref(false)
+const assignmentQueryParams = {
+  projectId: currentProject.id,
+  tenantId: currentTenant.id,
+}
 
 function handleFlowAction(action: string) {
   if (action === 'taskSend') sendVisible.value = true
@@ -436,6 +442,7 @@ function handleAfterSend() {
     :work-id="task.workId"
     :deal-user="currentUser"
     :variables="variables"
+    :assignment-query-params="assignmentQueryParams"
     :show-trigger="false"
     default-opinion="同意"
     @after-send="handleAfterSend"
@@ -670,7 +677,7 @@ const firstHandleNodes: FlowNode[] = result.data || []
 import flowstream from '@leadal/flowstream-ui-plus'
 
 async function submitBusiness() {
-  await flowstream.getRuntimeService().start({
+  const result = await flowstream.getRuntimeService().start({
     processDefinitionId,
     draftUserId: currentUser.id,
     draftUserName: currentUser.name,
@@ -679,6 +686,21 @@ async function submitBusiness() {
       name: borrowTitle,
     },
     variables,
+    assignmentQueryParams: {
+      projectId: currentProject.id,
+      tenantId: currentTenant.id,
+    },
+    async onBeforeStart(startArgs) {
+      // 可执行同步校验，也可以 await 业务项目自己的表单弹窗。
+      const formData = await openBusinessForm()
+      if (!formData) return false
+      startArgs.variables = { ...startArgs.variables, ...formData }
+      return true
+    },
+    async onBeforeSend(context) {
+      // false：实例已经创建，但不打开审批人选择弹窗。
+      return validateBeforeSend(context)
+    },
     onStarted(result) {
       saveFlowRelation(result.processInstanceId)
     },
@@ -687,15 +709,52 @@ async function submitBusiness() {
       refreshBusinessList()
     },
     onClose() {
-      // 关闭发送弹窗不会撤销已经启动的流程。
+      // 未发送就关闭弹窗时，运行时服务会撤销刚创建的流程实例。
     },
     onError(error) {
       console.error(error.phase, error.message)
     },
   })
+  if (result === false) return
 }
 ```
 
-`start()` 返回 `processInstanceId`、`processDefinitionId` 和起草人当前 `workId`。当前流程的发送弹窗关闭后，可调用 `flowstream.getRuntimeService().open()` 重新打开；调用 `close()` 只关闭弹窗，不撤销流程实例。`singleAssignee` 默认为 `true`，也可在启动参数中传入 `dialogTitle`、`dialogWidth`、`defaultOpinion` 和 `bpmnXml`。
+`onBeforeStart` 在首办节点查询和 `quickStart` 之前执行；返回 `false` 时 `start()` 返回 `false`，不会创建流程实例。`onBeforeSend` 在实例创建成功后、发送弹窗打开前执行；返回 `false` 时 `start()` 仍返回流程实例结果，但不会弹窗，并保留当前会话。之后调用 `await flowstream.getRuntimeService().open()` 会重新执行 `onBeforeSend`，通过后才打开弹窗；若决定放弃，调用 `close()` 会撤销该实例并释放会话。
+
+两个前置钩子都支持 `boolean | Promise<boolean>`。因此业务项目需要“弹表单、校验通过后再启动”时，应让业务弹窗封装成 Promise，而不是由流程组件识别业务字段：
+
+```ts
+let finishBeforeStart: ((allowed: boolean) => void) | undefined
+
+function waitForBusinessForm() {
+  businessDialogVisible.value = true
+  return new Promise<boolean>(resolve => {
+    finishBeforeStart = resolve
+  })
+}
+
+async function confirmBusinessForm() {
+  const valid = await businessFormRef.value?.validate().catch(() => false)
+  if (!valid) return
+  businessDialogVisible.value = false
+  finishBeforeStart?.(true)
+  finishBeforeStart = undefined
+}
+
+function cancelBusinessForm() {
+  businessDialogVisible.value = false
+  finishBeforeStart?.(false)
+  finishBeforeStart = undefined
+}
+
+await flowstream.getRuntimeService().start({
+  processDefinitionId,
+  draftUserId: currentUser.id,
+  draftUserName: currentUser.name,
+  onBeforeStart: waitForBusinessForm,
+})
+```
+
+业务弹窗通过右上角关闭、路由离开或组件卸载时也必须 `resolve(false)`，避免 `start()` 一直处于等待状态。`singleAssignee` 默认为 `true`，也可在启动参数中传入 `dialogTitle`、`dialogWidth`、`defaultOpinion`、`bpmnXml` 和 `assignmentQueryParams`。
 
 `quickStart()`、`getFirstHandleNodes()`、`nextSendNode()`、`nodeAssistant()` 和 `sendTask()` 仍作为底层 API 导出，供组件内部及高级扩展使用；普通业务项目应优先调用 `flowstream.getRuntimeService().start()`，不要自行复制流程编排。