《独立开发者的商业指南·收入与财务工程》2.3 单位经济失效的五个信号

// file: src/unit/signals.ts
// tier: L1
// verify: node --test test/unit/signals.test.ts

import { type Cents } from "../core/money.ts";
import { type Bps } from "../core/rate.ts";

export type SignalId =
  | "gross-margin"
  | "ltv-cac"
  | "payback"
  | "churn"
  | "grr";

export type SignalStatus = "ok" | "watch" | "fail" | "unknown";

export type Signal = {
  id: SignalId;
  label: string;
  status: SignalStatus;
  value: number | null;
  unit: "bps" | "months" | "ratio";
  threshold: string;
  note: string;
};

export type SignalInput = {
  grossMarginBps?: Bps;
  ltvCents?: Cents;
  cacCents?: Cents;
  paybackMonths?: number;
  monthlyChurnBps?: Bps;
  grrBps?: Bps;
};

export type SignalVerdict = "healthy" | "watch" | "fail" | "incomplete";

export type SignalReport = {
  signals: Signal[];
  counts: { ok: number; watch: number; fail: number; unknown: number };
  verdict: SignalVerdict;
};

function missing(
  id: SignalId,
  label: string,
  unit: Signal["unit"],
  threshold: string,
): Signal {
  return {
    id,
    label,
    status: "unknown",
    value: null,
    unit,
    threshold,
    note: "输入不足，无法判定",
  };
}

export function checkGrossMargin(grossMarginBps?: Bps): Signal {
  const threshold = "ok >= 75.0%；watch 60.0%–74.9%；fail < 60.0%";
  if (
    grossMarginBps === undefined ||
    !Number.isInteger(grossMarginBps) ||
    grossMarginBps < 0 ||
    grossMarginBps > 10000
  ) {
    return missing("gross-margin", "毛利率", "bps", threshold);
  }
  let status: SignalStatus = "ok";
  if (grossMarginBps < 6000) {
    status = "fail";
  } else if (grossMarginBps < 7500) {
    status = "watch";
  }
  return {
    id: "gross-margin",
    label: "毛利率",
    status,
    value: grossMarginBps,
    unit: "bps",
    threshold,
    note:
      status === "ok"
        ? "毛利足以覆盖获客与运营"
        : "毛利偏薄，先检查变动成本口径",
  };
}

export function checkLtvCac(
  ltvCents?: Cents,
  cacCents?: Cents,
): Signal {
  const threshold = "ok >= 3.0x；watch 1.0x–2.9x；fail < 1.0x";
  if (
    ltvCents === undefined ||
    cacCents === undefined ||
    !Number.isInteger(ltvCents) ||
    ltvCents < 0 ||
    !Number.isInteger(cacCents) ||
    cacCents <= 0
  ) {
    return missing("ltv-cac", "LTV / CAC", "ratio", threshold);
  }
  const value = Math.round((ltvCents / cacCents) * 100) / 100;
  let status: SignalStatus = "ok";
  if (value < 1) {
    status = "fail";
  } else if (value < 3) {
    status = "watch";
  }
  return {
    id: "ltv-cac",
    label: "LTV / CAC",
    status,
    value,
    unit: "ratio",
    threshold,
    note:
      status === "ok"
        ? "获客投入有足够的毛利回收空间"
        : "获客回报偏薄，需检查 LTV 口径",
  };
}

export function checkPayback(payback?: number): Signal {
  const threshold = "ok <= 12 个月；watch 12.1–18 个月；fail > 18 个月";
  if (
    payback === undefined ||
    !Number.isFinite(payback) ||
    payback < 0
  ) {
    return missing("payback", "CAC 回本期", "months", threshold);
  }
  let status: SignalStatus = "ok";
  if (payback > 18) {
    status = "fail";
  } else if (payback > 12) {
    status = "watch";
  }
  return {
    id: "payback",
    label: "CAC 回本期",
    status,
    value: payback,
    unit: "months",
    threshold,
    note:
      status === "ok"
        ? "获客成本可在一年内由毛利收回"
        : "回本慢于一年，增长会先消耗现金",
  };
}

export function checkChurn(monthlyChurnBps?: Bps): Signal {
  const threshold = "ok <= 3.0%/月；watch 3.1%–5.0%/月；fail > 5.0%/月";
  if (
    monthlyChurnBps === undefined ||
    !Number.isInteger(monthlyChurnBps) ||
    monthlyChurnBps < 0 ||
    monthlyChurnBps > 10000
  ) {
    return missing("churn", "月流失率", "bps", threshold);
  }
  let status: SignalStatus = "ok";
  if (monthlyChurnBps > 500) {
    status = "fail";
  } else if (monthlyChurnBps > 300) {
    status = "watch";
  }
  return {
    id: "churn",
    label: "月流失率",
    status,
    value: monthlyChurnBps,
    unit: "bps",
    threshold,
    note:
      status === "ok"
        ? "流失速度在可管理范围"
        : "流失偏快，LTV 会被显著压缩",
  };
}

export function checkGrr(grrBps?: Bps): Signal {
  const threshold = "ok >= 85.0%；watch 80.0%–84.9%；fail < 80.0%";
  if (
    grrBps === undefined ||
    !Number.isInteger(grrBps) ||
    grrBps < 0 ||
    grrBps > 20000
  ) {
    return missing("grr", "毛利留存率 GRR", "bps", threshold);
  }
  let status: SignalStatus = "ok";
  if (grrBps < 8000) {
    status = "fail";
  } else if (grrBps < 8500) {
    status = "watch";
  }
  return {
    id: "grr",
    label: "毛利留存率 GRR",
    status,
    value: grrBps,
    unit: "bps",
    threshold,
    note:
      status === "ok"
        ? "存量收入漏损可控"
        : "存量收入漏损偏高，需看扩张是否掩盖了流失",
  };
}

/** Run all five checks and return a structured verdict. */
export function evaluateSignals(input: SignalInput): SignalReport {
  const signals = [
    checkGrossMargin(input.grossMarginBps),
    checkLtvCac(input.ltvCents, input.cacCents),
    checkPayback(input.paybackMonths),
    checkChurn(input.monthlyChurnBps),
    checkGrr(input.grrBps),
  ];
  const counts = { ok: 0, watch: 0, fail: 0, unknown: 0 };
  for (const signal of signals) {
    counts[signal.status] += 1;
  }
  let verdict: SignalVerdict = "healthy";
  if (counts.fail > 0) {
    verdict = "fail";
  } else if (counts.watch > 0) {
    verdict = "watch";
  } else if (counts.unknown > 0) {
    verdict = "incomplete";
  }
  return { signals, counts, verdict };
}