《独立开发者的商业指南·收入与财务工程》4.2 收入质量：集中度、续费、退款

总分 = (3000 × 集中度 + 3000 × 留存 + 2000 × 退款 + 2000 × 经常性) ÷ 10000

年化留存率 = (1 − 月流失率)^12

年化留存 = (1 − 0.015)^12 = 83.41%
年化流失 = 1 − 83.41% = 16.59%，与事实表的「年流失约 16.6%」一致

产品年化留存 = (1 − 0.03)^12 = 69.38%

混合留存 = 72.7% × 70.0% + 27.3% × 69.38%
         = 50.89% + 18.94%
         = 69.83%

LedgerLite = 130,240 ÷ 240,240 = 54.2%
Tidecast   = 121,171 ÷ 138,171 = 87.7%
Nord       = 34,320 ÷ 154,320 = 22.2%

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

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

export type QualityWeights = {
  concentration: Bps;
  retention: Bps;
  refund: Bps;
  recurring: Bps;
};

export const DEFAULT_QUALITY_WEIGHTS: QualityWeights = {
  concentration: 3000,
  retention: 3000,
  refund: 2000,
  recurring: 2000,
};

export type RetentionInput =
  | { kind: "monthly-churn"; monthlyChurnBps: Bps }
  | { kind: "annual-renewal"; annualRetentionBps: Bps }
  | { kind: "none" };

export type QualityInput = {
  label: string;
  /** Largest known single customer or channel share, in basis points. */
  topExposureBps: Bps;
  retention: RetentionInput;
  refundRateBps: Bps;
  recurringShareBps: Bps;
  /** True when the refund rate is a teaching assumption, not a fact-table value. */
  refundAssumed?: boolean;
  assumptions?: string[];
};

export type QualityComponents = {
  concentration: Bps;
  retention: Bps;
  refund: Bps;
  recurring: Bps;
};

export type QualityScore = {
  label: string;
  components: QualityComponents;
  total: Bps;
  assumptions: string[];
};

export type QualityBand = "strong" | "mixed" | "weak";

function checkRate(value: Bps, label: string): string | null {
  if (!Number.isInteger(value) || value < 0 || value > 10000) {
    return `${label} must be between 0 and 10000 bps`;
  }
  return null;
}

/** Annualized retention implied by a constant monthly churn rate. */
export function annualRetention(monthlyChurnBps: Bps): Result<Bps> {
  const error = checkRate(monthlyChurnBps, "monthly churn");
  if (error) {
    return fail(error);
  }
  const monthlyRetention = 1 - monthlyChurnBps / 10000;
  return ok(Math.round(Math.pow(monthlyRetention, 12) * 10000));
}

/** Revenue-weighted retention across lines with different share and renewal. */
export function blendRetention(
  parts: { shareBps: Bps; annualRetentionBps: Bps }[],
): Result<Bps> {
  if (parts.length === 0) {
    return fail("at least one retention part is required");
  }
  let shareTotal = 0;
  let weighted = 0;
  for (const part of parts) {
    const shareError = checkRate(part.shareBps, "share");
    if (shareError) {
      return fail(shareError);
    }
    const retentionError = checkRate(
      part.annualRetentionBps,
      "annual retention",
    );
    if (retentionError) {
      return fail(retentionError);
    }
    shareTotal += part.shareBps;
    weighted += part.shareBps * part.annualRetentionBps;
  }
  if (shareTotal !== 10000) {
    return fail(`shares must sum to 10000 bps, got ${shareTotal}`);
  }
  return ok(Math.round(weighted / 10000));
}

function resolveRetention(input: RetentionInput): Result<Bps> {
  if (input.kind === "none") {
    return ok(0);
  }
  if (input.kind === "monthly-churn") {
    return annualRetention(input.monthlyChurnBps);
  }
  const error = checkRate(input.annualRetentionBps, "annual retention");
  if (error) {
    return fail(error);
  }
  return ok(input.annualRetentionBps);
}

/**
 * Four-part revenue quality score, each part on a 0-10000 scale:
 *   concentration = 10000 - largest known exposure
 *   retention     = annualized renewal / retention rate
 *   refund        = 10000 - refund rate
 *   recurring     = recurring revenue share
 * The total is the weighted average of the four parts.
 */
export function scoreQuality(
  input: QualityInput,
  weights: QualityWeights = DEFAULT_QUALITY_WEIGHTS,
): Result<QualityScore> {
  if (input.label.trim() === "") {
    return fail("label must not be empty");
  }
  const exposureError = checkRate(input.topExposureBps, "top exposure");
  if (exposureError) {
    return fail(exposureError);
  }
  const refundError = checkRate(input.refundRateBps, "refund rate");
  if (refundError) {
    return fail(refundError);
  }
  const recurringError = checkRate(
    input.recurringShareBps,
    "recurring share",
  );
  if (recurringError) {
    return fail(recurringError);
  }
  const weightSum =
    weights.concentration + weights.retention + weights.refund +
    weights.recurring;
  if (weightSum !== 10000) {
    return fail(`weights must sum to 10000 bps, got ${weightSum}`);
  }
  const retention = resolveRetention(input.retention);
  if (!retention.ok) {
    return retention;
  }

  const components: QualityComponents = {
    concentration: 10000 - input.topExposureBps,
    retention: retention.value,
    refund: 10000 - input.refundRateBps,
    recurring: input.recurringShareBps,
  };
  const total = Math.round(
    (weights.concentration * components.concentration +
      weights.retention * components.retention +
      weights.refund * components.refund +
      weights.recurring * components.recurring) /
      10000,
  );

  const assumptions = [...(input.assumptions ?? [])];
  if (input.refundAssumed) {
    assumptions.push("refund rate is a teaching assumption");
  }
  if (input.retention.kind === "none") {
    assumptions.push("no contractual renewal: retention part scores zero");
  }
  return ok({
    label: input.label,
    components,
    total,
    assumptions,
  });
}

export function qualityBand(total: Bps): QualityBand {
  if (total >= 8000) {
    return "strong";
  }
  if (total >= 6000) {
    return "mixed";
  }
  return "weak";
}