sf-data

Salesforce 数据操作专家（sf-data）

当用户需要进行 Salesforce 数据工作时使用此技能：记录 CRUD、批量导入/导出、测试数据生成、清理脚本，或用于验证 Apex、Flow 或集成行为的数据工厂模式。

此技能负责的任务

以下工作使用 sf-data：

• sf data CLI 命令
• 记录创建、更新、删除、插入或更新、导出，或树形导入/导出
• 生成逼真的测试数据
• 批量数据操作和清理
• 用于数据填充 / 回滚的匿名 Apex 脚本

以下情况委派给其他技能：

• 只编写 SOQL → sf-soql
• 运行或修复 Apex 测试 → sf-testing
• 先部署元数据 → sf-deploy
• 探查架构 / 字段定义 → sf-metadata

---

重要的模式选择

确认用户需要哪种模式：

模式	适用情况
脚本生成	用户需要可复用的 .apex、CSV 或 JSON 文件，但暂时不操作组织
远程执行	用户希望现在就在真实组织中创建 / 更改记录

如果用户可能只需要脚本，不要假定需要远程执行。

---

首先需要收集的上下文

询问或推断：

• 目标对象
• 需要远程执行时使用的组织别名
• 操作类型：查询、创建、更新、删除、插入或更新、导入、导出、清理
• 预计数据量
• 这是测试数据、迁移数据，还是一次性故障排查数据
• 必须先创建哪些父子关系记录

---

核心操作规则

• 除非用户明确要求在本地生成脚本，否则 sf-data 操作的是远程组织数据。
• 创建数据前，对象和字段必须已存在。
• 对于自动化测试，如果批量行为很重要，优先使用 251 条以上记录。
• 创建大量或冗余数据前，务必考虑清理方案。
• 生成的测试数据中绝不能使用真实个人身份信息。
• 简单的 CRUD 优先使用 CLI；只有操作确实需要服务器端编排时才使用匿名 Apex。

如果缺少元数据，请停止并转交给：

• sf-metadata 或 sf-deploy

---

推荐工作流

1. 确认前置条件

确认对象 / 字段是否可用、组织是否已通过身份验证，以及所需的父记录是否存在。

2. 架构不确定时，先运行 describe 进行预检

创建或更新记录前，使用对象 describe 数据验证：

• 必填字段
• 可创建与不可创建的字段
• 选项列表值
• 关系字段和父记录要求

示例模式：

sf sobject describe --sobject ObjectName --target-org <alias> --json

实用筛选器：

# Required + createable fields
jq '.result.fields[] | select(.nillable==false and .createable==true) | {name, type}'

# Valid picklist values for one field
jq '.result.fields[] | select(.name=="StageName") | .picklistValues[].value'

# Fields that cannot be set on create
jq '.result.fields[] | select(.createable==false) | .name'

3. 选择最精简且正确的方式

需求	默认方法
少量的一次性 CRUD	sf data 单记录命令
大批量导入/导出	通过 sf data ... bulk 使用 Bulk API 2.0
父子记录种子数据集	树形导入/导出
可复用的测试数据集	工厂 / 匿名 Apex 脚本
可撤销的实验	清理脚本或基于 savepoint 的方式

4. 执行操作或生成文件

适用时，使用 assets/ 下的内置模板：

• assets/factories/
• assets/bulk/
• assets/cleanup/
• assets/soql/
• assets/csv/
• assets/json/

5. 验证结果

创建或更新后，检查数量、关系和记录 ID。

6. 采用有界重试策略

如果创建失败：

1. 按主要 CLI 命令格式尝试一次
2. 使用修正后的参数重试一次
3. 重新运行 describe / 验证假设
4. 改用其他方式或提供手动解决办法

不要无限重复同一条失败命令。

7. 提供清理指引

创建了数据时，提供准确的清理命令或回滚文件。

---

高优先级规则

批量操作安全

• 大批量数据使用批量操作
• 在适当情况下，使用 251 条以上记录测试对自动化敏感的行为
• 批量场景中避免逐条处理记录的模式

数据完整性

• 包含必填字段
• 创建前验证选项列表值
• 验证父级 ID 和关系完整性
• 考虑验证规则和重复约束
• 从输入负载中排除不可创建的字段

清理规范

优先采用以下方式之一：

• 按 ID 删除
• 按模式删除
• 按创建日期范围删除
• 在基于脚本的测试运行中使用回滚／保存点模式

---

常见失败模式

错误	可能原因	默认修复方向
INVALID_FIELD	字段 API 名称错误或 FLS 问题	验证架构和访问权限
REQUIRED_FIELD_MISSING	遗漏必填字段	根据 describe 数据提供必填值
INVALID_CROSS_REFERENCE_KEY	父级 ID 无效	先创建／验证父级
FIELD_CUSTOM_VALIDATION_EXCEPTION	验证规则阻止了记录	使用有效测试数据或调整设置
选项列表值无效	使用了猜测的值，而非基于 describe 数据的值	先检查选项列表值
字段不可写错误	字段不可创建／更新	从负载中移除该字段
批量限制／超时	使用了不适合当前数据量的工具	切换到批量／分阶段导入

---

输出格式

完成后，按以下顺序报告：

1. 执行的操作
2. 对象和数量
3. 目标 org 或本地制品路径
4. 记录 ID／输出文件
5. 验证结果
6. 清理说明

建议格式：

Data operation: <create / update / delete / export / seed>
Objects: <object + counts>
Target: <org alias or local path>
Artifacts: <record ids / csv / apex / json files>
Verification: <passed / partial / failed>
Cleanup: <exact delete or rollback guidance>

---

跨技能集成

需求	委派给	原因
探索对象／字段结构	sf-metadata	准确地以架构为依据
运行对批量操作敏感的 Apex 验证	sf-testing	测试执行和覆盖率
先部署缺失的架构	sf-deploy	确保元数据就绪
实现使用这些数据的生产逻辑	sf-apex 或 sf-flow	行为实现

---

参考索引

从这里开始

• references/sf-cli-data-commands.md
• references/test-data-best-practices.md
• references/orchestration.md
• references/test-data-patterns.md
• references/test-data-factory-usage.md

查询／批量操作／清理

• references/soql-relationship-guide.md
• references/relationship-query-examples.md
• references/bulk-operations-guide.md
• references/cleanup-rollback-guide.md
• references/cleanup-rollback-example.md

示例／限制

• references/crud-workflow-example.md
• references/bulk-testing-example.md
• references/anonymous-apex-guide.md
• references/governor-limits-reference.md
• assets/

---

评分指南

分数	含义
117+	适合生产环境且安全的数据工作流
104–116	操作良好，仍有小幅改进空间
91–103	可以接受，但建议审查
78–90	存在不完整／有风险的模式
< 78	修正前禁止使用