Merge pull request #130 from codingapi/dev

Dev

Author: xlorne

docs/changes/024982-processNodes-data-fix.md

@@ -0,0 +1,97 @@
+# processNodes 数据返回修复
+
+> 编码: 024982 | 日期: 2026-04-28 | 调整类型: Bug修复 | 状态: 草稿
+
+## 调整背景
+
+FlowService 下的 processNodes 函数在返回的数据过程中存在多个问题，影响流程节点展示的准确性。
+
+## 现状描述
+
+### 问题1：历史记录未按 nodeId 合并（核心问题）
+
+`FlowProcessNodeService.processNodes()` 中，为每条 FlowRecord 单独创建一个 ProcessNode：
+
+```java
+// FlowProcessNodeService.java:94-96, 107-109
+for (FlowRecord historyRecord : historyRecords) {
+    ProcessNode processNode = new ProcessNode(historyRecord, this.workflow);
+    nodeList.add(processNode);
+}
+```
+
+**影响**：当同一节点存在多条 FlowRecord（如多人审批场景），同一 nodeId 会生成多个 ProcessNode，每个仅包含一个审批人，导致前端重复展示同一节点。
+
+### 问题2：`isDone()` 分支将 TODO 记录错误标记为历史节点
+
+当 `flowRecord.isDone()` 为 true 时，加载该 processId 下的**所有**记录：
+
+```java
+// FlowProcessNodeService.java:93
+List<FlowRecord> historyRecords = flowRecordService.findFlowRecordByProcessId(this.flowRecord.getProcessId());
+```
+
+**影响**：多人审批场景下，已审批完的用户的 `isDone()` 为 true，但同一 processId 下其他用户的记录可能仍在 TODO 状态。这些 TODO 记录会被错误标记为 `STATE_HISTORY`（因为构造函数固定设置 `state = STATE_HISTORY`）。
+
+### 问题3：`equals()` 与 `hashCode()` 不一致
+
+```java
+// ProcessNode.java:108-119
+public boolean equals(Object target) {
+    // 只比较 nodeId
+    return targetNode.getNodeId().equals(this.getNodeId());
+}
+
+public int hashCode() {
+    // 包含 nodeId, nodeName, nodeType, state, operators
+    return Objects.hash(nodeId, nodeName, nodeType, state, operators);
+}
+```
+
+**影响**：违反 Java equals/hashCode 契约。两个 nodeId 相同但 state/operators 不同的 ProcessNode 会 `equals` 但 `hashCode` 不同，在 HashSet/HashMap 中使用时会导致数据丢失。同时影响 `NextNodeLoader` 中的去重逻辑正确性。
+
+## 目标状态
+
+1. 相同 nodeId 的历史记录合并为一个 ProcessNode，operators 列表包含所有审批人
+2. TODO 状态的记录不被错误标记为历史节点
+3. 修复 equals/hashCode 一致性，确保去重逻辑正确
+
+## 调整范围
+
+### 范围内
+
+- `FlowProcessNodeService.processNodes()` — 历史记录合并逻辑
+- `FlowProcessNodeService` 内部类 `NextNodeLoader` — 去重逻辑
+- `ProcessNode` — equals/hashCode 修复、新增合并方法
+- `ProcessNode(FlowRecord, Workflow)` 构造函数 — 调整 state 赋值逻辑
+
+### 范围外
+
+- FlowRecordService 接口（不修改查询方法签名）
+- REST API 层（接口不变）
+- 前端展示逻辑
+
+## 约束与前提
+
+- 不改变 `List<ProcessNode>` 返回类型
+- 保持现有测试用例通过
+- 修改后需执行编译验证
+
+## 不调整的影响
+
+- 多人审批节点在前端重复显示
+- 已完成流程的节点状态可能不准确
+- 在 HashSet 中使用 ProcessNode 可能丢失数据
+
+## 相关资料
+
+- `FlowProcessNodeService.java` (flow-engine-framework)
+- `ProcessNode.java` (flow-engine-framework)
+- `FlowRecordService.java` (flow-engine-framework)
+- `FlowDetailServiceTest.java` (flow-engine-framework)
+
+## 备注
+
+涉及文件：
+- `flow-engine-framework/src/main/java/com/codingapi/flow/service/impl/FlowProcessNodeService.java`
+- `flow-engine-framework/src/main/java/com/codingapi/flow/pojo/response/ProcessNode.java`

docs/components/flow-engine-framework_FlowScriptContext.md

@@ -22,7 +22,7 @@ description: Groovy 脚本运行时的 $bind 上下文对象，为脚本提供
 <dependency>
     <groupId>com.codingapi.flow</groupId>
     <artifactId>flow-engine-framework</artifactId>
-    <version>0.0.28</version>
+    <version>0.0.29</version>
 </dependency>
 ```
 

docs/components/flow-engine-framework_GatewayContext.md

@@ -22,7 +22,7 @@ GatewayContext 是框架内部获取流程操作人（IFlowOperator）数据的
 <dependency>
     <groupId>com.codingapi.flow</groupId>
     <artifactId>flow-engine-framework</artifactId>
-    <version>0.0.28</version>
+    <version>0.0.29</version>
 </dependency>
 ```
 

docs/components/flow-engine-framework_GroovyScriptBind.md

@@ -22,7 +22,7 @@ GroovyScriptBind 是脚本编写者在流程 Groovy 脚本中通过 `$bind` 变
 <dependency>
     <groupId>com.codingapi.flow</groupId>
     <artifactId>flow-engine-framework</artifactId>
-    <version>0.0.28</version>
+    <version>0.0.29</version>
 </dependency>
 ```
 

docs/components/flow-engine-framework_GroovyScriptRequest.md

@@ -22,7 +22,7 @@ GroovyScriptRequest 是流程 Groovy 脚本中 `request` 参数的实际类型
 <dependency>
     <groupId>com.codingapi.flow</groupId>
     <artifactId>flow-engine-framework</artifactId>
-    <version>0.0.28</version>
+    <version>0.0.29</version>
 </dependency>
 ```
 

docs/components/flow-engine-framework_GroovyWorkflowRequest.md

@@ -22,7 +22,7 @@ GroovyWorkflowRequest 用于工作流级别（非会话级别）的脚本场景
 <dependency>
     <groupId>com.codingapi.flow</groupId>
     <artifactId>flow-engine-framework</artifactId>
-    <version>0.0.28</version>
+    <version>0.0.29</version>
 </dependency>
 ```
 

docs/components/flow-engine-framework_IFlowOperator.md

@@ -22,7 +22,7 @@ IFlowOperator 是流程引擎中对参与流程的用户（审批人、创建者
 <dependency>
     <groupId>com.codingapi.flow</groupId>
     <artifactId>flow-engine-framework</artifactId>
-    <version>0.0.28</version>
+    <version>0.0.29</version>
 </dependency>
 ```
 

docs/components/flow-engine-framework_RepositoryHolderContext.md

@@ -22,7 +22,7 @@ RepositoryHolderContext 是流程引擎运行时的基础设施注册中心。
 <dependency>
     <groupId>com.codingapi.flow</groupId>
     <artifactId>flow-engine-framework</artifactId>
-    <version>0.0.28</version>
+    <version>0.0.29</version>
 </dependency>
 ```
 

docs/components/flow-engine-framework_ScriptRegistryContext.md

@@ -22,7 +22,7 @@ ScriptRegistryContext 是流程引擎中所有默认 Groovy 脚本的注册中
 <dependency>
     <groupId>com.codingapi.flow</groupId>
     <artifactId>flow-engine-framework</artifactId>
-    <version>0.0.28</version>
+    <version>0.0.29</version>
 </dependency>
 ```
 

docs/plan/024982-change-processNodes-data-fix.md

@@ -0,0 +1,100 @@
+# 调整计划: processNodes 数据返回修复
+
+> 编码: 024982 | 日期: 2026-04-28 | 类型: 调整任务 | 来源: change | 基于: docs/changes/024982-processNodes-data-fix.md
+
+## 调整目标
+
+修复 `processNodes()` 在返回流程节点数据时的三个问题：历史记录未按 nodeId 合并、TODO 记录被错误标记为历史、equals/hashCode 不一致。
+
+## 影响面（基于指令结果）
+
+- 涉及 Maven 模块: `flow-engine-framework`
+- 直接依赖者: `flow-engine-starter-api`（仅引用 ProcessNode 类型作为返回值，无逻辑变更）
+- 外部 API / 公共组件影响: 否，REST API 接口 `POST /api/cmd/record/processNodes` 签名和返回结构不变
+
+## 分步策略
+
+将调整拆分为 3 步，每步可独立通过编译验证：
+
+1. **Step 1**: 修复 `ProcessNode` 的 equals/hashCode 一致性，新增合并方法
+2. **Step 2**: 修复 `FlowProcessNodeService.processNodes()` 的历史记录合并逻辑与 TODO 过滤
+3. **Step 3**: 编译验证 + 现有单测通过
+
+## 新增文件
+
+| 文件路径 | 用途说明 |
+|----------|----------|
+
+（无新增文件）
+
+## 修改文件
+
+| 文件路径 | 修改内容 |
+|----------|----------|
+| `flow-engine-framework/src/main/java/com/codingapi/flow/pojo/response/ProcessNode.java` | 1. `hashCode()` 改为只使用 `nodeId`，与 `equals()` 一致<br>2. 新增 `addOperator(FlowOperatorBody)` 方法，支持向已有 ProcessNode 追加审批人 |
+| `flow-engine-framework/src/main/java/com/codingapi/flow/service/impl/FlowProcessNodeService.java` | 1. 新增 `buildHistoryNodes(List<FlowRecord>)` 方法，按 nodeId 合并历史记录<br>2. `processNodes()` 中 `isDone()` 分支：过滤仅保留已办记录，使用合并方法<br>3. `processNodes()` 中非 `isDone()` 分支：使用合并方法处理 beforeRecords |
+
+## 移除文件（若有）
+
+| 文件路径 | 移除原因 |
+|----------|----------|
+
+（无移除文件）
+
+## 兼容性与迁移
+
+- 保留的 API / 行为: `List<ProcessNode>` 返回类型不变；`ProcessNode` 的公共字段不变；REST API 端点签名不变
+- 破坏性变更: `ProcessNode.hashCode()` 返回值变化（之前包含全部字段，现在只包含 nodeId）。如果下游代码将 ProcessNode 存入 HashMap/HashSet，行为会更正（之前因 equals/hashCode 不一致可能导致数据丢失）
+- 数据/配置迁移: 无
+
+## 核验机制
+
+| 验证项 | 说明 |
+|--------|------|
+| 编译 | `mvn compile` 通过 |
+| 单测 | `flow-engine-framework` 模块现有测试通过 |
+| 打包 | `mvn package` 通过 |
+| 行为回归 | `FlowDetailServiceTest.processNodes()` 测试用例通过 |
+
+具体验证命令：
+
+```bash
+mvn -pl flow-engine-framework -am compile
+mvn -pl flow-engine-framework -am test
+mvn package
+```
+
+## 执行顺序
+
+### Step 1: 修复 ProcessNode equals/hashCode + 新增合并方法
+
+1. **修改** `flow-engine-framework/src/main/java/com/codingapi/flow/pojo/response/ProcessNode.java`
+   - `hashCode()` 方法：改为 `return Objects.hash(nodeId);`（与 equals 一致）
+   - 新增 `addOperator(FlowOperatorBody operator)` 方法：向 `this.operators` 追加审批人
+
+### Step 2: 修复 FlowProcessNodeService 历史记录合并与 TODO 过滤
+
+2. **修改** `flow-engine-framework/src/main/java/com/codingapi/flow/service/impl/FlowProcessNodeService.java`
+   - 新增私有方法 `buildHistoryNodes(List<FlowRecord> records)`：
+     - 使用 `LinkedHashMap<String, ProcessNode>` 按 nodeId 分组
+     - 遍历 records，nodeId 相同时调用 `addOperator()` 追加审批人
+     - 返回合并后的 `List<ProcessNode>`
+   - 修改 `processNodes()` 方法第 92-103 行（`isDone()` 分支）：
+     - 使用 `records.stream().filter(FlowRecord::isDone)` 过滤仅保留已办记录
+     - 用 `buildHistoryNodes()` 替代原来的逐条 new ProcessNode
+   - 修改 `processNodes()` 方法第 106-110 行（非 `isDone()` 分支）：
+     - 用 `buildHistoryNodes()` 替代原来的逐条 new ProcessNode
+
+### Step 3: 编译验证
+
+3. **运行** `mvn -pl flow-engine-framework -am compile` 验证编译通过
+4. **运行** `mvn -pl flow-engine-framework -am test` 验证单测通过
+
+## 现状-目标对照表
+
+| 现状位置 | 现状内容 | 目标变更 |
+|----------|----------|----------|
+| `ProcessNode.java:117-119` | `hashCode` 使用 `nodeId, nodeName, nodeType, state, operators` | 改为只使用 `nodeId`，与 `equals` 一致 |
+| `ProcessNode.java` | 无合并方法 | 新增 `addOperator(FlowOperatorBody)` 方法 |
+| `FlowProcessNodeService.java:93-97` | `isDone()` 分支加载所有记录逐条创建 ProcessNode | 过滤仅已办记录 + 按 nodeId 合并 |
+| `FlowProcessNodeService.java:106-110` | 非 `isDone()` 分支逐条创建 ProcessNode | 按 nodeId 合并 |