《独立开发者的商业指南·收入与财务工程》10.1 五个核心指标与口径

// file: src/fin/dashboard.ts
// tier: L1
// verify: node --test test/fin/dashboard.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 Status = "green" | "amber" | "red";

export type MetricKey =
  | "mrr_growth"
  | "gross_margin"
  | "sde_rate"
  | "cash_conversion"
  | "runway";

export type MetricReading = {
  key: MetricKey;
  label: string;
  value: number | null;
  unit: "bps" | "months";
  status: Status;
};

export type DashboardInput = {
  mrr: Cents;
  priorMrr: Cents | null;
  nrrBps?: Bps;
  grossMarginBps: Bps;
  priorGrossMarginBps: Bps;
  sde: Cents;
  revenue: Cents;
  operatingCashFlow: Cents;
  netIncome: Cents;
  cash: Cents;
  monthlyFixedCosts: Cents;
};

/** Teaching thresholds, not industry standards. Change them in one place. */
export const LIMITS = {
  mrrGreen: 100,
  mrrRed: -100,
  nrrGreen: 10000,
  nrrRed: 9500,
  marginGreen: 7500,
  marginRed: 6500,
  marginDropAmber: 300,
  marginDropRed: 500,
  sdeGreen: 4000,
  sdeRed: 2500,
  cashGreen: 8000,
  cashRed: 5000,
  runwayGreen: 6,
  runwayRed: 3,
} as const;

export type Dashboard = {
  readings: MetricReading[];
  green: number;
  amber: number;
  red: number;
  overall: Status;
};

function highStatus(value: number, green: number, red: number): Status {
  if (value >= green) return "green";
  if (value < red) return "red";
  return "amber";
}

function checkInput(input: DashboardInput): string | null {
  if (!Number.isInteger(input.mrr) || input.mrr < 0) {
    return "mrr must be a non-negative integer";
  }
  if (
    input.priorMrr !== null &&
    (!Number.isInteger(input.priorMrr) || input.priorMrr <= 0)
  ) {
    return "prior mrr must be null or a positive integer";
  }
  if (
    input.nrrBps !== undefined &&
    (!Number.isInteger(input.nrrBps) ||
      input.nrrBps < 0 ||
      input.nrrBps > 30000)
  ) {
    return "nrr must be between zero and 30000 bps";
  }
  if (
    !Number.isInteger(input.grossMarginBps) ||
    input.grossMarginBps < 0 ||
    input.grossMarginBps > 10000 ||
    !Number.isInteger(input.priorGrossMarginBps) ||
    input.priorGrossMarginBps < 0 ||
    input.priorGrossMarginBps > 10000
  ) {
    return "gross margins must be between zero and 10000 bps";
  }
  if (
    !Number.isInteger(input.sde) ||
    !Number.isInteger(input.revenue) ||
    input.revenue < 0 ||
    !Number.isInteger(input.operatingCashFlow) ||
    !Number.isInteger(input.netIncome)
  ) {
    return "sde, revenue, cash flow and net income must be integer cents";
  }
  if (!Number.isInteger(input.cash) || input.cash < 0) {
    return "cash must be a non-negative integer";
  }
  if (!Number.isInteger(input.monthlyFixedCosts) || input.monthlyFixedCosts <= 0) {
    return "monthly fixed costs must be a positive integer";
  }
  return null;
}

function mrrReading(input: DashboardInput): MetricReading {
  if (input.priorMrr === null) {
    return {
      key: "mrr_growth",
      label: "MRR 净变化",
      value: null,
      unit: "bps",
      status: "amber",
    };
  }
  const value = divide(input.mrr - input.priorMrr, input.priorMrr);
  let status: Status;
  if (
    value >= LIMITS.mrrGreen &&
    (input.nrrBps === undefined || input.nrrBps >= LIMITS.nrrGreen)
  ) {
    status = "green";
  } else if (
    value < LIMITS.mrrRed ||
    (input.nrrBps !== undefined && input.nrrBps < LIMITS.nrrRed)
  ) {
    status = "red";
  } else {
    status = "amber";
  }
  return { key: "mrr_growth", label: "MRR 净变化", value, unit: "bps", status };
}

function grossMarginReading(input: DashboardInput): MetricReading {
  let status = highStatus(
    input.grossMarginBps,
    LIMITS.marginGreen,
    LIMITS.marginRed,
  );
  const drop = input.priorGrossMarginBps - input.grossMarginBps;
  if (status === "green" && drop >= LIMITS.marginDropAmber) status = "amber";
  if (drop >= LIMITS.marginDropRed) status = "red";
  return {
    key: "gross_margin",
    label: "毛利率",
    value: input.grossMarginBps,
    unit: "bps",
    status,
  };
}

function sdeRateReading(input: DashboardInput): MetricReading {
  const value = divide(input.sde, input.revenue);
  return {
    key: "sde_rate",
    label: "SDE 率",
    value,
    unit: "bps",
    status: highStatus(value, LIMITS.sdeGreen, LIMITS.sdeRed),
  };
}

function cashConversionReading(input: DashboardInput): MetricReading {
  if (input.netIncome <= 0) {
    return {
      key: "cash_conversion",
      label: "现金转换率",
      value: null,
      unit: "bps",
      status: input.operatingCashFlow >= 0 ? "amber" : "red",
    };
  }
  const value = divide(input.operatingCashFlow, input.netIncome);
  return {
    key: "cash_conversion",
    label: "现金转换率",
    value,
    unit: "bps",
    status: highStatus(value, LIMITS.cashGreen, LIMITS.cashRed),
  };
}

function runwayReading(input: DashboardInput): MetricReading {
  const value = Math.round((input.cash / input.monthlyFixedCosts) * 10) / 10;
  return {
    key: "runway",
    label: "零收入 runway",
    value,
    unit: "months",
    status: highStatus(value, LIMITS.runwayGreen, LIMITS.runwayRed),
  };
}

/**
 * One red tile turns the whole month red. A five-tile dashboard is a short
 * priority list, not an average score.
 */
export function buildDashboard(input: DashboardInput): Result<Dashboard> {
  const inputError = checkInput(input);
  if (inputError) return fail(inputError);
  const readings = [
    mrrReading(input),
    grossMarginReading(input),
    sdeRateReading(input),
    cashConversionReading(input),
    runwayReading(input),
  ];
  const green = readings.filter((r) => r.status === "green").length;
  const amber = readings.filter((r) => r.status === "amber").length;
  const red = readings.filter((r) => r.status === "red").length;
  const overall: Status = red > 0 ? "red" : amber > 0 ? "amber" : "green";
  return ok({ readings, green, amber, red, overall });
}