《独立开发者的商业指南·收入与财务工程》7.1 客户分层：按收入、按成本

// file: src/unit/tiers.ts
// tier: L1
// verify: node --test test/unit/tiers.test.ts

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

export type CustomerTier = {
  name: string;
  customers: number;
  annualRevenueCents: Cents;
  serviceCostCents: Cents;
};

export type CostDriver = "revenue" | "accounts" | "equal";

export type TierContribution = {
  name: string;
  customers: number;
  annualRevenueCents: Cents;
  serviceCostCents: Cents;
  grossProfitCents: Cents;
  grossMarginBps: Bps;
  revenueShareBps: Bps;
  profitShareBps: Bps;
  revenuePerCustomerCents: Cents;
  costPerCustomerCents: Cents;
};

type Totals = {
  revenue: Cents;
  cost: Cents;
  profit: Cents;
};

function validate(tiers: CustomerTier[]): Result<Totals> {
  if (tiers.length === 0) {
    return fail("at least one tier is required");
  }
  for (const tier of tiers) {
    if (tier.name.trim() === "") {
      return fail("tier name must not be empty");
    }
    if (!Number.isInteger(tier.customers) || tier.customers <= 0) {
      return fail(`invalid customer count for ${tier.name}`);
    }
    if (
      !Number.isInteger(tier.annualRevenueCents) ||
      tier.annualRevenueCents < 0
    ) {
      return fail(`invalid annual revenue for ${tier.name}`);
    }
    if (
      !Number.isInteger(tier.serviceCostCents) ||
      tier.serviceCostCents < 0
    ) {
      return fail(`invalid service cost for ${tier.name}`);
    }
  }
  const revenue = sum(tiers.map((tier) => tier.annualRevenueCents));
  if (revenue <= 0) {
    return fail("total tier revenue must be positive");
  }
  const cost = sum(tiers.map((tier) => tier.serviceCostCents));
  return ok({ revenue, cost, profit: revenue - cost });
}

function weightsFor(tiers: CustomerTier[], driver: CostDriver): number[] {
  if (driver === "revenue") {
    return tiers.map((tier) => tier.annualRevenueCents);
  }
  if (driver === "accounts") {
    return tiers.map((tier) => tier.customers);
  }
  return tiers.map(() => 1);
}

/**
 * Allocate a shared service cost across tiers with integer cents.
 * The last tier receives the rounding remainder so the parts always
 * sum exactly to the requested total.
 */
export function allocateServiceCost(
  tiers: CustomerTier[],
  totalCostCents: Cents,
  driver: CostDriver,
): Result<Cents[]> {
  const checked = validate(tiers);
  if (!checked.ok) {
    return checked;
  }
  if (!Number.isInteger(totalCostCents) || totalCostCents < 0) {
    return fail("total service cost must be a non-negative integer number of cents");
  }
  const weights = weightsFor(tiers, driver);
  const weightTotal = weights.reduce((acc, weight) => acc + weight, 0);
  if (weightTotal <= 0) {
    return fail("allocation weights must sum to a positive value");
  }
  let allocated = 0;
  return ok(
    weights.map((weight, index) => {
      if (index === weights.length - 1) {
        return totalCostCents - allocated;
      }
      const part = Math.floor((totalCostCents * weight) / weightTotal);
      allocated += part;
      return part;
    }),
  );
}

/**
 * Revenue share, gross profit share and per-customer economics for
 * each tier. Service costs are whatever `serviceCostCents` holds,
 * so the caller decides whether they came from revenue, accounts or
 * a mixed allocation.
 */
export function tierContribution(
  tiers: CustomerTier[],
): Result<TierContribution[]> {
  const checked = validate(tiers);
  if (!checked.ok) {
    return checked;
  }
  return ok(
    tiers.map((tier) => {
      const grossProfit = tier.annualRevenueCents - tier.serviceCostCents;
      return {
        name: tier.name,
        customers: tier.customers,
        annualRevenueCents: tier.annualRevenueCents,
        serviceCostCents: tier.serviceCostCents,
        grossProfitCents: grossProfit,
        grossMarginBps: divide(grossProfit, tier.annualRevenueCents),
        revenueShareBps: divide(tier.annualRevenueCents, checked.value.revenue),
        profitShareBps:
          checked.value.profit > 0
            ? divide(grossProfit, checked.value.profit)
            : 0,
        revenuePerCustomerCents: Math.round(
          tier.annualRevenueCents / tier.customers,
        ),
        costPerCustomerCents: Math.round(
          tier.serviceCostCents / tier.customers,
        ),
      };
    }),
  );
}

/**
 * Allocate one shared cost with a single driver and return the tier
 * contributions. Callers that split cloud, payment and support across
 * different drivers can call `allocateServiceCost` twice and add the
 * parts before calling `tierContribution`.
 */
export function tierReport(
  tiers: CustomerTier[],
  totalCostCents: Cents,
  driver: CostDriver,
): Result<TierContribution[]> {
  const parts = allocateServiceCost(tiers, totalCostCents, driver);
  if (!parts.ok) {
    return parts;
  }
  return tierContribution(
    tiers.map((tier, index) => ({
      ...tier,
      serviceCostCents: tier.serviceCostCents + parts.value[index],
    })),
  );
}