一、 错误与性能监控：基于 RUM 与质量左移的 Sentry 实践#

本项目针对 Sentry 的应用打破了传统的“前端直连上报、事后查错”模式，而是采用了**“架构解耦 + 性能防劣化门禁”**的深度基建方案。

1. 架构解耦：底层无侵入式数据采集

• 实现逻辑：前端应用源码层面完全剥离了监控逻辑，未引入 @sentry/browser 或 @sentry/vue 等 SDK，也不包含任何 Sentry.init 或侵入式的错误捕获代码。线上监控数据依赖于平台架构统一在网关层或容器层注入的 RUM（真实用户监控）脚本进行底层静默采集。
• 深度思考：这种设计的核心优势在于彻底的架构解耦。业务代码无需感知监控体系的存在，避免了前端包体积的无谓膨胀，同时也防止了由于监控 SDK 自身报错而引发的业务主流程阻断风险。

1. 质量左移：CI/CD 自动化性能门禁

• 实现逻辑：将 Sentry 从“事后排查看板”升级为“事前发布门禁”。在国内 UAT 环境的 CI 流水线中，系统首先通过 Playwright 驱动 E2E 测试脚本，强制页面刷新并挂起 15 秒，以模拟真实用户访问并触发 Pageload 性能数据上报。随后，Node 脚本（exec_task.js）延迟 10 秒后，向内部的 bcode 中台调用 API，精准拉取当前 sentryId（如 14）对应的性能切片数据。
• 深度思考：这是典型的质量保障左移（Shift-Left）策略。通过硬编码性能阈值（如要求 FCP ≤ 1800 ms、LCP ≤ 2500 ms、CLS ≤ 0.1），一旦指标劣化，脚本会立即调用 msg_to_teser.js 触发 DIM 告警并中断发布流。附带生成的 perf-report.html 报告（内置 Sentry 自定义看板链接）强制研发人员在代码上线前解决性能隐患。

二、 用户行为与业务埋点：B 端定制化的 Matomo 实践#

区别于 C 端重转化漏斗的特性，本项目的埋点体系依托 vue-matomo 底座，在 framework/matomo-api 层进行了深度重构，重点解决 B 端系统对“数据准确度”、“动态上下文”以及“渲染性能监控”的苛刻要求。

1. 声明式全埋点：基于捕获阶段的全局拦截

• 实现逻辑：应用初始化时调用 installReport()，在 window 对象上注册基于捕获阶段（capture: true）的全局 click 监听器。通过解析 DOM 树寻找 ga-data 属性，并映射至预设常量字典（如 riskGaTextMap）获取真实的 Category 和 Name 后，调用底层的 $matomo.trackEvent 进行上报。找到目标节点后立即触发 break 跳出循环。
• 深度思考：采用“声明式埋点”取代“命令式埋点”，使得研发人员只需在 HTML 模板上挂载属性，实现了埋点逻辑与业务 JS 逻辑的物理隔离。利用捕获阶段加 break 的设计，完美规避了前端常见的“DOM 事件冒泡导致父子节点重复发包”的痼疾。

1. 舍弃自动挡：精准把控 SPA 路由与动态上下文

• 实现逻辑：主动禁用了 Matomo 官方的自动路由上报功能，改为在 app.vue 中手动监听 $route 变化并触发 trackAppRouter。在此过程中，系统会显式提取 meta.trackTitle 或真实 Document Title 写入内存作为后续事件的 Category；并在用户登录后，通过 initMatomoUser 强行注入用户 userId 及平台特有的自定义维度（如维度 1 为角色，维度 2 为租户/渠道）。

• 深度思考：

  • 规避 SPA 异步渲染痛点：单页应用路由切换瞬间，DOM 往往尚未更新，自动上报极易抓取到上一页的旧 Title。手动接管可确保拿到最准确的动态路由标题。
  • 满足 B 端数据聚合需求：独立的 PV 数据在 B 端毫无意义，必须附带操作者的角色和租户信息。手动拦截保障了在发送 PV 之前，所有异步拉取的用户上下文均已准备就绪并完成组装。

1. 隐式性能雷达：针对超大列表的前置探测

• 实现逻辑：在底层的 Axios 请求封装（request.js）中，植入了 checkBigDataAndReport 拦截器。当接口成功返回 JSON 数据时进行递归扫描，一旦发现任一字段的数组长度 ≥ 500 条，立刻触发一条特定的手动静默埋点事件，上报该接口及字段名。
• 深度思考：B 端系统极易因“接口返回全量数据”导致前端 DOM 节点爆炸而卡死。该设计跳出了传统的行为统计范畴，将 Matomo 转化为前置的性能健康雷达。在用户产生实质性白屏或卡顿客诉前，研发即可通过埋点看板揪出潜在的数据量超限接口，进行分页或虚拟列表优化。

三、 典型问题排查 SOP（标准作业程序）#

结合底层监控与行为埋点基建，项目内形成了如下的线上问题排查链路：

1. 功能失效 / 按钮点击无响应

• 行为闭环验证：优先利用 Matomo 面板查看点击流。若目标按钮（通过 ga-data 映射）的点击事件已成功上报，但业务未继续流转，可断定是前端本地的表单校验拦截了逻辑。
• 异常阻断排查：登录 Sentry 平台的 Discover 板块。通过筛选特定时间范围及用户环境，核查是否发生 JS TypeError 等导致主线程崩溃的静默错误，或 Network 层级发生 500/502 等致命接口阻断。

1. 页面白屏 / 加载阻断

• 渲染致命错误：首先在 Sentry Discover 中排查框架级错误（如 Vue 的 Render Error 或 React 的 ErrorBoundary 捕获记录）。
• 资源拉取失败：切换至 Sentry 的自定义 Pageload 看板，若发现特定事务（transaction.op:corePageload）处于未完成或极高耗时状态，需结合报错日志确认是否为前端发版后产生的 ChunkLoadError（CDN 旧缓存失效拉取不到新 JS 资源）或跨域资源拦截。

1. 页面渲染卡顿 / 交互迟滞

• 宏观指标复核：查阅 CI 每日生成的 perf-report.html，确认该模块的客观 Web Vitals（尤其是 LCP 和耗时超 50ms 的 Long Task 引起的 FID 飙升）是否处于劣化状态。
• 数据量爆炸排查：进入 Matomo 面板，定向搜索由 checkBigDataAndReport 拦截器触发的大数组警告。验证卡顿是否由单次渲染大于 500 条数据的表格或下拉框引起。
• 后端响应拖累排查：在 Sentry 看板内拉取 Slow API 耗时分布。对比 TTFB（首字节到达时间）与最终前端 DOM 挂载时间，明确划分是后端慢查询导致前端处于长期 Loading，还是前端自身的重绘重排导致的主线程阻塞。