sf-vlocity-build-deploy

sf-vlocity-build-deploy：Vlocity Build DataPack 部署

当用户需要编排 Vlocity DataPack 部署时，使用此技能：导出/部署工作流、由清单驱动的部署、失败问题排查，以及 OmniStudio/Industries DataPack 的 CI/CD 执行顺序。

---

此技能负责的任务

在工作涉及以下内容时，使用 sf-vlocity-build-deploy：

• vlocity packDeploy、packRetry、packContinue、packExport、packGetDiffs、validateLocalData
• DataPack 作业文件设计（projectPath、expansionPath、manifest、queries）
• 组织间 DataPack 迁移和重试循环
• 排查 DataPack 依赖项、匹配键和 GlobalKey 问题

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

• 使用 sf project deploy 部署标准元数据 -> sf-deploy
• 构建 OmniScripts、FlexCards、IPs 或 Data Mapper -> sf-industry-commoncore-*
• 设计 Product2 EPC 套件 -> sf-industry-cme-epc-model
• 编写 Apex/LWC 代码 -> sf-apex、sf-lwc

---

关键操作规则

• 使用 Vlocity Build（vlocity） 命令处理 DataPack，而不是 sf project deploy。
• 如果可用，优先使用 Salesforce CLI 身份验证集成（-sfdx.username <alias>），而不是用户名/密码文件。
• 完整部署前始终先执行部署前质量门禁：
  1. validateLocalData
  2. 可选的 packGetDiffs
  3. 然后执行 packDeploy
• 当错误数量持续减少时，反复使用 packRetry；重试不再改善结果时停止。
• 确保源组织和目标组织的匹配键策略及 GlobalKey 完整性保持一致。

---

首先需要收集的上下文

询问或推断以下信息：

• 源组织和目标组织别名
• 作业文件路径和 DataPack 项目路径
• 部署范围（完整项目、清单子集，或特定的 -key）
• 操作类型是导出、部署、重试、继续还是仅比较差异
• 命名空间模型（%vlocity_namespace%、vlocity_cmt 或 core）
• 已知限制（新沙盒引导配置、触发器行为、匹配键自定义项）

预检：

vlocity help
sf org list
sf org display --target-org <alias> --json
test -f <job-file>.yaml

---

推荐工作流

1. 确保工具已就绪

npm install --global vlocity
vlocity help

2. 在本地验证项目数据

vlocity -sfdx.username <source-alias> -job <job-file>.yaml validateLocalData

仅在用户明确要求并说明影响后，才使用 --fixLocalGlobalKeys。

3. 从源组织导出（如有需要）

vlocity -sfdx.username <source-alias> -job <job-file>.yaml packExport
vlocity -sfdx.username <source-alias> -job <job-file>.yaml packRetry

4. 部署到目标组织

vlocity -sfdx.username <target-alias> -job <job-file>.yaml packDeploy
vlocity -sfdx.username <target-alias> -job <job-file>.yaml packRetry

5. 继续被中断的作业

vlocity -sfdx.username <target-alias> -job <job-file>.yaml packContinue

6. 验证部署后的数据一致性

vlocity -sfdx.username <target-alias> -job <job-file>.yaml packGetDiffs

作业文件模板：references/job-file-template.md

---

常见故障模式

错误 / 症状	可能原因	默认修复方向
No match found for ...	目标组织中缺少依赖项	包含缺失的 DataPack 键并重新部署
Duplicate Results found for ... GlobalKey	目标组织中存在重复记录	清理重复记录并重新运行部署
Multiple Imported Records ... same Salesforce Record	源组织中存在重复的匹配键记录	在源组织中删除重复记录并重新导出
No Configuration Found	DataPack 设置过时	运行 packUpdateSettings 或启用 autoUpdateSettings
Some records were not processed	设置不匹配 / 依赖项状态不完整	刷新两个组织的设置，然后重试
SASS / 模板编译失败	缺少被引用的 UI 模板资源	先导出并部署被引用的模板依赖项

详细矩阵：references/troubleshooting-matrix.md

---

CI/CD 指南

默认流水线结构：

1. 通过身份验证登录组织（sf org login ...）
2. 验证本地 DataPack 完整性（validateLocalData）
3. 导出变更范围（packExport 或由清单驱动的导出）
4. 部署（packDeploy）
5. 重试循环（packRetry），直到稳定
6. 比较（packGetDiffs）并发布部署报告

如需优化增量部署，可使用作业文件选项，例如：

• gitCheck: true
• gitCheckKey: <folder>
• manifest，用于确定性范围控制

---

跨技能集成

需求	委派给	原因
在 DataPack 之外部署元数据	sf-deploy	Metadata API 工作流
编写 OmniStudio 组件	sf-industry-commoncore-*	在部署前构建产物
编写 EPC 产品和报价负载	sf-industry-cme-epc-model	Product2/DataPack 模型质量
诊断 Apex 触发器/日志错误	sf-debug、sf-apex	修复自动化端的根本原因

---

参考索引

从这里开始

• references/job-file-template.md
• references/troubleshooting-matrix.md
• examples/business-internet-plus-bundle/TRANSCRIPT.md
• examples/business-internet-plus-bundle-deploy/TRANSCRIPT.md

外部参考

• Vlocity Build GitHub

---

完成格式

DataPack goal: <export / deploy / retry / diff / ci-cd>
Source org: <alias or N/A>
Target org: <alias or N/A>
Scope: <job file + manifest/key/full>
Result: <passed / failed / partial>
Key findings: <errors, dependencies, retries, diffs>
Next step: <safe follow-up action>