《独立开发者的商业指南·收入与财务工程》5.1 自上而下与自下而上的预算

收入差额 = 自上而下收入 − 自下而上收入
成本差额 = 自上而下成本 − 自下而上成本
差额率   = 差额 ÷ 自下而上基数

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

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

export type BudgetCategory = "revenue" | "people" | "software" | "marketing";

export type BudgetLine = {
  label: string;
  category: BudgetCategory;
  annual: Cents;
};

export type CategoryTotals = Record<BudgetCategory, Cents>;

export type Budget = {
  lines: BudgetLine[];
  revenue: Cents;
  costs: Cents;
  byCategory: CategoryTotals;
};

function emptyTotals(): CategoryTotals {
  return { revenue: 0, people: 0, software: 0, marketing: 0 };
}

function isCents(value: number): boolean {
  return Number.isInteger(value) && value >= 0;
}

/**
 * Bottom-up: every line comes from a contract, invoice or explicit driver.
 * Revenue lines are summed as income; people, software and marketing lines
 * are summed as costs. The four categories must cover every budgeted dollar.
 */
export function buildBottomUp(lines: BudgetLine[]): Result<Budget> {
  if (lines.length === 0) {
    return fail("at least one budget line is required");
  }
  const byCategory = emptyTotals();
  for (const line of lines) {
    if (line.label.trim() === "") {
      return fail("budget line label must not be empty");
    }
    if (!Object.hasOwn(byCategory, line.category)) {
      return fail(`unknown budget category: ${line.category}`);
    }
    if (!isCents(line.annual)) {
      return fail(`budget line ${line.label} must be a non-negative integer`);
    }
    byCategory[line.category] = add(byCategory[line.category], line.annual);
  }
  const revenue = byCategory.revenue;
  const costs = add(
    add(byCategory.people, byCategory.software),
    byCategory.marketing,
  );
  return ok({ lines: [...lines], revenue, costs, byCategory });
}

export type TopDownInput = {
  revenue: Cents;
  people: Cents;
  software: Cents;
  marketing: Cents;
};

/**
 * Top-down: revenue target and cost envelopes are agreed first, usually as
 * percentages of revenue or as prior-year ratios. Lines are not itemised.
 */
export function buildTopDown(input: TopDownInput): Result<Budget> {
  const values = [input.revenue, input.people, input.software, input.marketing];
  if (values.some((value) => !isCents(value))) {
    return fail("top-down amounts must be non-negative integers");
  }
  const byCategory: CategoryTotals = {
    revenue: input.revenue,
    people: input.people,
    software: input.software,
    marketing: input.marketing,
  };
  return ok({
    lines: [],
    revenue: input.revenue,
    costs: add(add(input.people, input.software), input.marketing),
    byCategory,
  });
}

export type BudgetReconciliation = {
  revenueGap: Cents;
  revenueGapBps: Bps;
  costGap: Cents;
  costGapBps: Bps;
  categoryGaps: CategoryTotals;
};

/**
 * Compares a top-down envelope with a bottom-up build. Gaps are top minus
 * bottom: a positive revenue gap means the target is above the build, while a
 * positive cost gap means the envelope is above the itemised plan.
 */
export function reconcile(top: Budget, bottom: Budget): Result<BudgetReconciliation> {
  if (bottom.revenue === 0 || bottom.costs === 0) {
    return fail("bottom-up revenue and costs must be non-zero");
  }
  const revenueGap = sub(top.revenue, bottom.revenue);
  const costGap = sub(top.costs, bottom.costs);
  return ok({
    revenueGap,
    revenueGapBps: divide(revenueGap, bottom.revenue),
    costGap,
    costGapBps: divide(costGap, bottom.costs),
    categoryGaps: {
      revenue: sub(top.byCategory.revenue, bottom.byCategory.revenue),
      people: sub(top.byCategory.people, bottom.byCategory.people),
      software: sub(top.byCategory.software, bottom.byCategory.software),
      marketing: sub(top.byCategory.marketing, bottom.byCategory.marketing),
    },
  });
}

export type ProductPlan = {
  label: string;
  price: Cents;
  quantity: number;
};

export type RevenueVariance = {
  total: Cents;
  price: Cents;
  volume: Cents;
  mix: Cents;
};

function planMap(
  plans: ProductPlan[],
  side: string,
): Result<Map<string, ProductPlan>> {
  const map = new Map<string, ProductPlan>();
  for (const plan of plans) {
    if (plan.label.trim() === "") {
      return fail(`${side} product label must not be empty`);
    }
    if (!isCents(plan.price)) {
      return fail(`${side} price must be a non-negative integer`);
    }
    if (!Number.isInteger(plan.quantity) || plan.quantity < 0) {
      return fail(`${side} quantity must be a non-negative integer`);
    }
    if (map.has(plan.label)) {
      return fail(`${side} product label ${plan.label} is duplicated`);
    }
    map.set(plan.label, plan);
  }
  return ok(map);
}

/**
 * Revenue variance split into price, volume and mix:
 *   price  = sum((actual price - budget price) * budget quantity)
 *   volume = sum(budget price * (actual quantity - budget quantity))
 *   mix    = total - price - volume
 * The mix part absorbs the price-volume interaction term, so the three parts
 * always add up exactly to the total variance.
 */
export function decomposeRevenueVariance(
  budgetPlans: ProductPlan[],
  actualPlans: ProductPlan[],
): Result<RevenueVariance> {
  if (budgetPlans.length === 0) {
    return fail("at least one budget product is required");
  }
  if (budgetPlans.length !== actualPlans.length) {
    return fail("budget and actual must have the same number of products");
  }
  const budget = planMap(budgetPlans, "budget");
  if (!budget.ok) {
    return budget;
  }
  const actual = planMap(actualPlans, "actual");
  if (!actual.ok) {
    return actual;
  }

  let budgetTotal = 0;
  let actualTotal = 0;
  let price = 0;
  let volume = 0;
  for (const plan of budgetPlans) {
    const match = actual.value.get(plan.label);
    if (!match) {
      return fail(`actual is missing product ${plan.label}`);
    }
    budgetTotal += plan.price * plan.quantity;
    actualTotal += match.price * match.quantity;
    price += (match.price - plan.price) * plan.quantity;
    volume += plan.price * (match.quantity - plan.quantity);
  }
  const total = actualTotal - budgetTotal;
  return ok({ total, price, volume, mix: total - price - volume });
}

/**
 * Spreads an annual budget across four quarters with explicit weights.
 * The first three quarters are rounded and the fourth absorbs the rounding
 * residual, so the four amounts always sum to the annual total.
 */
export function spreadQuarterly(annual: Cents, weightsBps: Bps[]): Result<Cents[]> {
  if (!isCents(annual)) {
    return fail("annual budget must be a non-negative integer");
  }
  if (weightsBps.length !== 4) {
    return fail("exactly four quarter weights are required");
  }
  let totalWeight = 0;
  for (const weight of weightsBps) {
    if (!Number.isInteger(weight) || weight < 0) {
      return fail("quarter weights must be non-negative integers");
    }
    totalWeight += weight;
  }
  if (totalWeight !== 10000) {
    return fail(`quarter weights must sum to 10000 bps, got ${totalWeight}`);
  }
  const quarters: Cents[] = [];
  for (let index = 0; index < 3; index += 1) {
    quarters.push(Math.round((annual * weightsBps[index]) / 10000));
  }
  const firstThree = quarters.reduce((total, value) => total + value, 0);
  quarters.push(annual - firstThree);
  return ok(quarters);
}