WeDataSphere
diff --git a/‎docs/1.21.0/design/工作流分支节点_设计.md‎
Lines changed: 106 additions & 174 deletions b/‎docs/1.21.0/design/工作流分支节点_设计.md‎
Lines changed: 106 additions & 174 deletions
@@ -1,188 +1,120 @@
 # 工作流分支节点设计文档
 
 ## 1. 文档信息
-- 版本：1.20.0
+- 版本：1.21.0
 - 状态：已更新
-- 实现方案：节点属性 `branch.rules` 驱动
+- 设计范围：DSS 发布层分支适配 + 语义对齐要求
 
 ## 2. 设计结论
-当前实现采用：
-- 分支节点类型：`workflow.branch`
-- 规则配置位置：分支节点属性 `branch.rules`
-- 上游变量映射位置：上游节点属性 `branch.output.mapping`
-- 运行时控制：记录选中的目标节点，仅放行该下游，其余直接下游跳过
-
-## 3. 核心架构
-### 3.1 元数据层
-通过节点元数据表下发分支节点和相关属性，不新增分支专用业务表。
-
-涉及元数据：
-- `workflow.branch` 节点定义
-- `branch.rules` 节点 UI 属性
-- `branch.output.mapping` 节点 UI 属性
-
-实现位置：
-- `db/dss_dml.sql`
-
-### 3.2 运行时链路
-1. 用户通过工作流执行接口提交流程。
-2. `FlowJobNodeParser` 为每个节点创建 runner，并把共享 `flow_var_map` 注入节点参数。
-3. 上游普通节点成功后，`FlowEntranceJob` 从结果集提取变量并回写到共享 `flow_var_map`。
-4. 分支节点执行时，`BranchNodeRunner` 读取 `branch.rules`，计算命中的目标下游节点。
-5. `FlowEntranceJob.recordBranchSelection` 记录分支节点最终选中的 target。
-6. `FlowDependencyResolverImpl` 解析 pending 节点时：
-   - 命中的直接下游转为 `scheduled`
-   - 未命中的兄弟直接下游转为 `skipped`
-
-## 4. 关键实现类
-### 4.1 执行入口
-文件：
-- `dss-flow-execution-server/.../restful/FlowEntranceRestfulApi.java`
-
-职责：
-- 接收执行请求
-- 提交流程到 `entranceServer`
-
-说明：
-- 不直接决定分支下游是否执行
-- 仅是工作流执行入口
-
-### 4.2 节点解析
-文件：
-- `dss-flow-execution-server/.../job/parser/FlowJobNodeParser.scala`
-
-职责：
-- 初始化共享 `flow_var_map`
-- 为 `workflow.branch` 绑定 `BranchNodeRunner`
-- 为普通节点绑定 `DefaultNodeRunner`
-
-### 4.3 变量收集
-文件：
-- `dss-flow-execution-server/.../job/FlowEntranceJob.scala`
-
-职责：
-- 在上游节点成功后采集输出变量
-- 支持读取上游结果集变量
-- 支持 `branch.output.mapping` 映射别名
-
-### 4.4 规则解析
-文件：
-- `dss-flow-execution-server/.../utils/BranchExpressionUtils.scala`
-
-职责：
-- 判断节点是否为分支节点
-- 读取 `branch.rules`
-- 将规则文本解析为 `condition -> targetName`
-- 计算条件表达式
-
-当前规则：
-- 多行规则
-- 按顺序匹配
-- 支持默认规则关键字：`default`、`else`、`*`
-
-### 4.5 分支节点执行
-文件：
-- `dss-flow-execution-server/.../node/BranchNodeRunner.scala`
-
-职责：
-- 读取共享变量上下文
-- 解析并执行 `branch.rules`
-- 将命中的 target 记录到 `FlowEntranceJob`
-- 自身不提交 Linkis 作业
-- 成功后触发后续调度
-
-### 4.6 下游节点放行与跳过
-文件：
-- `dss-flow-execution-server/.../resolver/FlowDependencyResolverImpl.scala`
-
-职责：
-- 判断某个 pending 节点是否是分支命中的 target
-- 命中则 `scheduled`
-- 未命中则 `skipped`
-
-这是“控制下游节点要不要执行”的真正实现位置。
-
-### 4.7 保存校验
-文件：
-- `dss-workflow-server/.../service/impl/DSSFlowServiceImpl.java`
-
-职责：
-- 保存工作流时校验分支节点配置
-
-校验规则：
-- 至少两条直接出边
-- `branch.rules` 非空
-- 规则中的目标节点名必须是直接下游节点名
-
-## 5. 规则语法
-### 5.1 基本格式
-```text
-条件=下游节点名
+本版本采用“DSS 规则配置 + 发布为 decision + 语义对齐 DSS FlowExecution”的方案：
+- DSS 节点类型保持 `workflow.branch`。
+- 规则配置保持 `branch.rules`。
+- 发布到 Schedulis 时分支节点 `.job` 转换为 `type=decision`。
+- Schedulis 运行期必须按 DSS FlowExecution 语义判定分支下游。
+
+## 3. 总体架构
+
+### 3.1 关键模块
+- `BranchWorkflowRewriteConverter`
+  - 提取分支规则并补充 route 元数据。
+- `BranchRouteJobTuning`
+  - 将分支节点类型调优为 `decision`。
+- `LinkisJobConverter`
+  - 生成 decision 节点属性：`condition.N/on.success.N/on.failure.N`。
+- `AzkabanDssJobType`
+  - 仅保留动态变量提取与 props 输出，不承担 guard/route 分支裁剪。
+
+### 3.2 架构示意图
+```mermaid
+flowchart LR
+    A[workflow.branch + branch.rules] --> B[BranchWorkflowRewriteConverter]
+    B --> C[LinkisJobConverter]
+    C --> D[BranchRouteJobTuning]
+    D --> E[type=decision .job]
+    E --> F[Schedulis]
+    F --> G[按 DSS FlowExecution 语义调度]
+```
+
+## 4. 核心设计
+
+### 4.1 决策节点发布设计
+分支节点发布规则：
+1. 读取 `wds.branch.route.rule.text`。
+2. 按 `;` 切分规则。
+3. 每条规则按最后一个 `=` 切分条件与目标。
+4. 输出：
+   - `condition.N`
+   - `on.success.N`
+   - `on.failure.N=`
+5. `default=xxx` 转换为 `condition.N=true`。
+
+### 4.2 字段过滤设计
+当 `type=decision` 时，不输出 linkis 专属字段：
+- `linkis.version`
+- `linkistype`
+- `command`
+
+### 4.3 分支语义对齐设计（重点）
+对齐依据：DSS `FlowDependencyResolverImpl`。
+
+关键语义：
+1. 父节点未全部完成 -> 等待。
+2. 存在分支父节点未命中当前节点 -> `skip`。
+3. 所有分支父节点命中且普通父节点完成无失败 -> 可执行。
+4. 普通父节点失败 -> 失败链路。
+
+特别说明：
+- 混合上游场景（分支未命中 + 普通父成功）必须 `skip`。
+- 该语义优先于“任一父成功即可执行”。
+
+### 4.4 状态判定流程图
+```mermaid
+flowchart TD
+    A[候选节点X] --> B{父节点是否全部完成?}
+    B -- 否 --> W[等待]
+    B -- 是 --> C{存在普通父失败?}
+    C -- 是 --> F[失败链路]
+    C -- 否 --> D{存在分支父未命中X?}
+    D -- 是 --> S[Skip]
+    D -- 否 --> E[Scheduled/Execute]
 ```
 
+## 5. 关键场景补充
+
+### 5.1 编号10场景（混合父节点）
+- 条件：节点 X 有普通父 A（成功）和分支父 B（未命中 X）。
+- 结果：X 必须 `skip`。
+- 原因：分支未命中判定优先，严格对齐 DSS FlowExecution。
+
 ### 5.2 示例
+输入：
 ```text
-amount>100=节点A
-amount<10=节点B
-default=节点C
+branch.rules = b==200=sql_1345;b<50=sql_9000
 ```
 
-### 5.3 语义
-- 条件成立时，选择右侧节点名对应的直接下游节点
-- 默认规则在前面所有规则都未命中时生效
-- 若无规则命中且无默认规则，则抛异常
-
-## 6. 变量模型
-### 6.1 共享变量
-共享变量保存在 `flow_var_map`。
-
-来源包括：
-- 工作流全局属性
-- 工作流启动参数
-- 上游节点结果集变量
-- `branch.output.mapping` 映射后的别名变量
-
-### 6.2 上游结果集约束
-当前版本主要支持：
-- 单结果集
-- 简单列名到值的映射
-
-建议上游输出示例：
-```sql
-select sum(price) as amount from order_info
+输出：
+```properties
+type=decision
+condition.1=b==200
+on.success.1=sql_1345
+on.failure.1=
+condition.2=b<50
+on.success.2=sql_9000
+on.failure.2=
 ```
 
-## 7. 前端设计
-当前版本前端以节点属性表单为主，不再以边配置为主。
-
-用户操作方式：
-1. 拖入分支节点
-2. 连出多个下游节点
-3. 在节点属性中填写 `branch.rules`
-4. 保存并执行
-
-说明：
-- 分支规则配置入口应放在分支节点属性面板中
-- 不要求边级条件配置弹窗作为正式入口
-
-## 8. 非目标设计
-以下方案已废弃：
-- `dss_workflow_branch` 表
-- `BranchNodeService`
-- `BranchNodeMapper`
-- `BranchNodeConfig` 独立实体
-- `POST/PUT/GET /workflow/node/branch/...` 配置接口
-- `SpEL` 复杂逻辑引擎依赖
-- `BranchNodeSkipStrategy` 独立跳过策略实现
-
-## 9. 兼容性
-- 不含分支节点的现有工作流执行逻辑不变
-- 分支节点仅影响自身直接下游
-- 旧版边条件配置不作为正式能力保留
-
-## 10. 验证要点
-- 分支节点必须能读取上游变量
-- 规则文本必须正确映射到直接下游节点名
-- 命中的 target 会执行
-- 同级未命中的 target 会跳过
-- 无命中且无默认规则时报错
+## 6. 实现约束
+1. 不再依赖 DSS `guard` 运行时裁剪语义来决定下游执行。
+2. 不允许 Schedulis 语义偏离 DSS 矩阵规则。
+3. jobtype 仅负责动态变量进入 props，供 decision 条件使用。
+
+## 7. 验证要点
+1. 分支节点发布后是 `type=decision`。
+2. decision 属性展开正确。
+3. 混合上游编号10场景验证为 `skip`。
+4. 与 DSS FlowExecution 语义逐条对齐通过。
+
+## 8. 非目标
+- 不引入新的分支 DSL。
+- 不新增分支数据库模型。
+- 不改动分支节点前端配置入口。