1. 项目概述当QClaw遇上智慧航道最近在做一个智慧航道相关的项目团队内部一直在寻找一个能快速搭建、灵活调整业务流程的工具。传统的开发模式一个审批流程或者数据流转的改动就得拉上前后端开发、测试折腾好几天沟通成本高响应速度慢。我们试过一些开源的工作流引擎像Flowable、Activity功能是强大但上手门槛不低配置起来也略显笨重对于业务部门想自己调整个表单字段或者加个审批节点基本不可能。后来我们接触到了QClaw一个将动态表单和工作流引擎深度融合的开源工具。它的核心理念很吸引人让业务人员也能通过可视化的方式像搭积木一样构建和修改业务流程。这正好切中了我们在智慧航道项目中“业务多变、需求迭代快”的痛点。智慧航道听起来高大上其实核心就是通过各种传感器、AIS船舶自动识别系统、视频监控等采集航道、船舶、环境数据然后经过处理分析为船舶航行、航道管理、应急指挥提供智能服务。这里面涉及大量跨部门、跨系统的数据流转与业务协同比如船舶报告、危险品申报、突发事件处置、航道疏浚审批等等每一个都是一条或多条复杂的工作流。经过一段时间的摸索和实践我们基于QClaw落地了两个非常典型的实战工作流效果出乎意料的好。这篇文章我就来详细拆解一下这两个工作流的设计思路、在QClaw中的具体实现以及我们踩过的一些坑和总结出来的经验。无论你是正在评估QClaw还是对如何将低代码工作流应用于物联网、智慧城市这类垂直领域感兴趣相信都能从中获得一些直接的参考。2. 工作流一航道突发事件智能上报与协同处置流这个工作流源于一个很实际的场景航道上的摄像头或船舶报告发现异常比如有船舶违章锚泊、航道出现不明漂浮物、发生小型碰撞事故等。传统流程是发现人打电话给值班室值班员记录后再通过电话或内部系统层层上报、分派效率低且信息在传递中容易失真。我们的目标是实现“发现即上报、上报即分派、处置全留痕”的闭环管理。2.1 核心流程设计与业务逻辑拆解整个流程的起点是一个多渠道的“事件上报”入口。这不仅仅是内部人员上报我们通过集成允许过往船舶通过甚高频VHF语音转译、或者小程序扫码等方式进行简易上报。上报的信息需要结构化所以我们设计的表单包含事件类型下拉选择船舶违章、漂浮物、污染、事故等、发生位置集成地图组件点击选取或输入经纬度、严重程度初级、中级、高级、现场描述文本图片/视频上传、上报人联系方式等。流程的核心逻辑如下自动创建与分派表单提交后自动创建工作流实例。系统首先根据“事件类型”和“发生位置”关联到管辖责任区进行规则判断自动分派给对应的航道管理处值班岗。这里用到了QClaw工作流的“条件网关”和“表达式”例如事件类型 ‘船舶违章’ 所属辖区 ‘第三管理区’则流向“第三管理区值班岗”处理节点。值班岗核实与升级值班岗人员收到待办查看上报详情。他需要做一个关键操作核实情况。如果信息模糊他可以退回要求补充如果核实属实且为一般事件他直接分派给辖区内的巡逻艇或现场工作人员任务节点如果判断为重大或紧急事件如涉及危险品泄漏他必须点击“升级”按钮流程会自动跳转到“指挥中心审批”节点并同步发送短信、应用内通知给指挥中心负责人。现场处置与反馈现场处置人员如巡逻艇船员在移动端接收任务前往现场。他们的任务节点表单包含处置措施文本、处置后现场照片、耗时、是否需其他部门协同等。处置完成后提交流程自动流向“上报人满意度回访”节点可选针对提供了联系方式的上报人和“值班岗结案审核”节点。归档与数据分析值班岗确认处置无误后点击结案。工作流结束但后台会自动将整个流程的所有表单数据、审批意见、操作日志、时间戳整合成一条完整的“事件档案”存储到业务数据库并推送到大数据平台用于后续的分析比如高频事件发生地段、平均处置时长等。注意在设计自动分派规则时一定要考虑“默认处理人”或“替补机制”。比如某个辖区当前所有值班人员都处于离线或忙碌状态规则引擎匹配失败流程不能卡住。我们的做法是设置一个“全局值班班长”角色作为默认兜底并同时发送告警通知给管理员提示需手动干预分派。2.2 在QClaw中的关键配置与实现细节在QClaw中实现上述流程主要涉及几个核心模块的配置1. 动态表单设计 我们为流程的每个用户任务节点都设计了独立的表单但共享一些基础数据。QClaw的表单设计器是拖拽式的对于“事件类型”这类固定选项我们使用“下拉框”组件并关联一个提前在后台维护好的数据字典这样便于统一管理。对于“发生位置”我们集成了第三方地图组件需要自定义开发一个表单控件实现了点击选点并自动获取经纬度及反向解析为文字地址的功能。图片上传组件直接使用QClaw内置的配置好存储路径我们指向了项目的MinIO对象存储桶和大小限制即可。2. 流程模型绘制与节点配置 在QClaw的流程设计器BPMN 2.0标准中我们绘制了包含开始事件、用户任务值班岗处理、指挥中心审批、现场处置等、条件网关用于自动分派和升级判断、并行网关用于同时触发回访和结案审核、结束事件的完整模型。用户任务最关键的是配置“处理人”。我们大量使用了“表达式指派”。例如值班岗处理人的表达式为#{dutyService.getDutyPerson(eventType, location)}这里的dutyService是我们自己开发的Spring Bean它根据事件类型和位置从组织架构和排班表中计算出当前应处理的值班人员ID。条件网关在流程线上设置条件。QClaw支持JUEL表达式。例如从“值班岗处理”流向“指挥中心审批”的线上条件设置为#{taskForm.severity ‘高级’ || taskForm.needUpgrade true}其中taskForm是当前任务表单的数据对象。3. 业务规则与外部集成自动分派规则如前所述我们将其封装成Java服务dutyService在QClaw中注册为流程可调用的“外部服务”。这样流程引擎在到达需要指派处理人的节点时会自动调用该服务获取处理人。消息通知QClaw支持在节点“创建”、“完成”等事件上配置监听器。我们配置了“消息通知监听器”当任务创建时调用内部的消息推送服务向处理人的App推送待办并根据紧急程度决定是否同步发送短信。数据归档在流程的“结束事件”上我们附加了一个“执行监听器”当流程实例结束时触发一个归档服务将散落在各任务表单中的数据连同流程实例ID、流转记录一起组装成标准格式存入业务库并发送到Kafka消息队列供其他系统消费。4. 移动端适配 QClaw本身提供了一套基础的前端但为了更好的移动体验我们基于其开放的RESTful API自己开发了轻量级的移动端H5页面。核心是调用“待办任务列表”、“获取任务表单”、“提交任务”等接口。这里要注意表单渲染的兼容性我们自定义的表单控件如地图在移动端需要有对应的展示和交互逻辑。2.3 部署与性能调优心得我们采用Docker Compose部署QClaw后端、前端、数据库MySQL分别容器化。对于生产环境有几点心得数据库优化QClaw的流程引擎运行时数据如任务、实例会频繁读写。我们给act_ru_task、act_ru_execution等核心运行时表增加了合适的索引并定期每周清理已结束超过3个月的流程实例历史数据act_hi_*表将其归档到历史库保证主库性能。服务拆分将QClaw的核心流程引擎服务与我们的业务服务如dutyService、消息服务解耦。业务服务通过Feign Client或REST方式供QClaw调用避免将沉重的业务逻辑写到QClaw的监听器Java类里造成引擎服务臃肿。高可用考虑我们部署了两台QClaw应用实例前面用Nginx做负载均衡。QClaw的流程状态保存在数据库所以多实例可以共享状态实现无状态横向扩展。需要确保它们连接到同一个MySQL集群和同一个Redis用于缓存和会话管理。3. 工作流二船舶定期报告与合规性自动检查流第二个工作流聚焦于船舶的日常管理。根据法规船舶在进入、离开或经过特定报告线时需要向海事/航道部门报告动态信息。我们将其数字化并增加了自动合规性检查环节减轻人工审核压力。3.1 流程闭环与自动检查点设计船舶通过船载终端或船员手机App提交报告表单内容包括船舶识别码MMSI、报告类型抵港、离港、过境、报告位置、时间、货物信息、船员信息、目的地等。流程设计如下报告提交与格式校验表单提交时前端和后端均进行基础校验非空、格式。通过后流程实例创建进入“自动合规检查”服务任务节点。服务任务自动合规检查这是一个无人参与的自动节点。系统在这里会调用多个外部接口进行核验船舶身份核验通过MMSI码调用海事数据库接口核验船舶是否真实、证书是否有效。黑名单检查查询本系统的船舶信用/黑名单库检查该船是否有未处理的违章或处于限制报告状态。货物合规性预审如果报告类型为“离港”且载有危险品系统会调用危险品规则库初步核对货物分类、包装等信息是否符合申报要求。航行计划冲突检测将本船的预计航迹基于目的地和速度与同期其他船舶的报告计划进行比对标记出存在潜在交会冲突的高风险点。检查结果路由合规检查服务会输出一个结果对象包含各项检查的通过状态和详情。流程根据结果进入条件网关全部通过流程自动完成系统向船舶发送“报告已接收”的回执并将报告数据归档。全程无人干预实现“秒级”自动办结。存在警告或需人工复核项流程流向“海事值班员人工复核”节点。值班员看到的是经过系统预筛选和标注了风险点的报告他只需要聚焦于系统提示的几项问题做出判断即可大幅提升效率。存在严重不通过项如船舶黑名单流程直接结束并向船舶发送“报告被拒绝”的通知及理由。人工复核与处置值班员复核后可以选择“通过”、“驳回”或“补充材料”。如果驳回流程结束并通知船方如果需要补充材料则创建一个新的子任务或发送消息给船方船方补充后流程回到复核节点。这个流程的精髓在于将大量规则明确、重复性高的工作交给“服务任务”自动化让人工只处理真正需要经验和判断的异常情况。3.2 QClaw服务任务与外部集成的深度应用在这个工作流中“自动合规检查”这个服务任务节点是核心。1. 服务任务配置 在QClaw设计器中拖入一个“服务任务”节点。其关键配置是“实现”类型。我们选择“表达式”并填入#{complianceCheckService.executeCheck(execution)}。complianceCheckService同样是我们编写的Spring Bean。QClaw引擎会在执行到这个节点时自动调用该Bean的executeCheck方法并将流程执行对象execution传入我们可以从中获取到流程变量即表单数据。2. 服务任务Bean开发Component(complianceCheckService) public class ComplianceCheckService { Autowired private ShipIdentityClient identityClient; // 船舶身份核验客户端 Autowired private RiskRuleEngine ruleEngine; // 风险规则引擎 public void executeCheck(DelegateExecution execution) { // 1. 从流程变量中获取报告数据 MapString, Object variables execution.getVariables(); ShipReport report (ShipReport) variables.get(shipReport); // 2. 调用各外部服务进行核验 CheckResult identityResult identityClient.verify(report.getMmsi()); CheckResult blacklistResult ruleEngine.checkBlacklist(report.getMmsi()); CheckResult cargoResult ruleEngine.checkCargoCompliance(report.getCargoInfo()); // ... 其他检查 // 3. 汇总结果并设置回流程变量 ComplianceResult finalResult aggregateResults(identityResult, blacklistResult, cargoResult); execution.setVariable(complianceResult, finalResult); // 还可以根据结果设置一个用于网关判断的布尔变量 execution.setVariable(needManualReview, finalResult.hasWarning() || !finalResult.isCargoPassed()); execution.setVariable(hasCriticalError, finalResult.hasCriticalError()); } }3. 异步服务任务与超时处理 合规检查可能涉及多个外部接口调用总耗时可能超过几秒。为了避免HTTP请求阻塞流程引擎线程我们将其改造成了异步服务任务。在QClaw中将服务任务的“异步”属性设置为true并配置一个“重试次数”和“超时时间”如30秒。这样引擎会立即继续执行实际上会暂停并创建一个作业而我们的complianceCheckService会在一个独立的线程池中执行。执行完成后引擎再回调继续流程。实操心得对于异步服务任务一定要做好异常处理和补偿机制。比如某个外部接口超时或返回异常我们的服务不能简单抛出异常导致流程中断。我们会在CheckResult中标记该子项检查为“未知”或“系统错误”并将整体结果标记为“需人工复核”。同时记录详细的错误日志并触发一个告警让运维人员知道有外部接口异常。这样保证了流程的健壮性不会因为第三方服务不稳定而大面积卡住。4. 规则引擎的集成 对于“黑名单检查”、“货物合规”这类基于规则的判断我们引入了轻量级的规则引擎如Drools。将业务规则从代码中剥离出来写成.drl规则文件。当规则需要变更时比如新增一种危险品限制业务人员可以在界面上修改规则文件并热加载无需重启应用或修改流程定义实现了业务规则的灵活配置。4. 两个工作流带来的价值与挑战反思通过落地这两个工作流我们真切感受到了低代码工作流平台在智慧航道这类复杂业务系统中的价值。核心价值业务敏捷性大幅提升航道管理处的工作人员经过简单培训已经可以自己在QClaw设计器中微调表单字段、修改某个审批环节的处理人规则。一个以前需要开发介入的需求现在可能半天就能由业务部门自己上线测试。流程可视化与透明度所有业务流程的图纸BPMN模型就是运行时的蓝图任何人都可以查看一个具体事件或报告当前走到了哪一步历史经过哪些环节谁处理的耗时多久。这极大促进了跨部门协作和问题追溯。人力解放与效率提升第二个工作流中的自动合规检查保守估计替代了原先70%的人工核验工作量。值班人员从繁重的信息核对中解放出来专注于处理真正的异常和复杂情况。数据资产自然沉淀流程的每一次流转都伴随着结构化数据的录入和更新。这些数据被完整地归档形成了高质量的业务数据源为后续的大数据分析、智能预警打下了坚实基础。遇到的挑战与应对复杂业务逻辑的“度”不是所有业务逻辑都适合放进工作流。我们最初试图把一些非常复杂的计算逻辑也做成服务任务导致流程模型变得异常复杂和难以维护。后来我们明确了原则工作流只管“流转”和“协同”复杂的业务计算封装成独立的微服务工作流只负责调用和传递结果。表单设计的灵活性需求QClaw自带的表单设计器能满足大部分需求但对于一些特殊场景如我们需要的动态地图选点、与船舶档案的复杂联动查询还是需要前端进行二次开发封装成自定义组件再集成进去。这要求团队有一定的前后端开发能力。历史流程实例的查询性能当运行了数万甚至数十万个流程实例后QClaw自带的历史实例查询接口可能会变慢。我们针对高频的查询场景如“查询我处理过的事件”单独建立了基于业务数据库的查询视图绕开了引擎的历史表直接面向归档后的业务数据查询性能好很多。与现有系统的集成QClaw不是孤岛需要与权限系统我们用的是Keycloak、消息推送系统、文件存储系统、多个外部数据接口集成。这部分需要投入一定的开发工作量设计好清晰的API边界和调用契约。5. 给后来者的实操建议与避坑指南如果你也打算在类似项目中引入QClaw或同类工作流引擎以下几点建议可能对你有帮助1. 始于试点小步快跑 不要一上来就试图把最核心、最复杂的业务流程搬上去。选择一两个相对独立、但又有一定复杂度的边缘流程作为试点比如我们选的“突发事件上报”。快速搭建、上线、收集反馈。这个过程能帮你快速熟悉工具特性磨合团队协作模式并建立信心。2. 流程建模前先统一语言 拉着业务方和开发一起用白板把业务流程从头到尾画清楚明确每个环节的输入、输出、处理人、判断规则、异常路径。务必达成共识后再动手在QClaw中绘制BPMN模型。避免边做边改后期返工成本很高。3. 高度重视异常处理 工作流中除了“阳光大道”主流程一定要设计好“崎岖小径”异常流。比如任务处理人长时间不处理怎么办配置任务超时提醒和转派规则自动服务调用失败怎么办配置重试和降级策略业务规则冲突怎么办明确兜底方案。在QClaw中要善用“边界事件”定时器、错误事件来处理这些异常。4. 建立流程版本管理规范 QClaw支持流程定义的版本管理。当你对一个已上线运行的流程进行修改时务必通过“新建版本”的方式发布。要明确新旧版本的关系通常新发起的流程实例使用新版本但已运行的旧实例继续按旧版本定义走完除非有特殊的数据迁移和流程实例升级方案。这一点一定要和业务方沟通清楚。5. 监控与运维不能少 需要建立对工作流引擎本身的监控。我们监控了几个关键指标流程实例启动速率、任务平均完成时长、服务任务失败率、数据库连接池状态。设置告警比如服务任务失败率连续5分钟超过1%或者有流程实例卡在某个节点超过24小时立即通知运维人员查看。6. 关于自定义开发 QClaw的开源版本提供了很好的扩展性但这也意味着你需要投入开发资源。建议先充分评估其开箱即用的功能是否能满足你80%的需求。对于必须自定义的部分如特定表单控件、复杂的指派规则最好将其封装成独立的、可复用的组件或服务方便在其他流程中调用。最后想说的是工具再好也只是工具。QClaw帮助我们解决了流程“可视化”和“可配置”的问题但背后对业务的理解、流程的梳理、异常情况的考量才是项目成功的关键。它更像是一个桥梁让懂业务的业务人员和懂技术的开发人员能用一种共同的“语言”BPMN模型进行高效协作。在智慧航道这个充满传统与创新碰撞的领域这样的协作方式或许比技术本身带来的价值更大。