1. 流程可视化追踪的核心价值与场景拆解
做过审批流、工单流、订单流转这类系统的朋友，大概率都碰过同一个需求：用户打开页面，想一眼看清楚这单货现在走到哪了、谁批过、谁还没批、下一步该找谁。如果只给一张静态流程图，用户还得自己拿流程定义去比对，体验非常割裂。所以“流程图显示 + 高亮连线和已执行节点 + 当前节点”这套组合，本质上是把流程引擎里的运行时数据，反向映射回流程定义图上，让图“活”起来。
我先把这套东西的定位说清楚：它不是一个独立功能，而是流程引擎能力、图形渲染能力、数据映射逻辑三者的交汇点。流程引擎负责告诉你“哪些节点执行过、当前停在哪个节点、哪些连线被走过”；图形渲染负责把 BPMN 图正确画出来；数据映射负责把引擎里的执行记录，精准对应到图上的元素 ID。三者任何一环对不上，高亮就会错位、漏亮、或者整条线不亮。
适合谁来参考？如果你正在做 OA、ERP、CRM、工单系统、审批中台，或者任何需要“流程进度可视化”的产品，这套思路都能直接套。前端同学可以重点看渲染和映射，后端同学可以重点看引擎数据怎么取、怎么组装，产品同学可以看交互上到底该亮哪些、不该亮哪些。
这里有个容易被忽略的点：高亮不是越全越好。我见过一些实现，把“已执行节点”和“当前节点”用同一种颜色，结果用户根本分不清是走完了还是卡住了。正确的做法是至少三态区分：已执行（历史）、当前（进行中）、未执行（未来）。连线同理，已走过的连线要亮，没走过的保持灰色。这个区分度直接决定用户能不能三秒看懂进度。
另外，流程图的显示本身也有坑。BPMN 图里节点位置、连线路径都是 XML 里定义的，如果渲染时坐标算错，高亮元素就会叠在一起或者偏移。所以这套功能的技术难点，往往不在“取数据”，而在“把数据准确贴到图上”。
2. 引擎侧数据获取与状态判定逻辑
2.1 已执行节点和连线的数据来源
流程引擎在运行过程中，会把每一步的执行记录落到历史表里。以常见的 Activiti 系引擎为例，历史活动表记录每个活动节点的执行实例，历史任务表记录用户任务，历史变量表记录流程变量。要判断“哪些节点执行过”，最直接的方式就是查历史活动表，按流程实例 ID 过滤，拿到所有已执行的活动 ID 集合。
但这里有个细节：历史活动表里同一条记录可能对应多个执行实例，比如多实例节点、并行网关分支。如果直接去重后拿 ID 集合，可能会漏掉“某个分支走过、另一个分支没走”的情况。所以更稳的做法是：按活动 ID 分组，同时保留每个活动的执行次数和最后执行时间。这样前端不仅能高亮，还能在悬浮时显示“该节点执行过 3 次，最后一次是某时刻”。
连线的数据来源稍微绕一点。连线在引擎里通常对应“顺序流”，它的执行记录不一定单独落表，而是通过“当前节点 + 历史节点”的先后关系推导出来的。具体来说，如果节点 A 执行过，节点 B 也执行过，且 A 到 B 之间存在一条顺序流，那这条线大概率被走过。但并行网关场景下，A 到 B 和 A 到 C 可能同时走，所以推导时要结合网关类型判断。
提示：不要试图只靠“当前节点”反推连线。当前节点只能告诉你“现在停在哪”，不能告诉你“从哪来”。必须结合历史节点集合一起算。
2.2 当前节点的精准定位
当前节点分两种情况：一种是流程停在某个用户任务上，等待人工处理；另一种是停在某个自动节点上，比如服务任务、脚本任务，只是瞬间状态。对于可视化来说，我们主要关心第一种，因为用户需要知道“现在该谁处理”。
获取当前节点最直接的方式是查运行时任务表，按流程实例 ID 过滤，拿到所有待办任务。但要注意：并行网关下可能有多个当前节点同时存在。比如一个会签场景，三个审批人同时待办，那当前节点就有三个。这时候高亮逻辑要支持多节点同时亮，而不是只亮一个。
还有一种情况是流程已经结束。结束后运行时任务表为空，但历史表里有完整记录。这时候“当前节点”应该显示为结束节点，或者干脆不显示当前节点，只显示已执行路径。我个人的做法是：流程结束时，把结束事件节点高亮为“已完成”，同时所有已执行连线保持高亮，给用户一个完整的闭环感。
2.3 状态判定的优先级与边界情况
状态判定看起来简单，实际有一堆边界要处理。我整理了一个优先级顺序，供你参考：
| 优先级 | 判定条件 | 高亮策略 |
|---|---|---|
| 1 | 流程已结束 | 所有已执行节点和连线高亮，结束节点特殊标记 |
| 2 | 存在运行时任务 | 已执行节点高亮，当前任务节点用进行中样式，已执行连线高亮 |
| 3 | 存在历史节点但无运行时任务 | 可能是流程被挂起或异常终止，按历史节点高亮，当前节点标记为异常 |
| 4 | 无历史无运行时 | 流程未启动，全部灰色 |
边界情况里最麻烦的是“驳回”和“跳转”。驳回后，原来的已执行节点还算不算已执行？我的经验是：算。因为用户确实走过那一步，只是后来被退回了。但当前节点要更新为驳回后的目标节点。跳转同理，跳转前的节点保留已执行状态，跳转后的节点作为当前节点。这样用户能看到完整的“走过弯路”的轨迹，反而更真实。
3. 图形渲染与高亮映射的实操方案
3.1 流程图渲染的技术选型
渲染 BPMN 图，常见方案有三种：一是用引擎自带的图生成能力，直接输出带高亮的图片；二是前端用 SVG 或 Canvas 自己画；三是用现成的 BPMN 渲染库，比如 bpmn-js 这类。
引擎自带图生成的好处是省事，后端一个接口返回图片流，前端直接展示。但缺点也很明显：样式定制困难，高亮颜色、线宽、节点图标基本改不动，而且每次状态变化都要重新生成图片，性能一般。我早期项目用过这种，后来因为产品要改高亮样式，被迫重构。
前端自己画 SVG 的灵活性最高，但工作量巨大。BPMN 的连线路径有直线、折线、曲线，还有网关的菱形、事件的圆形，全部手写坐标计算，维护成本很高。除非你的流程图非常简单，否则不建议从零造轮子。
用现成渲染库是目前最稳的方案。以 bpmn-js 为例，它能把 BPMN XML 渲染成 SVG，并且暴露了元素注册表，你可以通过元素 ID 拿到对应的 SVG 节点，然后直接改样式类。这样高亮逻辑就变成“给指定 ID 的元素加一个 CSS 类”，非常干净。
3.2 元素 ID 映射的关键细节
不管用哪种渲染方案，核心都是“引擎里的活动 ID”和“图上的元素 ID”要对上。BPMN XML 里每个节点和连线都有 id 属性，引擎在部署时会把流程定义解析成活动，活动 ID 通常就是 XML 里的 id。所以理论上，你从历史表拿到的 activityId，直接拿去图上找同名元素就行。
但实际项目里，有几个坑：
第一，子流程嵌套。如果流程里有子流程，子流程内部的活动 ID 可能和外部重复，或者引擎在存储时加了前缀。这时候直接按 ID 匹配会错位。解决办法是：取历史数据时，同时取“执行实例 ID”和“活动 ID”，映射时用执行实例的层级关系去定位。
第二，多实例节点。多实例节点在图上是一个元素，但引擎里可能生成多个执行实例。高亮时只需要亮那一个图元素，但悬浮提示里要显示“已执行 N 次”。
第三，连线 ID 的获取。连线在历史表里不一定直接有记录，需要从流程定义 XML 里解析出所有顺序流，然后根据“源节点已执行 + 目标节点已执行”来判定。这里建议在部署时就把流程定义的连线关系缓存起来，避免每次查询都解析 XML。
3.3 高亮样式的设计与实现
样式设计上，我建议至少定义四套类：
.highlight-completed：已执行节点，用浅绿或浅蓝填充，边框加深.highlight-current：当前节点，用橙色或主题色填充，加脉冲动画.highlight-completed-line：已执行连线，用主题色描边，线宽加粗.highlight-default：未执行元素，保持灰色
CSS 大概长这样：
.highlight-completed .djs-visual > :first-child { fill: #e6f7e6 !important; stroke: #52c41a !important; } .highlight-current .djs-visual > :first-child { fill: #fff7e6 !important; stroke: #fa8c16 !important; stroke-width: 2px !important; } .highlight-completed-line .djs-visual > path { stroke: #52c41a !important; stroke-width: 2px !important; }注意!important在这里是必要的，因为渲染库自带的样式优先级可能比较高。但不要滥用，只在你确认覆盖不掉的时候加。
当前节点的脉冲动画可以用 CSS keyframes 实现：
@keyframes pulse { 0% { stroke-width: 2px; } 50% { stroke-width: 4px; } 100% { stroke-width: 2px; } } .highlight-current .djs-visual > :first-child { animation: pulse 1.5s infinite; }这样用户一眼就能看到“现在停在这”。
4. 完整实操流程与核心代码拆解
4.1 后端接口设计与数据组装
后端需要提供一个接口，入参是流程实例 ID，出参是三类数据：已执行节点 ID 列表、已执行连线 ID 列表、当前节点 ID 列表。我一般会封装成一个对象：
{ "processInstanceId": "proc-123", "completedNodeIds": ["startEvent1", "userTask1", "userTask2"], "completedLineIds": ["flow1", "flow2"], "currentNodeIds": ["userTask3"], "finished": false }取数逻辑分三步：
第一步，查历史活动表，拿到所有已执行的活动 ID。SQL 大致是：
SELECT DISTINCT ACT_ID_ FROM ACT_HI_ACTIVITY WHERE PROC_INST_ID_ = #{processInstanceId}第二步，查运行时任务表，拿到当前节点 ID：
SELECT TASK_DEF_KEY_ FROM ACT_RU_TASK WHERE PROC_INST_ID_ = #{processInstanceId}第三步，推导已执行连线。这一步需要流程定义的连线关系。我通常会在部署时把 BPMN XML 解析一遍，存成“源节点 -> 目标节点 -> 连线 ID”的映射表。然后遍历已执行节点集合，如果某条连线的源和目标都在集合里，就把这条连线加入已执行连线列表。
注意：并行网关下，源节点执行了、目标节点也执行了，但连线不一定走过。比如 A 到 B 和 A 到 C 是两条分支，如果 B 执行了但 C 没执行，那 A 到 C 的连线就不该亮。所以判定条件要更严格：连线的源节点已执行，且目标节点已执行，且两者之间存在执行时序关系。时序关系可以从历史活动的开始时间和结束时间推断。
4.2 前端渲染与高亮注入
前端拿到接口数据后，先渲染 BPMN 图，然后遍历元素注册表，给匹配的 ID 加类。以 bpmn-js 为例：
const elementRegistry = modeler.get('elementRegistry'); const canvas = modeler.get('canvas'); // 清除旧高亮 elementRegistry.forEach(element => { canvas.removeMarker(element.id, 'highlight-completed'); canvas.removeMarker(element.id, 'highlight-current'); canvas.removeMarker(element.id, 'highlight-completed-line'); }); // 注入新高亮 data.completedNodeIds.forEach(id => { canvas.addMarker(id, 'highlight-completed'); }); data.currentNodeIds.forEach(id => { canvas.addMarker(id, 'highlight-current'); }); data.completedLineIds.forEach(id => { canvas.addMarker(id, 'highlight-completed-line'); });这里用canvas.addMarker而不是直接操作 DOM，是因为渲染库内部会管理元素状态，直接改 DOM 可能在重绘时被覆盖。用 marker 的方式，重绘后样式依然保留。
如果用的是其他渲染方案，思路一样：找到元素对应的 SVG 节点，加类或改属性。关键是不要硬编码坐标，一定要通过元素 ID 去查。
4.3 参数计算与性能优化
当流程节点很多时，每次状态变化都全量重绘会卡。我实测下来，一个 50 节点的流程，全量重绘大概 200ms 左右，还能接受。但如果是 200 节点以上，就要做增量更新。
增量更新的思路是：缓存上一次的高亮集合，和新集合做差集，只移除消失的、只添加新增的。这样大部分情况下只需要操作几个元素，性能提升明显。
另一个优化点是接口缓存。流程状态在两次查询之间通常不会变，可以在前端加一个短时缓存，比如 5 秒内重复请求直接返回缓存结果。但要注意，用户手动刷新时要强制绕过缓存。
还有个细节：连线高亮的层级。BPMN 图里连线通常在节点下层，如果高亮连线时被节点盖住，看起来就像没亮。解决办法是给高亮连线加一个z-index或者调整 SVG 的绘制顺序。bpmn-js 里可以通过canvas.addMarker配合 CSS 的pointer-events和层级处理，但更稳的方式是在渲染时就把连线分组放到节点上方。
5. 常见问题排查与避坑经验实录
5.1 高亮错位与漏亮问题
问题一：节点亮了，但连线没亮。最常见的原因是连线 ID 没取对。很多人以为历史表里会存连线 ID，其实不一定。我建议在部署时就把流程定义的连线关系解析出来，存成映射，运行时直接查映射，不要依赖历史表。
问题二：当前节点亮了，但已执行节点没亮。这通常是历史查询条件写错了。比如只查了用户任务，没查服务任务和网关。历史活动表里所有类型的活动都有记录，查询时不要加类型过滤，除非你明确只要用户任务。
问题三：并行网关下只亮了一个分支。这是因为去重时把不同分支的活动 ID 合并了。解决办法是保留执行实例 ID，按实例分组，而不是简单去重。
问题四：驳回后原节点不亮了。有些实现会在驳回时删除历史记录，导致原节点丢失。正确做法是保留历史，驳回只是新增一条执行记录，不删旧的。
5.2 样式冲突与渲染异常
问题五：高亮样式不生效。九成是 CSS 优先级不够。渲染库自带的样式可能用了!important，你的类被覆盖了。解决办法是提高选择器权重，或者也用!important。但更优雅的方式是通过渲染库的 API 改样式，而不是硬覆盖 CSS。
问题六：脉冲动画导致页面卡顿。如果当前节点很多，每个都加动画，浏览器重绘压力大。建议只给第一个当前节点加动画，或者用will-change提示浏览器优化。
问题七：流程图缩放后高亮偏移。这通常是渲染库的坐标计算问题，不是高亮逻辑问题。检查一下渲染时是否用了正确的 viewBox，以及缩放后是否重新计算了元素位置。
5.3 常见问题速查表
| 现象 | 可能原因 | 排查方向 | 解决方案 |
|---|---|---|---|
| 节点全灰 | 接口没返回数据 | 查网络请求 | 检查流程实例 ID 是否正确 |
| 连线不亮 | 连线 ID 映射缺失 | 查映射表 | 部署时解析 XML 存映射 |
| 当前节点多个 | 并行网关 | 查运行时任务表 | 支持多节点同时高亮 |
| 驳回后轨迹丢失 | 历史被删 | 查历史表 | 保留历史，不物理删除 |
| 样式不生效 | CSS 优先级 | 查计算样式 | 提高权重或用 API |
| 动画卡顿 | 动画元素过多 | 查性能面板 | 限制动画元素数量 |
5.4 独家避坑技巧
第一个技巧：在流程部署时就把图元素 ID 和连线关系缓存到本地，不要每次查询都解析 XML。解析 XML 是 CPU 密集型操作，流程多了会拖慢接口。
第二个技巧：高亮逻辑和流程引擎解耦。不要把高亮代码写在引擎的监听器里，而是做成独立的查询服务。这样引擎升级或换实现时，高亮逻辑不用动。
第三个技巧：给用户一个“刷新”按钮。流程状态可能被其他人操作改变，自动轮询有延迟，手动刷新能让用户主动获取最新状态。刷新时记得清缓存。
第四个技巧：测试时覆盖驳回、跳转、并行、子流程、多实例这五种场景。这五种是 bug 高发区，普通直线流程反而没问题。
第五个技巧：高亮颜色要符合无障碍标准。不要只用颜色区分状态，最好加上图标或文字标签，比如已执行节点加个对勾，当前节点加个圆点。色弱用户也能看懂。
6. 扩展思路与个人实践体会
这套东西做完之后，其实还能往上叠不少能力。比如把每个节点的处理人、处理时间、耗时也映射到图上，悬浮时显示详情，用户就不用跳转到历史列表去查了。再比如把超时节点用红色标记，提醒用户赶紧处理。还可以做路径回放，按时间顺序依次点亮节点，像放动画一样展示流程怎么一步步走过来的。
我在实际项目里踩过最大的坑，是早期把高亮逻辑写在了前端，后端只返回原始历史数据。结果前端要自己推导连线、自己处理并行分支，代码越写越乱。后来改成后端统一组装好三类 ID 列表，前端只负责加类，维护成本直接降了一半。所以我的建议很明确：推导逻辑放后端，渲染逻辑放前端，边界清晰，谁也别越界。
另外，流程图的显示不要追求一次到位。先做静态展示，再加已执行高亮，再加当前节点，最后加连线和动画。每加一层都测试一轮，确保不破坏已有功能。我见过有人一口气全做完，结果样式冲突、数据错位、性能问题一起爆发，排查起来非常痛苦。
最后分享一个小技巧：如果流程节点特别多，可以在图上加一个“聚焦当前节点”的按钮，点击后自动滚动到当前节点位置并放大。这个功能用户反馈非常好，尤其是长流程场景，省去了手动拖拽找节点的麻烦。实现上就是拿到当前节点的 SVG 坐标，然后调渲染库的滚动 API。不难，但体验提升很明显。
