《移动游戏产品的架构·商业化与发行工程》7.3 买量 ROI 与回收周期

ROI(day) = 该 cohort 截至第 day 天的累计收入 / 该 cohort 的买量花费

边际 ROI = (新增收入 - 原收入) / (新增花费 - 原花费)

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

export interface RoiPoint {
  readonly day: number;
  readonly roiPct: number;
}

export interface Cohort {
  readonly cohortId: string;
  readonly cpiCents: number;
  readonly curve: readonly RoiPoint[];
}

export type CurveCode = "ok" | "empty" | "bad-day" | "bad-roi";

export interface CurveCheck {
  readonly ok: boolean;
  readonly code: CurveCode;
  readonly detail: string;
}

export function validateCurve(curve: readonly RoiPoint[]): CurveCheck {
  if (curve.length === 0) {
    return { ok: false, code: "empty", detail: "curve has no points" };
  }
  let previousDay = -1;
  for (const point of curve) {
    if (!Number.isFinite(point.day) || point.day < 0 || point.day <= previousDay) {
      return {
        ok: false,
        code: "bad-day",
        detail: `day ${point.day} must be finite, non-negative and strictly increasing`,
      };
    }
    if (!Number.isFinite(point.roiPct) || point.roiPct < 0) {
      return { ok: false, code: "bad-roi", detail: `roi ${point.roiPct} must be non-negative` };
    }
    previousDay = point.day;
  }
  return { ok: true, code: "ok", detail: `${curve.length} points checked` };
}

export function roiAt(curve: readonly RoiPoint[], day: number): number | null {
  if (!validateCurve(curve).ok || curve.length === 0) {
    return null;
  }
  const first = curve[0] as RoiPoint;
  const last = curve[curve.length - 1] as RoiPoint;
  if (day < first.day || day > last.day) {
    return null;
  }
  for (let index = 0; index < curve.length; index += 1) {
    const point = curve[index] as RoiPoint;
    if (point.day === day) {
      return point.roiPct;
    }
    const next = curve[index + 1];
    if (next !== undefined && day > point.day && day < next.day) {
      const ratio = (day - point.day) / (next.day - point.day);
      return round2(point.roiPct + ratio * (next.roiPct - point.roiPct));
    }
  }
  return null;
}

export function paybackDay(curve: readonly RoiPoint[]): number | null {
  if (!validateCurve(curve).ok || curve.length === 0) {
    return null;
  }
  for (let index = 0; index < curve.length; index += 1) {
    const point = curve[index] as RoiPoint;
    if (point.roiPct < 100) {
      continue;
    }
    const previous = curve[index - 1];
    if (previous === undefined) {
      return point.day;
    }
    if (point.roiPct === previous.roiPct) {
      return point.day;
    }
    const ratio = (100 - previous.roiPct) / (point.roiPct - previous.roiPct);
    return round2(previous.day + ratio * (point.day - previous.day));
  }
  return null;
}

export function revenuePerInstallCents(cpiCents: number, roiPct: number): number {
  return Math.round((cpiCents * roiPct) / 100);
}

export function marginalRoiPct(
  previousSpendCents: number,
  previousRevenueCents: number,
  nextSpendCents: number,
  nextRevenueCents: number,
): number | null {
  const spendDelta = nextSpendCents - previousSpendCents;
  if (spendDelta <= 0) {
    return null;
  }
  const revenueDelta = nextRevenueCents - previousRevenueCents;
  return round2((revenueDelta / spendDelta) * 100);
}

export interface ScaleInput {
  readonly marginalRoiPct: number | null;
  readonly paybackDay: number | null;
  readonly targetPaybackDay: number;
  readonly minMarginalRoiPct: number;
}

export type ScaleAction = "scale" | "hold" | "cut";

export interface ScaleDecision {
  readonly action: ScaleAction;
  readonly reason: string;
}

export function decideScale(input: ScaleInput): ScaleDecision {
  if (input.marginalRoiPct === null) {
    return { action: "hold", reason: "insufficient-increment-data" };
  }
  if (input.marginalRoiPct < 100) {
    return { action: "cut", reason: "marginal-roi-below-cost" };
  }
  if (input.paybackDay === null) {
    return { action: "hold", reason: "no-payback-in-curve" };
  }
  if (input.paybackDay > input.targetPaybackDay) {
    return { action: "hold", reason: "payback-beyond-target" };
  }
  if (input.marginalRoiPct < input.minMarginalRoiPct) {
    return { action: "hold", reason: "marginal-roi-below-threshold" };
  }
  return { action: "scale", reason: "payback-and-marginal-roi-within-target" };
}

function round2(value: number): number {
  return Math.round(value * 100) / 100;
}

export function formatRoi(cohort: Cohort, day: number): string {
  const roi = roiAt(cohort.curve, day);
  const payback = paybackDay(cohort.curve);
  const roiText = roi === null ? "n/a" : `${roi}%`;
  const paybackText = payback === null ? "n/a" : `D${payback}`;
  const rpi =
    roi === null ? "n/a" : `¥${(revenuePerInstallCents(cohort.cpiCents, roi) / 100).toFixed(2)}`;
  return `${cohort.cohortId} D${day} roi=${roiText} payback=${paybackText} rpi=${rpi}`;
}