# 脉冲遥测实现使用“@nutanix-ui/pulse-telemetry”为 Web 应用程序实现遥测跟踪。该技能使用门控工作流程：搭建基础，验证一个事件在浏览器中端到端工作，然后在实现其余要求之前询问用户。 ## 工作流程 1. 检测 → 2. 支架 → 3. 冒烟测试 → 3c.交接文件 → 4. 检查点 ✋ → 5. 全部实施 → 6. 验证 → 7. 报告 ### 1\.检测项目状态 **首先，检查现有的切换文档**（遥测实用程序目录中的“TELEMETRY_STATUS.md”）。如果存在，请阅读它 - 它包含先前会话的完整上下文：文件映射、已建立的模式和需求跟踪器。从状态为“Pending”的第一行继续。跳过步骤 2-4 并转到步骤 5，但只要遇到移交文档中未涵盖的需求类型或模式，请继续使用此技能的参考文件（模板、需求类型映射、代码库适配器）。如果不存在切换文档，请在代码库中搜索现有遥测设置：寻找： ├── TELEMETRY_STATUS.md 位于 utils/telemetry/ 或共享/telemetry/ ├── TelemetryProvider 或 TelemetryManager 导入 ├── utils/telemetry/或shared/telemetry/目录 ├──constants.ts 与 FEAT_NAME / PAGE_SECTION / SUB_PAGE_SECTION ├── data/ 目录与 TelemetryConfigObj 聚合 ├── JSX/HTML 中的数据遥测属性 └── package.json 中的 @nutanix-ui/pulse-telemetry **如果移交文档存在：** 读取它并从第一个“待处理”要求继续（跳到步骤 5）。对于不熟悉的需求类型，仍请查阅技能参考文件。 **如果遥测存在但没有切换文档：**扩展当前设置 - 根据需要添加新常量、配置文件和提供程序连接。 **如果遥测丢失：**搭建完整的基础（步骤 2）。有关检测命令、脚手架规则和切换文档恢复逻辑，请参阅 [references/setup-detection.md]()。 ### 2\.脚手架缺失地基仅创建尚不存在的文件。所需基础：文件 |目的 ---|--- `utils/telemetry/constants.ts` | `FEAT_NAME`、`PAGE_SECTION`、`SUB_PAGE_SECTION` 作为 const 对象 `utils/telemetry/data/index.ts` |将所有功能配置聚合到一个 `TelemetryConfigObj` 中 `utils/telemetry/data/.ts` |每个功能“TelemetryConfigData”，默认值 + eventMap `utils/遥测/index.ts` |导出配置参数；如果非 React 代码需要访问，则创建 `TelemetryManager` 供应商接线|应用程序/页面根目录处的“TelemetryProvider”，或非 React 的“TelemetryManager.initialize()” 有关复制粘贴文件模板，请参阅 [references/templates.md]()。 **适应，不要复制粘贴。** 模板显示完整的模式 - 仅使用您实际需要的部分。除非特定情况需要，否则不要添加包装器组件、额外文件或抽象。匹配现有代码库的风格和复杂性。有关详细信息，请参阅 [references/templates.md]() 中的一般原则部分。 **重要提示：** 在此阶段，仅使用冒烟测试事件（步骤 3）所需的值填充 `constants.ts`。请勿添加完整需求列表中的所有常量 - 这些常量将在用户批准后在步骤 5 中添加。 ### 3\.冒烟测试——一个事件端到端在实施完整的要求列表之前，请通过端到端测试一个事件来验证基本遥测设置是否正常工作。 #### 3a。选择一个简单的需求从需求列表中选择最简单的配置驱动的单击事件（例如，具有静态“data-test”属性的按钮单击）。只实现这个单一事件： 1. 将这一事件所需的最少常量添加到 `constants.ts` 2. 仅使用这一“eventMap”条目创建配置文件 3. 连接聚合和提供者 4. 确保相关元素上存在“data-telemetry”和“data-test”属性 #### 3b。在浏览器中验证此步骤是强制性的。使用浏览器自动化工具（或要求用户协助）确认事件正确触发： 1. 在提供程序/配置选项中启用 `debugLog: true` 和 `verboseClicks: true` 2.启动开发服务器（或确认它已经在运行） 3. 导航到包含被跟踪元素的页面 4. 单击该元素并检查浏览器控制台是否有遥测日志输出 5. 确认记录的有效负载具有正确的“featName”、“actionName”、“pageSection”、“subPageSection”和“actionType” 请参阅 [references/payload-verification.md]() 了解控制台输出的外观和常见问题。 **如果事件正确触发：** 继续执行步骤 3c（移交文档）。 **如果它没有触发：** 在继续之前调试并修复设置。常见问题包括父容器上缺少“data-telemetry”、“data-test”/“eventMap”键不匹配或提供程序未包装组件树。 #### 3c。创建交接文档冒烟测试通过后，在遥测 utils 目录中创建“TELEMETRY_STATUS.md”（例如“utils/telemetry/TELEMETRY_STATUS.md”）。该文件是一个简洁的上下文快照，允许新的代理线程恢复实现而无需重新发现代码库。移交文件必须包含： 1. **快速入门** - 开发服务器 URL、下一个待处理的要求、已知的怪癖（例如，在测试之前关闭模式）、活动的“数据遥测”容器键 2. **遥测文件映射** — 所有创建/修改的遥测文件和关键非遥测连接文件的路径（例如，添加 `TelemetryProvider` 的组件） 3. **已建立的模式** - 在检测过程中发现的特定于项目的规则（例如，EBR 使用 `telemetryName`、代码库适配器类型、导入别名约定） 4. **需求跟踪器** — 包含以下列的表：`#`、`需求`、`状态`、`类型`、`文件`、`已验证的有效负载`。将冒烟测试行标记为“完成”并验证有效负载。所有剩余行均以“Pending”开头。 5. **代码片段** — 一个具体示例，显示用于冒烟测试事件的模式（配置条目 + 接线）。保持简短——足以让新代理复制模式而无需重新读取模板。请参阅 [references/templates.md]() 了解“TELEMETRY_STATUS.md”模板。 **规则：** * 将文档控制在 200 行以下。使用表格而不是散文，使用片段而不是完整的文件。 * 切勿在负载示例中包含敏感数据或用户输入的内容。 * 该文档是工作辅助工具，而不是可交付成果——请勿提交。如果尚未忽略，请将其添加到“.gitignore”。 ### 4\.检查点 — 在继续之前询问用户 ✋ **在此停止。** 不要继续自动实施其余要求。向用户呈现： 1. **设置了什么** — 列出脚手架文件和提供商接线 2. **冒烟测试结果** — 显示步骤 3b 中验证的有效负载 3. **切换文档** — 提及“TELEMETRY_STATUS.md”的路径，并且它可用于在新线程中恢复 4. **剩余的工作** - 总结还剩下多少需求以及它们的类型（配置驱动的点击、悬停跟踪、去抖输入等）然后询问用户： “基本遥测设置正在运行 - [描述已验证的事件]。我已在“[TELEMETRY_STATUS.md 的路径]”处创建了一个移交文档，因此如果需要，可以在新线程中继续工作。还有 [N] 个剩余要求需要实现。您希望我继续实现所有这些要求，还是希望先检查设置？” **等待用户的响应。** 如果用户确认，则仅继续执行步骤 5。 ### 5\.实施剩余要求按顺序处理每个剩余的需求行。对于每个： 1. **分类**需求类型（静态点击、动态点击、悬停、去抖输入、教程步骤、非 React 事件） 2. **选择方法** — 配置驱动优先；仅在需要时才编程 3. **使用匹配模式实现** 4. **更新移交文档** — 将行的状态设置为“完成”，填写触及的文件并验证有效负载。这使“TELEMETRY_STATUS.md”保持最新状态，以便如果会话中断，新线程可以从确切的中断点恢复。 5. **记录**接触的文件和预期的有效负载有关分类表和实现模式，请参阅 [references/requirement-type-map.md]()。请参阅 [references/codebase-adapters.md]()，了解如何使模式适应不同的代码库结构。 #### 决策：配置驱动与程序化使用配置驱动 |使用程序化 ---|--- 静态元素的简单点击 |悬停/工具提示跟踪具有现有“数据测试”的元素 |去抖搜索/输入按钮、链接、选项卡、复选框 |多步骤教程/向导 |需要动态负载数据的事件 |非 React 代码（渲染函数、中间件） ### 6\.验证有效负载对于每个已实现的要求，验证发出的有效负载是否与预期的遥测数据相匹配。 **自动化（首选）：**启用 `debugLog: true` 和 `verboseClicks: true`，触发交互，确认记录的有效负载字段。 **手动后备：**运行时不可用时的结构化清单。有关完整的验证手册，请参阅 [references/payload-verification.md]()。 ### 7\.退货完成报告全部要求落实后： 1. 确保“TELEMETRY_STATUS.md”中的每一行都标记为“完成”（或带有原因的“不可行”）。移交文档的需求跟踪器应该是完全最新的。 2. 为用户生成汇总表： | ＃|要求 |状态 |类型 |文件 |有效负载| |---|-------------|--------|------|--------|---------| | 1 | ... |完成 |配置驱动| ... | { ... } | 有关报告模板，请参阅 [references/templates.md]()。 ## 护栏这些规则是不可协商的： 1. **配置驱动优先** — 使用 `data-telemetry` \+ `data-test` \+ `eventMap` 进行静态点击。仅当配置驱动无法处理交互类型时才使用编程跟踪。 2. **类型化常量** — 所有 `featName`、`pageSection`、`subPageSection` 值必须来自于 `constants.ts` 中类型化的 `as const` 对象。切勿在配置或事件调用中使用原始字符串。 3. **`ACTION_TYPE` 枚举** — 始终使用 `ACTION_TYPE.CLICK`、`ACTION_TYPE.HOVER`、`ACTION_TYPE.CHANGE`。切勿使用原始字符串“click”。 4. **`data-test` / `data-telemetry` 一致性** — 每个 `eventMap` 键必须与 DOM 中实际的 `data-test` 属性匹配。每个“数据遥测”值必须与聚合的“TelemetryConfigObj”中的键匹配。 5. **动态 ID 的正则表达式** — 当“data-test”包含动态段（实体 ID、行索引）时，将正则表达式添加到“defaults.regexList”并使用静态前缀作为“eventMap”键。 6. **非 React 代码中的`getInstanceSafe()` - 始终在 React 组件外部使用 `telemetryManager.getInstanceSafe()` （带有可选链接）。切勿使用“getInstance()”，如果未初始化，它会抛出异常。 7. **无敏感数据** — 跟踪发生的操作，而不是用户输入的内容。 `actionName: '搜索'`，而不是 `actionName: searchQuery`。 8. **`mapDataToEventMap` 用于重复操作** - 当 3 个以上按钮共享相同的 `subPageSection` 时，使用帮助器来减少样板文件。 9. **类似功能的共享事件** - 导出常见事件映射并将其传播到特定于功能的配置中，而不是重复。 10. **snake_case 命名** — `featName`、`pageSection`、`subPageSection` 使用 `snake_case`。 `actionName` 是人类可读的和描述性的。 11. **切勿在没有检查点的情况下批量实施** - 在实施完整的需求列表之前，始终完成步骤 1-4（检测、脚手架、冒烟测试、检查点）。不要跳过用户确认步骤。 12. **始终创建和维护移交文档** — 在冒烟测试（步骤 3c）后创建“TELEMETRY_STATUS.md”，并在实现每个需求后更新它（步骤 5）。如果从现有的移交文档恢复，请在实施之前重新验证引用的文件是否仍然存在。

脉冲遥测

包含技能