《互联网产品的客户端架构·交易、增长与平台化》12.3 漏斗与归因的端上边界

// file: src/analytics/funnel.ts
// tier: L1
// verify: node --test test/analytics/funnel.test.ts

export type FunnelEventName =
  | "trade.product_impression"
  | "trade.product_click"
  | "trade.cart_add"
  | "trade.order_submit"
  | "trade.order_pay";

export type EventSource = "client" | "server";

export interface FunnelEvent {
  eventId: string;
  name: FunnelEventName;
  sessionId: string;
  orderId: string | null;
  occurredAt: number;
  source: EventSource;
}

export interface FunnelStep {
  key: string;
  eventName: FunnelEventName;
  requireOrder: boolean;
}

export interface FunnelConfig {
  steps: FunnelStep[];
  windowMs: number;
}

export interface StepResult {
  key: string;
  sessions: number;
  conversionFromPrev: number | null;
  conversionFromStart: number;
}

export interface FunnelResult {
  sessions: number;
  steps: StepResult[];
  excluded: {
    serverTruth: number;
    outsideWindow: number;
    ambiguousOrder: number;
  };
}

export const DEFAULT_STEPS: FunnelStep[] = [
  { key: "impression", eventName: "trade.product_impression", requireOrder: false },
  { key: "click", eventName: "trade.product_click", requireOrder: false },
  { key: "cart", eventName: "trade.cart_add", requireOrder: false },
  { key: "submit", eventName: "trade.order_submit", requireOrder: true },
  { key: "pay", eventName: "trade.order_pay", requireOrder: true },
];

export const DEFAULT_CONFIG: FunnelConfig = {
  steps: DEFAULT_STEPS,
  windowMs: 30 * 60_000,
};

function ratio(part: number, whole: number): number | null {
  if (whole === 0) return null;
  return Math.round((part / whole) * 10_000) / 10_000;
}

export function buildFunnel(
  events: FunnelEvent[],
  config: FunnelConfig = DEFAULT_CONFIG,
): FunnelResult {
  if (config.steps.length === 0) throw new Error("漏斗至少需要一个步骤");
  if (!Number.isInteger(config.windowMs) || config.windowMs <= 0) {
    throw new Error("归因窗口必须是正整数毫秒");
  }
  const bySession = new Map<string, FunnelEvent[]>();
  for (const event of events) {
    const list = bySession.get(event.sessionId);
    if (list === undefined) bySession.set(event.sessionId, [event]);
    else list.push(event);
  }
  const counts = config.steps.map(() => 0);
  const excluded = { serverTruth: 0, outsideWindow: 0, ambiguousOrder: 0 };
  let sessions = 0;

  for (const list of bySession.values()) {
    const clientEvents = list.filter((event) => event.source === "client");
    excluded.serverTruth += list.length - clientEvents.length;
    if (clientEvents.length === 0) continue;

    const orderIds = new Set(
      clientEvents
        .map((event) => event.orderId)
        .filter((id): id is string => id !== null && id !== ""),
    );
    if (orderIds.size > 1) {
      excluded.ambiguousOrder += 1;
      continue;
    }
    const orderId = orderIds.size === 1 ? [...orderIds][0] : null;
    const sorted = [...clientEvents].sort(
      (a, b) => a.occurredAt - b.occurredAt || a.eventId.localeCompare(b.eventId),
    );

    let cursor = -Infinity;
    let anchor: number | null = null;
    let matched = 0;
    for (let i = 0; i < config.steps.length; i += 1) {
      const step = config.steps[i];
      const candidate = sorted.find(
        (event) =>
          event.name === step.eventName &&
          event.occurredAt >= cursor &&
          (!step.requireOrder || (orderId !== null && event.orderId === orderId)),
      );
      if (candidate === undefined) break;
      if (anchor !== null && candidate.occurredAt - anchor > config.windowMs) {
        excluded.outsideWindow += 1;
        break;
      }
      matched += 1;
      counts[i] += 1;
      cursor = candidate.occurredAt;
      anchor = candidate.occurredAt;
    }
    if (matched > 0) sessions += 1;
  }

  const start = counts[0];
  return {
    sessions,
    steps: config.steps.map((step, i) => ({
      key: step.key,
      sessions: counts[i],
      conversionFromPrev: i === 0 ? null : ratio(counts[i], counts[i - 1]),
      conversionFromStart: ratio(counts[i], start) ?? 0,
    })),
    excluded,
  };
}

export type Metric =
  | "impression"
  | "click"
  | "add_to_cart"
  | "submit_started"
  | "submit_succeeded"
  | "paid"
  | "refunded"
  | "gmv";

export type ComputeTier = "client" | "client_estimate" | "server_truth";

export interface MetricBoundary {
  tier: ComputeTier;
  caveat: string;
}

const BOUNDARIES: Record<Metric, MetricBoundary> = {
  impression: { tier: "client", caveat: "只统计可见曝光，避免预渲染撑大分母" },
  click: { tier: "client", caveat: "端上直接记录，需按会话去重" },
  add_to_cart: { tier: "client", caveat: "端上可算，但要与服务端购物车对账" },
  submit_started: { tier: "client", caveat: "只代表发起提交，不代表下单成功" },
  submit_succeeded: {
    tier: "client_estimate",
    caveat: "必须等待服务端回执，端上只能估算",
  },
  paid: { tier: "server_truth", caveat: "以支付渠道与服务端确认结果为准" },
  refunded: { tier: "server_truth", caveat: "退款是服务端事实，端上不能自行判定" },
  gmv: { tier: "server_truth", caveat: "金额口径必须由服务端订单汇总" },
};

export function metricBoundary(metric: Metric): MetricBoundary {
  return { ...BOUNDARIES[metric] };
}

export function clientMayCompute(metric: Metric): boolean {
  return BOUNDARIES[metric].tier === "client";
}

export function needsServerTruth(metric: Metric): boolean {
  return BOUNDARIES[metric].tier === "server_truth";
}

$ node --test test/analytics/funnel.test.ts
✔ 完整链路在默认五步漏斗中逐级计数 (1.114834ms)
✔ 同一会话的重复事件只计一次 (0.105334ms)
✔ 未走到下一步的会话在对应步骤掉队 (0.095083ms)
✔ 跨会话的事件不会被串成同一条漏斗 (0.090709ms)
✔ 同一会话出现多个订单号时整段排除 (0.071375ms)
✔ 订单步骤要求与前面步骤使用同一个订单号 (0.068959ms)
✔ 订单步骤遇到空订单号时不匹配 (0.074709ms)
✔ 超过归因窗口的下一步被断开 (0.070583ms)
✔ 刚好落在窗口边界内的事件仍可归因 (0.075125ms)
✔ 服务端事件不进入端上漏斗但单独计数 (0.114458ms)
✔ 没有候选下一步时不计入窗口外排除 (0.062875ms)
✔ 转化率同时给出环比与相对首步 (0.081917ms)
✔ 没有事件时所有计数为零且不除零 (0.054292ms)
✔ 空步骤与非法窗口被拒绝 (0.222542ms)
✔ 支付与退款属于服务端事实 (0.079834ms)
✔ 提交成功只是端上估算，不能当事实 (0.047958ms)
✔ 曝光、点击与加购可由端上直接计算 (0.040458ms)
✔ 默认漏斗只覆盖到支付，不把退款算作转化 (0.044625ms)
ℹ tests 18
ℹ suites 0
ℹ pass 18
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 170.310917