18 可观测性与稳定性
  ├─ 前置：11 性能（指标）、14 Node/BFF（服务端）
  ├─ 紧接：20 工程效能（复盘与组织）
  ├─ 交叉：12 安全（异常检测）、13 测试（回归用例）
  └─ 长期：稳定性治理体系

/**
 * 1) JS 运行时错误
 */
window.addEventListener('error', (event) => {
  // 资源加载失败也会触发 error，但没有 error 对象
  if (!event.error) return;
  report({
    type: 'js',
    message: event.message,
    stack: event.error?.stack,
    filename: event.filename,
    lineno: event.lineno,
    colno: event.colno,
  });
});

/**
 * 2) Promise 未捕获拒绝
 */
window.addEventListener('unhandledrejection', (event) => {
  const reason = event.reason;
  report({
    type: 'promise',
    message: reason?.message ?? String(reason),
    stack: reason?.stack,
  });
});

/**
 * 3) 资源加载失败（捕获阶段才能拿到）
 */
window.addEventListener('error', (event) => {
  const target = event.target;
  if (target instanceof HTMLScriptElement ||
      target instanceof HTMLLinkElement ||
      target instanceof HTMLImageElement) {
    report({ type: 'resource', tag: target.tagName, url: target.src || target.href });
  }
}, true); // 关键：捕获阶段

/**
 * 4) 接口错误（在请求封装层统一处理）
 */
async function request(url, options) {
  try {
    const res = await fetch(url, options);
    if (!res.ok) report({ type: 'api', url, status: res.status });
    return res;
  } catch (err) {
    report({ type: 'network', url, message: err.message });
    throw err;
  }
}

/**
 * sendBeacon：页面卸载也能发出，不阻塞导航。
 * 降级：fetch keepalive。
 */
function send(payload) {
  const body = JSON.stringify(payload);

  if (navigator.sendBeacon) {
    navigator.sendBeacon('/log', new Blob([body], { type: 'application/json' }));
    return;
  }

  fetch('/log', { method: 'POST', body, keepalive: true }).catch(() => {});
}

/**
 * 采样：错误全采，行为按比例采，避免成本失控。
 */
const SAMPLE = 0.1;

function shouldSample(type) {
  if (type === 'error') return true;        // 错误不采样
  return Math.random() < SAMPLE;
}

/**
 * 去重：同一错误在同一会话只报一次，避免风暴。
 */
const seen = new Set();
function dedupe(key) {
  if (seen.has(key)) return false;
  seen.add(key);
  return true;
}

/**
 * 只报 "Cannot read property 'id' of undefined" 基本无法定位。
 * 必须带：页面、版本、用户、设备、操作路径、请求 id。
 */
function buildContext() {
  return {
    url: location.href,
    release: window.__APP_VERSION__,
    userId: getUserId(),          // 注意脱敏
    ua: navigator.userAgent,
    viewport: `${innerWidth}x${innerHeight}`,
    dpr: devicePixelRatio,
    network: navigator.connection?.effectiveType,
    traceId: window.__TRACE_ID__,
  };
}

/**
 * ErrorBoundary 只捕获子树「渲染、生命周期、构造函数」中的错误。
 * 事件回调、定时器、Promise、SSR 数据请求都不在它的范围内。
 */
class Boundary extends React.Component {
  state = { error: null };

  static getDerivedStateFromError(error) {
    return { error };
  }

  componentDidCatch(error, info) {
    // info.componentStack 能定位到组件层级
    report({ type: 'react', error, componentStack: info.componentStack });
  }

  render() {
    return this.state.error ? <Fallback /> : this.props.children;
  }
}

/**
 * 动态导入失败时重试一次，仍失败则提示刷新。
 * 原因：发版后旧 chunk 被清理，用户手里的 index.html 仍指向旧文件。
 */
async function lazyImport(factory, retries = 1) {
  try {
    return await factory();
  } catch (error) {
    if (retries > 0 && /Loading chunk|Importing a module script failed/.test(String(error))) {
      return lazyImport(factory, retries - 1);
    }
    report({ type: 'chunk-load', error });
    showReloadTip(); // 提示用户刷新，而不是停在空白页
    throw error;
  }
}

/**
 * 极简上报队列：批量、失败退避、页面隐藏时补发。
 * @param {{endpoint: string, maxBatch?: number, interval?: number}} options
 */
function createReporter({ endpoint, maxBatch = 10, interval = 5000 }) {
  const queue = [];
  let timer = null;
  let retry = 0;

  const flush = async () => {
    if (queue.length === 0) return;
    const batch = queue.splice(0, maxBatch);
    try {
      await fetch(endpoint, {
        method: 'POST',
        body: JSON.stringify(batch),
        keepalive: true,
      });
      retry = 0;
    } catch {
      // 失败放回队首，指数退避，最多保留 200 条
      queue.unshift(...batch);
      if (queue.length > 200) queue.length = 200;
      retry += 1;
      setTimeout(flush, Math.min(30000, 1000 * 2 ** retry));
    }
  };

  const push = (item) => {
    queue.push(item);
    if (queue.length >= maxBatch) flush();
    else if (!timer) timer = setTimeout(flush, interval);
  };

  document.addEventListener('visibilitychange', () => {
    if (document.visibilityState === 'hidden') flush();
  });

  return { push, flush };
}

构建 → 生成 .map → 上传到监控平台 → 用 release + filename 关联
上报 → 堆栈是压缩后的位置 → 平台用 map 反解出源码行列

/**
 * 上报时带上版本，否则平台无法匹配对应的 map。
 */
report({ ..., release: '1.8.3', dist: '20261030.1' });

/**
 * 采集核心指标 + 分位统计所需的原始值。
 * 注意：只上报数值，不要在客户端聚合，便于后端按维度切分。
 */
new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    report({
      type: 'metric',
      name: 'LCP',
      value: Math.round(entry.startTime),
      element: entry.element?.tagName,
      url: location.pathname,
    });
  }
}).observe({ type: 'largest-contentful-paint', buffered: true });

/**
 * 面包屑：记录最近 N 个操作，出错时一起上报。
 * 注意：不记录输入内容（隐私）。
 */
const breadcrumbs = [];
const MAX = 20;

function addBreadcrumb(action) {
  breadcrumbs.push({ action, at: Date.now() });
  if (breadcrumbs.length > MAX) breadcrumbs.shift();
}

// 常用埋点
addBreadcrumb({ type: 'click', target: 'submit-order' });
addBreadcrumb({ type: 'route', from: '/cart', to: '/checkout' });
addBreadcrumb({ type: 'api', url: '/api/order', status: 500 });

/**
 * 指纹：用「错误类型 + 消息模板 + 关键堆栈帧」生成稳定 hash。
 * 消息里的动态内容要归一化，否则每条都不同。
 */
function fingerprint(error) {
  const msg = error.message
    .replace(/\d+/g, 'N')
    .replace(/"[^"]*"/g, '"S"')
    .replace(/'[^']*'/g, "'S'");

  const frame = error.stack?.split('\n')[1]?.trim() ?? '';
  return hash(`${error.name}|${msg}|${frame}`);
}

告警分级：
P0：核心链路不可用（白屏率 > 5%、下单成功率 < 90%）→ 立即电话
P1：部分用户受影响（错误率翻倍、P99 超阈值）→ 工作时间处理
P2：趋势异常（缓慢上涨）→ 每日巡检

/**
 * 结构化日志：字段固定，便于检索与聚合。
 * 禁止：拼接字符串、打印敏感信息、无级别。
 */
logger.error('order.create.failed', {
  requestId,
  userId: mask(userId),
  orderId,
  code: err.code,
  durationMs: Date.now() - start,
});

采集 ─► 内存队列 ─► 批量序列化 ─► 压缩 ─► 传输 ─► 网关 ─► 存储 ─► 查询
        │              │                        │
        └─ 上限淘汰     └─ 超过阈值立即发        └─ 鉴权/限流/采样

错误：全量（但做指纹去重）
性能：全量原始值 + 后端降采样
行为：按会话采样（1%–10%）
调试日志：仅灰度/白名单开启

浏览器生成 traceId
  → 请求头 x-trace-id
  → BFF 透传 + 生成 span
  → 下游服务继续透传
  → 日志/错误都带上 traceId

/**
 * 前端注入 traceId，并在错误上报时携带，
 * 这样「用户报错」能直接查到后端日志。
 */
const traceId = crypto.randomUUID();

function withTrace(headers = {}) {
  return { ...headers, 'x-trace-id': traceId };
}

report({ ..., traceId });

/**
 * 采样法：在视口内取若干点，检查是否命中有效元素。
 * 有效元素：非 html/body、有尺寸、非透明。
 */
function isBlank() {
  const points = [
    [innerWidth / 2, innerHeight / 2],
    [innerWidth / 4, innerHeight / 3],
    [innerWidth * 0.75, innerHeight * 0.6],
  ];

  return points.every(([x, y]) => {
    const el = document.elementFromPoint(x, y);
    if (!el || el === document.body || el === document.documentElement) return true;
    const rect = el.getBoundingClientRect();
    return rect.width === 0 || rect.height === 0;
  });
}

// 在 load + 3s 时检测，避免误判慢加载
setTimeout(() => {
  if (isBlank()) report({ type: 'blank-screen', url: location.href });
}, 3000);

错误预算用完后：
  冻结非必要发布 → 集中修复稳定性 → 复盘 → 恢复发布

1. 确认影响面：多少用户、哪些页面、哪些版本、哪些地域
2. 看时间线：什么时候开始，和什么变更重合
3. 分层排查：前端（错误/白屏）→ 网络（DNS/CDN）→ BFF → 下游
4. 用 traceId 找具体请求
5. 对比版本/灰度分组
6. 止血优先于根因

/**
 * 上报前统一脱敏：
 * - 手机号/身份证/邮箱
 * - URL 中的 token/查询参数
 * - 输入框内容
 */
function mask(text) {
  return String(text)
    .replace(/\d{11}/g, '***********')
    .replace(/[\w.-]+@[\w.-]+/g, '***@***')
    .replace(/(token|password|secret)=[^&]*/gi, '$1=***');
}

错误：100%
接口慢请求（> 2s）：100%
关键页面（下单/支付）：50%–100%
普通页面性能：5%–10%
用户行为：1%–5%，按会话一致性采样

/**
 * 会话级采样：用 sessionId 的哈希决定，保证同一会话内一致。
 * @param {string} sessionId
 * @param {number} rate 0–1
 */
function sampled(sessionId, rate) {
  let h = 0;
  for (let i = 0; i < sessionId.length; i += 1) {
    h = (h * 31 + sessionId.charCodeAt(i)) >>> 0;
  }
  return h % 10000 < rate * 10000;
}

预防：测试、灰度、容量、依赖治理
发现：监控、告警、合成拨测、用户反馈
止血：降级开关、回滚、限流、切流
改进：复盘、用例沉淀、机制建设

1. 事实时间线（精确到分钟，不含猜测）
2. 影响面（用户数、时长、金额）
3. 根因（技术 + 流程）
4. 改进项（每条有 owner 与截止时间）
5. 哪些做得好（可复制的经验）

[P1] 下单页白屏
影响：约 8% 用户，集中在 iOS 16 / 版本 3.2.1
开始：14:03，当前状态：已定位到 chunk 加载失败
已做：回滚静态资源版本至 3.2.0（14:18）
待做：观察白屏率 15 分钟；确认 CDN 缓存已刷新
下次同步：14:35
指挥：@张三  沟通：@李四

关闭功能开关 → 回滚版本 → 切流/降级 → 限流 → 紧急修复

// 1) 全局错误 + 资源失败 + 白屏检测 + 版本
// 2) 上报带：url、release、设备、网络、traceId、面包屑

/**
 * 极简错误采集：采样、去重、批量、页面隐藏时补发。
 * @param {{endpoint: string, sampleRate?: number, maxBatch?: number}} options
 */
function createErrorReporter({ endpoint, sampleRate = 0.3, maxBatch = 10 }) {
  const queue = [];
  const seen = new Set();

  /** 生成指纹：同名同栈只报一次 */
  const fingerprint = (err) => `${err.name}|${err.message}|${(err.stack ?? '').slice(0, 120)}`;

  const flush = () => {
    if (queue.length === 0) return;
    const batch = queue.splice(0, maxBatch);
    navigator.sendBeacon(endpoint, JSON.stringify({ ts: Date.now(), errors: batch }));
  };

  const push = (payload) => {
    if (Math.random() > sampleRate) return;
    const fp = fingerprint(payload);
    if (seen.has(fp)) return;
    seen.add(fp);
    queue.push(payload);
    if (queue.length >= maxBatch) flush();
  };

  // JS 运行时错误
  window.addEventListener('error', (e) => {
    // 资源错误没有 error 对象
    if (!e.error) {
      push({ type: 'resource', target: e.target?.src || e.target?.href, message: 'load failed' });
      return;
    }
    push({ type: 'js', message: e.message, stack: e.error.stack, filename: e.filename, line: e.lineno });
  }, true);

  // 未处理的 Promise rejection
  window.addEventListener('unhandledrejection', (e) => {
    const reason = e.reason;
    push({ type: 'promise', message: String(reason?.message ?? reason), stack: reason?.stack });
  });

  // 页面隐藏时兜底发送
  document.addEventListener('visibilitychange', () => {
    if (document.visibilityState === 'hidden') flush();
  });

  return { push, flush };
}

/**
 * 白屏检测：在首屏区域取采样点，命中内容过少则判定白屏。
 * @param {{points?: number, threshold?: number}} [options]
 * @returns {boolean}
 */
function isBlank({ points = 20, threshold = 0.02 } = {}) {
  const el = document.elementFromPoint(window.innerWidth / 2, window.innerHeight / 2);
  if (!el) return true;

  const html = document.body;
  if (!html || html.scrollHeight < window.innerHeight * 0.2) return true;

  let hits = 0;
  for (let i = 0; i < points; i += 1) {
    const x = Math.floor((i % 5) * (window.innerWidth / 5) + window.innerWidth / 10);
    const y = Math.floor(Math.floor(i / 5) * (window.innerHeight / 4) + window.innerHeight / 8);
    const node = document.elementFromPoint(x, y);
    if (node && node !== document.body && node !== document.documentElement) hits += 1;
  }
  return hits / points <= threshold;
}

/**
 * 把动态消息归一化后生成稳定指纹，用于聚合「同一类错误」。
 * 关键：ID、时间、金额、URL 参数都要替换为占位符。
 * @param {{name: string, message: string, stack?: string}} error
 * @returns {string} 指纹
 */
function fingerprint(error) {
  const normalize = (text = '') =>
    text
      .replace(/[0-9a-f]{8}-[0-9a-f-]{27,}/gi, '<uuid>')
      .replace(/\b\d{10,}\b/g, '<num>')
      .replace(/"[^"]{0,200}"/g, '"<str>"')
      .replace(/'(?:[^'\\]|\\.){0,200}'/g, "'<str>'")
      .replace(/https?:\/\/[^\s)]+/g, '<url>');

  // 只取前 3 个业务栈帧，避免不同调用链导致同一错误分成多个指纹
  const frames = (error.stack ?? '')
    .split('\n')
    .slice(1)
    .map((line) => line.trim().replace(/:\d+:\d+$/, ''))
    .filter((line) => line && !line.includes('node_modules'))
    .slice(0, 3)
    .join('|');

  const raw = `${error.name}|${normalize(error.message)}|${normalize(frames)}`;

  // FNV-1a：短、稳定、无需依赖
  let hash = 0x811c9dc5;
  for (let i = 0; i < raw.length; i += 1) {
    hash ^= raw.charCodeAt(i);
    hash = Math.imul(hash, 0x01000193);
  }
  return (hash >>> 0).toString(16).padStart(8, '0');
}