service-omni-supervisor-users-create

service-omni-supervisor-users-create

在 Salesforce 组织中创建 N 个主管用户，用于经典版 Omni-Channel 主管配置（OmniSupervisorConfig），该配置通过 OmniSupervisorConfigUser 绑定指定用户记录。用户采用确定性的 supervisor{i}.<suffix>@example.com 模式，以便协调器在多次运行之间重新找到这些用户。此工具与 service-omni-agent-users-create 相对应，并共用其检测、密码和幂等性模型；唯一的区别是用户名／别名前缀和调试日志标记。将这些用户绑定到配置（service-omni-supervisor-config-deploy）以及授予其主管访问权限（service-omni-supervisor-permset-assign）是单独的叶节点。

输入

开始时一次性确认：

• org-alias（必填，无默认值）——必须能通过 sf org display 解析。
• 主管数量（可选，默认值为 1，范围为 1..5；协调器通常请求 1 个）。
• 配置文件名称（可选，默认值为 Standard User）。协调器会将其覆盖为 Service Cloud 配置文件，以便主管使用 Service Cloud 许可证；主管访问权限本身则通过之后分配的标准 ContactCenterSupervisor 权限集授予。

不接受操作员提供的用户名和密码——两者均自动生成（用户名根据组织后缀生成，密码通过 Anonymous Apex 生成）。

前提条件与安全措施

• 目标组织已通过 sf CLI 进行身份验证（使用 My Domain URL，而非 .lightning.force.com），具有 Service Cloud 许可证，且 sf CLI 版本 ≥ 2.139.6。
• 执行用户具有 PermissionsModifyAllData 和 PermissionsManagePasswordPolicies（系统管理员通常默认具有这些权限）。
• **生产环境防护：**检测脚本将 safe_to_write 计算为 IsSandbox OR TrialExpirationDate != null OR OrganizationType 属于 {Developer Edition, Base Edition}；如果结果为 false，技能将阻止操作且不允许覆盖。CDO、临时组织和开发组织均允许操作。

**密码处理（失败时默认拒绝）。**通过 Anonymous Apex System.setPassword 设置密码（sf user password generate 无法指定通过 Apex 插入的用户）。密码明文会出现在 inline executeAnonymous 调试日志中；仅当运行用户存在活动的调试日志 TraceFlag 时，密码明文才会出现在可查询的 ApexLog 中。因此，包装器会在首次调用 System.setPassword 之前默认拒绝操作：通过经 SOQL 筛选的 Tooling API 查询（ExpirationDate > now），确认不存在活动的 TraceFlag。如果无法确切证明安全，则完全不设置密码；用户保持 ACTIVE，标记为 password_status:"reset_required"，并通过 security_warning 说明原因。绝不删除日志。无法设置密码的用户会保持 ACTIVE 并标记为需要重置——绝不会停用。

运行

# read-only preview (never writes)
bash scripts/detect-and-create.sh plan <org-alias> [count] [profile-name]
# detect, enforce safe_to_write, then insert only the missing supervisors
bash scripts/detect-and-create.sh run  <org-alias> [count=1] [profile-name="Standard User"]

detect-and-create.sh 是规范入口点：它会重新运行检测、执行生产环境防护，然后才进行插入。不要直接调用 scripts/run-create.sh——它是内部脚本，不会执行防护。

行为

检测。 检测器从 Organization.Id 派生出一个 8 字符后缀，按名称解析配置文件，并查询 User 中符合 supervisor{i}.<suffix>@example.com 的用户，将已占用的槽位分为活跃的 existing_users 和非活跃的 inactive_users。

插入。 Apex 加载 assets/create-supervisors.apex.template，替换 __COUNT__/__PROFILE_ID__/__SUFFIX__，并且只插入缺失的索引；它会在事务内重新检查，防止单次运行重复插入。但对于并发运行，这项检查无法提供保证（两次运行都可能在任一方提交之前通过预查询），因此并发情况下的重复保护依赖全局用户名唯一性约束以及 DUPLICATE_USERNAME 重试（参见 references/apex-template-notes.md）。创建的用户会获得 Service Cloud 功能（UserPermissionsSupportUser=true）；如果配置文件的许可证不允许该功能，Apex 会移除该标志并重试（之后，permset 分配会阻止操作，直到用户获得合适的许可证）。每个创建的用户都会通过 SUPERVISOR_CREATED|<id>|<username>|<email> 报告（标记中没有密码——密码由单独的 System.setPassword 提交设置）。

非活跃的占用用户。 占用主管槽位的非活跃用户不能作为可复用的主管，也无法重新创建（用户名在全局范围内唯一）。系统会将其列为需要手动重新激活的用户，并且绝不会将其计入所需槽位——若计入会导致配置中的主管数量不足。

验证。 插入后，检测器会再次运行，且必须显示 missing_count == 0。

输出约定

detect-and-create.sh 会输出一个 JSON 对象，其中 status ∈ created | partial | reused | action_needed | blocked，此外还包括 detect、create（未创建任何用户时为 null）、created_count、reused_count、total_present_after、users_needing_password_reset、action_required 和 safe_to_write。

• created — 所有缺失的索引均已创建，且密码可用。
• partial — 创建了部分用户但未全部完成、任意一次 System.setPassword 失败（用户仍为 ACTIVE，并列在 users_needing_password_reset 中），或某个槽位被需要重新激活的非活跃用户占用。
• reused — 所有请求的槽位都已存在；未执行 DML。
• action_needed — 仅限计划模式。
• blocked — 未满足前置条件。

create.created_users[].password 仅会为本次运行创建且 System.setPassword 成功的用户填充。create.rolled_back_users 始终为空（此技能绝不会停用用户）。生成的密码属于机密：它只会出现在返回的 JSON 中；调用方若持久化标准输出，只能将其写入受限的 CREDENTIALS.json（模式 0600），在其他位置对其脱敏，并在分发后删除该文件——协调器会自动执行这些操作。

限制

• 用户名模式和组织后缀固定不变，且无法由操作员配置——这种确定性正是幂等重运行得以实现的原因。
• 只创建主管用户；绝不会删除或停用用户，包括此前运行遗留的孤立主管用户。
• 常见的 User 错误（DUPLICATE_USERNAME、INVALID_EMAIL、LICENSE_LIMIT_EXCEEDED）会转换为便于操作员理解的消息，而不会直接显示原始错误。

参考资料

文件	阅读时机
references/apex-patterns.md	运行 Apex 前——了解 Apex 结构、User 字段默认值、密码策略以及配置文件本地化风险
references/apex-template-notes.md	创建操作返回重复项、许可证、密码或跟踪安全错误时
assets/create-supervisors.apex.template	当必须插入缺失的主管用户时，由 scripts/run-create.sh 加载
scripts/detect-existing.sh	由 scripts/detect-and-create.sh 加载，用于对组织、配置文件、安全性和现有用户执行只读检查
scripts/run-create.sh	内部写入脚本，仅在守卫检查通过后由 scripts/detect-and-create.sh 加载