service-omni-queue-deploy

service-omni-queue-deploy

验证是否存在一个 Group（Type='Queue'），且它通过 QueueSobject 绑定到请求的可路由 sObject；如果已有，则复用。使用 --create-if-missing 时，如果没有绑定，则通过 Metadata API 创建队列（Group + QueueSobject），并可选择将其 QueueRoutingConfigId 与调用方指定的 QRC 对齐。此技能根据队列的 QueueSobject.SobjectType 绑定来发现队列，而非根据名称，因为实际的 org 中队列名称并不一致（CaseQueue、messagingqueue、Omni_Demo_Cases_Queue）——队列与其支持的路由之间的功能性关联是绑定，而非 DeveloperName。该技能由 service-omni-channel-setup-coordinate 调用；队列成员资格由独立的叶节点 service-omni-queue-members-assign 处理；它对齐的 QRC 来自 service-omni-queue-routing-config-deploy。

输入

bash scripts/verify-and-align.sh <org-alias> [Case|Incident|MessagingSession|VoiceCall] [routing_config_dn] [queue_developer_name] [--create-if-missing]
# create + bind a Voice queue on a fresh org:
bash scripts/verify-and-align.sh myorg VoiceCall Voice_Routing_Config "" --create-if-missing

• org-alias（必填）。
• sobject_type（可选，默认值为 Case）。
• routing_config_dn（可选）——传入时，强制与该 QRC 对齐；未传入时，若为 Case，则默认使用 Case_Routing_Config；若为其他 sObject，则技能会报告现有绑定，不强制对齐。
• queue_developer_name（可选的第 4 个位置参数）——要操作的指定队列，或使用 --create-if-missing 时要创建的队列名称。
• --create-if-missing（标志，或 QUEUE_CREATE_IF_MISSING=1）——没有绑定队列时，通过 Metadata API 创建队列；标签默认使用 DeveloperName 的空格分隔形式（可通过 QUEUE_LABEL 覆盖）。

前置条件与安全

• 目标 org 已通过 sf CLI（My Domain URL）完成身份验证，具有 Service Cloud 许可证，且 sf CLI 版本 ≥ 2.139.6。
• 目标 sObject 已在 org 上启用——任何写入操作之前都会通过 EntityDefinition 验证；未启用的 sObject 会阻止执行，并提供功能启用的点击路径（Incident 对应 Incident Management，MessagingSession 对应 Enhanced Messaging）。
• 提供 routing_config_dn 时，该 QRC 必须已存在（通过 DeveloperName 解析）；否则运行会被阻止，并提示使用 service-omni-queue-routing-config-deploy。
• 适用三方 safe_to_write 生产环境保护措施。

运行

verify-and-align.sh 运行完整流程并输出报告：

1. 前置检查 — 通过 EntityDefinition 确认 sObject。
2. 发现 — 查询 QueueSobject WHERE SobjectType = '<sobject_type>'。如果找到，则复用。未找到时：若指定 --create-if-missing，则通过 Metadata API 创建；否则阻止执行并提供 Setup 点击路径。
3. 检查 — 读取队列的 QueueRoutingConfigId 及其完整的 QueueSobject 列表。
4. 对齐（可选） — 提供 routing_config_dn 时，解析其 Id；若存在偏差，则 PATCH Group.QueueRoutingConfigId。
5. 重新查询 — 确认已收敛并输出 JSON。

行为

优先发现，而非按名称判断。 任何 QueueSobject 将目标 sObject 路由到的队列，就是该 sObject 的队列，无论队列名称是什么。按名称检查可能会漏掉 messagingqueue 这样的队列，进而阻止操作或创建重复队列。

创建操作具有幂等性。 Metadata deploy 会按 fullName 执行 upsert，因此 --create-if-missing 会采用并更新已存在的同名队列，而不是再创建一个。创建时会采用最小安全配置（doesSendEmailToMembers=false，并绑定 sObject），且绝不会删除现有的 QueueSobject 行——其他 sObject 可能有意路由到同一队列。

强制指定与发现 QRC。 对于 Case，协调器希望与 Case_Routing_Config 保持确定性一致，因此该技能会强制指定它。对于没有协调器管理的 QRC 的其他 sObject，该技能会报告队列当前绑定的 QRC（source: discovered），而不会强制指定可能不存在的名称。运行时会通过 DeveloperName 解析 QRC ID——绝不硬编码。

歧义处理。 如果多个不同队列绑定到同一 sObject，该技能不会猜测，而是阻止操作并要求操作员消除歧义；但如果有队列名称与规范名称匹配，或显式提供 queue_developer_name 锁定确切队列，则除外。

PATCH 操作规范。 sf api request rest 会在 stderr 输出 beta 警告；该技能会单独捕获 stderr，避免其干扰 JSON 解析，并在 PATCH 时保留队列 ID（绝不删除后重建），因为下游引用指向该 ID。

输出契约

单个 JSON 对象，包含 status ∈ created | reused | updated | blocked，以及 sobject_type、developer_name、queue_created、id、queue_routing_config_id、queue_routing_config_developer_name、queue_routing_config_source（forced | discovered）、queue_sobjects、before 快照、manual_actions 和 blocking_issue。

• created — 尚无绑定队列，且 --create-if-missing 创建了一个队列（若提供 QRC，则同时绑定该 QRC）。
• reused — 已存在绑定队列，且在传入 QRC 时，该队列已匹配（未执行 PATCH）。
• updated — 已存在绑定队列，但调用方提供的 QRC 已发生偏差；已执行 PATCH。
• blocked — sObject 不存在、没有绑定队列且未指定 --create-if-missing、所提供的 QRC 不存在，或重新查询后发现状态未收敛。

仅当本次运行部署了新队列时，queue_created 才为 true；blocking_issue 会指出未满足的具体前置条件，manual_actions 则提供点击操作路径。

限制

• 仅支持 Case、Incident、MessagingSession、VoiceCall——可通过添加 dispatcher 分支来扩展。
• 绝不删除队列或其 QueueSobject 行，也不会修改队列成员。
• 创建时采用最小队列配置；不会设置特殊字段（doesIncludeBosses、电子邮件路由地址）。

参考资料

文件	阅读时机
references/api-notes.md	因队列缺失而阻止操作时（手动点击操作路径），或遇到意外的 Data API 错误时——其中包含 Queue/QueueSobject 架构、Metadata API 创建结构，以及 stderr 分离和队列命名差异说明