《移动游戏产品的架构·商业化与发行工程》10.2 漏斗、留存与付费转化

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

export interface FunnelEvent {
  readonly subjectId: string;
  readonly step: string;
  readonly atMs: number;
}
export interface FunnelStepResult {
  readonly step: string;
  readonly subjects: number;
  readonly fromPrevPct: number | null;
  readonly fromStartPct: number;
}
export type FunnelCode = "empty-steps" | "duplicate-step" | "bad-window" | "count-length" | "count-order";
export type FunnelResult =
  | { readonly ok: true; readonly steps: readonly FunnelStepResult[]; readonly windowMs: number; readonly subjects: number }
  | { readonly ok: false; readonly code: FunnelCode; readonly detail: string };
export type RateCode = "bad-active" | "paid-exceeds-active" | "bad-cohort" | "retained-exceeds-cohort";
export type RateResult =
  | { readonly ok: true; readonly pct: number }
  | { readonly ok: false; readonly code: RateCode; readonly detail: string };
export interface RetentionPoint {
  readonly day: number;
  readonly ratePct: number;
}
export interface CaseAggregates {
  readonly mau: number;
  readonly paidUsers: number;
  readonly orders: number;
  readonly dropRatePct: number;
  readonly refundRatePct: number;
  readonly revenueCents: number;
}

export const CASE: Readonly<Record<"xiaoxiao" | "fangzhou", CaseAggregates>> = {
  xiaoxiao: { mau: 3_200_000, paidUsers: 89_600, orders: 420_000, dropRatePct: 0.35, refundRatePct: 1.2, revenueCents: 987_000_000 },
  fangzhou: { mau: 1_000_000, paidUsers: 65_000, orders: 150_000, dropRatePct: 0.2, refundRatePct: 0.8, revenueCents: 2_820_000_000 },
};

export function computeFunnel(
  events: readonly FunnelEvent[],
  steps: readonly string[],
  windowMs: number,
): FunnelResult {
  if (steps.length === 0) {
    return { ok: false, code: "empty-steps", detail: "a funnel needs at least one step" };
  }
  const seen = new Set<string>();
  for (const step of steps) {
    if (step.length === 0 || seen.has(step)) {
      return { ok: false, code: "duplicate-step", detail: `step ${JSON.stringify(step)} is empty or repeated` };
    }
    seen.add(step);
  }
  if (!Number.isFinite(windowMs) || windowMs < 0) {
    return { ok: false, code: "bad-window", detail: `${windowMs} is not a valid window` };
  }

  const bySubject = new Map<string, FunnelEvent[]>();
  for (const event of events) {
    const list = bySubject.get(event.subjectId);
    if (list === undefined) {
      bySubject.set(event.subjectId, [event]);
    } else {
      list.push(event);
    }
  }

  const reached = new Array<number>(steps.length).fill(0);
  for (const list of bySubject.values()) {
    const ordered = [...list].sort((left, right) => {
      if (left.atMs !== right.atMs) {
        return left.atMs - right.atMs;
      }
      return steps.indexOf(left.step) - steps.indexOf(right.step);
    });
    let cursor = Number.NEGATIVE_INFINITY;
    let start: number | null = null;
    let depth = 0;
    for (let index = 0; index < steps.length; index += 1) {
      const wanted = steps[index] as string;
      let matched: FunnelEvent | null = null;
      for (const event of ordered) {
        if (event.step !== wanted || event.atMs < cursor) {
          continue;
        }
        if (start !== null && event.atMs - start > windowMs) {
          continue;
        }
        matched = event;
        break;
      }
      if (matched === null) {
        break;
      }
      if (index === 0) {
        start = matched.atMs;
      }
      cursor = matched.atMs;
      depth = index + 1;
    }
    for (let index = 0; index < depth; index += 1) {
      reached[index] = (reached[index] as number) + 1;
    }
  }

  const subjects = reached[0] as number;
  const result: FunnelStepResult[] = steps.map((step, index) => {
    const count = reached[index] as number;
    const previous = index === 0 ? null : (reached[index - 1] as number);
    return {
      step,
      subjects: count,
      fromPrevPct: previous === null ? null : rate(count, previous),
      fromStartPct: subjects === 0 ? 0 : rate(count, subjects),
    };
  });
  return { ok: true, steps: result, windowMs, subjects };
}

export function funnelFromCounts(counts: readonly number[], steps: readonly string[]): FunnelResult {
  if (counts.length !== steps.length || steps.length === 0) {
    return { ok: false, code: "count-length", detail: `${counts.length} counts for ${steps.length} steps` };
  }
  for (let index = 0; index < counts.length; index += 1) {
    const count = counts[index] as number;
    if (!Number.isInteger(count) || count < 0) {
      return { ok: false, code: "count-order", detail: `count ${count} is not a non-negative integer` };
    }
    const previous = counts[index - 1];
    if (previous !== undefined && count > previous) {
      return { ok: false, code: "count-order", detail: `step ${steps[index]} grows from ${previous} to ${count}` };
    }
  }
  const subjects = counts[0] as number;
  const result: FunnelStepResult[] = steps.map((step, index) => {
    const count = counts[index] as number;
    const previous = index === 0 ? null : (counts[index - 1] as number);
    return {
      step,
      subjects: count,
      fromPrevPct: previous === null ? null : rate(count, previous),
      fromStartPct: subjects === 0 ? 0 : rate(count, subjects),
    };
  });
  return { ok: true, steps: result, windowMs: 0, subjects };
}

export function paidConversion(activeUsers: number, paidUsers: number): RateResult {
  if (!Number.isInteger(activeUsers) || activeUsers <= 0) {
    return { ok: false, code: "bad-active", detail: `${activeUsers} is not a positive user count` };
  }
  if (!Number.isInteger(paidUsers) || paidUsers < 0 || paidUsers > activeUsers) {
    return { ok: false, code: "paid-exceeds-active", detail: `paid ${paidUsers} must be between 0 and ${activeUsers}` };
  }
  return { ok: true, pct: rate(paidUsers, activeUsers) };
}

export function retentionRate(cohortUsers: number, retainedUsers: number): RateResult {
  if (!Number.isInteger(cohortUsers) || cohortUsers <= 0) {
    return { ok: false, code: "bad-cohort", detail: `${cohortUsers} is not a positive cohort` };
  }
  if (!Number.isInteger(retainedUsers) || retainedUsers < 0 || retainedUsers > cohortUsers) {
    return { ok: false, code: "retained-exceeds-cohort", detail: `retained ${retainedUsers} must be between 0 and ${cohortUsers}` };
  }
  return { ok: true, pct: rate(retainedUsers, cohortUsers) };
}

export function validateRetentionCurve(points: readonly RetentionPoint[]): { readonly ok: boolean; readonly detail: string } {
  let previousDay = -1;
  for (const point of points) {
    if (!Number.isInteger(point.day) || point.day <= previousDay) {
      return { ok: false, detail: `day ${point.day} must be a strictly increasing integer` };
    }
    if (!Number.isFinite(point.ratePct) || point.ratePct < 0 || point.ratePct > 100) {
      return { ok: false, detail: `rate ${point.ratePct} must be within 0..100` };
    }
    previousDay = point.day;
  }
  return { ok: points.length > 0, detail: `${points.length} points checked` };
}

export function arppuCents(revenueCents: number, payers: number): number | null {
  if (!Number.isFinite(revenueCents) || revenueCents < 0 || !Number.isInteger(payers) || payers <= 0) {
    return null;
  }
  return Math.round(revenueCents / payers);
}

export function arpuCents(revenueCents: number, activeUsers: number): number | null {
  if (!Number.isFinite(revenueCents) || revenueCents < 0 || !Number.isInteger(activeUsers) || activeUsers <= 0) {
    return null;
  }
  return Math.round((revenueCents / activeUsers) * 100) / 100;
}

export function formatFunnel(result: FunnelResult): string {
  if (!result.ok) {
    return `funnel error=${result.code} detail=${result.detail}`;
  }
  const parts = result.steps.map((step) => {
    const prev = step.fromPrevPct === null ? "n/a" : `${step.fromPrevPct}%`;
    return `${step.step} users=${step.subjects} start=${step.fromStartPct}% prev=${prev}`;
  });
  return `funnel window=${result.windowMs}ms subjects=${result.subjects} ${parts.join(" ")}`;
}

function rate(part: number, whole: number): number {
  if (whole === 0) {
    return 0;
  }
  return Math.round((part / whole) * 10000) / 100;
}