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 — 探索

解析 SFDX 專案路徑 — 找到專案的 sfdx-project.json，並識別 sharingRules/ 的套件目錄。
檢查現有的共用規則 — 尋找 <packageDir>/sharingRules/<ObjectName>.sharingRules-meta.xml。若找到，請閱讀以了解現有規則並避免重複。

若本機沒有檔案，從組織擷取：

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

階段 2 — 決定操作和規則類型

識別操作 — 判斷使用者想要建立、編輯或刪除共用規則。
根據使用者意圖選擇規則類型。閱讀 references/rule-types.md 以取得每種類型的完整結構描述及其必要元素。
對於 Account 共用規則：accountSettings 元素是必要的。除非使用者另有指定，否則將子存取層級預設為 None。
對於訪客規則：sharedTo 必須使用 <guestUser>，並使用網站訪客使用者的社群暱稱。訪客規則絕不可使用 <role> 或 <group>。

階段 3 — 執行操作

建立：

8a. 建構 XML，遵循 references/rule-types.md 中的結構描述。主要結構：
- 每個物件一個 .sharingRules-meta.xml 檔案
- 相同物件的所有規則放在同一個檔案中
- 若附加到現有檔案，請在現有的 <SharingRules> 根元素內新增規則元素

8b. 命名規則 — 從意圖推導 <fullName>（PascalCase、無空格、具描述性）。產生相符的 <label>，使用 Title Case 並含空格。

編輯：

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 — 與使用者確認關鍵

在寫入磁碟之前，呈現變更摘要。您必須停止並等待使用者確認。摘要格式如下：

操作： 建立 / 編輯 / 刪除
物件： <ObjectName>
規則： <fullName>（<label>）
變更：（描述將建立/修改/移除的內容）

是否繼續？（是 / 否 / 編輯）

在使用者明確確認之前，請勿寫入任何檔案變更。 若使用者說「否」，請中止。若使用者說「編輯」，請納入其意見並重新呈現。

階段 5 — 寫入與驗證

僅在使用者確認後套用變更：
- 建立：將檔案寫入 <packageDir>/sharingRules/<ObjectName>.sharingRules-meta.xml。
- 編輯：僅更新步驟 8b 中識別的元素；其他所有元素保持原樣。
- 刪除（仍有規則）：寫入已移除目標規則的更新檔案。
- 刪除（最後一個規則）：完全移除檔案 <packageDir>/sharingRules/<ObjectName>.sharingRules-meta.xml。
執行下列驗證檢查清單，並在呈現輸出前查閱 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>` 會導致：「Specify a guest user's nickname for the guestUser field」
帳戶規則需要 `<accountSettings>`	缺少時會導致：「AccountSettings is required for account sharing rules」
條件式規則需要 `includeRecordsOwnedByAll`	缺少時會導致：「Required field is missing: sharingCriteriaRules」
訪客規則需要 `includeHVUOwnedRecords`	缺少時會導致部署失敗
條件欄位值必須存在於組織的挑選清單值中	無效值會導致：「Picklist value does not exist」
絕不硬編碼檔案路徑 — 從 `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 — 在驗證期間，檢查每種情境類型的預期行為