【代码评审】工作流：getTodoTask 的评审

yudao-module-bpm/yudao-module-bpm-biz/src/main/java/cn/iocoder/yudao/module/bpm/controller/admin/task/BpmTaskController.java

@@ -74,12 +74,13 @@ public class BpmTaskController {
         return success(BpmTaskConvert.INSTANCE.buildTodoTaskPage(pageResult, processInstanceMap, userMap));
     }
 
+    // TODO @jason：这个接口还要哇？
     @GetMapping("my-todo")
     @Operation(summary = "获取我的待办任务,取第一条")
     @Parameter(name = "processInstanceId", description = "流程实例的编号", required = true)
     @PreAuthorize("@ss.hasPermission('bpm:task:query')")
     public CommonResult<BpmTaskRespVO> getMyTodoTask(@RequestParam("processInstanceId") String processInstanceId) {
-        return success(taskService.getTodoTask(getLoginUserId(), processInstanceId));
+        return success(taskService.getFirstTodoTask(getLoginUserId(), processInstanceId));
     }
 
     @GetMapping("done-page")

yudao-module-bpm/yudao-module-bpm-biz/src/main/java/cn/iocoder/yudao/module/bpm/controller/admin/task/vo/instance/BpmApprovalDetailReqVO.java

@@ -6,11 +6,12 @@ import io.swagger.v3.oas.annotations.media.Schema;
 import jakarta.validation.constraints.AssertTrue;
 import lombok.Data;
 
-// TODO @jason：这个可以简化下，使用 @RequestParam。嘿嘿，主要 VO 项不要太多
 @Schema(description = "管理后台 - 审批详情 Request VO")
 @Data
 public class BpmApprovalDetailReqVO {
 
+    // TODO @jason：这里要不注释说明下，什么情况下，使用 processDefinitionId、processInstanceId、activityId、taskId。
+
     @Schema(description = "流程定义的编号", example = "1024")
     private String processDefinitionId;
 
@@ -21,7 +22,7 @@ public class BpmApprovalDetailReqVO {
     private String activityId; // 对应 BPMN XML 节点 Id
 
     @Schema(description = "流程任务编号", example = "95f2f08b-621b-11ef-bf39-00ff4722db8b")
-    private String taskId; // UserTask 对应的Id
+    private String taskId; // 对应的 UserTask Id
 
     @AssertTrue(message = "流程定义的编号和流程实例的编号不能同时为空")
     @JsonIgnore

yudao-module-bpm/yudao-module-bpm-biz/src/main/java/cn/iocoder/yudao/module/bpm/service/task/BpmTaskService.java

@@ -33,13 +33,13 @@ public interface BpmTaskService {
     PageResult<Task> getTaskTodoPage(Long userId, BpmTaskPageReqVO pageReqVO);
 
     /**
-     * 获得用户的待办任务， 多条待办任务按时间顺序返回第一条
+     * 获得用户在指定流程下，收个需要处理（待办）的任务
      *
      * @param userId 用户编号
      * @param processInstanceId 流程实例编号
      * @return 待办任务
      */
-    BpmTaskRespVO getTodoTask(Long userId, String processInstanceId);
+    BpmTaskRespVO getFirstTodoTask(Long userId, String processInstanceId);
 
     /**
      * 获得已办的流程任务分页

yudao-module-bpm/yudao-module-bpm-biz/src/main/java/cn/iocoder/yudao/module/bpm/service/task/BpmTaskServiceImpl.java

@@ -123,29 +123,28 @@ public class BpmTaskServiceImpl implements BpmTaskService {
         return new PageResult<>(tasks, count);
     }
 
-    // TODO 1： @jason：这个，赞要不要放到 BpmApprovalDetailRespVO 里？然后 BpmApprovalDetailRespVO 返回流程实例的信息 processInstance、待审批的信息 todoTask、approveNodes 审批信息列表、以及 getFormFieldsPermission 也融合进去；
-    // 类似我们现在新的 get-bpmn-model-view，就是给 bpmn xml 高亮用的。那 get-approval-detail 就是给审批第一个 tab 用的，基本信息 + 按钮 + 流程预测
-
     @Override
-    public BpmTaskRespVO getTodoTask(Long userId, String processInstanceId) {
+    public BpmTaskRespVO getFirstTodoTask(Long userId, String processInstanceId) {
-        // TODO 芋艿：暂未 review，后续再瞅瞅。先沟通完整体设计。
         if (processInstanceId == null) {
             return null;
         }
+        // 1.1 查询任务
         TaskQuery taskQuery = taskService.createTaskQuery()
                 .active()
                 .processInstanceId(processInstanceId)
                 .includeTaskLocalVariables()
                 .includeProcessVariables()
                 .orderByTaskCreateTime().asc(); // 按创建时间升序
-        HistoricProcessInstance processInstance = processInstanceService.getHistoricProcessInstance(processInstanceId);
-        BpmnModel bpmnModel = bpmProcessDefinitionService.getProcessDefinitionBpmnModel(processInstance.getProcessDefinitionId());
         List<Task> todoList = taskQuery.list();
-        // 找到子任务。用于减签
+        if (CollUtil.isEmpty(todoList)) {
+            return null;
+        }
+        // 1.2 构建子任务 Map，用于减签。key：parentTaskId
         Map<String, List<Task>> childrenTaskMap = convertMultiMap(
                 filterList(todoList, r -> StrUtil.isNotEmpty(r.getParentTaskId())),
                 Task::getParentTaskId);
-        // 获取用户信息
+
+        // 2.1 获取用户信息
         Set<Long> userIds = CollUtil.newHashSet();
         todoList.forEach(task -> {
             CollUtil.addIfAbsent(userIds, NumberUtils.parseLong((task.getAssignee())));
@@ -154,8 +153,13 @@ public class BpmTaskServiceImpl implements BpmTaskService {
         Map<Long, AdminUserRespDTO> userMap = adminUserApi.getUserMap(userIds);
         Map<Long, DeptRespDTO> deptMap = deptApi.getDeptMap(
                 convertSet(userMap.values(), AdminUserRespDTO::getDeptId));
+        // 2.2 构建 Task 列表的返回信息
+        HistoricProcessInstance processInstance = processInstanceService.getHistoricProcessInstance(processInstanceId);
+        BpmnModel bpmnModel = bpmProcessDefinitionService.getProcessDefinitionBpmnModel(processInstance.getProcessDefinitionId());
         List<BpmTaskRespVO> taskList = convertList(todoList, task -> {
             // 找到分配给当前用户，或者当前用户加签的任务（为了减签）
+            // TODO @jason：1）可以抽个小方法，判断是否是当前用户的任务；2）尽量不做取反，而是通过 ObjUtil.notEquals 。
+            //  TODO 3）(!userId.equals(NumberUtil.parseLong(task.getOwner(), null)) || BpmTaskSignTypeEnum.of(task.getScopeType()) == null) 这个判断的目的是啥？
             if (!userId.equals(NumberUtil.parseLong(task.getAssignee(), null)) &&
                     (!userId.equals(NumberUtil.parseLong(task.getOwner(), null)) || BpmTaskSignTypeEnum.of(task.getScopeType()) == null)) {
                 return null;
@@ -169,8 +173,11 @@ public class BpmTaskServiceImpl implements BpmTaskService {
                 findAndThen(deptMap, ownerUser.getDeptId(), dept -> taskVO.getOwnerUser().setDeptName(dept.getName()));
             }
             // 当前用户加签的任务. 找到它的子任务 (为了减签)
+            // TODO @json：这里最好也抽个小方法，userId.equals(NumberUtil.parseLong(task.getOwner(), null))
+            //                    && BpmTaskSignTypeEnum.of(task.getScopeType()) != null
             if (userId.equals(NumberUtil.parseLong(task.getOwner(), null))
                     && BpmTaskSignTypeEnum.of(task.getScopeType()) != null) {
+                // TODO @jason：170 到 173，和 181 到 192 这段拼接的逻辑，可以拿到 convert 里面。这样，这块 Service 更聚焦。
                 List<Task> childTasks = childrenTaskMap.get(task.getId());
                 if (CollUtil.isNotEmpty(childTasks)) {
                     taskVO.setChildren(