审批节点编辑设计文档

审批节点审批人编辑区块设计

1. 目标

在页面设计器的“创建区块 -> 其它区块”中增加“审批节点编辑”区块。页面使用者在该区块中只能修改所选审批事件工作流里审批节点的“审批人”。

审批人编辑器沿用现有审批节点的审批人交互，可编辑已有审批人的“选择用户”或“查询用户”配置，并可配置条件组、字段、比较符和值。区块不提供新增审批人的入口；已有审批人可删除和拖动排序。保存后，修改结果同步到对应工作流审批节点的审批人配置。

本设计只覆盖新插件内的创建区块能力，不修改核心、原审批插件或其它插件，也不改动现有工作流编辑页。

2. 范围

2.1 包含

在 page:addBlock 初始化器的“其它区块”分组注册“审批节点编辑”。
选择一个审批事件工作流。
只可选择同时满足 enabled=true、current=true 的工作流版本。
展示所选工作流的完整工作流画布，包括全部节点、连线、分支、节点上下游关系和结束节点。
非审批节点保持原生只读展示；所有审批节点均开放“审批人”编辑器，包括分支子树中的审批节点。
复用原审批节点的审批人字段组件和数据结构，支持编辑已有审批人的选择用户与查询用户配置、删除和拖动排序。
仅保存实际修改过的审批人，并同步到对应审批节点。
工作流发布新当前启用版本后，区块自动跟随该版本。

2.2 不包含

不为条件判断、通知、计算、数据处理、结束等非审批节点提供编辑入口。
不为审批节点展示或提供直通模式/分支模式、协商模式、多人处理顺序、处理期限及其它任何配置表单项；审批节点只有“审批人”可编辑。
不支持新增审批人。
不支持新增、删除、复制、移动节点，不支持修改节点类型、节点关系或工作流触发器。

3. 创建区块与工作流选择

页面设计者在页面设计模式下按以下入口添加区块：

创建区块
└── 其它区块
    └── 审批节点编辑

添加后先配置“审批事件工作流”。选择器的数据源只返回：

已注册的审批事件工作流类型；
enabled=true；
current=true。

区块长期保存工作流稳定标识 workflowKey，不绑定某一个工作流版本 ID。区块每次加载时都根据 workflowKey 重新查询当前且启用的版本，避免复制并启用新版本后仍编辑旧版本。

建议保存的区块配置如下：

{
  workflowKey: string;
}

没有可选工作流时，区块显示空状态；工作流被停用、删除或不存在当前启用版本时，隐藏审批人编辑器并提示重新选择工作流。

4. 工作流画布与审批人编辑

区块加载工作流后，使用现有工作流画布渲染全部节点、连线和分支，保持与工作流编辑页一致的节点顺序和分支布局。区块不额外生成审批节点列表，审批人的编辑器直接显示在对应审批节点中。

条件判断、通知、计算、数据处理、结束等非审批节点照常显示原生节点卡片，但没有编辑入口。审批节点也照常显示在画布中；其可编辑表单只保留“审批人”，不渲染节点标题、直通模式/分支模式、协商模式、多人处理顺序、处理期限或其它配置项。

每个已有审批人字段必须复用原审批节点的审批人字段组件或 schema，保持同一套数据格式和交互：

点击已有审批人字段的操作菜单，可以切换为“选择用户”或“查询用户”。
编辑为“选择用户”时，使用现有用户选择器修改审批人。
编辑为“查询用户”时，使用现有条件编辑器配置条件组、字段、比较符和值。
不显示“添加”入口，不能新增审批人；已有审批人支持编辑、删除和拖动排序。
区块不自行实现另一套用户选择、用户查询或条件表达式格式。

区块底部提供统一“保存”操作。初始加载、保存中、保存成功和保存失败状态均不改变未编辑字段的当前值。

5. 节点筛选与分支规则

区块加载并渲染所有工作流节点，但编辑资格只授予审批节点。所有审批节点（包括分支子树中的审批节点）均可编辑审批人；非审批节点始终只读，不参与保存队列。

审批节点启用分支模式时，其分支子树继续在画布中完整展示。子树中的审批节点同样可编辑审批人；该区块只提交审批人字段，不修改分支关系、节点类型或其它处理配置。

6. 数据加载与状态

6.1 工作流与节点加载

根据区块的 workflowKey 查询 enabled=true、current=true 的审批事件工作流。
加载该工作流的节点数据。
使用现有工作流画布渲染全部节点和分支。
依据节点类型标记全部可编辑审批节点，其余节点保持只读。
使用现有审批节点审批人字段组件渲染该初始值。

审批人字段及其嵌套数据结构以原审批插件为准。实现时不得根据假设重新定义“选择用户”或“查询用户”的配置结构。

6.2 页面状态

状态	展示与操作
未配置工作流	显示工作流选择器
加载中	显示加载状态，不显示旧节点数据
已加载	显示完整工作流画布；可编辑审批节点显示审批人字段和保存按钮
无可编辑审批节点	显示完整只读工作流画布，不显示保存按钮
工作流不可用	显示提示和重新选择入口
保存中	禁用保存按钮与当前编辑器，保留所有填写内容
部分保存失败	标记失败的审批节点，保留其编辑值，可再次保存

7. 保存与增量合并规则

审批人配置的保存必须是按节点、按字段的增量更新，不能把页面当前可见值直接当作完整节点配置提交。

7.1 脏数据追踪

加载后，以每个节点的原始审批人值作为比较基准。用户实际改变审批人后，才将该节点标记为待保存；没有变化的节点不发送更新请求。

比较时应按审批人字段的完整数据结构进行深度比较，确保“选择用户”与“查询用户”之间切换、条件组调整等变更都能被正确识别。

7.2 单节点请求内容

对一个已修改节点，保存请求只更新该节点，并按以下原则组装 config：

const nextConfig = {
  ...originalConfig,
  approver: changedApprover,
};

其中 approver 表示现有审批节点中审批人字段的真实存储路径。最终实现必须复用原审批插件的字段定义确认该路径；不能依赖文档示例猜测字段名或嵌套结构。

请求继续使用新插件已有的审批节点更新能力，由服务端确认节点为审批节点并执行原有审批配置校验。区块不提交节点标题或其它字段。

7.3 结果处理

某节点保存成功后，将该节点的新完整 config 作为新的原始快照，并清除其脏状态。
某节点保存失败后，保留其用户修改值和脏状态，不回滚其它已保存成功的节点。
同一节点中除审批人外的原始配置必须保持不变。
未修改审批节点不请求接口、不刷新其配置、不覆盖其值。

8. 现有代码复用与模块边界

后续实现仅在 packages/plugins/@youchaoyun/plugin-workflow-approval-editable 范围内进行，客户端代码放在 src/client，不写入 src/client-v2，不手改 dist。

现有能力	区块中的使用方式
`schemaInitializerManager`	向“创建区块 -> 其它区块”注册区块入口
`NodeDefaultView`、`Branch`、`FlowContext`	渲染完整工作流画布、节点和分支，并保留非审批节点只读状态
审批节点审批人字段组件/schema	在审批节点中原样复用“选择用户”和“查询用户”交互及其配置格式
工作流查询能力	查询当前且启用的审批事件工作流和节点
`flow_nodes:update` 及新插件服务端校验	按节点保存合并后的 `config`，继续校验审批节点与配置合法性

区块自身只负责工作流选择、完整画布渲染、节点编辑资格控制、审批人字段渲染、脏数据追踪和保存编排。它不替换全局审批节点视图，也不改变工作流编辑页或执行历史页的编辑状态。

9. 验收标准

“审批节点编辑”出现在“创建区块 -> 其它区块”。
工作流选择器只显示审批事件、当前版本且已启用的工作流。
选择工作流后，完整展示流程画布、全部节点、连线和分支关系。
条件判断、通知、计算、数据处理、结束等非审批节点可见但没有编辑入口。
每个可编辑审批节点只显示一个“审批人”编辑字段；其它审批配置项不展示也不可编辑。
已有审批人字段可编辑为“选择用户”和“查询用户”，查询用户可配置现有条件组、字段、比较符和值；不显示新增审批人的入口。
已有审批人可编辑、删除和拖动排序。
分支模式审批节点及其分支子树中的审批节点均可编辑审批人；非审批节点保持不可编辑。
保存后，修改过的审批人同步到对应工作流审批节点。
未修改节点不发送更新请求。
同一节点的其它配置在保存前后保持原样。
工作流切换为新的当前启用版本后，区块加载新版本；旧版本不再被编辑。
保存失败时，失败节点的修改值保留并可重试；已成功节点不被回滚。
不修改核心、原审批插件、其它插件或 dist 文件。

10. 测试计划

客户端

工作流列表请求固定包含审批事件类型、enabled=true 和 current=true。
工作流全部节点、连线和分支都会进入画布渲染数据。
非审批节点不生成编辑项；分支子树内的审批节点生成审批人编辑项。
审批节点只渲染审批人编辑字段，不渲染其它审批配置。
不显示新增审批人入口；已有审批人可编辑、删除和拖动排序。
审批人“选择用户”和“查询用户”沿用现有字段组件的数据回写格式。
只有审批人实际变化的节点会进入保存队列。
保存请求以原始 config 合并修改后的审批人，其它配置不丢失。
部分保存失败时，只保留失败节点的脏状态。

服务端与集成

审批节点更新继续经过现有审批节点类型、权限与配置校验。
对非审批节点发起区块保存请求会被拒绝。
保存一个审批人后，读取工作流节点可获得新审批人配置。
同节点的分支模式、协商模式、多人处理顺序等其它原有配置在保存后保持不变。
复制并启用新版本后，区块读取新当前版本；未启用的新版本不会被读取。