@leadal/flowstream-ui-plus 0.0.2 → 0.0.4

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

@@ -179,6 +179,10 @@ const diagramRef = ref<InstanceType<typeof FlowDiagram>>()
   :process-definition-id="task.processDefinitionId"
   :deal-user-id="loginUser.id"
   :deal-user-name="loginUser.name"
+  :assignment-query-params="{
+    projectId: currentProject.id,
+    tenantId: currentTenant.id,
+  }"
   force-single-assignee
   :before-action="validateBeforeAction"
   :after-action="reloadAfterAction"
@@ -206,6 +210,10 @@ import { ref } from 'vue'
 import { FlowSend } from '@leadal/flowstream-ui-plus'
 
 const sendVisible = ref(false)
+const assignmentQueryParams = {
+  projectId: currentProject.id,
+  tenantId: currentTenant.id,
+}
 
 function handleAction(action: string) {
   if (action === 'taskSend') sendVisible.value = true
@@ -222,6 +230,7 @@ function handleAction(action: string) {
     :deal-user="currentUser"
     :show-trigger="false"
     :variables="variables"
+    :assignment-query-params="assignmentQueryParams"
     @before-send="handleBeforeSend"
     @after-send="handleAfterSend"
     @error="handleError"
@@ -231,6 +240,8 @@ function handleAction(action: string) {
 
 推荐通过 `v-model` 控制弹窗，避免宿主依赖组件实例；实例仍公开 `open()`、`close()`、`getNextNode()`、`assembleData()` 和 `send()`。组件通过 `nodeAssistant` 请求 `POST /flowstream/server/assignment/event/query` 加载下一节点候选人，并在确认时直接提交 `/flowstream/server/task/event/send`。
 
+`assignmentQueryParams` 是可选的自定义路由参数对象，可以传一个、多个字段或不传。它会追加到每次候选办理人查询（包括组织树懒加载）中。组件自己的 `processDefinitionId`、`activityId`、`userId` 和 `parentId` 不允许被该对象覆盖。使用 `FlowButtons` 内置发送弹窗或 `getRuntimeService().start()` 时也可传入同名参数。
+
 ## 10. ui-flow-jump
 
 `FlowJump` 内置“开始节点 + 办理人”选择弹窗。办理人支持组织树懒加载；如果节点没有配置办理人，组件会回填当前用户。跳转不编辑业务变量，请求中固定提交 `variables: {}`。
@@ -292,12 +303,25 @@ const firstHandleNodes = result.data || []
 import flowstream from '@leadal/flowstream-ui-plus'
 
 async function submit() {
-  await flowstream.getRuntimeService().start({
+  const result = await flowstream.getRuntimeService().start({
     processDefinitionId,
     draftUserId: currentUser.id,
     draftUserName: currentUser.name,
     business: { key: businessId, name: businessName },
     variables,
+    assignmentQueryParams: {
+      projectId: currentProject.id,
+      tenantId: currentTenant.id,
+    },
+    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)
     },
@@ -306,22 +330,29 @@ async function submit() {
       refreshBusinessList()
     },
     onClose() {
-      console.log('发送弹窗已关闭，流程实例仍然存在')
+      console.log('发送弹窗已关闭；未发送时流程实例会被撤销')
     },
     onError(error) {
       console.error(error.phase, error.message)
     },
   })
+  if (result === false) return
 }
 ```
 
-- `start()` 内部依次完成首办节点解析、`quickStart`、发送弹窗初始化、下一节点和候选办理人查询。
+- `onBeforeStart(args)` 在任何流程查询和启动接口之前执行，支持 `boolean | Promise<boolean>`；返回 `false` 时不会创建流程实例，`start()` 返回 `false`。
+- `start()` 通过启动校验后，内部依次完成首办节点解析、`quickStart`、发送弹窗初始化、下一节点和候选办理人查询。
+- `onBeforeSend(context)` 在实例创建成功后、审批人选择弹窗打开前执行，也支持 Promise；返回 `false` 时保留流程实例和当前会话，但不打开弹窗。
+- 条件稍后满足时调用 `await flowstream.getRuntimeService().open()`，组件会重新执行 `onBeforeSend`；决定放弃时调用 `close()` 撤销实例并释放会话。
 - 调用成功后直接打开选择弹窗，业务模板不需要挂载隐藏组件。
 - 候选办理人可以有多个；`singleAssignee` 默认开启，每个下一节点只能选择一人。
+- 自定义业务路由参数通过 `assignmentQueryParams` 传入，并自动附加到候选办理人查询请求。
 - 用户确认后由内部发送组件调用 `sendTask()`；`onAfterSend` 参数中的 `sendData.flowNodeAssignees` 是实际发送的下一节点和办理人。
-- 用户关闭弹窗只会取消本次发送，不会撤销已启动实例；可调用 `flowstream.getRuntimeService().open()` 重新打开。
+- 用户未发送就关闭弹窗时会撤销刚创建的流程实例并释放会话；只有 `onBeforeSend` 返回 `false`、弹窗尚未打开时，才能调用 `open()` 在条件满足后继续。
 - `processDefinitionId`、`draftUserId`、`draftUserName` 均为必填；快速启动不支持多个首办节点或多个起草人待办。
 
+业务表单弹窗应由接入项目实现，并将用户操作转换为 Promise：确认且校验成功时 `resolve(true)`，取消、关闭或组件卸载时 `resolve(false)`。不要只修改一个响应式布尔变量而不结束 Promise，否则 `start()` 会一直等待。
+
 ## 14. 获取应用与流程
 
 业务页面需要「选应用 → 选流程 → 发起」级联场景时，可查询应用列表和流程定义列表。
@@ -358,4 +389,3 @@ const flows = await flowstream.getRuntimeService().getFlows({ appId })
 - 接口约定（路径待后端确认）：`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.2",
+  "version": "0.0.4",
   "description": "FlowStream workflow components for Vue 3",
   "type": "module",
   "main": "dist/flowstream-ui-plus.umd.cjs",