docs(116393): 补充并行/人工/包容分支节点排序错误的 Bug 文档与修复计划

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Author: claude

docs/bugs/116393-并行人工包容分支节点排序错误.md

@@ -0,0 +1,33 @@
+# processNodes 接口分支节点排序异常
+
+> 编码: 116393 | 日期: 2026-05-14 | 严重度: S2 | 状态: 待确认
+
+## 现象描述
+
+`processNodes` 接口返回的节点列表中，并行分支节点（`ParallelBranchNode`）、人工分支节点（`ManualBranchNode`）、包容分支节点（`InclusiveBranchNode` / `InclusiveElseBranchNode`）等分支类节点出现在了结束节点（`EndNode`）之后，未按流程图中的节点定义顺序排序，导致前端展示的流程路径不直观。
+
+## 关键信息
+
+- **可能关联的模块**：
+  - flow-engine-starter-api（REST API 层）- 提供 `/api/cmd/record/processNodes` 接口
+  - flow-engine-framework（节点引擎）- `FlowProcessNodeService` 和 `NextNodeLoader`
+
+- **可能关联的节点类型**：
+  - `ParallelNode` / `ParallelBranchNode`（并行分支）
+  - `ManualNode` / `ManualBranchNode`（人工分支）
+  - `InclusiveNode` / `InclusiveBranchNode` / `InclusiveElseBranchNode`（包容分支）
+
+- **受影响的功能**：
+  - `processNodes` 接口的节点返回顺序
+  - 流程预览中分支节点位置展示
+
+- **初步判断**：
+  问题可能在 `FlowProcessNodeService.NextNodeLoader.fetchNextNode()`（`flow-engine-framework/src/main/java/com/codingapi/flow/service/impl/FlowProcessNodeService.java:170-192`）的递归遍历逻辑中。当前实现是深度优先递归，将每个节点 add 到一个共享 `nodeList`，分支控制节点的子分支可能在递归回溯阶段才被加入，导致顺序晚于 End 节点。需要确认递归顺序与节点 `order` 字段的关系，或在遍历完成后按节点定义顺序重新排序输出。
+
+## 期望行为
+
+`processNodes` 接口返回的节点列表应按照流程图中的节点定义顺序排序（即按 Start → 各业务节点 → 各分支控制节点 → End 的顺序），分支节点应出现在它实际所在的流程位置，而不是 End 节点之后。
+
+## 备注
+
+{待人工补充}

docs/plan/116393-bugfix-并行人工包容分支节点排序错误.md

@@ -0,0 +1,149 @@
+# 修复计划: processNodes 接口分支节点排序异常
+
+> 编码: 116393 | 日期: 2026-05-14 | 类型: Bug 修复 | 来源: bugfix | 基于: docs/bugs/116393-并行人工包容分支节点排序错误.md
+
+## 根因分析
+
+问题位于 `FlowProcessNodeService.NextNodeLoader.fetchNextNode()`（`flow-engine-framework/src/main/java/com/codingapi/flow/service/impl/FlowProcessNodeService.java:174-197`），递归逻辑是**深度优先（DFS）**：
+
+```java
+this.nodeList.add(processNode);                                    // 先 add 当前
+List<IFlowNode> nextNodes = workflow.nextNodes(flowNode);
+List<IFlowNode> selected = selectBranchNodes(nextNodes, ...);
+this.fetchNextNode(flowSession.updateSession(flowNode), selected); // 再递归
+```
+
+对并行（`ParallelNode`）/ 人工（`ManualNode`）/ 包容（`InclusiveNode`，当多分支同时满足）等"必须走多条分支"的控制节点，遍历会**先把第一条分支一路走到 End**，再回溯处理其它分支：
+
+```
+顺序: Start → ParallelNode → Branch_1 → Approval_A → ParallelEnd → End
+           ↑ DFS 一路走到底
+      → (回溯) Branch_2 → Approval_B   ← 此时才 add，已经在 End 之后
+      → (回溯) Branch_3 → Approval_C
+```
+
+`NextNodeLoader.loadNextNode()`（`FlowProcessNodeService.java:229-240`）最后只做了 `isDisplay` 过滤和"重复 nodeId 去重"，**没有按节点定义顺序重排**，因此最终对外返回的列表顺序就是 DFS 的访问顺序：`[Start, Approval_A, ParallelEnd, End, Approval_B, Approval_C]`，分支节点错位在 End 之后。
+
+而条件分支（`ConditionNode`）不受影响，因为 `selectBranchNodes`（`FlowProcessNodeService.java:199-227`）会把条件分支收敛到单条路径，DFS 不会回溯到其它分支。
+
+证据：
+- `FlowProcessNodeService.java:174-197` DFS 递归未做后置排序
+- `FlowProcessNodeService.java:199-227` 当前 `selectBranchNodes` 只覆盖 `ConditionBranchNode` / `InclusiveBranchNode` 等 4 个类型，且对 if 命中的情况会单选一条
+- `ParallelBranchNode.filterBranches`（`ParallelBranchNode.java:50-65`）返回全部分支节点（不收敛），由此走 DFS 全遍历
+- `ManualNode.filterBranches`（`ManualNode.java:45-54`）在无 advice 时返回全部分支
+- 节点的"定义顺序"权威来源是 `Workflow.nodes`（`Workflow.java:108、162-164`），它是按 `WorkflowBuilder.addNode` 顺序追加的有序 `List`
+
+## 影响面评估
+
+- 直接修改的 Maven 模块: `flow-engine-framework`
+- 可能回归的场景:
+  - 含并行节点（`ParallelNode`）的流程预览顺序
+  - 含人工节点（`ManualNode`）的流程预览顺序
+  - 含包容节点（`InclusiveNode`）多分支同时命中场景
+  - 普通直线流程 / 条件分支流程（应当保持原顺序，因为 DFS 顺序本就与定义顺序一致）
+  - 已运行流程（含历史节点 + 未来节点混合返回的场景）
+- 是否需要数据迁移/配置变更: 否
+
+## 新增文件
+
+| 文件路径 | 用途说明 |
+|----------|----------|
+| (无) | 排序逻辑直接复用 `Workflow.nodes` 索引，无需新增类 |
+
+## 修改文件
+
+| 文件路径 | 修改内容 |
+|----------|----------|
+| `flow-engine-framework/src/main/java/com/codingapi/flow/service/impl/FlowProcessNodeService.java` | 在 `NextNodeLoader.loadNextNode()` 完成 DFS 与去重后，按 `workflow.getNodes()` 索引对结果重排，让"未来节点"按节点定义顺序输出。历史节点（buildHistoryNodes 返回）的顺序在 `processNodes()` 中独立保留，不受此处影响 |
+
+## 关键代码修改
+
+`NextNodeLoader.loadNextNode()` 当前实现：
+
+```java
+public List<ProcessNode> loadNextNode(FlowSession flowSession) {
+    this.fetchNextNode(flowSession, List.of(this.currentNode));
+    List<ProcessNode> displayNodes = nodeList.stream().filter(ProcessNode::isDisplay).toList();
+    List<ProcessNode> processNodeList = new ArrayList<>();
+    for (ProcessNode node : displayNodes) {
+        if (!processNodeList.contains(node)) {
+            processNodeList.add(node);
+        }
+    }
+    return processNodeList;
+}
+```
+
+修改为：
+
+```java
+public List<ProcessNode> loadNextNode(FlowSession flowSession) {
+    this.fetchNextNode(flowSession, List.of(this.currentNode));
+    List<ProcessNode> displayNodes = nodeList.stream().filter(ProcessNode::isDisplay).toList();
+    List<ProcessNode> processNodeList = new ArrayList<>();
+    for (ProcessNode node : displayNodes) {
+        if (!processNodeList.contains(node)) {
+            processNodeList.add(node);
+        }
+    }
+    return sortByWorkflowNodeOrder(processNodeList);
+}
+
+private List<ProcessNode> sortByWorkflowNodeOrder(List<ProcessNode> processNodes) {
+    List<IFlowNode> workflowNodes = workflow.getNodes();
+    Map<String, Integer> indexMap = new HashMap<>();
+    for (int i = 0; i < workflowNodes.size(); i++) {
+        indexMap.put(workflowNodes.get(i).getId(), i);
+    }
+    // 未在 workflow.nodes 顶层注册的节点（如嵌套子节点）放到末尾，相对顺序保持稳定
+    return processNodes.stream()
+            .sorted(Comparator.comparingInt(
+                    n -> indexMap.getOrDefault(n.getNodeId(), Integer.MAX_VALUE)))
+            .toList();
+}
+```
+
+要点说明：
+
+1. **以 `Workflow.nodes` 索引为权威排序键**：该列表在 `WorkflowBuilder.addNode()` 中按调用顺序追加，对应前端流程图保存时的节点顺序，是"定义顺序"的事实依据
+2. **稳定排序**：`Comparator.comparingInt` 配合 `Stream.sorted` 是稳定排序，索引相同（如未注册节点）的元素保持 DFS 顺序，不会引入新的不确定性
+3. **不动 `fetchNextNode` 内部逻辑**：递归 add 顺序保持原状，仅在最终输出前做一次重排。避免影响 `processNode.setCurrentState()` 等中间状态判定
+4. **不影响历史节点**：`processNodes()` 在调用 `loadNextNode` 之前已经把历史节点 add 到 `this.nodeList` —— 这里返回的 `processNodeList` 只是"未来节点"部分，外层 `nodeList.addAll(nextNodes)` 仍把它们追加在历史节点之后
+
+## 回归验证
+
+| 验证项 | 说明 |
+|--------|------|
+| 并行分支顺序 | 构造 Start → ParallelNode（含 3 个分支，每分支 1 个 Approval）→ ParallelEnd → End 的流程，调用 `processNodes`，验证返回顺序为 Start → Approval_A → Approval_B → Approval_C → ParallelEnd → End |
+| 人工分支顺序 | 构造含 `ManualNode` 的流程（无 advice，返回全部分支），验证分支节点按定义顺序排列 |
+| 包容分支顺序 | 构造含 `InclusiveNode` 多分支同时命中的场景，验证分支节点按定义顺序排列 |
+| 条件分支不回归 | 验证 107562 修复的条件分支单路径选择行为依旧正确（包括 if 命中和 fallback else 两种情况） |
+| 直线流程不回归 | 普通 Start → Approval → End 流程顺序不变 |
+| 历史节点混合 | 已运行流程预览：历史节点（按时间顺序）排在前，未来节点（按定义顺序）排在后 |
+| 编译验证 | `mvn -pl flow-engine-framework -am compile` |
+| 既有测试不回归 | `mvn -pl flow-engine-framework test` |
+
+具体验证命令：
+
+```bash
+mvn -pl flow-engine-framework -am compile
+mvn -pl flow-engine-framework test
+```
+
+## 执行顺序
+
+1. 创建 git worktree（按项目规范，所有开发必须在 worktree 中进行）
+2. 修改 `flow-engine-framework/src/main/java/com/codingapi/flow/service/impl/FlowProcessNodeService.java`：
+   - 增加 `java.util.Comparator` / `java.util.HashMap` / `java.util.Map` 的 import（如未引入）
+   - 在 `NextNodeLoader` 类中新增私有方法 `sortByWorkflowNodeOrder(List<ProcessNode>)`
+   - 修改 `loadNextNode(FlowSession)` 的 `return` 语句，最后调用 `sortByWorkflowNodeOrder`
+3. 执行 `mvn -pl flow-engine-framework -am compile` 编译验证
+4. 执行 `mvn -pl flow-engine-framework test` 完整回归
+5. 人工审核后提交 PR（目标分支：dev）
+
+## 注意事项
+
+- 严格遵循 CLAUDE.md 中的开发规范：本变更必须在 git worktree 中进行，PR 目标为 `dev` 分支
+- **依赖 107562 的修复**：本计划基于"selectBranchNodes 已存在"的代码版本撰写。若所在分支尚未合并 107562，需先合并或同源开发，避免 `loadNextNode` 区域出现冲突
+- 不修改运行时分支选择路径（`FlowSession.matchNextNodes` / 各 `filterBranches` 实现），仅作用于 `processNodes` 预览路径
+- `Workflow.nodes` 列表中通常仅包含顶层节点；嵌套在 `IBlockNode.blocks` 中的子节点（如 `ConditionBranchNode`）会被 `indexMap` 视为未注册节点排到末尾。鉴于这些子节点本身不是 `IDisplayNode`，已在 `loadNextNode` 上游被过滤，不会出现在最终结果中