platform-custom-object-generate

何時使用此技能

當您需要以下情況時，請使用此技能：

• 建立新的自訂物件
• 產生自訂物件中繼資料 XML
• 設定物件共用和安全性設定
• 設定物件功能和能力
• 疑難排解與自訂物件相關的部署錯誤
• 在現有物件上新增、更新或刪除欄位或驗證規則 — 任何這些操作都可能使物件的 <description> 過時，因此您必須重新整理它（提出建議並確認）。這同樣適用於驗證規則的變更，而不僅僅是欄位。請參閱第 3.B 節。

規格

1. 概述與目的

本文件定義了產生 CustomObject 中繼資料 XML（.object-meta.xml 檔案）的強制約束。代理程式必須在輸出 XML 之前驗證這些約束，以防止 Metadata API 部署錯誤。

副檔名： .object-meta.xml

🔔 描述新鮮度 — 適用於每個物件變更，包括欄位和驗證規則： 每當您在物件上新增、更新或刪除欄位或驗證規則時，<description> 可能已過時。在完成之前，請根據第 3.B 節重新整理它（提出建議、與使用者確認、寫入）。驗證規則的變更與欄位變更完全一樣 — 在描述協調一致之前，變更尚未完成。這在驗證規則的編輯/刪除時很容易被遺忘 — 請不要忘記。

---

2. 語法要點（第 1 層）

以下約束必須成立，XML 主體才能成功部署。

注意： API 名稱（fullName）不是標籤；它是檔案名稱（例如 Vehicle__c.object-meta.xml）。

必要元素

元素	需求	備註
<label>	必要	單數 UI 名稱
<pluralLabel>	必要	複數 UI 名稱
<sharingModel>	必要	請參閱下方的共用模型規則
<deploymentStatus>	必要	一律設定為 Deployed
<nameField>	必要	主要記錄識別碼（需要 <label> 和 <type>）
<visibility>	必要	一律設定為 Public

共用模型規則

預設： 將 <sharingModel> 設定為 ReadWrite。

例外： 如果此物件包含主從關係欄位，則 <sharingModel> 必須是 ControlledByParent。

決策邏輯：

• 如果物件沒有主從欄位 → 使用 ReadWrite
• 如果物件有主從欄位 → 使用 ControlledByParent
• 如果將主從欄位新增到現有的子物件 → 該現有物件的 <sharingModel> 也必須更新為 ControlledByParent

❌ 錯誤 — 將導致錯誤：Cannot set sharingModel to ReadWrite on a CustomObject with a MasterDetail relationship field

<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">
  <label>Order Line Item</label>
  <pluralLabel>Order Line Items</pluralLabel>
  <sharingModel>ReadWrite</sharingModel>  <!-- 錯誤：物件有主從欄位 -->
  <deploymentStatus>Deployed</deploymentStatus>
</CustomObject>

✅ 正確：

<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">
  <label>Order Line Item</label>
  <pluralLabel>Order Line Items</pluralLabel>
  <sharingModel>ControlledByParent</sharingModel>  <!-- 正確 -->
  <deploymentStatus>Deployed</deploymentStatus>
</CustomObject>

---

3. 智慧預設與決策邏輯（第 2 層）

代理程式必須根據物件的預期使用案例選擇要啟用的功能。

A. 名稱欄位決策

類型	使用時機	其他需求
Text	人類命名實體的預設（專案、位置、團隊）	無
AutoNumber	用於交易、日誌或 ID（發票、請求、工單）	必須包含 <displayFormat>（例如 INV-{0000}）和 <startingNumber>1</startingNumber>

文字名稱欄位範例：

<nameField>
  <label>Project Name</label>
  <type>Text</type>
</nameField>

自動編號名稱欄位範例：

<nameField>
  <label>Invoice Number</label>
  <type>AutoNumber</type>
  <displayFormat>INV-{0000}</displayFormat>
  <startingNumber>1</startingNumber>
</nameField>

B. 物件描述（豐富化）

<description>：強制 — 每個自訂物件都必須有描述。它必須讀起來像人工撰寫的文件，絕不能是通用範本（「用於追蹤和管理……的物件」）或中繼資料傾印（「包含 8 個欄位，包括 Project_Name__c……」）。

一律撰寫豐富的描述 — 在建立物件時，以及在對其進行任何變更時：新增、更新或刪除欄位或驗證規則（這樣它永遠不會過時）。變更（欄位或驗證規則）在您重新整理物件的描述之前尚未完成。這不是可選的；不要詢問是否要新增描述。

每次變更都確認 — 每次都這樣。 對每個欄位/規則變更分別提出建議並確認。先前的「保持目前」僅適用於該次變更；絕不是跳過後續變更提案的永久許可。不要從先前的答案推斷偏好 — 每次新變更都要重新提出並重新詢問。

撰寫描述（步驟如下）。如果物件已有描述，請將其視為強烈訊號 — 保留其承載的業務脈絡（網域、團隊、結構描述無法顯示的意圖），並將新欄位/規則納入其中，而不是丟棄。

然後根據是否已有描述來分支：

• 沒有現有描述（全新物件）： 沒有什麼可覆寫 — 直接寫入撰寫的描述。不要提示。

• 有現有描述（更新、刪除或任何重新豐富化）： 絕不要靜默覆寫 — 您無法從檔案判斷它是管理員手寫的還是先前產生的。顯示提案、詢問，然後停止 — 等待使用者回覆後再寫入：

  {Object} 的建議描述：
  <the enriched description>
  目前：<the existing description>
  使用這個嗎？（是 / 保持目前 / 編輯）

  在使用者回覆之前，您絕對不能寫入 <description> — 顯示差異不是核准，即使變更看起來明顯或微小。然後採取行動：是 → 寫入建議的文字 · 保持目前 → 保持現有描述不變（這僅適用於此次變更 — 下次變更時重新提出） · 編輯 → 使用使用者的措辭。

最後一定要寫入 <description>。

撰寫描述：

1. 分類每個欄位，根據它在描述中的呈現方式：
   • 受限（必要、唯一、externalId、限制選擇清單） → 選擇性括號：VIN (required, external ID)、Color (Red/Green only)
   • 行為（公式、彙總） → 描述它計算的內容：「Age Years 欄位會自動計算車輛年齡」
   • 關係（主從、查閱） → 融入脈絡：「作為 Account 的子項」（絕不要「(Master-Detail to Account)」）
   • 標準 → 僅標籤
2. 按此順序撰寫，使用欄位標籤而非 API 名稱：

   目的 → 關鍵欄位 → 計算欄位 → 驗證規則（作為業務規則） → 「常用於 {使用案例}。」

3. 寫入前計數並修剪（必要）： 計算字數；目標約 45，硬上限 50。如果超過，先緊縮措辭，然後按優先順序刪除整個句子（使用案例 → 規則 → 計算；絕不要刪除句子 1–2）。重新計數。在 ≤ 50 之前不要寫入。

範例（Car，46 字）：

<description>The Car object tracks vehicle inventory and maintenance. It captures Year, VIN (required, external ID), Color (Red/Green only), and Location; the Age Years field auto-calculates vehicle age. VIN is required and Black cars cannot be sold. Commonly used for fleet management, inventory tracking, and service scheduling.</description>

→ 如需完整工作流程和範例，請閱讀 references/description-enrichment.md。

C. 聯結物件命名

如果物件是兩個父項之間的多對多連結，請結合兩個父實體來命名物件，以確保結構描述保持直觀。

範例：

• Position_Candidate__c（連結 Position 和 Candidate）
• Job_Application__c（連結 Job 和 Application）

D. 功能啟用（乾淨 XML）

為維持「乾淨 XML」，僅在偏離 Salesforce 平台預設值 false 時才包含選用標籤。

情境 A：使用者導向物件（應用程式、追蹤器、業務實體）

• 觸發：物件旨在供使用者直接互動
• 動作：將 <enableSearch>、<enableReports>、<enableActivities> 和 <enableHistory> 設定為 true

情境 B：系統導向物件（聯結、背景日誌）

• 觸發：物件存在於技術關聯或背景資料
• 動作：省略這些標籤以保持 UI 乾淨且 XML 精簡

---

4. 關鍵約束與常見失敗

保留字

絕不要使用保留字作為自訂物件或自訂欄位的 API 名稱：

類別	保留字（請勿用作 API 名稱）
SOQL/SQL	Select、From、Where、Limit、Order、Group
系統	User、External、View、Type
時間	Date、Number

關係上限

不要為單一物件建立超過 2 個主從關係。如果需要第三個關係，請改用查閱。

XML 根元素

請勿在 .object-meta.xml 檔案的根目錄包含 <fullName> 標籤。API 名稱來自檔案名稱。

❌ 錯誤：

<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">
  <fullName>Vehicle__c</fullName>  <!-- 錯誤：移除這個 -->
  <label>Vehicle</label>
</CustomObject>

✅ 正確：

<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">
  <label>Vehicle</label>
  <!-- fullName 來自檔案名稱：Vehicle__c.object-meta.xml -->
</CustomObject>

驗證規則命名慣例

驗證規則名稱遵循與自訂欄位不同的慣例。

規則：

• 只能包含英數字元和底線
• 必須以字母開頭
• 不能以底線結尾
• 不能包含兩個連續底線
• 不能以 __c 結尾（與自訂欄位不同）

❌ 錯誤：

<validationRules>
  <fullName>Require_Start_Date__c</fullName>  <!-- 錯誤：有 __c 後綴 -->
  <active>true</active>
  <errorMessage>Start Date is required.</errorMessage>
  <formula>ISBLANK(Start_Date__c)</formula>
</validationRules>

錯誤： The validation name can only contain alphanumeric characters, must begin with a letter, cannot end with an underscore...

✅ 正確：

<validationRules>
  <fullName>Require_Start_Date</fullName>  <!-- 正確：沒有 __c 後綴 -->
  <active>true</active>
  <errorMessage>Start Date is required.</errorMessage>
  <formula>ISBLANK(Start_Date__c)</formula>
</validationRules>

命名模式參考：

中繼資料類型	命名模式	範例
自訂欄位	以 __c 結尾	Start_Date__c
驗證規則	無後綴	Require_Start_Date
自訂物件	以 __c 結尾	Vehicle__c

---

5. 驗證檢查清單

在產生自訂物件 XML 之前，請驗證：

語法檢查

• [ ] <label> 和 <pluralLabel> 都存在嗎？
• [ ] <deploymentStatus> 設定為 Deployed 嗎？
• [ ] <visibility> 設定為 Public 嗎？
• [ ] <nameField> 包含 <label> 和 <type> 嗎？
• [ ] 如果 <type> 是 AutoNumber，是否包含 <displayFormat> 和 <startingNumber>？

共用模型檢查（關鍵）

• [ ] 此物件有主從關係欄位嗎？
  • 如果有 → <sharingModel> 必須是 ControlledByParent
  • 如果沒有 → <sharingModel> 應該是 ReadWrite

約束檢查

• [ ] API 名稱沒有保留字嗎？
• [ ] 主從關係是否 ≤ 2 個？
• [ ] XML 根目錄沒有 <fullName> 嗎？

驗證規則檢查（如果適用）

• [ ] 驗證規則名稱不以 __c 結尾嗎？
• [ ] 驗證規則名稱遵循英數字元和底線模式嗎？

描述豐富化品質檢查

• [ ] 以「The {Object} object...」+ 業務目的開頭（不是「Object used to track and manage...」）
• [ ] 使用欄位標籤，絕不使用 API 名稱；沒有「Contains N fields including」傾印
• [ ] 公式/彙總以行為描述；驗證以業務規則陳述；關係作為脈絡
• [ ] 包含常見使用案例（「Commonly used for...」）且少於 50 字
• [ ] 將目前描述的任何業務脈絡納入建議的描述中（沒有丟棄）
• [ ] 對於現有描述（更新/刪除/重新豐富化），在寫入前停止並等待使用者回覆 — 不要將顯示差異視為核准

架構檢查

• [ ] <description> 存在嗎？（根據第 B 節豐富化 — 寫入前已提出並與使用者確認。）
• [ ] 如果是使用者導向，<enableSearch> 和 <enableReports> 設定為 true 嗎？
• [ ] 檔案名稱符合預期的 API 名稱嗎？

---

參考檔案索引

檔案	何時閱讀
references/description-enrichment.md	撰寫或重新整理物件的 <description> 時（建立時，或欄位/規則變更時）— 完整的豐富化工作流程、欄位優先順序層級、聯結/子項處理、邊緣案例和更多範例