sf-datacloud-prepare

sf-datacloud-prepare：Data Cloud 准备阶段

当用户需要摄取数据并准备数据湖时使用此技能：数据流、Data Lake Object（DLO）、转换、Document AI、非结构化数据摄取，或从连接器设置移交至已启用的数据流。

此技能适用的任务

当工作涉及以下内容时，使用 sf-datacloud-prepare：

• sf data360 data-stream *
• sf data360 dlo *
• sf data360 transform *
• sf data360 docai *
• 选择数据应如何进入 Data Cloud
• 在源更新后重新运行或重新扫描数据摄取
• 连接器设置完成后，准备由 Ingestion API 支持的数据流

以下情况应转交给其他技能：

• 仍在创建或测试源连接 → sf-datacloud-connect
• 映射到 DMO 或设计 IR/数据图 → sf-datacloud-harmonize
• 查询已摄取的数据 → sf-datacloud-retrieve

---

首先收集所需上下文

询问或推断：

• 目标 org 别名
• 源连接名称
• 源对象／数据集／文档源
• 所需的数据流类型
• DLO 命名预期
• 用户是要创建、更新、运行还是删除数据流
• 源是 CRM、数据库连接器、非结构化文件源还是 Ingestion API 数据源

---

核心操作规则

• 运行 Data Cloud 命令前，确认外部插件运行时可用。
• 修改摄取资源前，运行共享就绪状态分类器：node ~/.claude/skills/sf-datacloud/scripts/diagnose-org.mjs -o <org> --phase prepare --json。
• 创建新的摄取资源前，优先检查现有数据流和 DLO。
• 常规使用时，通过 2>/dev/null 抑制关联插件的警告噪声。
• 将 DLO 命名和字段命名视为 Data Cloud 专用，而非 CRM 原生。
• 创建数据流前，确认每个数据集应归类为 Profile、Engagement 还是 Other。
• 处理非结构化源时，区分数据流级刷新与连接级重新运行。
• 如果平台限制了初始数据流或非结构化资源的创建，应有针对性地使用 UI 设置。
• 只有在摄取资源明确处于健康状态后，才移交给 Harmonize。

---

推荐工作流

1. 对准备工作的就绪状态进行分类

node ~/.claude/skills/sf-datacloud/scripts/diagnose-org.mjs -o <org> --phase prepare --json

2. 检查现有摄取资源

sf data360 data-stream list -o <org> 2>/dev/null
sf data360 dlo list -o <org> 2>/dev/null

3. 创建前确认数据流类别

建议类别时使用以下规则：

类别	适用场景	典型要求
Profile	人员／实体记录	主键
Engagement	基于时间的事件或交互	主键 + 事件时间字段
Other	参考／配置／辅助数据集	主键

如果源数据含义不明确，应明确询问用户，该数据集应归类为 Profile、Engagement 还是 Other。

4. 有针对性地创建或检查数据流

sf data360 data-stream get -o <org> --name <stream> 2>/dev/null
sf data360 data-stream create-from-object -o <org> --object Contact --connection SalesforceDotCom_Home 2>/dev/null
sf data360 data-stream create -o <org> -f stream.json 2>/dev/null
sf data360 data-stream run -o <org> --name <stream> 2>/dev/null

5. 检查 DLO 结构

sf data360 dlo get -o <org> --name Contact_Home__dll 2>/dev/null

6. 选择合适的刷新机制

选择与用户目标相符且范围更小的刷新方式：

sf data360 data-stream run -o <org> --name <stream> 2>/dev/null
sf data360 connection run-existing -o <org> --name <connection-id> 2>/dev/null

• data-stream run 最接近数据流级刷新或重新扫描。
• connection run-existing 在连接级运行，适用于某些连接器工作流，但不能可靠地替代非结构化源的数据流刷新。
• 对于非结构化文档连接器，如果目标是重新扫描新增或已更改的文件，优先使用 data-stream run。

7. 有针对性地处理非结构化源

对于类似 SharePoint 的文档摄取，最精简的非结构化 DLO 负载示例如下：

{
  "name": "my_udlo",
  "label": "My UDLO",
  "category": "Directory_Table",
  "dataSource": {
    "sourceType": "SF_DRIVE",
    "directoryAndFilesDetails": [
      {
        "dirName": "SPUnstructuredDocument/<CONNECTION_ID>/<SITE_ID>",
        "fileName": "*"
      }
    ],
    "sourceConfig": {
      "reservedPrefix": "$dcf_content$"
    }
  }
}

如果用户需要更完整的端到端流程，首次设置非结构化数据时应使用 UI。UI 流程可以创建额外的文档元数据字段和下游资源，而直接使用 CLI 创建 DLO 的简单流程可能不会自动配置这些内容。

8. 使用本地 Ingestion API 示例完成数据发送工作流

对于向 Data Cloud 推送记录的外部系统：

1. 在 sf-datacloud-connect 中创建连接器
2. 使用 sf data360 connection schema-upsert 上传架构
3. 如有需要，在 UI 中创建数据流
4. 使用 examples/ingestion-api/ 中的本地示例发送记录

cd examples/ingestion-api
cp .env.example .env
python3 send-data.py

关键细节：

• 身份验证采用分阶段流程：JWT → Salesforce 令牌 → Data Cloud 令牌
• 摄取端点使用租户 URL，而不是 Salesforce 实例 URL
• 202 表示已接受载荷进行处理，并不表示记录可以立即查询
• 验证失败通常会显示在 Problem Records DLO 系列中

9. 然后再进入协调阶段

数据流和 DLO 状态正常后，转交给 sf-datacloud-harmonize。

---

高优先级注意事项

• 由 CRM 支持的数据流行为与完全自定义的连接器框架摄取并不相同。
• sf data360 data-stream run 和 sf data360 connection run-existing 不能互换；对于非结构化数据重新扫描，优先使用数据流级刷新。
• SFDC 数据流按平台管理的计划同步；data-stream run 并不是刷新 CRM 连接器的通用控制路径。
• 某些外部数据库连接器可以通过 API 创建，但创建数据流仍需要通过 UI 流程或针对组织的浏览器自动化。不要承诺所有连接器类型都能通过纯 CLI 创建数据流。
• 最初的 SharePoint 类非结构化数据设置，在 UI 中可能比精简版 CLI DLO 创建流程更完善。
• 删除数据流也可能删除关联的 DLO，除非删除模式另有说明。
• DLO 字段命名与 CRM 字段命名不同，包括 __c → _c 转换。
• 使用 Data Cloud SQL 查询 DLO 记录数，不要想当然地认为列表输出已足够。
• CdpDataStreams 表示当前组织／用户无法使用数据流模块；请引导用户检查配置和权限，而不是盲目重试。

---

输出格式

Prepare task: <stream / dlo / transform / docai>
Source: <connection + object>
Target org: <alias>
Artifacts: <stream names / dlo names / json definitions>
Verification: <passed / partial / blocked>
Next step: <harmonize or retrieve>

---

参考资料

• README.md
• examples/ingestion-api/README.md
• ../sf-datacloud/assets/definitions/data-stream.template.json
• ../sf-datacloud/references/plugin-setup.md
• ../sf-datacloud/references/feature-readiness.md