platform-sharing-rules-generate

共享规则生成器

创建、编辑和删除 Salesforce 共享规则元数据，以控制超出组织默认设置的记录级访问。支持基于条件的规则、基于角色/组的属主规则，以及 Experience Sites 的访客用户规则。

范围

• 范围内：创建、编辑和删除 sharingCriteriaRules、sharingOwnerRules 和 sharingGuestRules 元数据；从组织中检索现有共享规则；向现有文件追加新规则；修改规则条件、访问级别或共享目标；从元数据文件中删除规则；为 Guest 和 Portal 配置文件配置规则。
• 范围外：更改组织默认设置（OWD/共享模型）、创建 Experience Sites、配置权限集或配置文件（使用 platform-permission-set-generate）、基于区域的共享规则。

---

澄清问题

在继续之前，如果尚未明确，请与用户确认：

对于创建操作：

• 共享规则应应用于哪个对象？（标准或自定义对象 API 名称）
• 规则类型是什么？（基于条件、基于角色/组的属主规则，或访客用户规则）
• 记录应与谁共享？（角色名称、组、门户角色或访客用户昵称）
• 访问级别是什么？（只读或读/写）
• 对于基于条件的规则：应匹配哪些字段条件？

对于编辑操作：

• 应修改哪个现有规则？（规则 fullName 或标签）
• 应更改什么？（访问级别、共享目标、条件、标签）

对于删除操作：

• 应删除哪些规则？（规则 fullName 或标签）
• 确认规则所属的对象

---

必需输入

在继续之前收集或推断：

• 对象 API 名称：规则针对的 sObject（例如 Account、Property__c）
• 规则类型：sharingCriteriaRules、sharingOwnerRules 或 sharingGuestRules 之一
• 共享目标：角色、组、门户角色或访客用户社区昵称
• 访问级别：Read 或 Edit（映射到只读或读/写）
• 条件（对于条件/访客规则）：每个筛选项目的字段名称、操作和值

除非指定，否则默认值：

• 访问级别：Read
• includeRecordsOwnedByAll：对于条件规则为 true
• includeHVUOwnedRecords：对于访客规则为 false
• 账户共享规则包括 accountSettings，所有子访问级别设置为 None

---

工作流程

每个阶段内的步骤是顺序的。阶段 3 按操作类型分支——仅执行匹配的分支。

阶段 1 — 发现

1. 解析 SFDX 项目路径 — 找到项目的 sfdx-project.json 并确定 sharingRules/ 的包目录。

2. 检查现有共享规则 — 查找 <packageDir>/sharingRules/<ObjectName>.sharingRules-meta.xml。如果找到，读取以了解现有规则并避免重复。

3. 如果本地文件不存在，从组织检索：

   sf project retrieve start --metadata "SharingRules:<ObjectName>" --target-org <org>
   

阶段 2 — 确定操作和规则类型

4. 识别操作 — 确定用户想要创建、编辑还是删除共享规则。

5. 根据用户意图选择规则类型。阅读 references/rule-types.md 以获取每种类型的完整架构及其必需元素。

6. 对于账户共享规则：accountSettings 元素是必需的。除非用户另有指定，否则默认子访问级别为 None。

7. 对于访客规则：sharedTo 必须使用 <guestUser> 并带有站点访客用户的社区昵称。切勿对访客规则使用 <role> 或 <group>。

阶段 3 — 执行操作

对于创建：

8a. 按照 references/rule-types.md 中的架构构建 XML。关键结构：
- 每个对象一个 .sharingRules-meta.xml 文件
- 同一对象的所有规则放在同一文件中
- 如果追加到现有文件，请在现有 <SharingRules> 根元素内添加新规则元素

8b. 命名规则 — 从意图中派生 <fullName>（PascalCase，无空格，描述性）。生成匹配的 <label>，使用标题大小写并带空格。

对于编辑：

8a. 定位目标规则 — 在现有的 .sharingRules-meta.xml 文件中按 <fullName> 或 <label> 查找规则。

8b. 确定修改 — 识别要更改的元素（例如 <accessLevel>、<sharedTo>、<criteriaItems>、<label>）以及新值。暂不写入——所有磁盘写入在阶段 5 用户确认后进行。

对于删除：

8a. 定位目标规则 — 在现有的 .sharingRules-meta.xml 文件中按 <fullName> 或 <label> 查找规则。

8b. 计算剩余规则数 — 运行：grep -c '<sharingCriteriaRules>\|<sharingOwnerRules>\|<sharingGuestRules>' <file> 获取总规则数。如果计数为 1（仅要删除的规则），则必须在阶段 5 完全删除该文件。暂不写入——所有磁盘写入在阶段 5 用户确认后进行。

阶段 4 — 与用户确认 关键

9. 在写入磁盘之前呈现更改摘要。您必须停止并等待用户确认。摘要格式如下：

   操作： 创建 / 编辑 / 删除
   对象： <ObjectName>
   规则： <fullName>（<label>）
   更改：（描述将创建/修改/删除的内容）

   继续？（是 / 否 / 编辑）

   在用户明确确认之前，不要写入任何文件更改。 如果用户说“否”，中止。如果用户说“编辑”，纳入他们的反馈并重新呈现。

阶段 5 — 写入和验证

10. 仅在用户确认后应用更改：

    • 创建：将文件写入 <packageDir>/sharingRules/<ObjectName>.sharingRules-meta.xml。
    • 编辑：仅更新步骤 8b 中识别的元素；保留所有其他元素完全不变。
    • 删除（规则剩余）：写入更新后的文件，移除目标规则。
    • 删除（最后一条规则）：完全删除文件 <packageDir>/sharingRules/<ObjectName>.sharingRules-meta.xml。

11. 运行下面的验证清单，并在呈现输出之前查阅 examples/test-cases.md 以获取特定场景的预期行为。

---

验证清单

通用检查

• [ ] 文件是否包含 XML 声明和 <SharingRules xmlns="http://soap.sforce.com/2006/04/metadata"> 根元素？
• [ ] 每个对象是否只有一个文件，且所有规则都在其中？
• [ ] <fullName> 是否使用 PascalCase 且无空格？
• [ ] <label> 是否存在且可读？
• [ ] <accessLevel> 是否为 Read 或 Edit 之一？

条件规则检查

• [ ] <includeRecordsOwnedByAll> 是否存在（必需布尔值）？
• [ ] 每个 <criteriaItems> 是否都有 <field>、<operation> 和 <value>？
• [ ] 选项列表值是否对目标组织有效？

访客规则检查 关键

• [ ] <sharedTo> 是否使用 <guestUser>（而不是 <role> 或 <group>）？
• [ ] <includeHVUOwnedRecords> 是否存在（必需布尔值）？
• [ ] <includeRecordsOwnedByAll> 是否不存在（仅用于条件规则，不用于访客规则）？

属主规则检查

• [ ] 规则是否同时具有 <sharedFrom> 和 <sharedTo> 元素？
• [ ] 两者是否都使用有效的 <role>、<roleAndSubordinates> 或 <group> 目标？

编辑操作检查

• [ ] 是否仅修改了预期元素？
• [ ] 编辑后所有必需元素是否仍然存在？
• [ ] 修改后的规则是否仍通过上述通用检查？
• [ ] 写入前是否收到用户确认？

删除操作检查

• [ ] 是否删除了正确的规则（按 <fullName> 匹配）？
• [ ] 剩余 XML 是否格式良好且具有正确的 <SharingRules> 根元素？
• [ ] 如果没有剩余规则，是否完全删除了文件？
• [ ] 写入前是否收到用户确认？

账户特定检查 关键

• [ ] 如果对象是 Account，<accountSettings> 是否存在且包含所有三个子元素？
• [ ] <caseAccessLevel>、<contactAccessLevel>、<opportunityAccessLevel> 是否都已设置？

---

规则 / 约束

约束	理由
每个对象一个 .sharingRules-meta.xml 文件	平台要求——多个文件会导致部署错误
访客规则必须在 sharedTo 中使用 <guestUser>	使用 <role> 或 <group> 会导致：“为 guestUser 字段指定访客用户的昵称”
账户规则需要 <accountSettings>	缺少它会导致：“账户共享规则需要 AccountSettings”
条件规则需要 includeRecordsOwnedByAll	缺少它会导致：“缺少必需字段：sharingCriteriaRules”
访客规则需要 includeHVUOwnedRecords	缺少它会导致部署失败
条件字段值必须作为选项列表值存在于组织中	无效值会导致：“选项列表值不存在”
切勿硬编码文件路径——从 sfdx-project.json 解析	客户项目使用自定义包目录
始终在写入更改前确认	防止意外创建、修改或删除共享规则
编辑必须保留未修改的元素	仅更改 accessLevel 不得更改 criteriaItems 或其他字段
删除必须移除整个规则块	部分删除会留下无效 XML 并导致部署失败
删除最后一条规则时删除文件	空的 <SharingRules> 根元素没有子元素是无效元数据

---

注意事项

问题	解决方案
访客规则使用 <role> 而不是 <guestUser>	替换为 <guestUser>CommunityNickname</guestUser>
账户规则缺少 accountSettings	添加 <accountSettings>，所有三个访问级别子元素设置为 None
条件规则缺少 includeRecordsOwnedByAll	添加 <includeRecordsOwnedByAll>true</includeRecordsOwnedByAll>
选项列表值不匹配	在生成条件之前查询组织以获取有效值
追加时重复现有规则名称	写入前检查现有 <fullName> 值
找不到访客用户昵称	查询：SELECT CommunityNickname FROM User WHERE UserType='Guest' AND IsActive=true
编辑本地不存在的规则	在尝试编辑之前先从组织检索
删除被其他自动化引用的规则	在确认前警告用户潜在的下游影响
编辑更改规则类型（例如，条件 → 属主）	不支持——删除旧规则并创建新规则
删除留下格式错误的 XML	确保删除后 XML 结构正确；验证文件格式良好

---

输出预期

交付物：

• <packageDir>/sharingRules/<ObjectName>.sharingRules-meta.xml — 目标对象的完整共享规则文件

---

跨技能集成

需求	委派给
权限集配置	platform-permission-set-generate 技能
自定义对象创建（如果目标对象不存在）	platform-custom-object-generate 技能

---

参考文件索引

文件	何时读取
references/rule-types.md	阶段 2 — 在生成任何规则之前，获取每种规则类型的完整 XML 架构
examples/test-cases.md	阶段 5，步骤 11 — 在验证期间，检查每种场景类型的预期行为