《独立开发者的商业指南·收入与财务工程》6.3 套餐组合的收入结构

ΔMRR = 价格效应 + 数量效应 + 结构效应
价格效应 = Σ(新价 − 旧价) × 旧数量
数量效应 = (新总数量 − 旧总数量) × 旧加权单价
结构效应 = ΔMRR − 价格效应 − 数量效应

// file: src/price/tier-mix.ts
// tier: L1
// verify: node --test test/price/tier-mix.test.ts

import { type Cents } from "../core/money.ts";
import { type Bps, divide, ratio } from "../core/rate.ts";
import { type Result, fail, ok } from "../core/result.ts";

export type TierLine = {
  name: string;
  unitPriceCents: Cents;
  units: number;
};

export type TierMix = {
  totalCents: Cents;
  totalUnits: number;
  blendedUnitPriceCents: Cents;
  sharesBps: Bps[];
};

export type MixChange = {
  oldTotalCents: Cents;
  newTotalCents: Cents;
  deltaCents: Cents;
  oldBlendedCents: Cents;
  newBlendedCents: Cents;
  priceEffectCents: Cents;
  volumeEffectCents: Cents;
  mixEffectCents: Cents;
};

function checkLines(lines: TierLine[]): string | null {
  if (!Array.isArray(lines) || lines.length === 0) {
    return "at least one tier line is required";
  }
  const names = new Set<string>();
  for (const line of lines) {
    if (typeof line.name !== "string" || line.name.length === 0) {
      return "every tier line needs a non-empty name";
    }
    if (names.has(line.name)) {
      return "tier line names must be unique";
    }
    names.add(line.name);
    if (!Number.isInteger(line.unitPriceCents) || line.unitPriceCents < 0) {
      return "unit price must be a non-negative integer amount in cents";
    }
    if (!Number.isInteger(line.units) || line.units < 0) {
      return "units must be a non-negative integer";
    }
  }
  const totalUnits = lines.reduce((sum, line) => sum + line.units, 0);
  if (totalUnits === 0) {
    return "total units must be above zero";
  }
  return null;
}

function totalOf(lines: TierLine[]): Cents {
  return lines.reduce(
    (sum, line) => sum + line.unitPriceCents * line.units,
    0,
  );
}

function totalUnitsOf(lines: TierLine[]): number {
  return lines.reduce((sum, line) => sum + line.units, 0);
}

export function tierMix(lines: TierLine[]): Result<TierMix> {
  const lineError = checkLines(lines);
  if (lineError) {
    return fail(lineError);
  }
  const totalCents = totalOf(lines);
  const totalUnits = totalUnitsOf(lines);
  return ok({
    totalCents,
    totalUnits,
    blendedUnitPriceCents: Math.round(totalCents / totalUnits),
    sharesBps: lines.map((line) =>
      divide(line.unitPriceCents * line.units, totalCents),
    ),
  });
}

function sameShape(oldLines: TierLine[], newLines: TierLine[]): boolean {
  if (oldLines.length !== newLines.length) {
    return false;
  }
  return oldLines.every((line, index) => line.name === newLines[index].name);
}

/**
 * Additive decomposition of an MRR change into price, volume and mix effects.
 * The mix effect is the residual, so it also absorbs any interaction between
 * simultaneous price and volume changes.
 */
export function decomposeMixChange(
  oldLines: TierLine[],
  newLines: TierLine[],
): Result<MixChange> {
  const oldError = checkLines(oldLines);
  if (oldError) {
    return fail(oldError);
  }
  const newError = checkLines(newLines);
  if (newError) {
    return fail(newError);
  }
  if (!sameShape(oldLines, newLines)) {
    return fail("old and new tier lines must have the same names in order");
  }

  const oldTotalCents = totalOf(oldLines);
  const newTotalCents = totalOf(newLines);
  const oldTotalUnits = totalUnitsOf(oldLines);
  const newTotalUnits = totalUnitsOf(newLines);

  let priceEffectCents = 0;
  for (let index = 0; index < oldLines.length; index += 1) {
    priceEffectCents +=
      (newLines[index].unitPriceCents - oldLines[index].unitPriceCents) *
      oldLines[index].units;
  }

  const volumeEffectCents = Math.round(
    (newTotalUnits - oldTotalUnits) * (oldTotalCents / oldTotalUnits),
  );
  const deltaCents = newTotalCents - oldTotalCents;

  return ok({
    oldTotalCents,
    newTotalCents,
    deltaCents,
    oldBlendedCents: Math.round(oldTotalCents / oldTotalUnits),
    newBlendedCents: Math.round(newTotalCents / newTotalUnits),
    priceEffectCents,
    volumeEffectCents,
    mixEffectCents: deltaCents - priceEffectCents - volumeEffectCents,
  });
}

/**
 * Convert a monthly churn rate into the share of a cohort lost over a year.
 * A 3.0% monthly churn becomes 30.6% annual churn.
 */
export function annualizedChurnBps(monthlyChurnBps: Bps): Result<Bps> {
  if (
    !Number.isInteger(monthlyChurnBps) ||
    monthlyChurnBps < 0 ||
    monthlyChurnBps > 10000
  ) {
    return fail("monthly churn must be between 0 and 10000 bps");
  }
  return ok(
    Math.round((1 - Math.pow(1 - ratio(monthlyChurnBps), 12)) * 10000),
  );
}