Frontend Insight 开发者阅读路径：从事件到指标，再到诊断

接手 Frontend Insight 时，一个常见问题是：浏览器已经上报了事件，为什么页面还没有数据？另一个问题恰好相反：页面已有访问记录，为什么分数仍然为空？这组文章沿事件从产生、校验、持久化到查询展示的过程，解释这些现象，也说明访问、操作和错误如何形成运营指标、质量事实与排障上下文。

这组文章面向有编程经验、准备理解或维护该项目的开发者。熟悉 Python 但尚未使用 Vue/NestJS，也可以从架构篇进入；文章解释必要的 TypeScript 运行时概念，不要求先学完一整套前端课程。项目用途、个人职责与代表性取舍见项目介绍。

按层阅读，也可以按问题进入

文章	核心问题	展开的实现
架构与代码边界	一次操作跨了哪些进程，应该从哪里读代码？	SDK、API、consumer、管理台、共享契约与依赖边界
事件校验、重试与消费	202、发送成功和可查询分别保证什么？	v3、内存队列、治理、Kafka、offset、DLQ 与去重
存储与读模型	页面上的数来自哪些事实，为什么有时必须为空？	MySQL/ClickHouse、迁移、时间快照、身份与分母
业务分析与版本化评分	怎样从工作流和使用事实得到有条件成立的分数？	实例归约、页面使用、组织覆盖、绑定、激活与门槛
前端、权限与设置	切项目、刷新和授权变化怎样影响请求与页面？	URL、请求竞争、认证续期、服务端权限、设置发布
维护与排障方法	怎样把故障现象变成可复现、可验证的修改？	质量刷新案例、事实定位、重复事件与最小回归
运行时诊断的维护边界	怎样保留当时上下文，又不改变业务和统计语义？	快照、console、受控请求、搜索、SourceMap、策略与恢复

第一次阅读可以从架构篇开始，先弄清哪些代码在哪个进程运行。如果正在排查具体故障，就沿对应问题进入，不必把整个系列读完再动手：

• 202 后查不到事件：事件管道 → 存储与读模型 → 维护排障。先确认同一 eventId 的持久化，再核对项目、环境和时间范围。
• 准备改指标或工作流：存储与读模型 → 业务评分。先固定分母、定义版本、实例与时间语义，再改计算和展示。
• 切环境后显示旧内容：前端权限 → 维护排障。检查 URL、cursor、请求取消与 generation，不从一个公共 helper 推断所有页面。
• 错误详情缺日志、正文或源码：运行时诊断 → 事件管道。分别判断采集、准入、存储、解析和访问状态，不把全部缺失归成一个空字符串。

先记住三组区别

接收与持久化。 浏览器接受 Beacon 入队时，事件还没有因此进入数据库；API 发布到 Kafka 后，consumer 仍要写库，查询才可能读到。每个确认点都对应一段尚未完成的工作，也决定失败时应该从哪里重试。

事实与解释。 看到 8 人访问，先只能说明观察到了这 8 人。还要知道目标人群、样本、覆盖和生效期，才能按相应版本定义计算指标、进入评分。因此，null、观察值和零值分别表达不同结论，不能为了页面有数字而互换。

统计与诊断详情。 一次错误的基础事实可用于计数，而原文详情可能被截断、抑制、过期或删除。详情的生命周期不应反向改变错误率；但接收和消费仍可能共同依赖数据库与队列，故障影响需要按实际控制流判断。

实现范围与版本

系列采用 Frontend Insight refactor 在 2026-10-27 核对的 aad88a6db2122616c107653010f5823161d78e1a。主线覆盖运营分析、质量分析及运行时诊断；源码阅读入口保留到固定提交，避免后续重命名让同一篇文章指向另一套实现。仓库链接可能需要访问权限，机制、例子与阅读顺序均在本站正文中展开。

各专题中的预算、字段和行为均有具体适用范围。例如当前传输批次最多 128 KiB，暂时失败可回到有界内存队列；这仍不意味着关页后的持久离线补传。需要修改实现时，应重新核对同一版本的契约、调用链和测试，避免把一个局部保证扩展到整个系统。

文章中的命令是定位和验证入口，需要相应源码依赖或隔离服务；它们不是这次内容更新重新执行应用验收的记录。已有性能数据在相关段落标明测量版本与环境，不能移作目标生产环境的容量承诺。以后实现变化时，先更新受影响的机制、反例和验证方法，保留本文及各专题的稳定地址。