《独立开发者的商业指南·收入与财务工程》5.3 预算偏差与季度校准

全年预测 = Q1 实际 + 剩余三季度预算 + 修正
         = $59,592 + $180,180 − $1,404
         = $238,368
与预算差额 = $238,368 − $240,240 = −$1,872（−0.78%）

全年预测 = 年初至今实际 + 剩余期间原预算 + 修正

// file: src/fin/variance.ts
// tier: L1
// verify: node --test test/fin/variance.test.ts

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

export type VarianceDirection = "revenue" | "cost";

export type Severity = "ok" | "watch" | "act";

export type VarianceLimits = {
  watchBps: Bps;
  actBps: Bps;
  watchCents: Cents;
  actCents: Cents;
};

export const DEFAULT_VARIANCE_LIMITS: VarianceLimits = {
  watchBps: 500,
  actBps: 1000,
  watchCents: 100000,
  actCents: 250000,
};

export type Variance = {
  actual: Cents;
  budget: Cents;
  absolute: Cents;
  rateBps: Bps;
  favorable: boolean;
};

/**
 * Measures actual against budget. For revenue a positive gap is favorable;
 * for cost a positive gap is an overrun and therefore unfavorable. The rate is
 * signed against the absolute budget, so -780 bps means 7.8% below budget.
 */
export function measureVariance(
  actual: Cents,
  budget: Cents,
  direction: VarianceDirection,
): Result<Variance> {
  if (!Number.isInteger(actual)) {
    return fail("actual must be an integer number of cents");
  }
  if (!Number.isInteger(budget) || budget <= 0) {
    return fail("budget must be a positive integer number of cents");
  }
  const absolute = actual - budget;
  const favorable = direction === "revenue" ? absolute >= 0 : absolute <= 0;
  return ok({
    actual,
    budget,
    absolute,
    rateBps: Math.round((absolute * 10000) / Math.abs(budget)),
    favorable,
  });
}

function checkLimits(limits: VarianceLimits): string | null {
  const values = [
    limits.watchBps,
    limits.actBps,
    limits.watchCents,
    limits.actCents,
  ];
  if (values.some((value) => !Number.isInteger(value) || value < 0)) {
    return "variance limits must be non-negative integers";
  }
  if (limits.watchBps > limits.actBps) {
    return "watch rate must not exceed act rate";
  }
  if (limits.watchCents > limits.actCents) {
    return "watch amount must not exceed act amount";
  }
  return null;
}

/**
 * Two independent triggers: a relative threshold and an absolute threshold.
 * Either one can escalate. annualizeQuarters scales the absolute gap before
 * the amount test, which is how a small quarterly miss becomes visible when it
 * is expected to repeat.
 */
export function classifyVariance(
  variance: Variance,
  limits: VarianceLimits = DEFAULT_VARIANCE_LIMITS,
  annualizeQuarters = 1,
): Result<Severity> {
  const error = checkLimits(limits);
  if (error) {
    return fail(error);
  }
  if (!Number.isInteger(annualizeQuarters) || annualizeQuarters < 1) {
    return fail("annualizeQuarters must be a positive integer");
  }
  const rate = Math.abs(variance.rateBps);
  const amount = Math.abs(variance.absolute) * annualizeQuarters;
  if (rate >= limits.actBps || amount >= limits.actCents) {
    return ok("act");
  }
  if (rate >= limits.watchBps || amount >= limits.watchCents) {
    return ok("watch");
  }
  return ok("ok");
}

export type RollingForecast = {
  actualToDate: Cents;
  remainingBudget: Cents;
  correction: Cents;
  fullYear: Cents;
  changeVsBudget: Cents;
  changeBps: Bps;
};

/**
 * Rolling forecast after a quarter closes:
 *   full year = actual to date + remaining budget + correction
 * The correction is where the quarter's learning enters; it can be negative.
 */
export function rollingForecast(
  actualToDate: Cents,
  remainingBudget: Cents,
  correction: Cents,
  annualBudget: Cents,
): Result<RollingForecast> {
  if (!Number.isInteger(actualToDate) || actualToDate < 0) {
    return fail("actual to date must be a non-negative integer");
  }
  if (!Number.isInteger(remainingBudget) || remainingBudget < 0) {
    return fail("remaining budget must be a non-negative integer");
  }
  if (!Number.isInteger(correction)) {
    return fail("correction must be an integer number of cents");
  }
  if (!Number.isInteger(annualBudget) || annualBudget <= 0) {
    return fail("annual budget must be a positive integer");
  }
  const fullYear = actualToDate + remainingBudget + correction;
  const changeVsBudget = fullYear - annualBudget;
  return ok({
    actualToDate,
    remainingBudget,
    correction,
    fullYear,
    changeVsBudget,
    changeBps: divide(changeVsBudget, annualBudget),
  });
}