service-omni-supervisor-permset-assign

service-omni-supervisor-permset-assign

通过 PermissionSetAssignment，将 Salesforce 随附的标准 ContactCenterSupervisor 权限集分配给现有主管用户。经典 Omni-Channel Supervisor UI（Command Center）要求主管先具备联系中心主管权限，service-omni-supervisor-config-deploy 才能为其绑定配置。此技能在 POST 前先检测，以确保幂等性，并将 DUPLICATE_VALUE 视为已满足分配要求。

许可。 主管系统权限（IsContactCenterSupervisor、OmniSupervisorManageQueue、ViewOmnichnlAnlytDshbrd）受权限集许可证限制。标准 ContactCenterSupervisor 集自带许可证关联，在启用了 Service Cloud 的组织中可以顺利分配，因此是默认且受支持的方式——手动创建并重新声明这些权限的自定义权限集会因 FIELD_INTEGRITY_EXCEPTION 失败。如果某个用户的许可证缺少底层授权，分配时会出现相同的异常，操作员可以将该用户移至具备相应授权的配置文件／许可证。

关于自定义权限集的警告，并不意味着分配现有的 Salesforce 随附 ContactCenterSupervisor 集会移除访问权限或改写该集合。此技能只会创建缺失的 PermissionSetAssignment；不会创建、编辑或替换权限集本身。

输入

bash scripts/verify-and-assign.sh <org-alias> [count=1] [permission-set-names-csv=ContactCenterSupervisor]

• org-alias（必填）。
• count（可选，默认为 1，范围为 1..5）——必须与主管用户数量一致。
• permission-set-names-csv（可选，默认为 ContactCenterSupervisor）——多个权限集以逗号分隔。每位主管都会获得所列的每个权限集（笛卡尔积）。

前置条件与安全性

• 目标组织已通过 sf CLI 进行身份验证，具有 Service Cloud 许可证，且 sf CLI 版本 ≥ 2.139.6。
• 主管用户已存在且处于启用状态；启用用户少于 count 时会阻止操作，并显示补救提示。
• ContactCenterSupervisor 集由 Salesforce 随附，且存在于任何启用了 Service Cloud 的组织中；如果缺少自定义名称对应的权限集，则会阻止操作，并提供 Setup 点击路径。
• 执行用户具有 PermissionsAssignPermissionSets 权限（System Administrator 的标准权限）——即使是组织管理员也必须具备此权限。
• 适用三重 safe_to_write 生产环境保护机制——在生产组织中分配权限集可能提升真实用户的权限，因此操作会被阻止且无法覆盖此限制。

运行

verify-and-assign.sh 会执行完整流程：

1. 计算 safe_to_write；派生出 8 位组织后缀。
2. 在调用任何 sf 命令前，将所有提供的权限集名称验证为格式正确的 DeveloperName（防止 SOQL 注入）。
3. 查找 supervisor{1..N}.<suffix>@example.com 用户，并筛选 IsActive=true 的用户；如果启用用户少于 count，则阻止操作（非启用用户不计入数量）。
4. 按名称查找每个 PermissionSet；如果有缺失，则阻止操作并指出名称。
5. 查询（用户 × 权限集）笛卡尔积中已有的 PermissionSetAssignment；计算缺失的配对。
6. 为每个缺失配对单独 POST 一条分配记录（不使用 allOrNone）；将 DUPLICATE_VALUE 视为已存在。
7. 重新查询以确认最终状态并生成报告。

行为

笛卡尔积。 每位主管都会获得所列的每个权限集；部分分配属于失败，而非预期功能。

幂等性。 PermissionSetAssignment 对 (AssigneeId, PermissionSetId) 设有唯一性约束，因此重复 POST 会引发 DUPLICATE_VALUE；此技能会先检测已有配对，并将其视为已复用，以确保并发运行安全。POST 请求逐条发送，因此一条出错不会回滚其他请求；所有 POST 完成后会重新查询——201 只表示写入请求已被接受，SOQL 查询才能确认分配已生效。

非破坏性。 仅创建；不会删除现有分配（主管可能持有通过其他方式授予的权限），并根据主管用户命名模式查找用户，而不是使用明确的用户 ID 列表。

输出约定

单个 JSON 对象，包含 status（取值为 assigned | reused | partial | blocked）、解析后的 permission_sets、org_suffix、requested_count、expected_assignment_count（= requested_count × len(permission_sets)）、before 快照、assigned_this_run/assigned_count、reused_count、after 快照、manual_actions 和 blocking_issue。

• assigned — 至少创建了一项新分配；完成后所有预期组合均已存在。
• reused — 所有预期组合此前均已存在；未执行任何 POST。
• partial — 部分 POST 失败；最终数量低于预期。
• blocked — 前置条件不满足（生产环境组织、缺少权限集、用户缺失/未激活，或许可证不允许该权限）。

除 partial 外，assigned_count + reused_count == expected_assignment_count；仅当状态为 blocked/partial 时，blocking_issue 才不为 null。

限制

• 为用户配置主管权限集所需的用户许可证，属于 users-create 技能的职责，不属于此技能。
• 仅分配单个 PermissionSet；PermissionSetGroup 是不同的 sObject，不在范围内。
• 仅创建，不会移除分配。

参考资料

文件	阅读时机
references/api-notes.md	POST 循环之前 — PermissionSetAssignment 架构、DUPLICATE_VALUE 语义，以及为什么用户是根据主管模式推导而来，而不是来自明确的 ID 列表