《独立开发者的商业指南·合同、应收与风险》9.2 返点、区域保护与价格冲突

// file: src/contract/rebate.ts
// tier: L1
// verify: node --test test/contract/rebate.test.ts

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

export type RebateTier = {
  minAnnualCents: Cents;
  rateBps: Bps;
};

/** Teaching assumption: the rebate is retroactive on the full annual purchase. */
export const REBATE_TIERS: RebateTier[] = [
  { minAnnualCents: 0, rateBps: 1000 },
  { minAnnualCents: 10_000_000, rateBps: 1500 },
  { minAnnualCents: 25_000_000, rateBps: 2000 },
];

export type RebateResult = {
  annualPurchaseCents: Cents;
  rateBps: Bps;
  rebateCents: Cents;
  netCents: Cents;
};

export type VolumeNet = RebateResult & {
  deals: number;
  unitNetCents: Cents;
};

export type ExitLossInput = {
  annualDeals: number;
  agentNetPerDealCents: Cents;
  directNetPerDealCents: Cents;
  recaptureRateBps: Bps;
};

export type ExitLoss = {
  lostAgentNetCents: Cents;
  recapturedDeals: number;
  recapturedNetCents: Cents;
  netLossCents: Cents;
};

function checkAmount(value: Cents, label: string): string | null {
  if (!Number.isInteger(value) || value < 0) {
    return `${label} must be a non-negative integer amount in cents`;
  }
  return null;
}

function checkBps(value: Bps, label: string): string | null {
  if (!Number.isInteger(value) || value < 0 || value > 10000) {
    return `${label} must be between 0 and 10000 bps`;
  }
  return null;
}

export function rebateRate(annualPurchaseCents: Cents): Result<Bps> {
  const error = checkAmount(annualPurchaseCents, "annual purchase");
  if (error) {
    return fail(error);
  }
  let selected = REBATE_TIERS[0].rateBps;
  for (const tier of REBATE_TIERS) {
    if (annualPurchaseCents >= tier.minAnnualCents) {
      selected = tier.rateBps;
    }
  }
  return ok(selected);
}

export function rebateOn(annualPurchaseCents: Cents): Result<RebateResult> {
  const rate = rebateRate(annualPurchaseCents);
  if (!rate.ok) {
    return rate;
  }
  const rebateCents = applyRate(annualPurchaseCents, rate.value);
  return ok({
    annualPurchaseCents,
    rateBps: rate.value,
    rebateCents,
    netCents: annualPurchaseCents - rebateCents,
  });
}

export function volumeNet(
  grossPerDealCents: Cents,
  deals: number,
): Result<VolumeNet> {
  if (!Number.isInteger(grossPerDealCents) || grossPerDealCents <= 0) {
    return fail("gross per deal must be a positive integer amount in cents");
  }
  if (!Number.isInteger(deals) || deals <= 0) {
    return fail("deals must be a positive integer");
  }
  const annualPurchaseCents = grossPerDealCents * deals;
  const rebate = rebateOn(annualPurchaseCents);
  if (!rebate.ok) {
    return rebate;
  }
  return ok({
    ...rebate.value,
    deals,
    unitNetCents: Math.round(rebate.value.netCents / deals),
  });
}

/**
 * The resale price at which the channel keeps exactly the required margin
 * after the rebate. A direct price below this line undercuts the channel.
 */
export function minimumResalePrice(
  netCostCents: Cents,
  requiredMarginBps: Bps,
): Result<Cents> {
  const costError = checkAmount(netCostCents, "net cost");
  if (costError) {
    return fail(costError);
  }
  if (netCostCents === 0) {
    return fail("net cost must be positive");
  }
  if (
    !Number.isInteger(requiredMarginBps) ||
    requiredMarginBps < 0 ||
    requiredMarginBps >= 10000
  ) {
    return fail("required margin must be between 0 and 9999 bps");
  }
  return ok(
    Math.ceil((netCostCents * 10000) / (10000 - requiredMarginBps)),
  );
}

export function marginAtPrice(
  netCostCents: Cents,
  resalePriceCents: Cents,
): Result<Bps> {
  const costError = checkAmount(netCostCents, "net cost");
  if (costError) {
    return fail(costError);
  }
  if (!Number.isInteger(resalePriceCents) || resalePriceCents <= 0) {
    return fail("resale price must be a positive integer amount in cents");
  }
  return ok(divide(resalePriceCents - netCostCents, resalePriceCents));
}

/** A most-favored-nation clause makes the vendor pay back the price gap. */
export function mfnMakeWhole(
  listPriceCents: Cents,
  directPriceCents: Cents,
  deals: number,
): Result<Cents> {
  for (const [value, label] of [
    [listPriceCents, "list price"],
    [directPriceCents, "direct price"],
  ] as Array<[Cents, string]>) {
    const error = checkAmount(value, label);
    if (error) {
      return fail(error);
    }
  }
  if (!Number.isInteger(deals) || deals <= 0) {
    return fail("deals must be a positive integer");
  }
  const gap = listPriceCents - directPriceCents;
  return ok(gap > 0 ? gap * deals : 0);
}

export function agentExitLoss(input: ExitLossInput): Result<ExitLoss> {
  if (!Number.isInteger(input.annualDeals) || input.annualDeals <= 0) {
    return fail("annual deals must be a positive integer");
  }
  for (const [value, label] of [
    [input.agentNetPerDealCents, "agent net per deal"],
    [input.directNetPerDealCents, "direct net per deal"],
  ] as Array<[Cents, string]>) {
    const error = checkAmount(value, label);
    if (error) {
      return fail(error);
    }
  }
  const rateError = checkBps(input.recaptureRateBps, "recapture rate");
  if (rateError) {
    return fail(rateError);
  }
  const lostAgentNetCents =
    input.annualDeals * input.agentNetPerDealCents;
  const recapturedDeals = Math.round(
    (input.annualDeals * input.recaptureRateBps) / 10000,
  );
  const recapturedNetCents =
    recapturedDeals * input.directNetPerDealCents;
  return ok({
    lostAgentNetCents,
    recapturedDeals,
    recapturedNetCents,
    netLossCents: lostAgentNetCents - recapturedNetCents,
  });
}