consumer-goods-tpe-dashboard-custom-kpi-configure

自定义 TPE 仪表板 KPI

以无头方式克隆基础 TPE Analytics 语义模型参数、可视化和仪表板，并在名称后添加客户指定的后缀，这样客户自己的 KPI 测量代码就会显示在 Promotion/Tactic Analysis 仪表板中，同时绝不修改随附的基础模型。整个流程完全通过 sf CLI 和 REST 针对已完成身份验证的组织执行。要求 consumer-goods-tpe-dashboard-configure 已安装 TPE Analytics 应用和 Extended TPM Analytics SDM——此技能不会安装它们，只会在其基础上进行自定义。

角色：为组织自定义 TPE 仪表板的 Salesforce TPM 系统管理员。

此技能涉及的三种工件类型（语义模型参数、可视化、仪表板）都没有原生的“克隆”端点——每次克隆都遵循相同的三步模式：GET 基础工件，对其 JSON 进行深拷贝并应用覆盖，然后将副本作为新工件 POST。绝不会就地修改基础模型工件。

5 个 KPI 槽位——每个槽位对应两个工件，而非一个

随附的 Extended TPM Analytics SDM 提供 5 个通用的 List 类型参数，供标准仪表板绑定：Promotion Measure 1-3（Promotion_Measure_{1,2,3}_prm / _value）和 Tactic Measure 1-2（Tactic_Measure_{1,2}_prm / _clc）。切勿假设 Tactic 的命名方式与 Promotion 的 _value 相同——必须根据实时模型分别解析两个槽位的测量 apiName，不能按模式推断。已确认的 apiName 和 JSON 结构请参阅 references/payload-shapes.md。

每个槽位对应两个 SDM 工件：参数（*_prm，类型为 List，包含 allowedValues 菜单项和 defaultValue）以及计算测量（可视化实际查询的内容；其 expression 会通过 apiName 链接回参数）。自定义槽位意味着同时克隆两者——参数会将客户的 KPI 作为新的或选定的 allowedValues 项，测量的 expression 则会改为引用克隆参数的新 apiName。

无论某个槽位是否有请求的覆盖，此技能始终会为 全部 5 个槽位生成克隆（10 个工件）——未提及的槽位仍会作为基础工件的精确副本进行克隆（仅 apiName/label 添加后缀）。

每个槽位有两种覆盖模式（准确的 --overrides 结构请参阅 references/procedure.md）：

• APPEND 模式（默认）：按测量代码将一个 {measureCode, displayName} 项写入基础菜单——相同代码会就地更新标签，新代码则追加。
• REPLACE 模式：客户提供的完整 allowedValues 数组将成为整个菜单。

无论采用哪种模式，此技能都假定底层测量数据已通过先前的 setup-rtr-datacloud-export/data-kit 设置填充——它不会自行创建底层数据。

首先需要收集的信息

开始前先询问。不要猜测。

1. TPM 系统管理员用户名 — 使用 node ./scripts/sf-rest.js org-status --target-org <username> 验证连接（绝不要直接运行 sf org display --json — 这会泄露有效的 accessToken）。如果状态不是 Connected ⇒ 停止，并请用户登录。
2. 是否试运行？ — 默认提供此选项。
3. 后缀 — 用于区分克隆的元数据与基础模型（例如 Cust）。建议默认使用 Cust。应用于每个新工件的 API 名称/标签 — 绝不重用基础模型的 API 名称。
4. 各度量的覆盖项 — 通过 AskUserQuestion 引导客户逐一处理 5 个度量，按仪表板分批提问（在一次调用中询问 Promotion Measure 1-3，在第二次调用中询问 Tactic Measure 1-2 — 绝不能在一次调用中询问全部 5 个，工具每次调用最多支持 4 个问题），绝不对用户使用内部术语“slot”。绝不要另行发送纯文本追问来收集列表 — 纯文本消息不会阻止下一次工具调用，因此如果在收到客户回复前就为下一个度量再次调用 AskUserQuestion，客户的回答可能会抢先到达并落到错误的问题上。相反，应在同一个阻塞式问题中收集完整列表：每个 AskUserQuestion 问题都会自动在你列出的选项后附加一个“Type Something”自由文本选项 — 无需自行添加占位选项，也绝不要指望仅写一个预设选项标签（例如“Replace with custom list”）就能带回列表，因为选中它只会返回该标签文本，而不会返回客户的数据。问题措辞和第二个选项的说明都应明确引导客户选择“Type Something”，例如，选项 2 = “Replace with custom list”，说明：“选择 Type Something（下方最后一个选项），然后输入以逗号分隔的 {measureCode}: {displayName} 对，以及要设为默认值的一项。”菜单可以有多个条目 — 始终收集完整数组，绝不能只收集一对（单条回答仍是长度为 1 的数组）。此收集到的数组会直接映射到该 slot 的 REPLACE 模式覆盖项（{"allowedValues":[...], "defaultValue": "<first displayName unless the customer says otherwise>"}）— 请参阅 references/procedure.md 中的覆盖模式结构。进入 Phase 0 前，向用户确认每个度量解析出的列表。
5. 要生成哪些仪表板 — Promotion Analysis、Tactic Analysis，或两者。如果任一仪表板上的任何度量有覆盖项，默认选择两者；否则应明确询问。

工作原理 — 阶段列表

1. 命名空间检测 — 通过 sf package installed list 解析 NS，以与同类技能保持一致，但绝不要将其应用于任何 /services/data/... 路径（这些路径永远不会带命名空间）。
2. 阶段 0 — 预检与发现：验证连接状态，固定 API 版本为 v67.0，遍历应用的资源列表，解析已安装应用及资源 ID（模型、两个仪表板、可视化内容）——绝不要硬编码 ID。如果缺少前置条件，则提供 consumer-goods-tpe-dashboard-configure 作为解决指引并阻止继续执行。完整详情：references/procedure.md。
3. 阶段 1 — 确定 5 个槽位的计划：深拷贝每个基础参数／度量并应用覆盖值，打印计划，并在执行任何写入操作前获得用户明确确认。
4. 阶段 2-4 — 克隆参数、度量、可视化内容、仪表板：运行 scripts/clone-tpe-dashboards.js（优先于手动逐个调用 REST）——完整 CLI 用法、覆盖模式的负载形状，以及脚本中编码的所有实际写入注意事项（标签唯一性、dataSource .type 剥离规则、克隆所有绑定 KPI 的可视化内容而非仅克隆某个“指定”可视化内容、外观标签文本替换、按度量代码执行 upsert），请参阅 references/procedure.md。
5. 阶段 5 — 验证：GET 取回每个已创建的资源，并确认参数、度量、可视化内容和仪表板都正确引用带新后缀的克隆，而绝不引用基础 apiName。完整详情：references/procedure.md。

关键规则（完整列表请参阅 references/procedure.md）

• 绝不修改基础模型资源——每次写入都必须是带后缀副本的新 POST。
• 未获得用户对阶段 1 计划的明确许可，绝不创建任何内容。
• 即使没有任何覆盖值，也始终生成全部 5 个槽位的克隆。
• 克隆度量的 expression 绝不能引用基础参数 apiName。
• 绝不跨组织硬编码资源 ID、api-name 或命名空间。
• 绝不假定每个仪表板只需克隆一个可视化内容——凡是可视化内容引用了某个槽位度量，都要克隆对应的小组件。

参考索引

主题	文件
完整的分阶段操作流程、脚本 CLI 用法、所有实际写入注意事项、完整规则列表	references/procedure.md
参数、计算度量、可视化内容、仪表板的已确认实时 JSON 形状，以及全部 4 个创建端点的 POST 正文形状	references/payload-shapes.md
组织 REST 助手（会剥离 accessToken；org-status 子命令）	scripts/sf-rest.js
阶段 2-4 的确定性驱动程序	scripts/clone-tpe-dashboards.js

报告

运行结束时，按阶段（0-5）向用户提供结构化状态：通过／阻止／待处理；如适用，说明具体阻止原因，并列出最终创建的资源（槽位 → 新参数、基础可视化内容 → 新可视化内容、基础仪表板 → 新仪表板）。指出因试运行或用户拒绝确认而跳过的任何内容。

通过委派调用时（调用技能使用 Skill 工具访问此文件，而非用户直接调用——例如 consumer-goods-tpe-dashboard-configure 的自定义步骤）：此报告是中间结果。请将其返回给调用技能，并让调用技能继续生成自己的报告——除非此技能是独立调用的，否则不要将此报告作为最终答复呈现给用户。