一、为什么数据采集遗漏比页面问题更隐蔽

页面坏了，用户和团队通常很快能看到。但数据采集漏了，问题经常要等到复盘、投放、增长分析或老板看报表时才暴露。最常见的情况是：页面正常上线，用户也确实点击了按钮、提交了表单、完成了注册，但数据看板里没有记录，或者不同看板口径互相打架。

这类问题麻烦的地方在于，它不一定是单个 bug。可能是前端没有埋点，可能是埋点事件名写错，可能是字段缺失，可能是后端接口没有记录日志，也可能是数据库里有数据但没有被同步到分析表。

Codex 适合做这类检查，因为它可以顺着代码路径阅读：从页面交互、事件上报、API 请求、服务端处理、数据库写入、队列任务、第三方 SDK 到测试覆盖，帮你把一条数据链路画出来，再指出断点和遗漏点。

二、什么叫“数据采集逻辑遗漏”

数据采集遗漏不只是“没有埋点”。只要业务上应该被记录的信息没有稳定进入可分析的数据系统，都可以算作遗漏。实际项目里，至少要检查下面几类问题。

三、Codex 检查前应该准备哪些上下文

不要直接说“帮我看看数据有没有漏”。这种指令太宽，Codex 只能猜。更好的做法是先提供产品目标、关键路径、现有埋点方案和代码范围，让它按数据链路检查。

• 产品关键路径：例如访问首页、点击 CTA、注册、填写资料、创建项目、发起支付、完成订阅。

• 现有埋点方案：事件名、字段、触发时机、第三方工具、数据字典。

• 前端代码范围：页面路由、组件、表单、按钮、hooks、analytics 工具函数。

• 后端代码范围：API 路由、controller、service、webhook、数据库写入、队列任务。

• 数据去向：PostHog、GA4、Amplitude、Mixpanel、Segment、自建日志表、BI 表、数据仓库。

• 验收方式：哪些事件必须出现，哪些字段必须完整，哪些测试或调试日志可以验证。

四、推荐的审计顺序

检查数据采集逻辑不要从某个按钮开始乱翻。更稳定的顺序是：先画业务路径，再找采集入口，再追踪上报链路，最后检查数据是否能被使用。

• 列出关键用户路径：用户从哪里进入、做了什么、在哪里产生价值、在哪里可能失败。

• 扫描采集入口：查找 analytics、track、gtag、posthog、mixpanel、logEvent、event、telemetry、auditLog 等关键词。

• 建立事件地图：事件名、触发文件、触发条件、payload 字段、上报目标、是否有测试。

• 检查路径覆盖：成功、失败、取消、返回、刷新、移动端、未登录、无权限、空状态是否都有记录。

• 检查字段一致性：字段命名、类型、枚举值、是否包含业务分析必需维度。

• 追踪后端链路：API 是否记录服务端日志，webhook 是否入库，队列失败是否可追踪。

• 检查数据消费：事件是否进入数据字典、漏斗、看板、告警或报表。

• 补齐验证：用单元测试、集成测试、E2E 测试或调试脚本证明采集没有遗漏。

五、第一段 Codex 指令：扫描现有数据采集入口

第一步不要让 Codex 修改代码。先让它扫描项目中所有可能的数据采集入口，并输出采集地图。

请先不要修改任何文件。请扫描当前项目中所有数据采集、埋点、日志和事件上报相关代码。 请重点搜索并分析以下内容： 1. 前端埋点：analytics、track、gtag、dataLayer、posthog、amplitude、mixpanel、segment、logEvent、telemetry； 2. 表单提交、按钮点击、CTA、注册、登录、支付、搜索、筛选、下载、分享等关键动作； 3. 后端日志、audit log、event log、webhook、queue、cron、数据库写入； 4. 数据字典、埋点文档、README、AGENTS.md、docs/analytics 或 docs/tracking； 5. 测试文件中是否覆盖了事件上报和 payload 校验。 请输出一份“数据采集入口地图”，包含：文件路径、函数名、事件名、触发条件、payload 字段、上报目标、是否有测试、你发现的风险。只输出报告，不要改代码。

六、第二段 Codex 指令：按用户路径检查漏采

入口地图只能告诉你项目里已经有哪里在采集。真正的遗漏要从用户路径倒推：哪些用户动作应该被记录，但代码里没有对应事件。

请基于当前项目，帮我审计【新用户注册到首次激活】这条路径的数据采集是否遗漏。 请按以下步骤执行： 1. 先列出这条路径中用户可能经过的页面、组件、API 和状态变化； 2. 为每一步判断是否应该采集事件； 3. 对照现有代码，找出已采集、未采集、采集不完整、重复采集的地方； 4. 特别检查失败路径：表单校验失败、验证码失败、邮箱已存在、网络错误、取消操作、页面返回、未登录访问； 5. 输出漏采清单，按严重程度分为 P0/P1/P2； 6. 每个问题都给出建议事件名、触发时机、payload 字段、涉及文件和验证方式。 先输出审计报告，不要直接修改代码。

七、第三段 Codex 指令：检查事件字段是否一致

很多项目不是没有采集，而是字段乱。字段乱会导致后续数据分析非常痛苦，尤其是做漏斗、分群、A/B 测试和渠道归因时。

请检查项目中所有数据采集事件的 payload 字段是否一致。 请重点检查： 1. 用户标识字段是否统一，例如 user_id / userId / uid 是否混用； 2. 会话字段是否统一，例如 session_id、anonymous_id、device_id； 3. 页面字段是否统一，例如 page_path、page_title、referrer、utm_source； 4. 业务字段是否统一，例如 plan、project_id、order_id、amount、currency、status； 5. 实验字段是否统一，例如 experiment_id、variant、feature_flag； 6. 字段类型是否稳定，例如金额是 number 还是 string，时间是 timestamp 还是 ISO string； 7. 是否存在敏感字段被误上报，例如手机号、邮箱明文、token、身份证、银行卡、完整地址。 请输出字段一致性审计表，包含：字段名、出现位置、当前写法、建议统一写法、是否影响分析、是否涉及隐私风险。不要修改代码。

八、第四段 Codex 指令：检查前端与后端是否断链

只看前端埋点不够。关键业务动作必须能在后端或数据库中核对，否则前端事件丢失、被拦截、重复触发时，很难判断真实业务结果。

请检查当前项目中关键数据采集链路是否存在“前端有事件、后端无记录”或“后端有数据、前端无事件”的断链问题。 请选择以下关键动作逐一追踪： - 注册成功 - 登录成功或失败 - 创建项目或提交表单 - 点击主要 CTA - 发起支付 - 支付成功、失败、取消 - 订阅升级或取消 每个动作请输出： 1. 前端触发文件和事件名； 2. 前端 payload 字段； 3. 请求的 API 路由； 4. 后端处理文件、日志、数据库写入或 webhook； 5. 数据是否能被看板或报表使用； 6. 当前断点和修复建议。 只做审计，不要改代码。

九、第五段 Codex 指令：检查异常路径是否被采集

很多产品只记录成功事件，不记录失败原因。这样看板会显得一切正常，但用户实际可能大量卡在错误提示、权限不足、支付失败或表单校验上。

请专项检查项目中的异常路径数据采集是否遗漏。 请覆盖以下场景： 1. 表单校验失败； 2. API 请求失败、超时、重试失败； 3. 登录态失效、无权限访问； 4. 支付失败、支付取消、webhook 校验失败； 5. 搜索无结果、筛选无结果、空状态； 6. 图片或文件上传失败； 7. 第三方服务不可用； 8. 移动端或小屏幕下关键按钮无法点击导致的转化中断。 请输出异常路径漏采表，包含：场景、当前代码位置、是否已有采集、建议事件名、建议字段、严重程度、验证方式。不要修改代码。

十、第六段 Codex 指令：生成数据字典和事件规范

如果项目没有数据字典，后面一定会越来越乱。可以让 Codex 基于现有代码生成一版数据字典，再由产品、研发和数据同学确认。

请基于当前项目中的现有埋点、日志和数据采集代码，生成一份数据采集事件字典草案。 请输出 Markdown 表格，字段包括： - event_name - 中文说明 - 触发时机 - 触发文件 - 必填字段 - 可选字段 - 字段类型 - 上报目标 - 是否进入漏斗或看板 - 是否已有测试 - 备注和风险 要求： 1. 只基于真实代码和文档生成，不要编造不存在的事件； 2. 对明显缺失但业务上应该存在的事件，放到“建议新增事件”部分； 3. 对命名不一致的事件，给出统一命名建议； 4. 标记可能涉及隐私或敏感数据的字段； 5. 最后生成一套事件命名规范。

十一、第七段 Codex 指令：补齐测试用例

数据采集要能被验证。否则今天修好了，下一次改组件、换路由、重构表单时又会漏。测试不一定要覆盖所有埋点，但关键路径必须有验证。

请为关键数据采集逻辑补齐测试方案。先不要写代码，先输出测试计划。 请覆盖： 1. 单元测试：payload builder、事件名、必填字段、字段类型； 2. 组件测试：关键按钮点击、表单提交、错误提示是否触发正确事件； 3. API 测试：服务端是否写入业务日志、audit log 或事件表； 4. E2E 测试：注册、激活、支付等关键路径是否触发预期事件； 5. 防重复测试：页面刷新、组件重新挂载、快速点击是否导致重复上报； 6. 隐私测试：payload 中不应出现 token、密码、完整手机号、身份证等敏感信息。 请输出测试清单、建议测试文件路径、mock 方式和验证命令。等我确认后再创建测试文件。

十二、第八段 Codex 指令：在确认后安全修复

数据采集修复不要一次性大改。更稳的方式是先让 Codex 输出分级修复计划，你确认后再按 P0/P1/P2 分批处理。

请根据前面的数据采集审计报告，制定修复计划。暂时不要修改代码。 请按 P0/P1/P2 分组： - P0：影响核心转化漏斗或关键业务结果的数据缺失； - P1：影响分析分组、归因、实验或异常定位的问题； - P2：命名、文档、测试覆盖、看板使用上的改进。 每个修复项请包含： 1. 问题描述； 2. 涉及文件； 3. 修改方式； 4. 新增或调整的事件名； 5. payload 字段； 6. 需要新增的测试； 7. 回归验证命令； 8. 可能风险。 等我确认后，只修复 P0，并保持最小改动。

十三、建议放进 AGENTS.md 的数据采集规则

如果数据采集是团队长期需要维护的能力，应该把稳定规则写进 AGENTS.md。这样 Codex 后续改页面、改表单、改支付路径时，会主动检查是否影响埋点和日志。

数据采集和分析规则

修改用户路径、表单、转化按钮、定价页、新手引导、支付、认证或项目创建流程时，必须检查分析事件、服务端日志、数据字典和相关文档是否需要同步更新。不要凭空发明事件名，要复用现有命名规范。每个关键事件都要定义触发时机、必填字段、上报目标和验证方式。用户标识、会话标识、匿名标识、页面路径、来源参数、套餐、项目 ID 和实验字段要保持一致。不要在分析 payload 中发送密码、令牌、API key、完整手机号、证件号、银行卡号或客户隐私数据。关键漏斗要同时记录成功和失败路径，避免组件重挂、路由切换、重试或双击造成重复事件。新增、删除或重命名事件时，要更新数据字典或 docs/analytics，并补充关键追踪逻辑的测试。收尾前运行 lint、类型检查、测试，以及项目已有的数据验证脚本。

十四、数据采集审计输出模板

让 Codex 输出报告时，最好固定格式。报告越结构化，越容易转成开发任务、PR 描述和验收清单。

十五、人工验收清单

Codex 可以帮你找到大量遗漏，但最后一定要人工验收。尤其是产品口径、数据隐私、第三方工具配置、BI 看板口径，不能只看代码。

十六、最容易被漏掉的数据采集场景

• 用户没有点击主按钮，而是通过键盘回车提交表单。

• 用户在移动端打开页面，按钮位置或浮层导致关键动作无法完成。

• 注册失败、支付取消、搜索无结果、筛选无结果、上传失败等负向路径。

• 第三方登录、第三方支付、webhook 回调失败。

• 同一个动作在不同入口触发，例如首页 CTA、顶部导航 CTA、定价页 CTA。

• A/B 测试或 feature flag 下的另一套流程。

• 服务端渲染页面的曝光事件和客户端路由切换后的曝光事件。

• 新用户、老用户、未登录用户、无权限用户的不同状态。

• 数据已经写入业务库，但没有同步到分析库或看板。

十七、常见问题

1. Codex 能不能直接判断哪些数据应该采集？

可以给出建议，但不能替代产品和数据口径决策。Codex 更适合根据业务路径和代码现状找出明显遗漏，最终事件定义还需要产品、研发和数据负责人确认。

2. 没有数据字典，还能检查吗？

可以。可以先让 Codex 扫描现有事件，反向生成一份数据字典草案。没有数据字典时，更容易出现事件名混乱、字段不一致和重复采集。

3. 只做前端埋点够不够？

不够。核心业务结果应该能被后端日志、数据库或 webhook 结果核对。只依赖前端事件，容易受网络、拦截器、页面跳转和重复点击影响。

4. 数据采集遗漏一定要马上修吗？

P0 必须尽快修，例如注册、支付、订阅、关键转化漏斗缺失。P1/P2 可以进入迭代计划，但要先写清影响和验证方式。

5. Codex 修复埋点时最需要注意什么？

不要一次性改大量事件名。事件名变动会影响历史看板和分析脚本。更稳的方式是先补漏，再逐步规范命名，并保留迁移说明。

十八、总结

用 Codex 检查数据采集逻辑是否遗漏，核心不是让它随便补几个埋点，而是让它沿着完整数据链路做审计：用户路径是什么，哪里应该采集，现有代码在哪里采集，payload 是否完整，前后端是否断链，异常路径是否记录，数据是否能进入字典、看板和测试。

最实用的流程是：先扫描采集入口，再按关键路径找漏采，再检查字段一致性和异常路径，最后输出 P0/P1/P2 修复计划。确认后再让 Codex 小步修复，并补充测试和文档。这样做出来的数据采集才不是“页面里加了一个 track”，而是可以支撑增长分析、产品复盘和业务决策的稳定数据链路。

参考依据： - OpenAI Codex 官方资料：Codex 可用于理解代码库、写代码、代码审查、调试和自动化软件开发任务。 - OpenAI Codex 指令ing 文档：提交提示词时应包含相关文件、上下文和验证步骤，并把复杂任务拆成更小步骤。 - OpenAI Codex Best Practices：把稳定项目规则沉淀进 AGENTS.md，保持规则简短、准确、可执行。 - OpenAI AGENTS.md 文档：Codex 会在开始工作前读取 AGENTS.md，并支持全局、仓库和子目录层级规则。