refactor: 使用通用转换工具解析请假业务主键，移除相关测试并完善工作流注释

ruoyi-api/src/main/java/org/dromara/workflow/api/domain/StartMessageEventDTO.java

@@ -15,14 +15,28 @@ public class StartMessageEventDTO implements Serializable {
     @Serial
     private static final long serialVersionUID = 1L;
 
-    /** 业务主键，调用方必须提供。 */
+    /**
+     * 业务主键，调用方必须提供。
+     */
     private String businessId;
-    /** 流程定义编码。 */
+
+    /**
+     * 流程定义编码。
+     */
     private String flowCode;
-    /** 消息启动事件名称。 */
+
+    /**
+     * 消息启动事件名称。
+     */
     private String eventName;
-    /** 合并到流程变量的消息数据，可为空。 */
+
+    /**
+     * 合并到流程变量的消息数据，可为空。
+     */
     private Map<String, Object> payload;
-    /** 操作人，留空时使用系统处理人。 */
+
+    /**
+     * 操作人，留空时使用系统处理人。
+     */
     private String handler;
 }

ruoyi-api/src/main/java/org/dromara/workflow/api/domain/StartTimerEventDTO.java

@@ -15,14 +15,28 @@ public class StartTimerEventDTO implements Serializable {
     @Serial
     private static final long serialVersionUID = 1L;
 
-    /** 业务主键，留空时生成数字雪花 ID。 */
+    /**
+     * 业务主键，留空时生成数字雪花 ID。
+     */
     private String businessId;
-    /** 已发布的流程定义 ID。 */
+
+    /**
+     * 已发布的流程定义 ID。
+     */
     private Long definitionId;
-    /** 定时启动事件节点编码。 */
+
+    /**
+     * 定时启动事件节点编码。
+     */
     private String nodeCode;
-    /** 合并到流程变量的业务数据，可为空。 */
+
+    /**
+     * 合并到流程变量的业务数据，可为空。
+     */
     private Map<String, Object> payload;
-    /** 操作人，留空时使用系统处理人。 */
+
+    /**
+     * 操作人，留空时使用系统处理人。
+     */
     private String handler;
 }

ruoyi-api/src/main/java/org/dromara/workflow/api/domain/TriggerMessageEventDTO.java

@@ -15,12 +15,23 @@ public class TriggerMessageEventDTO implements Serializable {
     @Serial
     private static final long serialVersionUID = 1L;
 
-    /** 已存在的流程实例 ID。 */
+    /**
+     * 已存在的流程实例 ID。
+     */
     private Long instanceId;
-    /** 等待中的消息捕获或消息边界事件名称。 */
+
+    /**
+     * 等待中的消息捕获或消息边界事件名称。
+     */
     private String eventName;
-    /** 合并到流程变量的消息数据，可为空。 */
+
+    /**
+     * 合并到流程变量的消息数据，可为空。
+     */
     private Map<String, Object> payload;
-    /** 操作人，留空时使用系统处理人。 */
+
+    /**
+     * 操作人，留空时使用系统处理人。
+     */
     private String handler;
 }

ruoyi-modules/ruoyi-workflow/src/main/java/org/dromara/workflow/service/impl/FlwInstanceServiceImpl.java

@@ -306,6 +306,13 @@ public class FlwInstanceServiceImpl implements IFlwInstanceService {
         return flowHisTaskList(null, businessId);
     }
 
+    /**
+     * 按实例 ID、业务 ID 查询流程图及历史办理记录；同时提供时须指向同一实例。
+     *
+     * @param instanceId 流程实例 ID，可为空
+     * @param businessId 业务 ID，可为空
+     * @return 流程图与办理记录
+     */
     @Override
     public Map<String, Object> flowHisTaskList(Long instanceId, String businessId) {
         if (instanceId == null && StringUtils.isBlank(businessId)) {

ruoyi-modules/ruoyi-workflow/src/main/java/org/dromara/workflow/service/impl/TestLeaveServiceImpl.java

@@ -229,7 +229,7 @@ public class TestLeaveServiceImpl implements ITestLeaveService {
     @EventListener(condition = "#processEvent.flowCode.startsWith('demo')")
     public void processHandler(ProcessEvent processEvent) {
         log.info("当前任务执行了{}", processEvent.toString());
-        Long leaveId = parseLeaveId(processEvent.getBusinessId());
+        Long leaveId = Convert.toLong(processEvent.getBusinessId());
         if (leaveId == null) {
             return;
         }
@@ -287,7 +287,7 @@ public class TestLeaveServiceImpl implements ITestLeaveService {
     @EventListener(condition = "#processDeleteEvent.flowCode.startsWith('demo')")
     public void processDeleteHandler(ProcessDeleteEvent processDeleteEvent) {
         log.info("监听删除流程事件，当前任务执行了{}", processDeleteEvent.toString());
-        Long leaveId = parseLeaveId(processDeleteEvent.getBusinessId());
+        Long leaveId = Convert.toLong(processDeleteEvent.getBusinessId());
         if (leaveId == null) {
             return;
         }
@@ -298,12 +298,4 @@ public class TestLeaveServiceImpl implements ITestLeaveService {
         leaveMapper.deleteById(testLeave.getId());
     }
 
-    static Long parseLeaveId(String businessId) {
-        try {
-            return Long.valueOf(businessId);
-        } catch (NumberFormatException e) {
-            return null;
-        }
-    }
-
 }

ruoyi-modules/ruoyi-workflow/src/main/java/org/dromara/workflow/service/impl/WorkflowServiceImpl.java

@@ -178,6 +178,12 @@ public class WorkflowServiceImpl implements WorkflowService {
         return flwTaskService.completeTask(taskBo);
     }
 
+    /**
+     * 外部消息按流程编码和事件名称启动新实例。
+     *
+     * @param request 消息启动参数，业务 ID 由调用方提供
+     * @return 新建流程实例 ID
+     */
     @Override
     @Transactional(rollbackFor = Exception.class)
     public Long startByMessageEvent(StartMessageEventDTO request) {
@@ -188,6 +194,12 @@ public class WorkflowServiceImpl implements WorkflowService {
             request.getEventName(), request.getPayload(), eventContext(request.getHandler())).getId();
     }
 
+    /**
+     * 触发实例中等待的消息捕获或消息边界事件。重复投递时引擎保持实例不变。
+     *
+     * @param request 消息事件参数
+     * @return 流程实例 ID
+     */
     @Override
     @Transactional(rollbackFor = Exception.class)
     public Long triggerMessageEvent(TriggerMessageEventDTO request) {
@@ -198,6 +210,12 @@ public class WorkflowServiceImpl implements WorkflowService {
             request.getPayload(), eventContext(request.getHandler())).getId();
     }
 
+    /**
+     * 手动发起定时启动事件，不改变等待记录及下一次自动触发时间。
+     *
+     * @param request 定时启动参数，业务 ID 留空时生成数字雪花 ID
+     * @return 新建流程实例 ID
+     */
     @Override
     @Transactional(rollbackFor = Exception.class)
     public Long startByTimerEvent(StartTimerEventDTO request) {
@@ -210,18 +228,40 @@ public class WorkflowServiceImpl implements WorkflowService {
             request.getNodeCode(), request.getPayload(), eventContext(request.getHandler())).getId();
     }
 
+    /**
+     * 从实例级错误捕获节点处理外部错误。
+     *
+     * @param instanceId   流程实例 ID
+     * @param errorCode    错误码，精确匹配优先于通配
+     * @param errorMessage 错误描述
+     * @return 错误事件已被处理时返回 true
+     */
     @Override
     @Transactional(rollbackFor = Exception.class)
     public boolean throwInstanceErrorEvent(Long instanceId, String errorCode, String errorMessage) {
         return FlowEngine.insService().throwError(instanceId, errorCode, errorMessage);
     }
 
+    /**
+     * 从当前待办的错误边界节点处理外部错误。
+     *
+     * @param taskId       当前待办任务 ID
+     * @param errorCode    错误码，精确匹配优先于通配
+     * @param errorMessage 错误描述
+     * @return 错误事件已被处理时返回 true
+     */
     @Override
     @Transactional(rollbackFor = Exception.class)
     public boolean throwTaskErrorEvent(Long taskId, String errorCode, String errorMessage) {
         return FlowEngine.taskService().throwError(taskId, errorCode, errorMessage);
     }
 
+    /**
+     * 构建事件上下文
+     *
+     * @param handler 操作人
+     * @return 事件上下文
+     */
     private WorkflowContext eventContext(String handler) {
         WorkflowContext context = new WorkflowContext();
         context.setHandler(StringUtils.isNotBlank(handler) ? handler : FlowEngine.getFlowConfig().getSystemHandler());

ruoyi-modules/ruoyi-workflow/src/test/java/org/dromara/workflow/service/impl/TestLeaveServiceImplTest.java

@@ -1,17 +0,0 @@
-package org.dromara.workflow.service.impl;
-
-import org.junit.jupiter.api.Test;
-
-import static org.junit.jupiter.api.Assertions.assertEquals;
-import static org.junit.jupiter.api.Assertions.assertNull;
-
-class TestLeaveServiceImplTest {
-
-    @Test
-    void ignoresEngineGeneratedBusinessIds() {
-        assertNull(TestLeaveServiceImpl.parseLeaveId("T2114648233624309762_1793006432000"));
-        assertNull(TestLeaveServiceImpl.parseLeaveId("9223372036854775808"));
-        assertNull(TestLeaveServiceImpl.parseLeaveId(null));
-        assertEquals(123L, TestLeaveServiceImpl.parseLeaveId("123"));
-    }
-}