consumer-goods-tpe-datakit-deploy

TPE Data Kit 部署

将 TPM Accruals Data Kit 及其 DMO 映射部署到 Salesforce 组织。它独立且自包含，可自行运行，也可作为委托步骤由 consumer-goods-tpe-dashboard-configure（步骤 7）调用；调用方会传入自己已收集的用户名和试运行标志，而不是由本技能重新推导。

开始前需要收集的输入

开始前先询问，除非调用方技能已提供。不要猜测。

1. TPM System Admin 用户名 — 已通过 sf CLI 完成身份验证。通过同目录下的脚本验证，绝不能直接运行 sf org display --json — 该命令的原始输出包含 accessToken（有效凭证），而此脚本会在打印前将其剔除：

   node ./scripts/sf-rest.js org-status --target-org <username>
   

   打印 {"username","alias","connectedStatus","orgId"}。退出码非零或 connectedStatus != "Connected" ⇒ 停止，并让用户自行登录。
2. 是否试运行？ — 默认提供此选项。试运行时，仍会执行阶段 1（预检）和阶段 2 的读取／差异检查步骤；会跳过阶段 2 的 FieldPermissions 写入和阶段 3-5（部署），并记录为 pending — not run (dry-run)。
3. 已安装并激活 TPM Data Connector — 无法通过程序验证。询问用户，并明确说明具体导航步骤，而不是只提设置名称："能否确认 TPM Data Connector 处于 Active 状态？1) 前往 Setup → Data Cloud Setup。2) 在左侧导航栏的 EXTERNAL INTEGRATIONS 下，点击 Other Connectors。3) 在列表中找到 'TPM Data Connector' 并检查其状态。" 等待用户明确确认。如果缺失或未激活，停止 — 告知用户 TPM Data Connector 必须处于激活状态才能继续，并说明根据组织类型采取的两种不同路径：
   • 生产组织 — 通常会在 Processing Service 配对后约 24 小时内自动安装，前提是组织拥有 Data Cloud 许可证。如果两个前提都满足，请用户等待后重试；如果任一前提不满足（尚未配对，或没有 Data Cloud 许可证），则应先解决这一实际阻碍。
   • 沙盒组织 — 通常不会自动安装；一般需要在 EXTERNAL INTEGRATIONS → Other Connectors 下手动激活。告知用户这在沙盒中是预期情况，请其在此处激活，然后确认后再继续。 用户确认已激活后，重新执行此检查。
4. Salesforce CRM Home 组织连接 — 无法通过程序验证。询问用户，并明确说明具体导航步骤："能否确认 Salesforce CRM Home 组织连接处于 Active 状态？1) 前往 Setup → Data Cloud Setup。2) 在左侧导航栏的 SALESFORCE INTEGRATIONS 下，点击 Salesforce CRM。3) 检查 Home 组织连接状态是否为 Active。" 等待用户明确确认。如果缺失或未激活，停止 — 告知用户必须先激活此连接才能继续（阶段 2 的字段权限授权需要 Data Cloud Salesforce Connector 权限集，而该权限集在配置此连接前不会存在）— 请用户先激活／配置该连接，然后重新执行此检查。
5. 已确认分配给 TPM Admin 角色的权限集，以及 GenieAdmin 权限集 — 如果作为 consumer-goods-tpe-dashboard-configure 的委派步骤调用，则会传入其前序阶段已确认的这两项结果；请复用，不要再次询问或查询。如果单独调用，则直接确认每一项：
   • TPM Admin 角色的权限集 — “TPM Admin 角色”是一个角色，并非实际的权限集名称；无法通过程序验证支持该角色的组织特定权限集（名称／分配情况）。请询问用户确认："是否已将 TPM Admin 角色所需的权限集分配给 <username>？" 等待用户明确确认。
   • GenieAdmin — 先解析其 Label（绝不向用户显示 API Name），然后检查分配情况：

     sf data query --target-org <username> --query "SELECT Label FROM PermissionSet WHERE Name = 'GenieAdmin'"
     sf data query --target-org <username> \
       --query "SELECT PermissionSet.Name FROM PermissionSetAssignment WHERE Assignee.Username = '<username>' AND PermissionSet.Name = 'GenieAdmin'"
     

     如果未分配 ⇒ 告知用户第一条查询返回的 Label（例如："用户 <username> 缺少 <Label> 权限集。现在分配吗？"），并在继续前征求分配许可：

     sf data create record --sobject PermissionSetAssignment \
       --values "AssigneeId=<userId> PermissionSetId=<psId>" --target-org <username>
     

     如果用户拒绝，则跳过并在报告中注明。
6. 命名空间（NS） — 如果作为委派步骤调用，consumer-goods-tpe-dashboard-configure 会传入其已检测到的 NS（原始命名空间字符串）；请复用，不要重新检测。如果单独调用，则在阶段 1 之前自行使用同目录下的脚本检测一次：

   node ./scripts/detect-namespace.js --target-org <username>
   

   将 {"NS","NS_SEGMENT","NS_APEX","NS_FIELD"} 作为单行 JSON 打印。保存全部四个值，并在下文各处复用。

阶段 1 — 预检

2. 用于后续验证的基线 — 在进行任何部署工作之前，立即捕获最新的 DataKitDeploymentLog Id，以避免阶段 5 中因 CreatedDate 时钟偏差导致的误判：

   sf data query --target-org <username> \
     --query "SELECT Id FROM DataKitDeploymentLog ORDER BY CreatedDate DESC LIMIT 1" --json
   

   保存为 LAST_ID_BEFORE_DEPLOY（若没有记录则为空）。
3. 下载并解压 CGCloudAddons — 此技能会自行获取该资源，不会要求用户手动操作。

   node ./scripts/download-static-resource.js \
     --target-org <username> --name CGCloudAddons
   

   从 stdout 中捕获 STATIC_RESOURCE_PATH=<dir>，并将其作为 <addons_root> — 以下所有路径均相对于它（例如，<addons_root>/TPM/Accruals/TPM Accruals Data Kit）。StaticResource 记录数为 0 ⇒ 阻止：此组织中安装的软件包版本不包含 CGCloudAddons。任何其他脚本失败 ⇒ 阻止并原样转达其 stderr。

阶段 2 — CRM 流的字段权限（根据下载的软件包派生）

两个配套脚本负责此阶段 — 切勿自行编写解析或授权调用；具体操作及原因请参阅各脚本自身的文档字符串：

1. 提取从下载的软件包中获取 {sobject, fields[]} 列表（只读，始终可以安全运行）：

   node ./scripts/extract-crm-field-permissions.js \
     --dir "<addons_root>/TPM/Accruals/TPM Accruals Data Kit/force-app/main/default/dataSourceObjects" \
     > /tmp/crm-field-permissions.json
   

   若输出中没有条目 ⇒ 阻止并报告 — 如果阶段 1 成功，这种情况不应发生。
2. 静默获取待更新的差异（脚本自身的 --dry-run — 只读：权限集、sobject/describe、现有 FieldPermissions/ObjectPermissions 记录）— 暂时不要向用户显示任何内容，这一步只是为了确定是否有待处理事项：

   node ./scripts/update-field-permissions.js \
     --target-org <username> --input /tmp/crm-field-permissions.json --dry-run
   

   {"error":"permission_set_not_found",...} ⇒ 停止此阶段，将其标记为已阻止，并告知用户："未找到“Data Cloud Salesforce Connector”权限集 — 可能的原因是尚未配置 Salesforce CRM（Setup → Data Cloud → Salesforce CRM）。请先完成配置，然后重新运行此阶段。"
3. 仅当 wouldGrant 或 objectWouldGrant 不为空时，向用户准确展示该差异（而非完整的提取列表），并在写入任何内容前征得用户明确同意。如果两者都为空，说明权限均已授予 — 直接跳到步骤 5，无需确认。
4. 获得确认后，正式执行 — 仅添加字段级和对象级权限（具体语义请参阅脚本文档字符串）：

   node ./scripts/update-field-permissions.js \
     --target-org <username> --input /tmp/crm-field-permissions.json
   

   退出代码为 3（或 failed[]/objectFailed[] 非空）⇒ 不要自行猜测解决方法 — 提示用户通过 Setup → Permission Sets → Data Cloud Salesforce Connector → Object Settings 手动操作，并使用 failed[]/objectFailed[] 中的准确列表，同时在报告中记录每项。
5. 为最终报告记录通过/已阻止/待处理状态，以及已处理字段/对象的结果（granted/alreadyGranted/notFlsEligible/failed、objectGranted/objectAlreadyGranted/objectFailed）。试运行模式（试运行模式下切勿继续执行步骤 4，因为该步骤会更新权限；步骤 1 和步骤 2 为只读操作，可以照常执行）。
6. 对于少量固定的 sobject（目前仅有 Product2），如果许可证限制了 permissionsViewAllRecords: false 标志，则 objectGranted/objectAlreadyGranted 条目中出现此值属于预期情况 — 这是脚本静默处理的已知平台限制；不要向用户提示此情况，也不要将其视为需要通过 Setup 手动处理的事项。

阶段 3 — 准备并部署数据工具包元数据

1. 在 <addons_root>/TPM/Accruals/TPM Accruals Data Kit 中，将占位符 __SF_ORG_ID__ 的所有实例替换为该组织的 15 位 Id。通过以下配套脚本获取组织 Id：

   node ./scripts/sf-rest.js org-status --target-org <username>
   

   从打印的 JSON 中获取 orgId 字段，并截取前 15 个字符（此调用成本低且幂等 — 此处务必重新运行，不要依赖 Inputs 步骤 1 的结果仍在上下文中）。
2. 从该文件夹部署：

   sf project deploy start --target-org <username>
   

阶段 4 — 部署 DMO 映射并运行部署脚本

1. DMO 映射 — 将数据套件的 DLO 映射到 Data 360 DMO。从 <addons_root>/TPM/Accruals/DmoMappings 中获取：

   sf project deploy start --target-org <username>
   

2. 部署脚本 — 从 <addons_root>/TPM/Accruals/Accruals Data Kit Deployment Scripts 中获取：

   SF_ORG_ALIAS=<username> node deploy-tpm-tpe.js
   

   此脚本会向 /services/data/v67.0/actions/custom/flow/sfdatakit__DeployDataKitComponents 发送 POST 请求，并立即返回一个异步 Flow interview guid；仅凭该响应并不代表部署成功——务必在阶段 5 通过 DataKitDeploymentLog 检查确认。此脚本需在已下载并解压的静态资源内部运行。

阶段 5 — 验证

sf data query --target-org <username> \
  --query "SELECT Id, DeploymentStatus, ComponentName, DeploymentError, CreatedDate FROM DataKitDeploymentLog WHERE Id > '<LAST_ID_BEFORE_DEPLOY>' ORDER BY CreatedDate DESC"

本次运行的每一行都必须满足 DeploymentStatus = 'Successful'，且 DeploymentError 为空。只要有任何一行的状态为 Failure 或错误字段非空，就绝不能声称成功。

替代 UI 检查方式：Data Cloud Setup → Data Kits → TPM Accruals → Local Deployment History → 状态为 Successful。

已知注意事项

• FlowDefinition 不支持 SOQL 查询——不要用它来检查就绪情况。
• 即使框架已正常运行，sfdatakit__DeployDataKitComponents ApexClass 检查也可能返回 0 行——优先直接检查 DataKitDeploymentLog（阶段 5），绝不要检查 Apex 类。

规则

• 只要本次运行的任何 DataKitDeploymentLog 行状态为 Failure 或 DeploymentError 非空，就绝不能声称成功。
• 只能读取 CGCloudAddons StaticResource（通过 download-static-resource.js）——绝不要部署或修改它；下载时使用组织自身经 sf 身份验证的访问令牌，绝不能使用硬编码凭据。
• 绝不要通过检查 FlowDefinition 或 sfdatakit__DeployDataKitComponents Apex 类来判断就绪情况——应检查 DataKitDeploymentLog。
• 绝不要查阅组织随附的 README.md（或 CGCloudAddons 中捆绑的任何其他包内文档）以获取部署指南——严格按照本技能中写明的各阶段执行。如果此处记录的脚本名称或路径与下载包中的实际内容不符，那是本技能需要修复的 bug（更新技能本身），而不是运行时改用包内文档的理由。
• 如果下载的文件夹中缺少脚本或文件夹，不要猜测或更改脚本。例如：绝不要更改脚本 deploy-tpm-tpe.js。
• 运行 update-field-permissions.js 前，必须先使用 --dry-run。如果其 wouldGrant/objectWouldGrant 返回非空，未经向用户展示确切差异并获得明确同意，绝不要实际运行——与本技能中的其他任何写入操作相同。如果两者都为空，则无需确认；直接继续报告即可。
• update-field-permissions.js 只会新增权限：在不存在的情况下新增 FieldPermissions/ObjectPermissions 行，或将现有行的关闭标志（PermissionsRead，或对象级别的 PermissionsViewAllRecords）切换为 true。绝不要以删除行、削弱现有授权或修改 PermissionsCreate/Edit/Delete/ModifyAllRecords 的方式调用它。
• 如果缺少 sfdc_a360_sfcrm_data_extract（“Data Cloud Salesforce Connector”）权限集，或某字段/对象出现在 update-field-permissions.js 的 failed[]/objectFailed[] 中，绝不要猜测变通方法——停止操作，并提示用户通过 Setup 手动授予字段级或对象级安全权限（参见阶段 2）。

报告

生成一份最终报告（通过/受阻/待处理），涵盖：CRM 流字段权限（来自 extract-crm-field-permissions.js 的各对象字段列表，以及 update-field-permissions.js 中每个字段的 granted/alreadyGranted/notFlsEligible/failed 结果——单独标出任何 onObject: false 的 notFlsEligible 条目，因为这是软件包/组织数据不匹配，而非正常跳过）、CRM 流对象级权限（同一脚本中每个 sobject 的 objectGranted/objectAlreadyGranted/objectFailed 结果——Product2 上的 permissionsViewAllRecords: false 是预期情况，无需特别指出）、预检（连接器状态）、元数据部署、DMO 映射部署、部署脚本运行，以及 DataKitDeploymentLog 验证结果（行数、任何失败）。这正是通过委派调用此技能时，consumer-goods-tpe-dashboard-configure 的步骤 7 所传达的自身结果。

通过委派调用时（调用技能通过 Skill 工具访问此文件，而非用户直接调用）：这份报告是中间结果，并非任务终点。将其返回给调用技能，并让它继续执行自己的下一阶段——不要将这份报告作为最终答案呈现给用户后停止。仅当此技能以独立方式调用时，才直接向用户提供这份报告。