DM-ROW 接口文档

Appearance

工作流引擎集成 ​

**本文引用的文件** - [lemes-service-dm-workflow-server/src/main/resources/application.yml](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-workflow/lemes-service-dm-workflow-server/src/main/resources/application.yml) - [lemes-service-dm-workflow-server/src/main/resources/bootstrap.yml](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-workflow/lemes-service-dm-workflow-server/src/main/resources/bootstrap.yml) - [lemes-service-dm-workflow-server/src/main/java/com/lenovo/lemes/service/dm/workflow/LemesServiceDmWorkflowServerApplication.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-workflow/lemes-service-dm-workflow-server/src/main/java/com/lenovo/lemes/service/dm/workflow/LemesServiceDmWorkflowServerApplication.java) - [lemes-service-dm-workflow-server/pom.xml](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-workflow/lemes-service-dm-workflow-server/pom.xml) - [lemes-service-dm-workflow-common/src/main/java/com/lenovo/lemes/service/dm/workflow/common/AsyncPoolConfig.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-workflow/lemes-service-dm-workflow-common/src/main/java/com/lenovo/lemes/service/dm/workflow/common/AsyncPoolConfig.java) - [lemes-service-dm-workflow-common/src/main/java/com/lenovo/lemes/service/dm/workflow/enums/WorkFlowBusinessEnum.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-workflow/lemes-service-dm-workflow-common/src/main/java/com/lenovo/lemes/service/dm/workflow/enums/WorkFlowBusinessEnum.java) - [lemes-service-dm-workflow-common/src/main/java/com/lenovo/lemes/service/dm/workflow/entity/dto/FlowPendingTaskDTO.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-workflow/lemes-service-dm-workflow-common/src/main/java/com/lenovo/lemes/service/dm/workflow/entity/dto/FlowPendingTaskDTO.java) - [lemes-service-dm-workflow-common/src/main/java/com/lenovo/lemes/service/dm/workflow/entity/dto/ActivityDTO.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-workflow/lemes-service-dm-workflow-common/src/main/java/com/lenovo/lemes/service/dm/workflow/entity/dto/ActivityDTO.java) - [lemes-service-dm-workflow-common/src/main/java/com/lenovo/lemes/service/dm/workflow/entity/dto/BreakInfoDTO.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-workflow/lemes-service-dm-workflow-common/src/main/java/com/lenovo/lemes/service/dm/workflow/entity/dto/BreakInfoDTO.java) - [lemes-job-devicemate-executor/src/main/java/com/lenovo/lemes/job/devicemate/executor/mapper/workflow/FlowUserMapper.java](file://lemes-job-devicemate/lemes-job-devicemate-executor/src/main/java/com/lenovo/lemes/job/devicemate/executor/mapper/workflow/FlowUserMapper.java) - [docs/ddl/workflow.sql](file://docs/ddl/workflow.sql) - [lemes-cloud/src/devops/k8s/service/dpms/workflow.yaml](file://lemes-cloud/src/devops/k8s/service/dpms/workflow.yaml) - [lemes-cloud/src/devops/k8s/service/expose-port/lemes-service-dm-workflow.yaml](file://lemes-cloud/src/devops/k8s/service/expose-port/lemes-service-dm-workflow.yaml)

目录 ​

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能考虑
  8. 故障排查指南
  9. 结论
  10. 附录

简介 ​

本技术文档面向设备管理系统中工作流引擎（Flowable）的集成与落地，围绕引擎配置、数据源与事务管理、服务启动与运行时参数、初始化流程、监控与管理、以及运维部署等方面进行系统化说明。文档以项目中的工作流服务模块为核心，结合前端 BPMN 编排工具链与后端执行器，给出可操作的配置建议与最佳实践。

项目结构 ​

工作流服务位于微服务架构下的业务子模块中，采用 Spring Boot + Spring Cloud + Flowable 的组合方式，通过 Nacos 进行注册与配置中心，暴露 Actuator 监控端点，并使用 Druid 数据源与 MyBatis Plus 进行持久化访问。

图表来源

章节来源

核心组件 ​

  • 应用入口与扫描路径：通过注解启用服务发现与 Feign 客户端，默认扫描 com.lenovo.lemes 包空间，排除 Druid 自动装配以自管数据源。
  • 配置中心与注册中心：基于 Nacos 的服务发现与配置拉取，支持命名空间、分组、共享配置等。
  • 监控与日志：暴露 Actuator 端点，统一使用 log4j2-spring 配置，按应用名输出到独立日志目录。
  • 数据访问：MyBatis Interceptor 针对特定 Mapper 方法进行拦截策略配置，配合多数据源注解实现跨库访问。
  • 引擎与 REST：引入 Flowable Spring Boot Starter Process REST，提供流程引擎与 REST API 能力。

章节来源

架构总览 ​

下图展示工作流服务在整体系统中的位置与交互关系，包括注册与配置中心、监控、数据库、以及前端模型编辑器。

图表来源

详细组件分析 ​

启动与配置（application.yml） ​

  • MyBatis 拦截器配置：针对匹配正则的方法进行查询/更新拦截，支持包含与排除列表，便于统一统计与审计。
  • 建议：将拦截范围限定在业务 Mapper，避免对全表扫描或高并发接口造成额外开销；排除高频查询以降低影响。

章节来源

启动与配置（bootstrap.yml） ​

  • 服务端口与优雅停机：设置端口与优雅停机超时，确保发布与下线过程平滑。
  • 应用名与生命周期：应用名为 artifactId 占位符，生命周期超时用于控制优雅停机阶段时间。
  • Nacos 配置：用户名、密码、服务地址、命名空间、心跳超时、端口元数据、共享配置等。
  • 监控端点：暴露所有 Actuator 端点，便于健康检查与指标采集。
  • 日志配置：使用 log4j2-spring-default.xml，日志路径按应用名生成，降低日志交叉污染。
  • 网络与网络工具：忽略特定网卡接口，优先网络段配置。

章节来源

应用入口与扫描（LemesServiceDmWorkflowServerApplication） ​

  • 启用服务发现与 Feign 客户端，指定默认配置类与扫描包范围。
  • 排除 Druid 数据源自动配置，以便自定义数据源与连接池参数。
  • 主方法启动 Spring Boot 应用。

章节来源

依赖与引擎集成（pom.xml） ​

  • 依赖框架与通用模块：framework-service、framework-auth、framework-datasource、workflow-common。
  • Flowable 集成：引入 Flowable Spring Boot Starter Process REST，排除 Swagger 与 JSR250 相关依赖以避免版本冲突。
  • 构建插件：资源过滤、Spring Boot 插件、Docker 插件。

章节来源

数据访问与多数据源 ​

  • 多数据源注解：在执行器模块中通过注解切换数据源，确保工作流相关表与业务表分离。
  • 建议：将工作流引擎的表空间与业务表空间隔离，避免跨库事务复杂度上升。

章节来源

引擎初始化与流程存储 ​

  • 初始化流程：通过 Flowable Starter 提供的自动配置创建引擎实例与 REST API。
  • 建议：在生产环境设置合适的历史级别与作业调度参数，避免历史数据膨胀与任务积压。

（本节为概念性说明，未直接分析具体代码文件）

监控与管理 ​

  • Actuator 暴露：通过配置开启所有端点，便于健康检查、指标导出与远程关闭。
  • 日志：统一使用 log4j2-spring，按应用名落盘，便于集中采集与检索。
  • 建议：结合 Prometheus/Grafana 对关键指标（如任务队列长度、执行耗时、错误率）进行可视化监控。

章节来源

错误处理与异常码 ​

  • 统一响应与异常码：在公共模块中定义 ServiceResponse 与异常码枚举，便于前后端一致处理。
  • 建议：在 REST 层捕获并转换为标准响应体，保留原始错误码与上下文信息。

章节来源

数据模型与 DTO ​

  • 待办任务 DTO：封装流程实例、任务节点等关键字段，便于前端展示与操作。
  • 活动节点 DTO：封装活动节点标识与名称，用于流程状态查询。
  • 回退信息 DTO：封装回退节点与替代用户等信息，支撑流程回退场景。

章节来源

BPMN 模型解析与属性映射（前端） ​

  • 元素解析：移除 flowable 前缀、合并 attributes、格式化数组与字符串。
  • 文档与表达式：将 documentation 合并为字符串，conditionExpression 提取 body。
  • 用户任务：根据 candidateUsers/candidateGroups/assignee 映射 userType 与值。

章节来源

BPMN 节点属性与监听器（前端） ​

  • 节点属性：对 async、dueDate、formKey、priority、skipExpression、isForCompensation、triggerable、class、autoStoreVariables、exclude、ruleVariablesInput、rules、resultVariable 等属性进行双向绑定与持久化。
  • 执行监听器与任务监听器：动态创建扩展元素，清理旧值，支持参数字段注入。

章节来源

依赖关系分析 ​

工作流服务对外部依赖主要集中在注册与配置中心、监控、数据库与前端模型编辑器；对内依赖包括通用框架、认证、数据源与工作流公共模块。

图表来源

章节来源

性能考虑 ​

  • 监控端点暴露：生产环境建议限制暴露端点与访问权限，仅开放必要指标。
  • 日志级别：根据环境调整日志级别，避免过多 I/O 开销。
  • 拦截器策略：合理设置包含/排除规则，避免对高频接口产生额外负担。
  • 数据库连接池：结合 Druid 或 HikariCP 的参数调优，控制最大连接数与空闲时间。
  • 历史级别：根据合规与性能平衡设置历史级别，避免历史表过大。
  • 异步任务：利用 Flowable 的异步执行能力与线程池配置，提升吞吐。

（本节为通用性能建议，未直接分析具体代码文件）

故障排查指南 ​

  • 启动失败：检查 Nacos 地址、命名空间、用户名密码是否正确；确认端口占用与优雅停机超时设置。
  • 监控不可用：确认 Actuator 暴露端点配置与访问权限；验证日志路径与权限。
  • 数据访问异常：核对多数据源注解与库名配置；检查 SQL 与表结构一致性。
  • BPMN 解析异常：前端解析逻辑需兼容 flowable 前缀与扩展属性，确保序列化/反序列化正确。
  • 引擎初始化问题：确认 Flowable Starter 版本与排除冲突依赖；检查历史级别与作业线程池配置。

章节来源

结论 ​

该工作流引擎集成方案以 Flowable 为核心，结合 Spring Cloud 与 Nacos 实现服务治理，通过统一的日志与监控配置保障可观测性，并以多数据源与拦截器策略实现数据访问的灵活性与可控性。前端 BPMN 编辑器与后端 REST API 形成闭环，满足设备管理场景下的流程编排与执行需求。建议在生产环境中进一步完善性能参数、历史级别与监控策略，确保系统稳定与高效运行。

附录 ​

配置清单与建议 ​

  • application.yml
    • MyBatis 拦截器：限定匹配范围，排除高频查询，避免影响性能。
  • bootstrap.yml
    • Nacos：校验 server-addr、namespace、group、用户名密码。
    • Actuator：按需暴露端点，生产环境限制访问。
    • 日志：确认 log4j2 配置与日志路径权限。
  • pom.xml
    • Flowable Starter：注意排除 Swagger 与 JSR250 冲突依赖。
    • 构建插件：保持资源过滤与 Spring Boot 插件配置一致。
  • 多数据源
    • 使用注解切换数据源，确保工作流表与业务表分离。
  • 历史级别与作业线程池
    • 生产环境建议设置合适的历史级别与作业线程池大小，避免历史表膨胀与任务积压。

章节来源

数据库脚本参考 ​

  • 工作流相关表结构可参考以下脚本文件，确保引擎与业务表结构一致。

章节来源

运维部署参考 ​

  • Kubernetes 服务与暴露端口配置可参考以下文件，确保服务发现与外部访问正常。

章节来源