《独立开发者的商业指南·合同、应收与风险》5.3 证据链与止损

继续服务 = 540.60 + 1,836 − 713.75 = 1,662.85

停工 = 450.50 + 3,052.35 − 499.62 = 3,003.23

// file: src/contract/evidence.ts
// tier: L1
// verify: node --test test/contract/evidence.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 EvidenceItem = {
  name: string;
  weightBps: Bps;
  present: boolean;
};

export type EvidenceAssessment = {
  scoreBps: Bps;
  strength: "weak" | "moderate" | "strong";
  missing: string[];
};

export type StopLossInput = {
  overdueCents: Cents;
  monthlyHours: number;
  hourlyRateCents: Cents;
  horizonMonths: number;
  deliveryCostBps: Bps;
  existingContinueBps: Bps;
  existingStopBps: Bps;
  continueCollectionBps: Bps;
  redeployBillableBps: Bps;
  redeployCollectionBps: Bps;
};

export type StopLossResult = {
  continueNetCents: Cents;
  stopNetCents: Cents;
  differenceCents: Cents;
  newBillingCents: Cents;
  redeployedBillingCents: Cents;
};

function checkAmount(value: Cents, label: string): Result<true> {
  if (!Number.isInteger(value) || value < 0) {
    return fail(`${label} must be a non-negative integer amount in cents`);
  }
  return ok(true);
}

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

/**
 * Evidence is scored by the share of the claim each item supports. The
 * weights are teaching assumptions; what matters is that a missing change
 * order or acceptance record is visible as a hole, not discovered after the
 * demand letter is sent. A strong file does not guarantee recovery, but a
 * weak file changes which procedures are worth paying for.
 */
export function assessEvidence(items: EvidenceItem[]): Result<EvidenceAssessment> {
  if (items.length === 0) {
    return fail("at least one evidence item is required");
  }
  let scoreBps = 0;
  const missing: string[] = [];
  for (const item of items) {
    if (item.name.trim() === "") {
      return fail("evidence name cannot be empty");
    }
    const weight = checkRate(item.weightBps, `${item.name} weight`);
    if (!weight.ok) {
      return weight;
    }
    if (item.present) {
      scoreBps += item.weightBps;
    } else {
      missing.push(item.name);
    }
  }
  scoreBps = Math.min(10000, scoreBps);
  const strength =
    scoreBps >= 8000 ? "strong" : scoreBps >= 5000 ? "moderate" : "weak";
  return ok({ scoreBps, strength, missing });
}

/**
 * Continuing to serve a payer who is already overdue adds new billing and new
 * delivery cost. Stopping frees the hours for other work but lowers the
 * expected recovery on the old balance. Comparing the two over the same
 * horizon turns "when do we stop?" into a cash number.
 */
export function compareStopLoss(input: StopLossInput): Result<StopLossResult> {
  const overdue = checkAmount(input.overdueCents, "overdue balance");
  if (!overdue.ok) {
    return overdue;
  }
  if (!Number.isFinite(input.monthlyHours) || input.monthlyHours <= 0) {
    return fail("monthly hours must be greater than zero");
  }
  if (!Number.isInteger(input.hourlyRateCents) || input.hourlyRateCents <= 0) {
    return fail("hourly rate must be a positive integer amount in cents");
  }
  if (!Number.isFinite(input.horizonMonths) || input.horizonMonths <= 0) {
    return fail("horizon months must be greater than zero");
  }
  const rates: Array<[number, string]> = [
    [input.deliveryCostBps, "delivery cost rate"],
    [input.existingContinueBps, "existing continue rate"],
    [input.existingStopBps, "existing stop rate"],
    [input.continueCollectionBps, "continue collection rate"],
    [input.redeployBillableBps, "redeploy billable rate"],
    [input.redeployCollectionBps, "redeploy collection rate"],
  ];
  for (const [value, label] of rates) {
    const checked = checkRate(value, label);
    if (!checked.ok) {
      return checked;
    }
  }

  const newBillingCents = Math.round(
    input.monthlyHours * input.horizonMonths * input.hourlyRateCents,
  );
  const continueDeliveryCents = applyRate(
    newBillingCents,
    input.deliveryCostBps,
  );
  const continueNetCents =
    applyRate(input.overdueCents, input.existingContinueBps) +
    applyRate(newBillingCents, input.continueCollectionBps) -
    continueDeliveryCents;

  const freedHours = input.monthlyHours * input.horizonMonths;
  const redeployedHours =
    (freedHours * input.redeployBillableBps) / 10000;
  const redeployedBillingCents = Math.round(
    redeployedHours * input.hourlyRateCents,
  );
  const redeployedDeliveryCents = applyRate(
    redeployedBillingCents,
    input.deliveryCostBps,
  );
  const stopNetCents =
    applyRate(input.overdueCents, input.existingStopBps) +
    applyRate(redeployedBillingCents, input.redeployCollectionBps) -
    redeployedDeliveryCents;

  return ok({
    continueNetCents,
    stopNetCents,
    differenceCents: stopNetCents - continueNetCents,
    newBillingCents,
    redeployedBillingCents,
  });
}