把流程能力嵌入自有前端：三条集成路径与工程细节

整站嵌入、半耦合、非耦合三条路各有代价。本文以非耦合为主线，讲清工具栏、审核组件、Token 与参数归一化的接入方式。

1. 什么是前端流程工具包？

1.1 用一句话理解

Toolkit 是一组可原样拷贝进您前端工程的「流程能力积木箱」。 它不是整站门户，也不替代您的业务表单设计；它负责把「发送、退回、审核、选人、会签……」这些流程动作，变成您页面上可直接使用的组件和 API。

1.2 它长什么样

• Toolkit 本质上是一组静态前端文件组成的目录（Vue3 工程里对应 src/Toolkit/）。
• 把这个目录放进您自己的前端架构后，通过 HTTP API 与独立运行的该 BPM 平台 / 该引擎服务器对话。
• Toolkit 与您的前端「同生共死」：路由、菜单、皮肤、布局仍由您掌控；流程办理能力由 Toolkit 提供。

可以把关系想象成：

您的前端系统（菜单、业务页、自绘表单）
        │
        │  引入 Toolkit 组件 / 调用 Dev2Interface
        ▼
   Toolkit 目录（工具栏、审核组件、WorkOpt、流程 API）
        │
        │  WF/Comm/ProcessRequest + Token
        ▼
   该 BPM 平台服务器（流程组件 引擎、节点属性、流程属性）

1.3 目前提供哪些版本

旧文档里若仍写「React 版 Toolkit」，以本文与仓库 Toolkit/README.md 为准。

1.4 Toolkit 能帮您做什么

1.5 Toolkit 边界（避免误用）

写清楚「不做啥」，比夸大「啥都能」更重要：

该 BPM 平台首先推荐使用 Toolkit 做二次开发：您保留业务表单与菜单体系，引擎侧的「会跑流程」能力用积木拼上去即可。

2. Toolkit 集成工作示意图

读图要点：

1. Toolkit 文件夹放在您的前端开发目录里（整包复制，不要拆散）。
2. 它通过 API 与该 BPM 平台服务器交互——服务器可独立部署，前后端分离。
3. 您的业务页面负责「填什么」；Toolkit 负责「怎么送、怎么退、怎么签」。

统一请求通道（与主站一致）：

后端侧，Toolkit 前端大量调用：

• 流程组件.HttpHandler.WF_TSDev2Interface —— TS/Toolkit 专用流程 API
• 流程组件.HttpHandler.WF_MyFlow —— 办理初始化、InitToolBar、发送等
• 流程组件.HttpHandler.WF_WorkOpt —— 选人、审核、会签等操作面板
• 流程组件.HttpHandler.WF_MyView / WF_MyCC —— 查看器 / 抄送处理器初始化

3. 集成模式怎么选？

把「自家系统」和「该引擎」拼在一起，常见有三条路。Toolkit 对应其中工作量较小、个性化最强的一条。

设计器里的对应项：节点表单方案 SDK 表单 ≈ 非耦合；嵌入式表单 ≈ 半耦合。智能 SDK（SmartSDKFrm.js）属历史方案，新项目请用 Vue3 Toolkit，不再展开。

4. 非耦合集成（Toolkit / SDK 表单）——推荐

4.1 这是什么体验？

工作量较小、边界清晰的集成模式：

• 该 BPM 平台 独立部署、独立运行；
• 您把 Toolkit 目录引进前端；
• 业务表单完全由您渲染；
• 流程动作通过 Toolkit 组件或 Dev2Interface 完成。

如下

可以把它想成：您装修客厅，该平台只提供「开关面板」和「水电接口」。 开关（工具栏按钮）亮不亮，由节点属性决定；水电（发送/退回）由引擎执行。

4.2 典型页面结构

┌─────────────────────────────────────────────┐
│  ToolBar：发送 | 保存 | 退回 | 移交 | 轨迹 … │  ← Toolkit
├─────────────────────────────────────────────┤
│                                             │
│         您自己的业务表单（任意技术栈 UI）      │  ← 宿主系统
│                                             │
├─────────────────────────────────────────────┤
│  WorkCheck：审核意见 / 签名 / 附件 / 轨迹    │  ← Toolkit
└─────────────────────────────────────────────┘

可选：退回信息条 ToolbarFlow、父子流程 WorkOpt/SubFlow.vue、发送选人等 WorkOpt 弹窗（由工具栏自动拉起）。

4.3 设计器侧怎么配

1. 流程/节点表单方案选择 SDK 表单（NodeFormType.SDKForm）。
2. 表单 URL 指向您的办理页（可用变量 @SDKFromServHost，或配置 VITE_GLOB_SDKFROESERV_HOST）。
3. 在节点属性中启停按钮（退回、移交、抄送、结束等）——运行时由 InitToolBar 下发给 ToolBar。
4. 在节点审核组件属性中配置 FWCSta（是否显示/可编辑）、FWCShowModel（普通/轨迹/时间轴）、FWCLab（标题文案）等。

4.4 打开办理页必传参数

Toolkit 提供 parseFlowUrlParams / buildWorkOptParams 帮助您从路由 query 归一化这些参数。

5. 环境准备：把 Toolkit「接上电」

5.1 整包复制

请复制整个 src/Toolkit/，不要只挑子目录。内部引用均为相对路径（独立宿主工程中，Dev2Interface.ts 应使用包内 ./utils/gener/HttpHandler，而非主站别名 /@/）。

目录摘要：

Toolkit/
├── index.ts                 # 导出入口（自动引入 toolkit.css）
├── ToolBar.vue              # 工作处理器工具栏
├── ToolbarFlow.vue          # 退回信息条
├── WorkOptModalHost.vue     # WorkOpt 弹窗宿主
├── Dev2Interface.ts         # 流程 API 门面
├── config/                  # API 地址、Token
├── adapters/                # WebUser 等可替换适配
├── components/              # 原生 UI（Modal/Drawer/Tree/Table）
├── styles/toolkit.css       # tk-* 样式
├── utils/                   # HttpHandler、TurnTo、参数解析…
├── WorkCheck/               # 审核组件
└── WorkOpt/                 # 选人、会签、挂起、父子流程等

5.2 依赖

pnpm add vue vue-router axios dayjs lodash-es

5.3 .env 与代理

VITE_GLOB_API_URL=http://localhost:8085/

vite.config.ts 开发代理示例：

server: {
  proxy: {
    '/api': {
      target: 'http://localhost:8085',
      changeOrigin: true,
      rewrite: (path) => path.replace(/^\/api/, ''),
    },
  },
},

5.4 Token：别让「钥匙」丢了

每次进入办理页建议：

import { setRequestToken } from '@/Toolkit';

onMounted(() => setRequestToken(String(route.query.Token || '')));
watch(toolbarParams, (p) => setRequestToken(String(p.Token || '')), { deep: true });

获取 Token 的常见方式：调用后端 Port_Login（或贵司封装的单点登录），再把 Token 拼进打开办理页的 URL。

6. 把功能页面绑到自己的菜单（免自绘列表）

若您暂时不想自己画「发起 / 待办 / 在途」列表，可以走整站嵌入或 FEForward 转发页：部署 Vue3 前端后，用 iframe 打开对应 action。

示例（部署地址假设为 https://bpm.your.com）：

https://bpm.your.com/#/FEForward?action=GL_Start&token=您的Token

当前常用 action：

第三方系统接入步骤要点：

1. 打包 Vue3 时设置 VITE_GLOB_IS_THIRDPART_SYSTEM=1，VITE_GLOB_API_URL 指向真实后端。
2. 业务系统登录后换取该 BPM 平台 Token（/WF/API/Port_Login 或 Java 侧 Dev2Interface.Port_Login）。
3. 菜单 iframe 的 src 带上 action 与 token。

说明：这些列表页属于产品前端能力；Toolkit 包聚焦办理组件与 API。两者可组合——列表用 iframe，办理页用 SDK+Toolkit。

7. 快速接入示例（SDK 办理页）

以下示例展示「工具栏 + 审核组件」最小闭环（完整说明见仓库 前端模块源码目录）：

<template>
  <div>
    <ToolBar :params="toolbarParams" :before-flow-send="beforeFlowSend" />
    <WorkCheck
      v-if="workCheckVisible"
      ref="workCheckRef"
      :params="workCheckParams"
      :node-info="nodeInfo"
      :is-readonly="workCheckReadonly"
      :examine-mode="examineMode"
    />
    <!-- 中间区域：放置您自己的业务表单 -->
  </div>
</template>

<script setup lang="ts">
import { computed, onMounted, watch, ref } from 'vue';
import { useRoute } from 'vue-router';
import {
  ToolBar,
  WorkCheck,
  setRequestToken,
  buildWorkOptParams,
  parseFlowUrlParams,
  useWorkCheckFwcSta,
} from '@/Toolkit';

const route = useRoute();
const workCheckRef = ref<InstanceType<typeof WorkCheck>>();
const queryReadonly = computed(() => parseInt(String(route.query.IsReadonly ?? '0'), 10) === 1);

const toolbarParams = computed(() =>
  buildWorkOptParams(parseFlowUrlParams(route.query as Record<string, unknown>)),
);

const { nodeInfo, examineMode, workCheckVisible, workCheckReadonly, beforeFlowSend: saveWorkCheckBeforeSend } =
  useWorkCheckFwcSta(toolbarParams, { queryIsReadonly: queryReadonly });

const workCheckParams = computed(() => ({
  DoWhat: 'WorkCheck',
  WorkID: toolbarParams.value.WorkID,
  NodeID: toolbarParams.value.NodeID ?? toolbarParams.value.FK_Node,
  FK_Node: toolbarParams.value.FK_Node ?? toolbarParams.value.NodeID,
  FlowNo: toolbarParams.value.FlowNo ?? toolbarParams.value.FK_Flow,
  Token: toolbarParams.value.Token,
}));

async function beforeFlowSend(): Promise<boolean> {
  return saveWorkCheckBeforeSend(workCheckRef);
}

onMounted(() => setRequestToken(String(route.query.Token || '')));
watch(toolbarParams, (p) => setRequestToken(String(p.Token || '')), { deep: true });
</script>

发送前钩子 beforeFlowSend 的典型职责：先保存审核意见，再允许发送——就像登机前先核验登机牌。

8. 核心组件详解

8.1 ToolBar —— 工作处理器的「遥控器」

职责：根据当前节点 InitToolBar 返回的按钮列表，渲染并执行发送、保存、退回等操作。

常用 props：

发送时的几种分支（由引擎规则决定，前端只是「听话」）：

1. 普通发送：下一节点与接收人已由方向条件算好，一点即发。
2. 需要选人（IsSelectEmps ≠ 0）：弹出接受人面板。
3. CondModel = 1：发送后弹出到达节点面板（ToNodesPanel），由办理人选择走向。

工具栏常见按钮（是否出现取决于节点配置）：

保存业务数据时，可通过 params 携带：

• paras：主表字段串
• dtls：从表数据
• aths：附件信息

对应后端 WF_TSDev2Interface.Node_SaveWork。

8.2 WorkCheck —— 审核组件

职责：意见填写、常用短语、手写签名、审核附件、轨迹/时间轴展示。

FWCSta（审核状态）决定组件生死：

推荐使用 useWorkCheckFwcSta：自动处理显隐、只读，并提供发送前保存。

注意：

• 不要写死 examineMode='normalMode'，应跟随节点 FWCShowModel（普通 / 轨迹 / 时间轴）。
• WorkCheck 不渲染区块标题；宿主请读取 FWCLab（默认「审核信息」）自行展示，用法类似父子流程的 SFLab。

8.3 WorkOpt —— 操作弹窗集群

由工具栏在需要时打开，例如：

• 发送选人、到达节点选择
• 会签加人
• 挂起、删除实例
• 分配、预置下一步接受人
• 父子流程 SubFlow.vue（展示子流程列表、发起子流程；标题文案看 SFLab / SFSta）

宿主一般只需挂好 WorkOptModalHost（随 ToolBar 体系使用），无需逐个手写弹窗。

8.4 ToolbarFlow —— 退回信息条

当工作是被退回回来的，顶部可展示退回原因、退回附件等，避免办理人「莫名其妙又看到自己的单」。

9. 前端 API：Dev2Interface（不用自己拼接口）

Toolkit 内的 Dev2Interface.ts 是面向 TS 的流程门面，底层打到 流程组件.HttpHandler.WF_TSDev2Interface（及部分 MyFlow / WorkOpt Handler）。

9.1 常用方法速查

使用建议：能嵌 ToolBar 就优先嵌组件——按钮权限、选人弹窗、TurnTo 跳转都已编排好；只有高度定制的页面才直接裸调 API。

9.2 与后端核心 SDK 的关系

C# 侧完整业务能力在 流程组件.Dev2Interface（列表查询、发送、退回、抄送等）； WF_TSDev2Interface 是给前端 Toolkit/TS 调用的 HttpHandler 薄封装。 Java（该引擎）侧有对等 API 命名习惯，集成思路一致。

四大菜单数据若您要自绘列表，也可直接调引擎 API，例如：

10. 半耦合：嵌入式表单（对照了解）

当节点表单方案为 嵌入式表单（SelfForm） 时：

• 头部：该平台工具栏
• 中部：您的 URL（iframe）
• 尾部：审核组件

系统会把 FK_Flow、FK_Node、WorkID、Token 等参数拼到您的 URL 后。 您的页面需实现 Save()：保存成功返回 true，失败返回 false——外壳点「发送」时会先调它，像安检门一样拦住不完整的数据。

该模式不必整包引入 Toolkit 办理组件（外壳已有），但若您希望完全自控 UI，仍应回到第 4 章的 SDK + Toolkit。

11. 发送之后去哪里？TurnTo 与嵌入约定

• 发送成功后的跳转由 utils/turnToNavigate.ts（如 handleTurnToResponse）处理。
• 嵌入该平台流程中心时：
  • 父 → 子：下发 Token、关闭指令等（可参考主站 MyFlowSelfForm.vue）；
  • 子 → 父：办结后 postMessage 关闭 Tab（如 type: 2）。
• SDK / 测试容器：WF/Admin/TestingContainer/Default.vue。

12. 常见问题

客户复制清单

13. 和「四大菜单、三大处理器」的关系

Toolkit 解决的是：打开一张单之后怎么办。 产品级入口仍可概括为：

发起 / 待办  ──► 工作处理器 MyFlow   ──► ToolBar + 表单 + WorkCheck
在途 / 完成  ──► 工作查看器 MyView   ──► 催办 / 撤销 / 轨迹（只读向）
抄送        ──► 抄送处理器 MyCC     ──► 知晓、打印、轨迹

非耦合集成时：列表可自绘或 iframe；处理器页面由您用 Toolkit 拼装，行为与产品三大处理器对齐。

14. 小结：怎么开始最省事

1. 本地跑通演示：http://toolkit.演示站点 （admin / 123）。
2. 整包复制 前端模块源码目录 到您的前端。
3. 配好 VITE_GLOB_API_URL、代理与 Token。
4. 节点表单方案选 SDK 表单，URL 指向您的办理页。
5. 页面上嵌入 ToolBar + 自绘表单 + WorkCheck。
6. 需要列表页时，用 FEForward iframe 挂上发起/待办/在途/抄送。

这样，您得到的是：自家产品的脸面 + 该引擎的筋骨——也是该 BPM 平台最推荐的 Toolkit 集成路径。