education-cloud-domain-configure

配置 Education Cloud 域

通过对话式设置，引导用户配置 Education Cloud 域。启用前置条件 Person Accounts，通过 Setup 激活目标域，并在每一步都征求用户确认后配置域专属子功能。

范围

• 范围内：Education Cloud 域配置（Student Success、Recruitment & Admissions、Academic Operations、Alumni Relations、Student Management、Mentoring）、启用 Person Accounts、子功能配置、优先使用 API，必要时回退到 UI
• 范围外：生成自定义元数据或对象（委托给 platform-custom-object-generate）、部署托管包、数据迁移、EDA（Education Data Architecture）配置——仅限原生 Education Cloud

---

必需输入

开始前收集：

• 目标域：要配置的 Education Cloud 域（Student Success、Recruitment & Admissions、Academic Operations、Alumni Relations、Student Management 或 Mentoring）
• 目标组织：具有管理员访问权限的活跃 Salesforce 组织
• 子功能（可选）：用户希望在域内启用的具体子功能

默认值：

• 确认方式：每一步都先询问
• 错误处理：说明错误、建议修复方法，并等待用户决定

---

域和功能开关写入路径（权威说明）

每个域/子功能开关都位于 IndustriesSettings 设置文件中（不在 Core 的 ORG_PREFERENCES 允许列表中），且不可逆（仅支持 false → true——切换前必须警告，绝不承诺可以回退）。写入顺序始终为读取（按 DurableId 执行 tooling GET）→ 写入（通过启用了写入功能的 dispatch 工具调用 PUT /services/data/v68.0/headless/metadata）→ 冷验证（重复执行 GET——仅凭 success:true 不能证明成功）。进行任何开关写入前，先阅读 references/toggle-write-path.md，其中包含完整的端点表、准确的 xmlRep 结构、DurableId 常量以及已确认的故障类型（静默无操作、冷验证 500 错误、许可证限制）。

---

编写规范

1. 以功能为主线。 先给出功能名称和通俗易懂的说明，介绍该功能对客户的作用（例如，“强制执行时间冲突限制——防止学习者注册日程冲突的课程开设”），而不是开关的 API 元素名称（enableCosConflicts）。仅在技术/API 调用小节中保留元素名称。
2. 切换前先说明。 对每项功能和子功能，都用一句话说明“功能作用”，让客户在确认前了解将启用什么。
3. 列出子功能并确认。 若某个域有子功能，须逐一列出，并请客户确认要启用或排除哪些功能，然后再继续。
4. 每次创建/更新/删除操作都先告知。 执行任何创建/更新/删除操作前，说明将执行的操作，并提供批准、拒绝或修改的选项。
5. 标明手动步骤。 如果某一步无法通过 API 完成，须注明需要手动操作，并在该域配置结束时一并列出。
6. 始终进行冷验证。 写入返回 success:true 并不能证明成功。重新读取状态（对记录或设置对象执行 GET），并确认目标字段/元素的值。

---

执行传输方式

首次调用前，检查传输健康状态：通过 headless-360 dispatch 执行 GET /services/data/vXX.X/limits。若返回 2xx → 所有调用都通过它执行。若不可用/返回 4xx/5xx → 使用相同的读取请求检查其他可用传输方式（其他 Salesforce MCP、经过身份验证的 sf CLI、自定义 MCP），并使用第一个健康的方式，同时告知用户。若没有可用方式 → 停止并请用户连接一种方式；绝不伪造结果。

SOQL 请求通过 headless-360 路由——通过 queryParams 传递查询，而不是在 url 中内联使用 ?q=（内联方式会因 ROUTE_NOT_FOUND 返回 404）。调用格式详情见：references/gotchas-extended.md（“Transport call shapes”）。

设置小部件

五个 HXL 小部件（display_widget：Intent、Review、Plan、Apply、Verify）用于可视化工作流。到达各检查点时自动渲染；绝不询问是否要显示。它们只是视觉辅助，不是关卡：如果宿主或组织无法渲染，就继续用文本进行。每个属性都必须根据实时读取结果计算。点击某一行的操作按钮（例如 Enable）即表示用户批准该项，无需另行确认。检查点、属性契约、渲染调用和回退方式：references/setup-widgets.md。

---

工作流

阶段 0 — 基础前提条件（组织级）

所有 Education Cloud 领域都需要这些基础设置。在继续配置领域之前，先进行验证。

可视化审查。 完成阶段 0、1 和 1.5 的读取后，使用 HxlSetupReview 将 8 项前提条件渲染一次（见“设置小部件”），然后通过对话逐项处理待办事项。每启用一项后都重新渲染。

1. 检查组织版本 — 使用 queryParams: {"q": "SELECT OrganizationType FROM Organization"} 查询 GET /services/data/v68.0/query（单例，无需 Id），然后将记录通过管道传入 scripts/check_org_edition.py --allowed "Enterprise Edition,Performance Edition,Unlimited Edition,Developer Edition"（标准输入：{"records": [...]}）。若 eligible: false → 提醒用户，Education Cloud 要求使用 Enterprise+ 版本。

2. 检查 Lightning Experience — 验证是否已启用 Lightning Experience。如果未启用，指导用户前往 Setup → User Interface → Enable Lightning Experience。

3. 检查 Education Cloud 许可证 — 权限集名称因组织/版本而异（已确认的两个组织都未提供 EducationCloudUser；请改为查找 %EducationCloud% 匹配项）。使用 queryParams: {"q": "SELECT Id, Name FROM PermissionSet WHERE Name LIKE '%EducationCloud%'"} 查询 GET /services/data/v68.0/query，并查询 GET /services/data/v68.0/sobjects/BusinessProfile/describe（记录 createable；若返回 404，则记录为 null），然后将两者传入 scripts/check_license_provisioned.py（标准输入：{"permissionSets": [...], "businessProfileDescribe": {...}}）。若 provisioned: false → 表示尚未配置，告知用户并停止。若 provisioned: true 且 matchingPermissionSets 为空 → 按已配置处理，但注明不匹配情况。

4. 分配 Education Cloud Full Access — 确定当前运行用户的 Id（若未知，询问其用户名），使用 queryParams: {"q": "SELECT Id, PermissionSet.Name FROM PermissionSetAssignment WHERE AssigneeId='<running user Id>' AND PermissionSet.Name LIKE '%EducationCloud%'"} 查询 GET /services/data/v68.0/query，然后将结果传入 scripts/check_permission_assigned.py（标准输入：{"records": [...]}）。若 assigned: false → 指导用户通过 Setup → Permission Sets → Manage Assignments 分配该组织的实际权限集（来自步骤 3 的 matchingPermissionSets）。

   当前界面无法使用 Bash 工具？ 这些脚本只执行本地数据转换，不调用组织，也不需要凭据。请直接进行等效比较，不要跳过检查。

5. 启用 Education Cloud Foundation — 不可逆操作——切换前警告用户；不要承诺可以撤销。 此操作不走元数据 PUT 路径（已确认 enableEducationCloud 会静默无操作），而是需要使用专用调用端点。阅读 references/toggle-write-path.md 中的“启用基础功能”，了解 READ → WRITE → 冷验证顺序及界面回退方案。冷验证显示 true 后，继续执行步骤 6。

阶段 1 — 启用个人帐户

6. 确认领域选择 — 如果用户尚未指定要配置的领域，请询问用户。提供以下列表：

   • 学生成功
   • 招聘与招生
   • 学术运营
   • 校友关系
   • 学生管理
   • 指导

   使用这六个领域及其状态渲染 HxlSetupIntent。

7. 说明个人帐户 — 说明：“Education Cloud 必须使用个人帐户。个人帐户允许将个人（学生、申请人、校友）同时作为帐户和联系人，统一记录在同一条记录中。”

   WARNING：启用个人帐户后无法将其禁用。继续操作前，请确认用户了解此操作不可逆。

8. 启用个人帐户（UI） — 个人帐户没有受支持的 org-preferences 写入 API（setup/org/preferences/{name} 端点会返回 404）。指导用户前往“设置” → “快速查找” → “帐户设置” → 选择“帐户设置” → 打开“启用个人帐户” → 点击“保存”。等待用户确认开关已打开并已保存，然后继续执行阶段 1.5。

   验证方法：GET /services/data/v68.0/sobjects/Account/describe，并确认其中包含 IsPersonAccount/Person* 字段。这是唯一有效的验证方式；切勿对 IsPersonAccount 或个人帐户字段运行 SOQL（参见 references/gotchas-extended.md 中的“Person Accounts verification”）。

阶段 1.5 — 基础设置：依赖功能和数据空间映射

此阶段与 Setup 自身的“基础设置”分组（个人帐户、依赖功能、数据空间映射）相对应，该分组位于各领域部分之前。多个领域的子功能可能会用到同一依赖功能，因此在此处进行配置可以避免在各领域配置过程中重复查找。

9. 展示依赖功能 — 阅读 references/dependent-features.md，并按类别（已确认的 API 开关／仅限手动 UI／未测试）向用户展示完整列表。每项以功能名称及一句话说明“其用途”开头，而非 API 元素名称。始终展示此列表并询问用户现在要启用哪些功能，即使用户拒绝启用所有功能，也要明确记录该决定，并继续执行阶段 2，不得跳过此步骤。之后可以重新启用任何被拒绝的功能。

10. 配置每项已选依赖功能 — references/dependent-features.md（“Configuration shapes”）将所有功能归为四种配置类型（IndustriesSettings 开关、org-preference 开关、与领域子功能重叠、仅限手动 UI）；在其中查找所选功能的确切元素名称、DurableIds 和注意事项。除非参考文档另有说明，否则开关均为不可逆：先警告，然后执行读取 → 写入 → 冷验证。

11. 启用 OmniStudio — OmniStudio 包含在 Education Cloud 许可证中。尝试调用 API，或指导用户前往“设置” → “OmniStudio 设置” → “启用”。

12. 启用 Business Rules Engine — Business Rules Engine 包含在 Education Cloud 许可证中。指导用户前往“设置” → “Business Rules Engine” → “启用”。

13. 数据空间映射 — 使用 DataSpaceFeatureMappings Setup Operation Recipe（/headless/invoke/platform/data-space-feature-mappings）。与此技能中的大多数开关不同，此功能可逆（支持删除）。完整的预检／读取／写入／冷验证／撤销流程、有效功能值和状态码处理方式，参见 references/dependent-features.md 中的“Data Space Mapping”部分。如果预检失败或任何 invoke 调用出错，请改用手动 UI（“设置” → “设置 Education Cloud” → “数据空间映射”）。

阶段 2 — 启用目标域

14. 说明域的用途 — 在 references/domain-features.md 的索引中查找所选域，并打开链接的域专属文件（例如 references/domain-features/student-success.md），向用户说明该域提供的功能，包括先决条件。

15. 检查域专属先决条件 — 除 OmniStudio/Business Rules Engine（阶段 0）外，大多数域还需要额外的许可证或预先启用其他域；各域的先决条件列表见 references/domain-features.md（“Domain prerequisites”）。如果缺少先决条件，请提醒用户，并询问是继续使用现有功能，还是先配置好先决条件。使用这些域先决条件渲染 HxlSetupReview。

16. 确认启用域 — 不可逆 — 按设计只能单向启用（false → true）。 明确提醒用户，不要承诺可以撤销或回滚。询问：“准备好启用 [Domain Name] 了吗？此操作会激活域专属对象、字段和设置功能，之后无法关闭。”

17. 启用域开关 — 每个域在 IndustriesSettings 上都有一个 enableXXX 字段。遵循域和功能开关写入路径：读取（通过 DurableId 执行 tooling GET）→ 写入（通过 dispatch 写入工具，使用 PUT /services/data/v68.0/headless/metadata，并在 xmlRep 中仅包含 <enableXXX>true</enableXXX> 元素）→ 验证（tooling GET 显示 true）。

    各域对应的开关字段：见 references/domain-features.md（“Domain toggle fields”）。Recruitment & Admissions 没有主开关；跳过此步骤，转到 references/domain-features/recruitment-admissions.md 的“Enablement & Toggles”。

    成功时（200 { success: true }，同步完成，无需轮询），继续第 18 步。失败时，指导用户前往 Setup → “Set Up Education Cloud” → 域对应部分（例如 “Set Up the Student Success App”）→ 打开域开关 → Save，然后等待确认。

18. 验证域已启用 — 第 17 步的冷验证（Is<Domain>Enabled = true）已确认开关状态。若要确认对象已配置，执行 GET /services/data/v68.0/sobjects/CaseTeamTemplate/describe：返回 200 表示对象存在（域已启用）；返回 404/NOT_FOUND 时，等待 1-2 分钟以完成异步配置，然后重试。也可以通过 queryParams 执行 SOQL SELECT count() FROM <Object>。

阶段 3 — 配置子功能

19. 阅读子功能参考资料 — 加载 references/domain-features/ 下所选领域对应的文件，了解可用的子功能及其详细设置步骤。

20. 展示子功能选项 — 列出该领域可用的子功能（以领域对应的 references/domain-features/ 文件为准），并询问用户要配置哪些。Student Success 有规定的执行顺序（Support Process → Case Record Types → Success Teams → Care Plans → Support Programs → Salesforce Scheduler → consoles/portal）；其他领域的子功能彼此独立。确定选择后，渲染 HxlSetupPlan。

21. 配置每项选定的子功能 — 说明其用途，提示是否不可逆，并征得用户确认（点击对应行的小组件按钮即视为确认），然后严格按照领域对应的 references/domain-features/ 文件中的设置路径操作（涵盖全部五种类型：通过 Data/Tooling API 创建记录、通过 Toggle Write Path 切换 IndustriesSettings 开关、应用/控制台设置、Experience Cloud 门户设置、OmniStudio 激活——每项子功能均提供端点、请求体结构、注意事项和验证方法）。开关遵循与领域开关相同的 IRREVERSIBLE + READ→WRITE→冷验证规则；如果 Phase 1.5 已设置，则先进行冷读取。API 失败时，改用参考资料中的 Setup UI 路径。每次冷验证后，都要渲染并重新渲染 HxlSetupApply。

22. 总结 — 配置完所有子功能后，列出已启用的功能及其启用方式（API、UI、OmniStudio）。报告任何失败或需要手动执行的步骤。如需建议后续步骤，只列出本次会话中确实遇到的阻碍/依赖（例如仍未启用的前置条件，或用户询问过但暂缓配置的子功能），不要不加区分地列出所有相关功能或领域。为每项经过冷验证的写入渲染一行 HxlSetupVerify。

---

规则 / 限制

限制	原因
在启用任何领域之前，必须先启用 Foundation、Person Accounts、OmniStudio 和 Business Rules Engine	领域依赖这些基础对象/设置，也依赖 OmniStudio/BRE 来支持门户组件和策略规则
每一步操作前始终征得用户确认，并先说明功能用途	对话式工作流模式 — 未经用户明确批准或理解，不得执行任何命令
UI 回退步骤后等待用户确认，并在每次启用后进行冷验证	切勿假定操作成功 — 重新读取状态（tooling GET、describe、record GET，或通过 queryParams 执行 SELECT ...）
启用领域前检查领域特定的前置条件	某些领域需要额外许可证，或需要先配置其他领域
Phase 0 检查使用 scripts/ 辅助脚本，而非内联文本逻辑	确定性强、速度快，无需调用组织或使用凭据 — 只有在没有 Bash 工具时，才以内联方式执行等效比较

---

注意事项

问题	解决方案
尚未为 Education Cloud 配置许可证	继续操作前，联系 Salesforce 客户团队配置许可证
启用后，Person Accounts、Education Cloud Foundation 和域开关都无法关闭	尝试启用前警告用户——此操作不可逆
setup/org/preferences/{name} 对 EDU 开关返回 404	不在 ORG_PREFERENCES 允许列表中——请改用 PUT /services/data/v68.0/headless/metadata 写入
对 Tooling sObject IndustriesSettings 执行 PATCH 返回 400 JSON_PARSER_ERROR	complexvalue 字段不接受 PATCH——请使用 headless metadata PUT 路径；Tooling GET 仅用于读取/验证
Tooling GET 需要真实的 DurableId，而非 000000000000000AAA	先查询 SELECT Id,DurableId FROM IndustriesSettings
域/子功能启用可能需要 1-2 分钟才能生效	如果 API 调用后立即验证却没有结果，请等待 2-3 分钟后重试

有关 AURA-IS-CANONICAL 静默无操作、冷验证 500 和许可证门控失败类别，请参阅 references/toggle-write-path.md；有关发生频率较低的注意事项，请参阅 references/gotchas-extended.md。

---

最终验证清单（不可逆写入）

在报告以下任一项已完成前，请确认该项写入对应的两个复选框均已勾选：

• Education Cloud Foundation — 已警告用户无法关闭，并且启用后冷验证（在全新读取中 educationCloudEnabled: true）通过。
• Person Accounts — 已警告用户启用后无法禁用，并且 Account describe 确认存在 IsPersonAccount/Person* 字段。
• 本次会话启用的每个域开关 — 用户在写入前已确认“之后无法关闭”，并且 Tooling GET 冷验证显示 Is<Domain>Enabled: true。（步骤 18 中的对象 describe 仅确认对象已配置——不能替代此冷验证。）
• 本次会话启用的每个不可逆子功能/依赖功能开关 — 用户在写入前已确认，并且冷验证显示该字段为 true。

除非对应功能的批准和冷验证复选框均已勾选，否则不要在最终摘要中将其列为“已启用”。

---

输出预期

此技能不会生成文件——配置通过 Setup 导航、CLI 命令或 API 调用完成。预期输出：每个步骤完成后的对话确认；在宿主和 org 支持的情况下，通过 display_widget 展示反映实时状态的 HXL Setup 小组件（Intent、Review、Plan、Apply、Verify）；显示配置已生效的验证结果；失败时显示包含建议修复方法的错误消息；以及列出所有已配置功能的最终摘要。

---

跨技能集成

需求	委托给
为 Education Cloud 创建自定义对象	platform-custom-object-generate
在 Education Cloud 对象上创建自定义字段	platform-custom-field-generate
生成验证规则	platform-validation-rule-generate
配置权限集	platform-permission-set-generate
部署元数据包	platform-metadata-deploy

---

参考文件索引

文件	阅读时机
references/domain-features.md	各领域参考文件索引——从这里开始，查找所选领域对应的文件
references/domain-features/<domain>.md	阶段 2 步骤 14（说明领域用途）、阶段 3 步骤 19（识别子功能）、阶段 3 步骤 21（子功能配置设置路径和 API 偏好名称）
references/dependent-features.md	阶段 1.5 步骤 11–12（设置基础——在任何领域之前展示并配置依赖功能），以及用户询问不属于某一领域的跨产品功能时——将其作为“设置依赖功能”展示，并在相关时注明领域重叠
references/setup-widgets.md	步骤 6、15、20、21、22 以及阶段 0 审查（5 个 HXL 设置小组件的属性约定和 Education Cloud 映射）
references/gotchas-extended.md	当错误与上方 Gotchas 表中的 10 个条目都不匹配时
scripts/check_org_edition.py	阶段 0 步骤 1（组织版本检查）
scripts/check_license_provisioned.py	阶段 0 步骤 3（Education Cloud 许可证检查）
scripts/check_permission_assigned.py	阶段 0 步骤 4（Education Cloud 完全访问权限分配检查）