《独立开发者的商业指南·收入与财务工程》10.2 月度关账流程

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

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

export type FlowCategory =
  | "revenue"
  | "variable_cost"
  | "operating_expense"
  | "salary"
  | "tax"
  | "deferred_revenue"
  | "receivable"
  | "other";

export const FLOW_CATEGORIES: FlowCategory[] = [
  "revenue",
  "variable_cost",
  "operating_expense",
  "salary",
  "tax",
  "deferred_revenue",
  "receivable",
  "other",
];

export type BankFlow = {
  id: string;
  category: FlowCategory;
  amount: Cents;
};

export type FlowSummary = {
  byCategory: Record<FlowCategory, Cents>;
  inflow: Cents;
  outflow: Cents;
  net: Cents;
};

/**
 * Classifies bank flows before any accrual. The net is the change the bank
 * statement shows; the category totals are what the three statements consume.
 * A flow is signed: money in is positive, money out is negative.
 */
export function summarizeFlows(flows: BankFlow[]): Result<FlowSummary> {
  if (!Array.isArray(flows)) {
    return fail("flows must be an array");
  }
  const byCategory: Record<FlowCategory, Cents> = {
    revenue: 0,
    variable_cost: 0,
    operating_expense: 0,
    salary: 0,
    tax: 0,
    deferred_revenue: 0,
    receivable: 0,
    other: 0,
  };
  for (const flow of flows) {
    if (!flow || typeof flow.id !== "string" || flow.id.trim().length === 0) {
      return fail("every flow needs an id");
    }
    if (!FLOW_CATEGORIES.includes(flow.category)) {
      return fail(`unknown flow category: ${flow.category}`);
    }
    if (!Number.isInteger(flow.amount)) {
      return fail("flow amounts must be integer cents");
    }
    byCategory[flow.category] += flow.amount;
  }
  const inflow = flows
    .filter((flow) => flow.amount > 0)
    .reduce((total, flow) => total + flow.amount, 0);
  const outflow = flows
    .filter((flow) => flow.amount < 0)
    .reduce((total, flow) => total + flow.amount, 0);
  return ok({ byCategory, inflow, outflow, net: inflow + outflow });
}

export type CloseInput = {
  cashOpening: Cents;
  cashClosing: Cents;
  operatingCashFlow: Cents;
  investingCashFlow: Cents;
  financingCashFlow: Cents;
  revenue: Cents;
  expenses: Cents;
  cashCollected: Cents;
  receivableChange: Cents;
  deferredRevenueChange: Cents;
  taxRateBps: Bps;
  taxAccrued: Cents;
  equityOpening: Cents;
  equityClosing: Cents;
  dividends: Cents;
  assets: Cents;
  liabilities: Cents;
};

export type CloseCheck = {
  name: string;
  passed: boolean;
  difference: Cents;
};

export type CloseReport = {
  checks: CloseCheck[];
  passed: boolean;
  failed: string[];
};

function checkInput(input: CloseInput): string | null {
  const integers: Array<[string, number]> = [
    ["cash opening", input.cashOpening],
    ["cash closing", input.cashClosing],
    ["operating cash flow", input.operatingCashFlow],
    ["investing cash flow", input.investingCashFlow],
    ["financing cash flow", input.financingCashFlow],
    ["revenue", input.revenue],
    ["expenses", input.expenses],
    ["cash collected", input.cashCollected],
    ["receivable change", input.receivableChange],
    ["deferred revenue change", input.deferredRevenueChange],
    ["tax accrued", input.taxAccrued],
    ["equity opening", input.equityOpening],
    ["equity closing", input.equityClosing],
    ["dividends", input.dividends],
    ["assets", input.assets],
    ["liabilities", input.liabilities],
  ];
  for (const [name, value] of integers) {
    if (!Number.isInteger(value)) {
      return `${name} must be an integer number of cents`;
    }
  }
  const nonNegative: Array<[string, number]> = [
    ["cash opening", input.cashOpening],
    ["cash closing", input.cashClosing],
    ["revenue", input.revenue],
    ["expenses", input.expenses],
    ["cash collected", input.cashCollected],
    ["tax accrued", input.taxAccrued],
    ["equity opening", input.equityOpening],
    ["equity closing", input.equityClosing],
    ["dividends", input.dividends],
    ["assets", input.assets],
    ["liabilities", input.liabilities],
  ];
  for (const [name, value] of nonNegative) {
    if (value < 0) {
      return `${name} must not be negative`;
    }
  }
  if (!Number.isInteger(input.taxRateBps) || input.taxRateBps < 0 || input.taxRateBps > 10000) {
    return "tax rate must be between zero and 10000 bps";
  }
  return null;
}

function makeCheck(name: string, difference: Cents): CloseCheck {
  return { name, passed: difference === 0, difference };
}

/**
 * Five tie-outs, in the order a close should run:
 *   1. cash roll: opening + operating + investing + financing = closing
 *   2. revenue tie: cash collected + receivable increase - deferred increase
 *   3. tax tie: accrued tax equals the rate applied to positive pretax income
 *   4. equity roll: opening equity + net income - dividends = closing equity
 *   5. balance sheet: assets = liabilities + closing equity
 * A non-zero difference is kept, not rounded away; the sign says which side is
 * higher, which is often enough to find the missing entry.
 */
export function reconcileClose(input: CloseInput): Result<CloseReport> {
  const inputError = checkInput(input);
  if (inputError) {
    return fail(inputError);
  }
  const cashExpected =
    input.cashOpening +
    input.operatingCashFlow +
    input.investingCashFlow +
    input.financingCashFlow;
  const revenueExpected =
    input.cashCollected + input.receivableChange - input.deferredRevenueChange;
  const pretax = input.revenue - input.expenses;
  const taxExpected = pretax > 0 ? applyRate(pretax, input.taxRateBps) : 0;
  const netIncome = pretax - input.taxAccrued;
  const equityExpected =
    input.equityOpening + netIncome - input.dividends;
  const checks: CloseCheck[] = [
    makeCheck("cash_roll", input.cashClosing - cashExpected),
    makeCheck("revenue_tie", input.revenue - revenueExpected),
    makeCheck("tax_tie", input.taxAccrued - taxExpected),
    makeCheck("equity_roll", input.equityClosing - equityExpected),
    makeCheck(
      "balance_sheet",
      input.assets - (input.liabilities + input.equityClosing),
    ),
  ];
  const failed = checks
    .filter((check) => !check.passed)
    .map((check) => check.name);
  return ok({ checks, passed: failed.length === 0, failed });
}