《独立开发者的商业指南·收入与财务工程》12.3 常见红旗与提前修复

// file: src/value/red-flags.ts
// tier: L1
// verify: node --test test/value/red-flags.test.ts

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

export type RedFlagSeverity = "low" | "medium" | "high";

export type DdFacts = {
  largestCustomerShareBps: Bps;
  topThreeCustomerShareBps: Bps;
  topPlatformShareBps: Bps;
  keyPersonRevenueShareBps: Bps;
  overdueReceivableBps: Bps;
  relatedPartyCents: Cents;
  restatedPeriods: number;
  contractsAssignable: boolean;
  personalDataGaps: number;
};

export type RedFlagRule = {
  id: string;
  title: string;
  severity: (facts: DdFacts) => RedFlagSeverity;
  evaluate: (facts: DdFacts) => string | null;
  explain: (facts: DdFacts) => string;
};

export type RedFlagFinding = {
  ruleId: string;
  title: string;
  severity: RedFlagSeverity;
  evidence: string;
  explanation: string;
};

const SEVERITY_ORDER: RedFlagSeverity[] = ["low", "medium", "high"];

export const RED_FLAG_RULES: RedFlagRule[] = [
  {
    id: "customer-concentration",
    title: "revenue concentrated in a few customers",
    severity: (facts) =>
      facts.largestCustomerShareBps >= 3000 ||
      facts.topThreeCustomerShareBps >= 6000
        ? "high"
        : "medium",
    evaluate: (facts) =>
      facts.largestCustomerShareBps >= 2000 ||
      facts.topThreeCustomerShareBps >= 4000
        ? `largestCustomerShareBps=${facts.largestCustomerShareBps} (${pct(facts.largestCustomerShareBps)}), topThreeCustomerShareBps=${facts.topThreeCustomerShareBps} (${pct(facts.topThreeCustomerShareBps)})`
        : null,
    explain: () =>
      "A buyer will test renewal, termination and assignment terms before trusting next year's revenue.",
  },
  {
    id: "platform-dependence",
    title: "revenue depends on one platform",
    severity: (facts) =>
      facts.topPlatformShareBps >= 7500 ? "high" : "medium",
    evaluate: (facts) =>
      facts.topPlatformShareBps >= 5000
        ? `topPlatformShareBps=${facts.topPlatformShareBps} (${pct(facts.topPlatformShareBps)})`
        : null,
    explain: () =>
      "Platform terms, fees and reach can change unilaterally; the buyer will ask for the agreement and a migration path.",
  },
  {
    id: "key-person",
    title: "revenue follows the founder",
    severity: () => "high",
    evaluate: (facts) =>
      facts.keyPersonRevenueShareBps >= 5000
        ? `keyPersonRevenueShareBps=${facts.keyPersonRevenueShareBps} (${pct(facts.keyPersonRevenueShareBps)})`
        : null,
    explain: () =>
      "If relationships and delivery depend on one person, the buyer is buying a resigned employee, not an asset.",
  },
  {
    id: "overdue-receivables",
    title: "receivables are past due",
    severity: (facts) => {
      if (facts.overdueReceivableBps >= 2400) return "high";
      if (facts.overdueReceivableBps >= 1200) return "medium";
      return "low";
    },
    evaluate: (facts) =>
      facts.overdueReceivableBps >= 600
        ? `overdueReceivableBps=${facts.overdueReceivableBps} (${pct(facts.overdueReceivableBps)} of receivables)`
        : null,
    explain: () =>
      "Past-due invoices are a cash and quality problem at once; the buyer will re-age the ledger and may hold back cash.",
  },
  {
    id: "related-party",
    title: "transactions with related parties",
    severity: () => "high",
    evaluate: (facts) =>
      facts.relatedPartyCents > 0
        ? `relatedPartyCents=${facts.relatedPartyCents}`
        : null,
    explain: () =>
      "Related-party flows must be disclosed and normalized; undisclosed ones turn into a warranty claim.",
  },
  {
    id: "restatement",
    title: "accounting policy changed mid-period",
    severity: (facts) => (facts.restatedPeriods >= 2 ? "high" : "medium"),
    evaluate: (facts) =>
      facts.restatedPeriods > 0
        ? `restatedPeriods=${facts.restatedPeriods}`
        : null,
    explain: () =>
      "A restated period breaks comparability; the buyer will rebuild the series on one policy before pricing it.",
  },
  {
    id: "non-assignable-contracts",
    title: "customer contracts cannot be transferred",
    severity: () => "high",
    evaluate: (facts) =>
      facts.contractsAssignable ? null : "contractsAssignable=false",
    explain: () =>
      "Without assignment or change-of-control language, consent is needed customer by customer and revenue can leave at closing.",
  },
  {
    id: "personal-data-gap",
    title: "personal data handling has gaps",
    severity: (facts) => (facts.personalDataGaps >= 3 ? "high" : "medium"),
    evaluate: (facts) =>
      facts.personalDataGaps > 0
        ? `personalDataGaps=${facts.personalDataGaps}`
        : null,
    explain: () =>
      "Missing records of processing, retention or deletion turn a compliance question into an indemnity request.",
  },
];

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

function validateFacts(facts: DdFacts): Result<true> {
  const shares: Array<[string, number]> = [
    ["largestCustomerShareBps", facts.largestCustomerShareBps],
    ["topThreeCustomerShareBps", facts.topThreeCustomerShareBps],
    ["topPlatformShareBps", facts.topPlatformShareBps],
    ["keyPersonRevenueShareBps", facts.keyPersonRevenueShareBps],
    ["overdueReceivableBps", facts.overdueReceivableBps],
  ];
  for (const [name, value] of shares) {
    if (!isBps(value)) {
      return fail(`${name} must be an integer between 0 and 10000`);
    }
  }
  if (!Number.isInteger(facts.relatedPartyCents) || facts.relatedPartyCents < 0) {
    return fail("relatedPartyCents must be a non-negative integer");
  }
  if (!Number.isInteger(facts.restatedPeriods) || facts.restatedPeriods < 0) {
    return fail("restatedPeriods must be a non-negative integer");
  }
  if (!Number.isInteger(facts.personalDataGaps) || facts.personalDataGaps < 0) {
    return fail("personalDataGaps must be a non-negative integer");
  }
  return ok(true);
}

export function detectRedFlags(facts: DdFacts): Result<RedFlagFinding[]> {
  const checked = validateFacts(facts);
  if (!checked.ok) {
    return checked;
  }
  const findings: RedFlagFinding[] = [];
  for (const rule of RED_FLAG_RULES) {
    const evidence = rule.evaluate(facts);
    if (evidence === null) {
      continue;
    }
    findings.push({
      ruleId: rule.id,
      title: rule.title,
      severity: rule.severity(facts),
      evidence,
      explanation: rule.explain(facts),
    });
  }
  return ok(findings);
}

export function highestSeverity(
  findings: RedFlagFinding[],
): RedFlagSeverity | "none" {
  let highest: RedFlagSeverity | "none" = "none";
  for (const finding of findings) {
    if (
      highest === "none" ||
      SEVERITY_ORDER.indexOf(finding.severity) >
        SEVERITY_ORDER.indexOf(highest)
    ) {
      highest = finding.severity;
    }
  }
  return highest;
}