Salesforce Flow 现代化
模型的默认 Flow 模式基于其训练数据：循环 + 决策 + 赋值、循环内 DML、触发记录的保存后更新、用于重新计算的额外屏幕。本技能将这些模式替换为当前平台元素，并为每个元素在 examples/ 目录中提供可部署验证的元数据。
以下规则决定了大多数结果：
- 现代元素是默认选择。 循环需要声明退出条件（见下文）。当某个元素的 XML 不熟悉时，从示例文件复制其结构，而非避免使用该元素。
- 不可验证不代表不可用。 可用性取决于组织的 API 版本和下面的决策表。如果某个元素的最低 API 版本等于或低于组织的版本，则无需网络访问即可使用。部署验证是最终的检查手段。
- 每个循环和每个回退都需要解释。 在循环的描述和交付物中注明退出条件。如果没有命名的退出条件，请勿编写循环。
工作流程
将以下检查清单复制到工作笔记中并逐项勾选：
- [ ] 1. 阅读 references/org-conventions.md；列出此任务依赖的未设置槽位
- [ ] 2. 确定组织 API 版本
- [ ] 3. 对任务进行分类：构建、审计或迁移；Flow 类型、触发事件、运行上下文
- [ ] 4. 通过决策表映射每个需求；打开您使用的每个示例
- [ ] 5. 编写元数据（或构建规范）
- [ ] 6. 运行 scripts/check-flow.mjs；修复所有 ERROR，决定每个 WARNING
- [ ] 7. 当有组织可用时进行部署验证；否则将 XML 标记为未验证
- [ ] 8. 运行 references/delivery.md 中的审查清单并交付
第 1 步：约定。 如果 org-conventions.md 中的某个槽位已填写，则其优先级高于本技能的默认值。空槽位表示应用默认值，并且交付物需在“未决决策”中列出。
第 2 步：API 版本。 如果有组织，sf org display --target-org <别名> 会显示“API 版本”。如果没有组织，则使用项目 sfdx-project.json 中的 sourceApiVersion，如果该字段也不存在，则使用 61.0，并在交付物中说明。将新 Flow 的 apiVersion 设置为该版本。
第 3 步：分类。 确定是现有 Flow 还是新建 Flow。Flow 类型（屏幕流、记录触发保存前或保存后流、自动启动流、计划触发流、平台事件触发流）。触发对象和触发事件，需在打开任何示例前根据需求确定。问题是：一个已经满足条件的记录是否算作触发，还是只有变为满足条件的记录才算。同时存在“创建和更新”时，选择“仅在更新为符合条件时”会在这种创建时触发，而仅更新则不会。如果需求未说明，则需询问或陈述假设（参见 record-triggered.md）。运行上下文（用户、系统、代理）。哪些操作必须是同步的。对于屏幕流，还需确定嵌入的表面以及其输入和输出。
第 4 步：映射。 对于每个集合操作、选择列表、屏幕交互、记录更新、时序需求和集成需求，从决策表中选取对应行。阅读您将要编写的每个元素的示例文件，以及其领域引用的限制。只阅读任务涉及的领域引用。
第 5 步：编写。 元数据输出到 force-app/main/default/flows/<ApiName>.flow-meta.xml（根据项目的包目录进行调整）。命名默认值：Flow API 名称为 Object_Verb_Condition，元素名称为 Type_Purpose（例如 Get_Open_Cases、Filter_High_Priority、Transform_To_Tasks、 Dec_Is_Renewal），除非 org-conventions.md 另有规定。设置 <status>Draft</status>，除非用户明确要求激活 Flow，或者激活策略槽位要求激活。示例文件是激活的，仅仅是因为它们曾被执行过。将同一类型的所有元素集中放在文件中（拆分组会导致部署失败）。如果没有 CLI 访问权限，则提供 delivery.md 格式的构建规范。
第 6 步：检查。 对您编写或需要审查的每个 Flow 运行检查器。它只需要 Node：
node <技能目录>/scripts/check-flow.mjs --api <组织-api-版本> force-app/main/default/flows/<ApiName>.flow-meta.xml
ERROR 表示平台拒绝的传统模式或结构，必须修复。WARNING 需要做一个决策，并在交付物中说明。
第 7 步：验证。 如果有已认证的组织，请明确指定组织名称，而不是依赖 CLI 的默认组织：
sf project deploy validate --source-dir force-app/main/default/flows/<ApiName>.flow-meta.xml --target-org <别名>
根据确切的错误进行修复并重新运行。未经验证的 XML 应在交付物中明确标记为“未验证”。
第 8 步：审查并交付。 运行 delivery.md 中的审查清单。交付物末尾应包含以下信息块，每行都需填写：
模式：元数据 | 构建规范
检查器：<命令> → <n> 个错误，<n> 个警告（每个警告的决策）
部署验证：<命令和结果> | 未运行，未验证（<原因>）
状态：草稿 | 激活（<原因>）
运行上下文：<runInMode 或默认值，以及对该 Flow 类型的意义>
豁免：<E-id 和每个循环或回退的原因> | 无
未决决策：<此 Flow 依赖的未设置约定槽位> | 无
运行上下文默认值（runInMode DefaultMode）：记录触发、计划触发和平台事件触发流在没有共享的系统上下文中运行。屏幕流和自动启动流在从 UI 或 REST API 启动时以用户上下文运行，在从 Apex 或其他 Flow 调用时以调用者上下文运行。自动启动并非默认以系统上下文运行。
审计和迁移
对于现有 Flow，首先在其上运行检查器，然后对照决策表最后一列列出剩余的传统模式。在重写之前，提供 delivery.md 中定义的审计报告，按影响程度排序：首先是限制器限制，然后是安全上下文，最后是用户体验。除非有要求，否则不要修改 Flow。当被要求修改时，按顺序遵循报告中的迁移计划。描述模式，而不是创建它们的人，因为大多数传统模式在编写时是推荐的方法。 Process Builder 和工作流规则映射请参考 legacy-migration.md。
决策表
“组织 API”是拥有该元素的最低组织 API 版本（参见 Flow, Metadata API Developer Guide）。示例文件位于 examples/flows/，已在 API 61.0 上部署并运行。
| 需求 | 使用 | 元数据 | 组织 API | 示例 | 替代方案 |
|---|---|---|---|---|---|
| 保留集合中符合标准的项目 | 集合筛选器（条件或公式） | collectionProcessors，FilterCollectionProcessor | 53 | Opportunity_Create_Followup_Tasks | 循环 + 决策 + 赋值 |
| 从集合构建记录，重塑字段 | 变换，映射 | transforms | 59 | Opportunity_Create_Followup_Tasks | 循环 + 赋值构建集合 |
| 对集合求和或计数 | 变换，求和 / 计数。在保存前 Flow 中，筛选器 + 赋值 AssignCount，或使用循环求和 (E3) | transforms，inputParameters | 59（原始目标 62） | Opportunity_Create_Followup_Tasks，Account_Before_Save_Count_Contacts | 循环计数器 |
| 按键合并两个集合 | 变换，内连接，映射在同一个变换中 | transforms，JoinDefinition | 63 | Opportunity_Create_Account_Tasks_Joined | 嵌套循环，循环内获取记录 |
| 排序集合 | 集合排序（就地排序） | SortCollectionProcessor | 50 | Opportunity_Allocate_Budget_Waterfall | 在循环中手动排序 |
| 创建、更新或删除多条记录 | 对准备好的集合执行一次 DML | recordCreates inputReference | 任意 | Opportunity_Create_Followup_Tasks | 循环内 DML |
| 来自记录或选择列表的选项 | 记录 / 选择列表选项集 | dynamicChoiceSets | 任意 | Account_Order_Entry_Screen | 获取记录 + 循环构建选项 |
| 跟随输入的合计、可见性或文本 | 响应式公式，visibilityRule | formulas，屏幕字段 | 59 | Account_Order_Entry_Screen | 用于重新计算的第二个屏幕 |
| 屏幕上的输入规则 | 组件 validationRule | 屏幕 fields | 任意 | Account_Order_Entry_Screen | 屏幕后的决策跳转到错误屏幕 |
| 不离开屏幕执行服务器逻辑 | 屏幕操作 + 操作按钮 | screens.actions，triggers | 59 | Account_Check_Pipeline_Screen | 下一步，获取记录，返回 |
| 设置触发记录的字段 | 保存前 Flow，对 $Record 的赋值 | triggerType RecordBeforeSave | 任意 | Opportunity_Before_Save_Set_Next_Step | 对 $Record 的保存后更新记录 |
| 用消息阻止保存 | 自定义错误 | customErrors | 59 | Opportunity_Before_Save_Set_Next_Step | 保存后补偿 |
| 仅当相关字段更改时运行 | 进入条件，带有 ISCHANGED 的 filterFormula，“仅在更新为符合条件时” | start | 55（公式） | Opportunity_Before_Save_Set_Next_Step，Opportunity_Closed_Won_Handover | 决策作为第一个元素 |
| 用户无需等待的呼叫、电子邮件、无关 DML | 异步路径 | scheduledPaths AsyncAfterCommit | 53 | Opportunity_Closed_Won_Handover | 全部同步 |
| 在记录日期之前或之后工作 | 计划路径 | scheduledPaths RecordField | 51 | Opportunity_Closed_Won_Handover | 计划触发 Flow 轮询到期记录 |
| 对平台事件做出反应 | 平台事件触发 Flow | triggerType PlatformEvent | 49 | Order_Event_Create_Task | 为启动 Flow 逻辑编写的 Apex 触发器 |
| 暂停直到事件到达 | 使用平台事件的等待元素 | waits | 任意 | Order_Wait_For_Confirmation | 轮询 |
| 面向 Agentforce 代理的 Flow 逻辑 | 具有描述性输入和输出的自动启动 Flow | variables description | 任意 | Case_Get_Status_For_Agent | 可调用的 Apex 包装器 |
| 同一对象上 Flow 间的顺序 | 触发顺序 | triggerOrder | 54 | Opportunity_Closed_Won_Handover | 依赖创建顺序 |
| 调用 REST API | HTTP 呼叫操作 | actionCalls（Builder 生成） | 参见集成参考 | 无 | 仅为呼叫而编写的 Apex |
在保存前 Flow 中不允许使用变换（部署错误）。保存前优先级高于变换，因此触发记录上的值会保持在保存前状态，而对该记录的求和将作为 E3 下的循环进行，永远不会使用保存后变换加第二次保存。其他所有元素在拥有相应概念的每种 Flow 类型中都能工作，领域引用列出了例外情况。
豁免条件
只有满足以下条件之一时，才允许使用传统模式。在循环的 <description> 中声明为 Escape: E<n> <原因>，并在交付物中声明。
| 编号 | 允许 | 仅在以下情况下成立 |
|---|---|---|
| E1 | 循环 | 每个项目需要分别调用一个仅接受单一值的操作、子 Flow 或 Apex 插件。循环体包含该调用。 |
| E2 | 循环 | 一个项目的结果依赖于之前项目（超出求和或计数范围）：例如运行余额、分配、序列号、循环调度。 |
| E3 | 循环 | 保存前 Flow 需要求和（变换在那里不被允许）。这是有意为之，因为内存中的循环比保存后的第二次保存成本更低。计数应使用筛选器 + AssignCount 代替。 |
| E4 | 在同步路径上工作 | 同一事务中的后续元素读取该结果，或者用户必须在保存完成前看到它。 |
| E5 | 无响应式或更新的屏幕功能 | 指定的嵌入表面不支持它们：Salesforce Classic 运行时、Slack（组件集有限），或响应式文档中列为非响应式的组件。 |
| E6 | 保留现有传统模式 | 仅限审计范围：该 Flow 不在您被要求进行的更改范围内。不适用于新建或重写的 Flow。 |
以下情况不构成豁免条件：
- “我无法验证该元素是否存在于这个组织中”（规则 2 适用，因此请检查 API 版本，然后进行部署验证）。
- “我不确定 XML 格式”（复制示例）。
- “循环更简单或更清晰。”
- “每个项目的条件值”（在变换公式中使用
IF()）。 - “一次遍历完成筛选和映射”（先筛选，再变换）。
- “表面可能不支持它”（明确表面名称或将其列为未决决策，因为未知表面不符合 E5）。
- 循环内的 DML 或获取记录。任何豁免都不允许这样做。
使用最简单的足够元素。这意味着仅需筛选时就只用筛选器，选项列表固定时使用静态选项，并且不要为只有一个调用者的逻辑创建子 Flow。
在断言前进行验证
- 可用性：将组织 API 版本与决策表对比。将需要许可证的功能（如 Agentforce、Einstein、Data 360、某些编排版本）视为假设，直到组织确认它们，并在交付物中说明。
- 可能改变设计或审计发现的限制和 GA 状态：引用官方来源（help.salesforce.com、developer.salesforce.com）。不要凭记忆引用数字，因为领域引用提供了已验证的数字。
错误处理
- CLI 缺失或组织不可达：提供标记为未验证的元数据，或提供一个构建规范，并说明原因。
- 验证失败：根据确切的错误消息进行修复，重新运行检查器和验证。领域引用列出了迄今为止遇到的部署错误。
- 组织中不支持的功能（API 版本、版本、许可证）：使用决策表中最近的支持行，说明差距和豁免。
参考文档
阅读任务需要的部分：
- org-conventions.md：团队决策，优先级高于默认值。
- collections.md：筛选、排序、变换（映射、求和、计数、联接）、批量 DML、循环。
- screens.md：选项集、响应式屏幕、验证、屏幕操作、嵌入。
- record-triggered.md：进入条件、顺序、保存前与保存后、重新评估行为。
- errors.md：自定义错误用法和最佳实践。
- async.md：异步和计划路径、等待元素。
- agents.md：面向 Agentforce 代理的自动启动 Flow。
- integration.md：HTTP 呼叫操作和其他集成模式。
- legacy-migration.md：Process Builder 和工作流规则映射。
- delivery.md：交付物格式和审查清单。