《独立开发者的商业指南·收入与财务工程》8.2 情景模拟：断供、退款潮、平台封禁

// file: src/cash/scenarios.ts
// tier: L1
// verify: node --test test/cash/scenarios.test.ts

import { type Cents } from "../core/money.ts";
import { type Result, fail, ok } from "../core/result.ts";
import {
  type Cash13,
  type WeekFlow,
  buildCash13,
  WEEKS_PER_QUARTER,
} from "./cash13.ts";

export const BPS = 10_000;

/**
 * A stress scenario is described by four independent knobs so that each one can
 * be sourced from a different case fact:
 *   permanentLossBps   a share of every week's inflow that never comes back
 *   shockLossBps       an extra share removed from startWeek onward
 *   weeklyOutflowDelta a recurring payment added from startWeek onward
 *   oneOffInflow/outflow  a single lump in a named week (renewal, tax, refund)
 * All shares are basis points; 10,000 bps is a total loss.
 */
export type ScenarioSpec = {
  name: string;
  permanentLossBps: number;
  shockLossBps: number;
  startWeek: number;
  weeklyOutflowDelta: Cents;
  oneOffInflow: Cents;
  oneOffInflowWeek: number;
  oneOffOutflow: Cents;
  oneOffOutflowWeek: number;
};

export type ScenarioOutcome = Cash13 & {
  name: string;
  lostInflow: Cents;
};

export function defaultSpec(name: string): ScenarioSpec {
  return {
    name,
    permanentLossBps: 0,
    shockLossBps: 0,
    startWeek: 1,
    weeklyOutflowDelta: 0,
    oneOffInflow: 0,
    oneOffInflowWeek: 1,
    oneOffOutflow: 0,
    oneOffOutflowWeek: 1,
  };
}

/** Rounded share of an amount, so 900 bps of 20,020 keeps whole cents. */
export function share(amount: Cents, bps: number): Cents {
  return Math.round((amount * bps) / BPS);
}

/**
 * Extra refund cash when the refund rate moves from baseBps to stressBps.
 * Tidecast: 400 bps to 1,200 bps is 8% of gross sales handed back.
 */
export function refundDelta(
  grossSales: Cents,
  baseRefundBps: number,
  stressRefundBps: number,
): Result<Cents> {
  if (!Number.isInteger(grossSales) || grossSales < 0) {
    return fail("gross sales must be a non-negative integer number of cents");
  }
  if (
    !Number.isInteger(baseRefundBps) ||
    !Number.isInteger(stressRefundBps) ||
    baseRefundBps < 0 ||
    stressRefundBps < 0 ||
    stressRefundBps > BPS
  ) {
    return fail("refund rates must be integers between 0 and 10,000 bps");
  }
  if (stressRefundBps <= baseRefundBps) {
    return fail("stress refund rate must exceed the base rate");
  }
  return ok(share(grossSales, stressRefundBps - baseRefundBps));
}

function validateSpec(spec: ScenarioSpec): Result<true> {
  const rates = [spec.permanentLossBps, spec.shockLossBps];
  for (const rate of rates) {
    if (!Number.isInteger(rate) || rate < 0 || rate > BPS) {
      return fail("loss rates must be integers between 0 and 10,000 bps");
    }
  }
  if (spec.permanentLossBps + spec.shockLossBps > BPS) {
    return fail("combined loss cannot exceed 10,000 bps");
  }
  if (
    !Number.isInteger(spec.startWeek) ||
    spec.startWeek < 1 ||
    spec.startWeek > WEEKS_PER_QUARTER
  ) {
    return fail(`start week must be between 1 and ${WEEKS_PER_QUARTER}`);
  }
  if (!Number.isInteger(spec.weeklyOutflowDelta)) {
    return fail("weekly outflow delta must be an integer");
  }
  if (!Number.isInteger(spec.oneOffInflow) || !Number.isInteger(spec.oneOffOutflow)) {
    return fail("one-off amounts must be integers");
  }
  return ok(true);
}

/**
 * Rewrites a base week series. Losses compound: the permanent share is removed
 * first, then the shock share applies to what is left. The one-off inflow is
 * signed, so a renewal that failed to land is a negative number.
 */
export function applyScenario(
  base: WeekFlow[],
  spec: ScenarioSpec,
): Result<WeekFlow[]> {
  const checked = validateSpec(spec);
  if (!checked.ok) {
    return checked;
  }
  const out: WeekFlow[] = [];
  for (let i = 0; i < base.length; i += 1) {
    const week = i + 1;
    const keepPermanent = BPS - spec.permanentLossBps;
    const keepShock = week >= spec.startWeek ? BPS - spec.shockLossBps : BPS;
    let inflow = Math.round(
      (base[i].inflow * keepPermanent * keepShock) / (BPS * BPS),
    );
    if (week === spec.oneOffInflowWeek) {
      inflow += spec.oneOffInflow;
    }
    let outflow = base[i].outflow;
    if (week >= spec.startWeek) {
      outflow += spec.weeklyOutflowDelta;
    }
    if (week === spec.oneOffOutflowWeek) {
      outflow += spec.oneOffOutflow;
    }
    out.push({ inflow, outflow });
  }
  return ok(out);
}

/** Applies a scenario and runs it through the 13-week table. */
export function runScenario(
  openingCash: Cents,
  base: WeekFlow[],
  spec: ScenarioSpec,
): Result<ScenarioOutcome> {
  const applied = applyScenario(base, spec);
  if (!applied.ok) {
    return applied;
  }
  const built = buildCash13(openingCash, applied.value);
  if (!built.ok) {
    return built;
  }
  const baseInflow = base.reduce((acc, row) => acc + row.inflow, 0);
  return ok({
    ...built.value,
    name: spec.name,
    lostInflow: baseInflow - built.value.totalInflow,
  });
}