platform-destructive-deploy

处理破坏性更改

通过破坏性更改清单协调删除 Salesforce 组织中的元数据。分为三个阶段：确定范围 → 验证 → 执行；生产环境的防护措施更严格。

阶段 1 — 确定删除范围

步骤 1a — 收集要移除的组件

询问用户（或根据上下文推断）要删除哪些组件。对于每个组件，记录：

• 元数据类型（例如 CustomObject、CustomField、ApexClass、Flow、PermissionSet）
• API 名称（例如 Project__c、Account.Status__c、MyController）

步骤 1b — 本地依赖扫描（尽力而为）

生成清单前，扫描本地项目，查找对每个组件的引用。使用 Grep 搜索 force-app/：

grep -rn "<componentApiName>" force-app/ --include='*.cls' --include='*.trigger' --include='*.xml' --include='*.js' --include='*.html'

如果找到引用：

• 将引用列出给用户
• 建议先更新这些引用，或在同一次破坏性部署中一并移除
• 不要默默继续 — 明确指出依赖风险

步骤 1c — 生成 destructiveChanges.xml

写入 manifest/destructiveChangesPre.xml（用于部署前删除）或 manifest/destructiveChangesPost.xml（用于部署后删除）。使用标准的 Salesforce 元数据格式：

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>Project__c</members>
        <members>OldThing__c</members>
        <name>CustomObject</name>
    </types>
    <types>
        <members>Account.Status__c</members>
        <name>CustomField</name>
    </types>
    <version>62.0</version>
</Package>

使用 sfdx-project.json 中的 sourceApiVersion 作为 API 版本。

按元数据类型对组件分组（每种类型一个 <types> 块）。对于命名空间字段，使用 Object.Field 表示法。

阶段 2 — 验证

执行破坏性部署前，必须先验证：

sf project deploy validate \
  --pre-destructive-changes manifest/destructiveChangesPre.xml \
  --manifest manifest/package.xml \
  --target-org <alias> \
  --test-level RunLocalTests \
  --json

（对于部署后破坏性更改：使用 --post-destructive-changes。）

如果不存在 package.xml，请在旁边创建一个空文件（仅删除的部署需要包描述符）：

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <version>62.0</version>
</Package>

如果验证失败，向用户说明错误并停止。常见失败原因：

• "Cannot delete: referenced by Apex/Flow/Layout" → 组件仍存在引用
• "Cannot delete: required for license" → 存在托管包或许可证依赖
• "Insufficient access" → 用户没有删除权限

阶段 3 — 执行

生产环境路径

执行前，确认目标是否为生产环境。可靠的检查方式是使用 gate 的分类器；它会像部署钩子一样解析组织（返回 production|sandbox|scratch|trial|unknown）：

"${CLAUDE_PLUGIN_ROOT}/scripts/sf-deploy-gate" bucket <alias>

unknown 表示无法确认组织类型（通常是组织记录不完整）。请明确说明：部署 gate 仍允许部署，该组织的保存时自动部署会保持关闭；重新使用 sf org login web 进行身份验证通常可以恢复分类结果。

如果分类器返回 production：

1. 显示破坏性操作确认横幅（与 platform-quick-deploy 一致）
2. 列出将被删除的所有组件
3. 要求用户明确输入“yes, delete from PRODUCTION”进行确认
4. 除非用户明确输入 --purge-on-delete，否则拒绝使用该选项

PreToolUse 钩子（sf-deploy-gate destructive）会阻止直接对生产环境执行破坏性命令 — 将这一拦截情况告知用户，不要绕过它。

Sandbox / Scratch 路径

sf project deploy start \
  --pre-destructive-changes manifest/destructiveChangesPre.xml \
  --manifest manifest/package.xml \
  --target-org <alias> \
  --json \
  --wait 30

只有在用户明确要求永久删除（跳过回收站）时，才添加 --purge-on-delete。

阶段 4 — 删除后清理

破坏性部署成功后：

• 建议执行 sf project retrieve start --metadata <Type>:<Name> 并无帮助（组件已不存在）— 应改为建议清理本地源文件：

  # Remove the now-deleted local files to keep source tracking accurate
  rm -rf force-app/main/default/<path-to-component>
  

• 如果删除的是包含数据的自定义字段，提醒用户数据已经丢失（或仍在回收站中，直到被清除）
• 建议运行测试，确认没有运行时回归

规则

• 必须先验证；绝不跳过阶段 2
• 必须扫描本地引用；绝不盲目删除
• 必须通过用户明确确认来把关生产环境操作
• 未经用户明确要求，绝不添加 --purge-on-delete
• 破坏性部署绝不使用 --ignore-errors
• 必须使用 sfdx-project.json 中的 API 版本，不得硬编码
• 如果用户要删除设置了 required="true" 的字段，或用于 RecordType 选项列表值的字段，继续操作前必须说明级联影响