platform-custom-field-generate

Salesforce 自訂欄位產生器與驗證器

概觀

產生並驗證 Salesforce CustomField 中繼資料 XML，特別處理失敗率最高的類型——彙總摘要與主從關係。代理程式必須在輸出 XML 前驗證下列限制，以避免 Metadata API 部署錯誤。

1. 通用必填屬性

每個產生的欄位都必須包含這些標籤：

屬性	需求	備註
`<fullName>`	必填	欄位名稱：從 `<label>` 衍生——每個單字首字母大寫，空格替換為 `_`，加上 `__c` 後綴。必須以字母開頭。例如，標籤 `Total Contract Value` → `Total_Contract_Value__c`。此規則適用於欄位名稱。下拉式清單值 `<fullName>` 不同——保持使用者拼寫的原文，包含空格，不加 `__c`（例如 `Closed Won`，不是 `Closed_Won`）。請參閱 `references/advanced-picklists.md`（參考 §3）。
`<label>`	必填	UI 名稱（標題大小寫）
`<description>`	一律包含	說明此欄位存在的業務原因。
`<inlineHelpText>`	一律包含	可操作的使用者指引，提供超越標籤的價值（例如「輸入含稅金額（美元）」，而非「金額」）。

即使 Metadata API 未強制要求，<description> 和 <inlineHelpText> 仍是必填輸出——省略會產生低品質的中繼資料。

檔案路徑（SFDX 來源格式）： 將每個欄位儲存為 force-app/main/default/objects/<Object>/fields/<FieldName>__c.field-meta.xml，其中 <Object> 是物件的 API 名稱（Account、Opportunity 或自訂的 Inventory_Item__c）。路徑錯誤的 XML 永遠不會被 Metadata API 看到。

外部 ID 設定

觸發條件： 如果使用者提及「整合」、「匯入資料」、「外部系統 ID」或「來自 [系統名稱] 的唯一金鑰」，請設定 <externalId>true</externalId>。

適用類型： 文字、數字、電子郵件

2. 精確度、小數位數與長度規則

為確保部署成功，請遵循以下數學限制：

精確度與小數位數規則

precision 是總位數；scale 是小數位數
規則： precision ≤ 18 且 scale ≤ precision
計算： 小數點左側位數 = precision - scale

「固定 255」規則

TextArea：不要包含 <length> — Metadata API 隱含地將長度固定為 255，並拒絕明確的 <length> 值，錯誤訊息為「Can not specify 'length' for a CustomField of type TextArea」。完全省略 <length>；欄位只需要 <fullName>、<label> 和 <type>TextArea</type>。

可見行數

長文字/豐富文字和多選下拉式清單必須設定，以控制 UI 高度。

3. 欄位資料類型

3.1 簡單屬性類型

類型	`<type>` 值	必填屬性
自動編號	`AutoNumber`	`displayFormat`（必須包含 `{0}`）、`startingNumber`
核取方塊	`Checkbox`	預設 `defaultValue` 為 `false`
日期	`Date`	不需要精確度/長度
日期/時間	`DateTime`	不需要精確度/長度
電子郵件	`Email`	內建格式驗證
查閱關係	`Lookup`	`referenceTo`、`relationshipName`、`deleteConstraint`
主從關係	`MasterDetail`	`referenceTo`、`relationshipName`、`relationshipOrder`
數字	`Number`	`precision`、`scale`
貨幣	`Currency`	預設精確度：18，小數位數：2
百分比	`Percent`	預設精確度：5，小數位數：2
電話	`Phone`	標準化電話號碼格式
下拉式清單	`Picklist`	`valueSet` 包含 `valueSetDefinition`（內嵌）或 `valueSetName`（參照）；`restricted`（請參閱下方「Picklist `restricted` 預設」；進階案例見 §3.4）
文字	`Text`	`length`（最大 255）
文字區塊	`TextArea`	無——不要包含 `<length>`；API 隱含地將長度固定為 255
文字（長）	`LongTextArea`	`length`、`visibleLines`（預設 3）
文字（豐富）	`Html`	`length`、`visibleLines`（預設 25）
時間	`Time`	僅儲存時間（不含日期）
URL	`Url`	驗證通訊協定和格式

3.2 計算與多值類型

類型	`<type>` 值	必填屬性
公式	結果類型（例如 `Number`）	`formula`、`formulaTreatBlanksAs`
彙總摘要	`Summary`	完整需求請參閱第 5 節
多選下拉式清單	`MultiselectPicklist`	`valueSet`、`visibleLines`（預設 4）

3.3 特殊類型

類型	`<type>` 值	必填屬性
地理位置	`Location`	`scale`、`displayLocationInDecimal`

Picklist `restricted` 預設

一律在 <valueSet> 內設定 <restricted>true</restricted>，除非使用者明確表示下拉式清單應接受管理員定義清單以外的自訂值（例如「不受限制」/「開放」）。受限集合上限為 1,000 個總值（啟用 + 停用）。最小內嵌形狀：

<valueSet>
  <restricted>true</restricted>
  <valueSetDefinition>
    <sorted>false</sorted>
    <value><fullName>Option_A</fullName><default>false</default><label>Option A</label></value>
  </valueSetDefinition>
</valueSet>

3.4 進階下拉式清單

上述內嵌 <valueSetDefinition> 是簡單案例。以下所有內容的完整規則和正確/錯誤範例請參閱
references/advanced-picklists.md — 任何非平凡的下拉式清單都請載入。下方括號中的章節編號（例如「ref §1」）指向該參考檔案，而非此技能。硬性規則：

值集參照（ref §1）。 <valueSet> 只能包含 <valueSetName>（參照）或
<valueSetDefinition>（內嵌）——絕不可同時包含。使用裸開發人員名稱參照——
標準集 Industry、全域值集 Priority_Levels，不加 __gvs 也不加 __c
（__gvs 後綴僅供組織儲存顯示；Metadata API 使用裸名稱）。值集支援的欄位是 <restricted>true</restricted>。建立值集是 platform-value-set-generate 技能的工作；此技能僅參照它。
值名稱保真（ref §3）。 下拉式清單值的 <fullName>/<label> 保持使用者的確切文字，包含空格（Closed Won，絕非 Closed_Won）。空格→_ + __c 規則僅適用於欄位名稱。
相依下拉式清單（ref §2）。 使用現代 API 38.0+ 形式：<controllingField> +
每對一個 <valueSettings>（<controllingFieldValue>+<valueName>）；絕不使用舊版
<picklist>/<picklistValues>/<controllingFieldValues> 標籤。控制與相依欄位都必須設定 <restricted>true</restricted>，即使請求未如此要求。
增強值屬性（ref §3）。 <value> 項目也接受 <color>（十六進位，開頭 #）、<isActive>（false 停用值）以及值層級的 <description>。
將下拉式清單範圍限定到記錄類型（ref §5）。 每個記錄類型的值可見性位於 RecordType（<picklistValues>），而非欄位。RecordType 檔案有自己的 <fullName>（裸開發人員名稱）。首先決定物件是否需要 BusinessProcess： 只有 Opportunity / Lead / Case / Solution 需要——它們在沒有 <businessProcess> 時無法部署（Required field is missing: businessProcess），即使只篩選自訂下拉式清單也是如此。此時輸出兩個耦合檔案：businessProcesses/<Name>.businessProcess-meta.xml 檔案，以及在 <RecordType> 內（<active> 之後、<picklistValues> 之前）的對應 <businessProcess><Name></businessProcess>；BP 檔案中的 <fullName> 是裸的，絕不帶物件限定。自訂物件（*__c）和所有其他標準物件（Account、Contact 等）不需要 BusinessProcess——僅輸出 RecordType；不要憑空發明。 範圍限制： 僅限每個記錄類型的下拉式清單值可見性——非一般記錄類型編寫（精簡版面、頁面版面、品牌）。

4. 主從關係規則（重要）

主從關係欄位有嚴格的屬性限制，與查閱欄位不同。違反這些規則會導致部署失敗。

主從關係欄位的禁止屬性

絕不在主從關係欄位上包含這些屬性：

禁止屬性	原因	後果
`<required>`	主從關係設計上永遠必填	部署錯誤
`<deleteConstraint>`	主從關係永遠串聯刪除	部署錯誤
`<lookupFilter>`	僅支援於查閱欄位	部署錯誤

主從關係 vs 查閱比較

屬性	主從關係	查閱
`<required>`	禁止	選用
`<deleteConstraint>`	禁止（永遠 CASCADE）	必填（`SetNull`、`Restrict`、`Cascade`）
`<lookupFilter>`	禁止	選用
`<relationshipOrder>`	必填（0 或 1）	不適用
`<reparentableMasterDetail>`	選用	不適用
`<writeRequiresMasterRead>`	選用	不適用

錯誤 — 主從關係包含禁止屬性：

<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
  <fullName>Account__c</fullName>
  <type>MasterDetail</type>
  <referenceTo>Account</referenceTo>
  <relationshipName>Contacts</relationshipName>
  <relationshipOrder>0</relationshipOrder>
  <required>true</required>                     <!-- 錯誤：移除 -->
  <deleteConstraint>Cascade</deleteConstraint>  <!-- 錯誤：移除 -->
  <lookupFilter>...</lookupFilter>              <!-- 錯誤：移除整個區塊 -->
</CustomField>

錯誤訊息： Master-Detail Relationship Fields Cannot be Optional or Required · Can not specify 'deleteConstraint' for a CustomField of type MasterDetail · Lookup filters are only supported on Lookup Relationship Fields

正確 — 主從關係欄位：

<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
  <fullName>Account__c</fullName>
  <label>Account</label>
  <description>將此記錄連結至其父項 Account</description>
  <type>MasterDetail</type>
  <referenceTo>Account</referenceTo>
  <relationshipLabel>子記錄</relationshipLabel>
  <relationshipName>ChildRecords</relationshipName>
  <relationshipOrder>0</relationshipOrder>
  <reparentableMasterDetail>false</reparentableMasterDetail>
  <writeRequiresMasterRead>false</writeRequiresMasterRead>
  <!-- 無 required、deleteConstraint 或 lookupFilter -->
</CustomField>

正確 — 查閱欄位（含選用屬性）：

<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
  <fullName>Related_Account__c</fullName>
  <label>相關帳戶</label>
  <description>可選的相關帳戶連結</description>
  <type>Lookup</type>
  <referenceTo>Account</referenceTo>
  <relationshipLabel>相關記錄</relationshipLabel>
  <relationshipName>RelatedRecords</relationshipName>
  <required>false</required>
  <deleteConstraint>SetNull</deleteConstraint>
  <lookupFilter>
    <active>true</active>
    <filterItems>
      <field>Account.Type</field>
      <operation>equals</operation>
      <value>Customer</value>
    </filterItems>
    <isOptional>false</isOptional>
  </lookupFilter>
</CustomField>

其他主從關係規則

關係順序： 物件上第一個主從關係 = 0，第二個 = 1
關係名稱： 必須是複數 PascalCase 字串（例如 Travel_Bookings）
聯結物件： 使用兩個主從關係欄位實現標準多對多（啟用彙總）
限制： 每個物件最多 2 個主從關係。其他關係請使用查閱。

5. 彙總摘要欄位規則（重要）

彙總摘要欄位的部署失敗率最高。請嚴格遵循這些規則。

彙總摘要的必填元素

元素	需求	格式
`<type>`	必填	一律 `Summary`
`<summaryOperation>`	必填	`count`、`sum`、`min` 或 `max`
`<summaryForeignKey>`	必填	`ChildObject__c.MasterDetailField__c`
`<summarizedField>`	條件式	`sum`、`min`、`max` 需要。`count` 不需要

彙總摘要的禁止元素

絕不在彙總摘要欄位上包含這些屬性：

禁止屬性	原因
`<precision>`	摘要繼承自彙總欄位
`<scale>`	摘要繼承自彙總欄位
`<required>`	不適用於摘要欄位
`<length>`	不適用於摘要欄位

summaryForeignKey 和 summarizedField 的格式規則

重要： summaryForeignKey 和 summarizedField 都必須使用完整限定格式：

ChildObjectAPIName__c.FieldAPIName__c

決策邏輯：

summaryForeignKey = ChildObject__c.MasterDetailFieldOnChild__c
summarizedField = ChildObject__c.FieldToSummarize__c

錯誤 — 彙總摘要常見錯誤：

<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
  <fullName>Total_Amount__c</fullName>
  <label>總金額</label>
  <type>Summary</type>
  <precision>18</precision>           <!-- 錯誤：移除 - 繼承自來源 -->
  <scale>2</scale>                    <!-- 錯誤：移除 - 繼承自來源 -->
  <summaryOperation>sum</summaryOperation>
  <summaryForeignKey>Order__c</summaryForeignKey>        <!-- 錯誤：缺少欄位名稱 -->
  <summarizedField>Amount__c</summarizedField>           <!-- 錯誤：缺少物件名稱 -->
</CustomField>

錯誤訊息：

Can not specify 'precision' for a CustomField of type Summary
Must specify the name in the CustomObject.CustomField format (e.g. Account.MyNewCustomField)

正確 — 彙總摘要（SUM 運算）：

<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
  <fullName>Total_Amount__c</fullName>
  <label>總金額</label>
  <description>所有明細項目金額的總和</description>
  <inlineHelpText>自動從子明細項目計算</inlineHelpText>
  <type>Summary</type>
  <summaryOperation>sum</summaryOperation>
  <summarizedField>Order_Line_Item__c.Amount__c</summarizedField>
  <summaryForeignKey>Order_Line_Item__c.Order__c</summaryForeignKey>
  <!-- 無 precision、scale、required 或 length -->
</CustomField>

COUNT： 結構與 SUM 相同，但完全省略 <summarizedField>（保留 <summaryForeignKey>）。MIN / MAX： 與 SUM 相同——只需 <summaryOperation>min</summaryOperation> 或 max，<summarizedField> 指向要尋找最小值/最大值的欄位。下方快速參考表涵蓋全部四種。

彙總摘要快速參考

運算	需要 summarizedField？	使用案例
`count`	否	計算子記錄數
`sum`	是	加總數值
`min`	是	尋找最小值
`max`	是	尋找最大值

彙總摘要先決條件

彙總摘要欄位只能在主從關係中的父項物件上建立
子物件必須有指向此父項的主從關係欄位
彙總欄位必須存在於子物件上

6. 公式欄位規則

公式結果類型

公式本身不是類型。<formula> 標籤是加在 <type> 設定為結果資料類型的欄位上：

Checkbox、Currency、Date、DateTime、Number、Percent、Text

公式 XML 產生規則

<formula> 標籤的內容必須包在 <![CDATA[ ... ]]> 區段中。這可防止 XML 解析器將公式運算子（如 &、<、>）解讀為 XML 標記。
如果公式文字本身包含字面序列 ]]>，請透過中斷 CDATA 區塊來跳脫：例如 <![CDATA[Text_Field__c & "]]]]><![CDATA[>"]]>
絕不使用名為 returnType 的屬性或標籤。Metadata API 中不存在此項目。<type> 標籤定義公式結果的傳回資料類型。

formulaTreatBlanksAs 規則

決策邏輯：

如果公式結果類型 = Number、Currency 或 Percent → 設定 <formulaTreatBlanksAs>BlankAsZero</formulaTreatBlanksAs>
如果公式結果類型 = Text、Date 或 DateTime → 設定 <formulaTreatBlanksAs>BlankAsBlank</formulaTreatBlanksAs>

錯誤 — 使用 Formula 作為類型：

<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
  <fullName>Calculated_Value__c</fullName>
  <type>Formula</type>  <!-- 錯誤：Formula 不是有效類型 -->
  <returnType>Number</returnType>  <!-- 錯誤：Metadata API 中不存在 returnType -->
  <formula>Field1__c + Field2__c</formula>  <!-- 錯誤：缺少 CDATA 包裝 -->
</CustomField>

正確 — 公式欄位：

<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
  <fullName>Calculated_Value__c</fullName>
  <label>計算值</label>
  <description>Field1 和 Field2 的總和</description>
  <type>Number</type>  <!-- 結果類型，不是 "Formula" -->
  <precision>18</precision>
  <scale>2</scale>
  <formula><![CDATA[Field1__c + Field2__c]]></formula>
  <formulaTreatBlanksAs>BlankAsZero</formulaTreatBlanksAs>
</CustomField>

公式欄位相依性與函式

參照其他欄位的公式欄位，如果參照的欄位不存在或尚未部署，部署會失敗——請先部署參照的欄位。
下拉式清單比較請使用 ISPICKVAL()（而非 ==）。
完整的公式函式參考（TEXT/VALUE/CASE/DAY/MONTH/DATEVALUE/ISCHANGED 類型規則），請交由 platform-validation-rule-generate 技能處理，該技能負責公式函式的正確性。

7. 常見部署錯誤

錯誤訊息	原因	修正
`ConversionError: Invalid XML tags or unable to find matching parent xml file for CustomField`	XML 註解放在根元素 `<CustomField>` 之前	移除 `.field-meta.xml` 檔案中 `<CustomField>` 之前的 XML 註解（`<!-- ... -->`）
`Field [FieldName] does not exist. Check spelling.`	參照的欄位不存在或尚未部署	確認參照的欄位存在並先於此欄位部署
`DUPLICATE_DEVELOPER_NAME`	欄位 fullName 已存在於物件上	使用唯一的業務導向名稱
`MAX_RELATIONSHIPS_EXCEEDED`	物件上超過 2 個主從關係或 15 個查閱欄位	第三個以上的主從關係使用查閱；檢視查閱數量
保留關鍵字錯誤	使用 `Order__c`、`Group__c` 等	重新命名為 `Status_Order__c` 等
`Value set must reference a value set name or define a value set, but not both`	`<valueSet>` 同時包含 `<valueSetName>` 和 `<valueSetDefinition>`	僅保留一個（請參閱第 3.4 節）
`duplicate value found: [X] is defined multiple times`	兩個 `<value>` 項目共用 `<fullName>`	讓每個下拉式清單值的 `<fullName>` 唯一
下拉式清單值上的 `Invalid fullName`	值 `<fullName>` 以數字開頭或包含連字號	以字母開頭；無連字號、無開頭數字。允許空格——不要加底線（請參閱 §3.4 值名稱保真）
`Element ...picklist is not allowed`	已棄用的 ≤37.0 相依下拉式清單語法（`<picklist>`/`<picklistValues>`/`<controllingFieldValues>`）	使用現代 `valueSettings`/`controllingFieldValue`/`valueName` 形式（第 3.4 節）

8. 驗證檢查清單

產生 CustomField XML 前，請驗證：

通用檢查

[ ] <fullName> 是否使用有效格式並以 __c 結尾？
[ ] <description> 和 <inlineHelpText> 是否都已填寫且有意義？
[ ] <label> 是否為標題大小寫？
[ ] 根元素 <CustomField> 之前是否沒有 XML 註解（）？（根元素前的註解會破壞 SDR 的解析器）

主從關係欄位檢查（重要）

[ ] <required> 屬性是否不存在？（主從關係永遠必填）
[ ] <deleteConstraint> 屬性是否不存在？（主從關係永遠串聯）
[ ] <lookupFilter> 區塊是否不存在？（僅適用於查閱欄位）
[ ] <relationshipOrder> 是否設定為 0 或 1？
[ ] 父物件的 <sharingModel> 是否設定為 ControlledByParent？

查閱欄位檢查

[ ] <deleteConstraint> 是否設定為 SetNull、Restrict 或 Cascade？
[ ] <relationshipName> 是否為複數 PascalCase？

下拉式清單欄位檢查

[ ] 每個 <valueSet> 是否僅包含 <valueSetName> 或 <valueSetDefinition>——絕不兩者兼有？
[ ] 對於值集參照：是否設定 <restricted>true</restricted>？
[ ] 對於 StandardValueSet 參照：名稱是否為裸列舉且無 __c（例如 Industry）？
[ ] 對於 GlobalValueSet 參照：名稱是否為裸開發人員名稱且無 __gvs 後綴？
[ ] 對於相依下拉式清單：是否設定 <controllingField>，且每對有一個 <valueSettings>（<controllingFieldValue> + <valueName>）？
[ ] 對於相依下拉式清單：已棄用的 <picklist>/<picklistValues>/<controllingFieldValues> 形式是否不存在？
[ ] 所有下拉式清單值的 <fullName> 是否唯一、以字母開頭且無連字號？（允許空格——不要替換為底線，依據 §3.4 值名稱保真規則）

彙總摘要欄位檢查（重要）

[ ] <precision> 屬性是否不存在？
[ ] <scale> 屬性是否不存在？
[ ] <summaryForeignKey> 是否為 ChildObject__c.MasterDetailField__c 格式？
[ ] 對於 SUM/MIN/MAX：<summarizedField> 是否為 ChildObject__c.FieldName__c 格式？
[ ] 對於 COUNT：<summarizedField> 是否不存在？
[ ] 子物件是否有指向此父項的主從關係欄位？

公式欄位檢查

[ ] <type> 是否設定為結果類型（不是 "Formula"）？
[ ] <formula> 內容是否包在 <![CDATA[ ... ]]> 中？
[ ] <returnType> 屬性是否不存在？（Metadata API 中不存在）
[ ] <formulaTreatBlanksAs> 是否設定為數值結果的 BlankAsZero 或文字/日期結果的 BlankAsBlank？
[ ] 所有參照的欄位是否存在並先於此欄位部署？

數值欄位檢查

[ ] scale ≤ precision 是否成立？
[ ] precision ≤ 18 是否成立？

文字區塊檢查

[ ] 對於 TextArea：是否省略 <length>？（API 會拒絕 TextArea 欄位上的明確 <length> 值。）
[ ] 對於 LongTextArea/Html：是否設定 <visibleLines>？

關係限制檢查

[ ] 物件上是否少於或等於 2 個主從關係？
[ ] 物件上是否少於或等於 15 個查閱關係？

命名檢查

[ ] API 名稱是否不含保留字（Order、Group、Select 等）？
[ ] API 名稱在此物件上是否唯一？

您可能也喜歡

sherpa-onnx-tts

386Kdevops-cloud

Local text-to-speech via sherpa-onnx (offline, no cloud)

openclaw

獲取

sherpa-onnx-tts

384Kdevops-cloud

透過 sherpa-onnx 實現本地文字轉語音（離線，無需雲端）

steipete

獲取

latency-critical-systems

240Kdevops-cloud

Use for latency-sensitive systems such as realtime dashboards, market data, streaming agents, execution gateways, queues, caches, or HFT-like infrastructure where freshness and p95 latency matter. Use when p95 latency or data freshness matters — realtime dashboards, market data, streaming agents, queues, or caches.

affaan-m

獲取

繼續探索

瀏覽 devops-cloud 熱門 Skills 最近更新

platform-custom-field-generate

相關技能

Salesforce 自訂欄位產生器與驗證器

概觀

1. 通用必填屬性

外部 ID 設定

2. 精確度、小數位數與長度規則

精確度與小數位數規則

「固定 255」規則

可見行數

3. 欄位資料類型

3.1 簡單屬性類型

3.2 計算與多值類型

3.3 特殊類型

Picklist restricted 預設

3.4 進階下拉式清單

4. 主從關係規則（重要）

主從關係欄位的禁止屬性

主從關係 vs 查閱比較

錯誤 — 主從關係包含禁止屬性：

正確 — 主從關係欄位：

正確 — 查閱欄位（含選用屬性）：

其他主從關係規則

5. 彙總摘要欄位規則（重要）

彙總摘要的必填元素

彙總摘要的禁止元素

summaryForeignKey 和 summarizedField 的格式規則

錯誤 — 彙總摘要常見錯誤：

正確 — 彙總摘要（SUM 運算）：

彙總摘要快速參考

彙總摘要先決條件

6. 公式欄位規則

公式結果類型

公式 XML 產生規則

formulaTreatBlanksAs 規則

錯誤 — 使用 Formula 作為類型：

正確 — 公式欄位：

公式欄位相依性與函式

7. 常見部署錯誤

8. 驗證檢查清單

通用檢查

主從關係欄位檢查（重要）

查閱欄位檢查

下拉式清單欄位檢查

彙總摘要欄位檢查（重要）

公式欄位檢查

數值欄位檢查

文字區塊檢查

關係限制檢查

命名檢查

您可能也喜歡

sherpa-onnx-tts

sherpa-onnx-tts

latency-critical-systems

繼續探索

Picklist `restricted` 預設