# TapDB 埋点指引

本指引适用于 TapDB 埋点设计、代码接入、已有埋点核查及上报验收。具体事件定义不在本文固化；事件名、属性名、类型、单位及 SDK 调用方式均须在执行时依据当前事实来源确认。

## 1. 任务场景与处理边界

- **新增或补充埋点**：依次执行代码扫描、预置事件匹配、方案确认、代码修改及结果验证。
- **核查已有埋点**：原则上仅执行只读操作，并按“已完成 / 需确认 / 未发现 / 不适用”说明判断依据及下一项必要操作。
- **后台无数据或数据异常**：优先核查业务动作是否触发、SDK 调用是否执行、数据是否发送及后台是否接收，不直接进入埋点重设计流程。
- **咨询埋点规则**：仅查阅当前通用知识库或 TapTap 开发者中心正文，不扫描项目代码，不执行代码修改。

仅在用户明确提出修复或补充需求时，方可由只读流程转入写入流程。

## 2. 新增或补充埋点

应优先从当前上下文和项目代码中获取所需信息。仅在下一步无法继续或即将执行写入操作时，向用户确认缺失信息或请求授权。

### 2.1 扫描项目代码

具备代码访问权限时，应识别以下内容：

- 平台、语言、框架、入口和 TapDB SDK 版本；
- 页面、控制器、服务及实际业务模块；
- 成功回调、结算节点、状态变化和异常分支；
- 已有埋点调用；
- 可作为事件属性的真实变量。

应形成“功能模块、文件或方法、业务动作、触发点、参数来源、确定性”清单。扫描范围以用户指定的项目为准，应排除第三方 SDK 内部代码和明确与目标无关的目录。不得为代码中不存在的功能推荐事件；业务语义无法确认时，应标记为待确认，不得自行推断。仅在无法访问用户指定项目时，方可请用户提供产品流程或功能清单。

本流程不开展完整的 SDK 接入审计，仅确认项目中存在可运行的 TapDB 初始化，且目标业务动作具备真实触发点及参数来源。初始化缺失时，应将其列为当前阻断项。

### 2.2 按功能模块读取事实来源

各类事实来源的职责如下，不得相互替代：

- **TapDB 通用知识库**：预置事件的业务语义、属性、类型、单位和触发时机；
- **TapTap 开发者中心**：当前平台和 SDK 版本的初始化、调用方式及自定义事件规范；
- **TapDB 后台**：当前项目实际存在的事件、属性和入库结果；
- **用户代码**：功能、位置、触发条件和参数来源。

同步前应确定项目所属区域：国内使用 `cn`，海外使用 `sg`。命令分别读取本地环境变量 `TAPDB_MCP_KEY_CN` 和 `TAPDB_MCP_KEY_SG`；若返回 `missing_credentials`，应引导用户在本地配置对应变量后重新执行，不得要求用户在对话中提供密钥，也不得使用 `-f` 代替凭证配置。

完成代码扫描后，每一推荐批次应按顺序执行一次：

```bash
python3 <SKILL_DIR>/scripts/tapdb_query.py sync_common_skills -r <region>
```

同步命令须在用户项目根目录执行，后续应以命令返回的 `skills_dir` 为准读取正文。同步完成后，应从其中的 `index.md` 路由至本批次相关的功能模块，并完整读取对应正文。同一批次涉及多个模块时仅同步一次；同一会话进入新的推荐批次时，仍须重新同步。Agent 仅调用 `sync_common_skills`，版本检查、文件下载、内容校验及解压均由命令内部完成。

除凭证缺失外，若同步失败或索引指向的正文缺失，Agent 应使用 `-f` 自动重试一次。重试后仍未恢复时，应停止受影响模块的预置事件推荐，并仅说明失败原因及下一项必要操作。问题恢复后，应重新同步并读取相关模块。

查阅 TapTap 开发者中心时，应根据实施方式分别进入[客户端接入](https://developer.taptap.cn/docs/sdk/tapdb/sdk/client-side-integration/)或[服务端接入](https://developer.taptap.cn/docs/sdk/tapdb/sdk/server-side-integration/)页面；设计或核对自定义事件时，还应查阅[数据规范](https://developer.taptap.cn/docs/sdk/tapdb/sdk/data-spec/)。海外项目应访问 `developer.taptap.io` 下的同路径页面。

读取页面时，应完整核对与代码平台、SDK 版本及目标功能对应的标题、正文、平台页签、参数表和代码示例。若正文或页签未完整加载，Agent 应先重试或改用同一官方站点中的有效页面；仅在需要登录、验证码、人工浏览器确认或业务决策时请求用户介入。

### 2.3 优先匹配预置埋点

只有同时满足以下条件才推荐预置事件：

- 当前通用知识库中存在明确的事件定义；
- 代码中的业务行为与事件语义一致；
- 能够准确定位事件触发时机；
- 必填属性能够从真实代码变量中取得。

查询后台元数据前，应从当前上下文或 `list_projects` 的结果中确认目标项目及所属区域（region）；无法可靠判断时，再向用户确认。

预置事件及其属性已为所有项目预置，无需登记。具备查询条件时，可使用 `list_events` 和 `list_props` 进行只读辅助核对，具体参数以 `SKILL.md` 的命令速查或 `describe` 返回结果为准；查询未返回对应记录或接口不适用时，不得仅据此停止接入。需要用户在页面中人工核对时，应引导其进入 TapDB 项目后台的“元数据管理”，分别查看“事件管理”和“事件属性管理”；相关概念及操作边界见[元数据管理](https://developer.taptap.cn/docs/sdk/tapdb/features/custom-event/meta-data/)。

预置埋点流程不得执行 `event_save`、`event_edit`、`property_save` 或 `property_edit`，也不得创建同名自定义事件。应依据通用知识库完成接入，并按第 3 节实际触发和验收；若后台返回结果与通用知识库存在明确冲突，或实际入库出现异常，应停止受影响项并说明冲突。不得因名称相近而复用语义不一致的预置事件。

识别到付费功能时，仅需额外确认项目是否使用 TapPayments。若 TapPayments 已覆盖当前支付流程，则不得重复添加手动付费埋点；否则按一般功能流程查阅当前通用知识库及 TapTap 开发者中心正文。

### 2.4 确认预置埋点方案

实施代码修改前，应向用户展示以下内容：

- 功能模块及代码位置；
- 预置事件及知识库来源；
- 触发时机和属性变量；
- 适配当前 SDK 的代码预览；
- 编译与触发步骤、后台验证方式，以及是否需要开启实时监测。

用户确认后，方可执行已展示的代码修改、编译或构建、安装、测试触发及后台验证。若方案中已明确列出实时监测开关操作，本次确认同时视为对该操作的授权。该确认不包含元数据写入，也不涵盖方案中未展示的操作。

### 2.5 确认自定义埋点需求

完成并验证全部适用的预置埋点后，应向用户说明仍未覆盖的实际功能，并询问：

> 预置埋点已完成，是否为这些未覆盖功能补充自定义埋点？

若用户无需补充自定义埋点，则结束本流程；若需要补充，应按以下规则设计最小方案。无法从当前上下文确定分析目标时，应在此阶段向用户确认。

- 每个事件仅表达一个明确的业务动作；
- 事件名称、属性类型及数据规范以当前 TapTap 开发者中心正文为准；
- 事件及属性均须来源于真实触发点、代码变量及分析目标；
- 优先复用后台已有且语义一致的自定义元数据；
- 明确区分事件属性与账号、设备等主体属性；
- 不得复用预置事件名称，不得设计代码中不存在的属性；
- 代码中已存在但后台尚未登记的自定义事件调用，应列为待确认项，不得自动登记或视为已完成。

执行前，应完整展示本批次涉及的事件、属性、主体、类型、说明、触发位置、变量来源、后台现状、登记操作及代码预览。用户确认后，方可执行已展示的元数据写入、代码修改、构建、测试触发及后台只读验证。

元数据登记及代码修改应按以下顺序执行：

1. 回读已有事件和属性；
2. 创建缺失属性；
3. 回读属性并取得真实 ID；
4. 创建事件并关联事件属性；
5. 回读核对登记结果；
6. 修改代码并构建；
7. 实际触发并完成后台验证。

未经用户确认，不得执行任何写入操作；属性或事件登记失败时，不得继续修改代码。

## 3. 已有埋点诊断与验收

完整验收必须开启实时上报明细。用户明确要求完成端到端验收时，视为授权 Agent 在本次验收中开启实时监测，并在结束后恢复原状态。用户明确拒绝开启时，仅可执行埋点概览核查，结果应标记为“验收未完成”，不得标记为通过。

仅诊断后台无数据且未要求完成端到端验收时，可查询开关状态及埋点概览，不得自行开启实时监测。

验收应按以下顺序执行：

1. 使用 `bury_point_real_time_status` 查询并记录实时监测的原始开关状态；
2. 原始状态为 `off` 时，执行 `bury_point_real_time_switch --status on`，并等待命令规定的生效时间；
3. 记录本次触发时间和可识别的测试标识；
4. 实际执行目标业务动作或服务端 API 请求，并确认业务回调及 SDK 或 API 调用已执行；
5. 使用 `bury_point_real_time_detail` 核对可与本次操作关联的目标事件及全部预期属性；
6. 使用 `bury_point_overview` 查询覆盖本次触发的有限时间范围，核对目标事件的接收、入库、异常及失败数量；
7. 概览中存在异常或失败时，使用相同时间范围及原始事件名调用 `bury_point_error_detail` 查询错误明细；
8. 验收结束后，将实时监测恢复为步骤 1 记录的原始开关状态。

验收结果应按以下状态分别说明：

- **已登记**：后台已存在对应元数据；
- **已触发**：业务回调及 SDK 调用已执行；
- **已接收**：实时上报明细中包含本次事件及预期属性；
- **验收通过**：业务动作及 SDK 或 API 调用已执行；实时上报明细中存在可与本次操作关联的目标事件且属性符合方案；埋点概览中目标事件在本次时间窗内的接收数量和入库数量均大于 0，入库异常数量和入库失败数量均为 0。
- **验收未完成**：任一验收通过条件不满足时，均标记为“验收未完成”。常见情形包括未开启实时上报明细、实时明细中未找到本次事件、概览尚未出现目标事件，或概览入库数量尚未大于 0。聚合延迟情况下可进行有限次数的技术性重查；达到重查上限仍不满足通过条件时，保持该状态。

埋点概览反映指定时间范围内的聚合结果，不能单独证明某一条测试数据是否成功上报。应通过实时上报明细确认本次上报内容，并通过埋点概览排除入库异常。SDK 日志、调用成功或编译成功均不得单独作为验收结论。查询时应限制轮询次数，避免将历史数据误判为本次测试结果。

## 4. 输出内容

埋点方案或验收结果至少应包含：

- 从代码识别的功能模块；
- 文件、方法或回调位置；
- 预置或自定义类型；
- 定义来源及官方链接；
- 触发时机和属性来源；
- 是否需要登记及授权范围；
- 实际代码改动（如有）；
- 触发步骤和后台验证结果（仅实施或验收场景）。

技术性重试应由 Agent 自行完成。仅在需要用户授权、人工验证或业务决策时，方可请求用户介入；提示内容应仅包含失败原因及下一项必要操作。