《独立开发者的商业指南·合同、应收与风险》1.3 价格、调价与付款条款：金额、时点、前提与违约责任

// file: src/contract/payment-terms.ts
// tier: L1
// verify: node --test test/contract/payment-terms.test.ts

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

export type Precondition = "invoice" | "delivery" | "acceptance" | "milestone";

export const PRECONDITIONS: Precondition[] = [
  "invoice",
  "delivery",
  "acceptance",
  "milestone",
];

export type PaymentTerm = {
  amountCents: Cents;
  netDays: number;
  precondition: Precondition;
  lateFeeBpsPerMonth: Bps;
};

export type TermAssessment = {
  amountCents: Cents;
  netDays: number;
  precondition: Precondition;
  lateFeeBpsPerMonth: Bps;
  dueOffsetDays: number;
  lateFeePer30DaysCents: Cents;
};

export type CashClock = {
  precondition: Precondition;
  appliedAcceptanceDays: number;
  netDays: number;
  totalDays: number;
};

export type NetTermRow = {
  netDays: number;
  balanceCents: Cents;
  shareOfRevenueBps: Bps;
};

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

/**
 * Validate the four elements of a payment term. The amount is always gross
 * of tax; currency and tax treatment belong in the contract text, not in
 * this arithmetic model.
 */
export function assessPaymentTerm(
  term: PaymentTerm,
): Result<TermAssessment> {
  if (!Number.isInteger(term.amountCents) || term.amountCents <= 0) {
    return fail("amount must be a positive integer amount in cents");
  }
  if (
    !Number.isInteger(term.netDays) ||
    term.netDays < 0 ||
    term.netDays > 365
  ) {
    return fail("net days must be an integer between 0 and 365");
  }
  if (!PRECONDITIONS.includes(term.precondition)) {
    return fail(`unknown precondition: ${term.precondition}`);
  }
  if (!isBps(term.lateFeeBpsPerMonth)) {
    return fail("late fee must be between 0 and 10000 bps per month");
  }
  return ok({
    amountCents: term.amountCents,
    netDays: term.netDays,
    precondition: term.precondition,
    lateFeeBpsPerMonth: term.lateFeeBpsPerMonth,
    dueOffsetDays: term.netDays,
    lateFeePer30DaysCents: applyRate(
      term.amountCents,
      term.lateFeeBpsPerMonth,
    ),
  });
}

/**
 * The cash clock starts when the precondition is met. For an acceptance-based
 * term, the acceptance wait is added before the net days; for invoice and
 * delivery terms the net days are the whole clock.
 */
export function cashClock(
  term: PaymentTerm,
  acceptanceDays: number,
): Result<CashClock> {
  const checked = assessPaymentTerm(term);
  if (!checked.ok) {
    return checked;
  }
  if (!Number.isInteger(acceptanceDays) || acceptanceDays < 0 || acceptanceDays > 365) {
    return fail("acceptance days must be an integer between 0 and 365");
  }
  const appliedAcceptanceDays =
    term.precondition === "acceptance" ? acceptanceDays : 0;
  return ok({
    precondition: term.precondition,
    appliedAcceptanceDays,
    netDays: term.netDays,
    totalDays: appliedAcceptanceDays + term.netDays,
  });
}

/**
 * A contractual net term translated into a static receivable balance:
 * annual revenue x net days / 365. This is the balance the business would
 * carry if every invoice took exactly the stated term to collect.
 */
export function netTermTable(
  annualRevenueCents: Cents,
  netDaysList: number[],
): Result<NetTermRow[]> {
  if (!Number.isInteger(annualRevenueCents) || annualRevenueCents <= 0) {
    return fail("annual revenue must be a positive integer amount in cents");
  }
  if (netDaysList.length === 0) {
    return fail("net term list must not be empty");
  }
  const seen = new Set<number>();
  const rows: NetTermRow[] = [];
  for (const netDays of netDaysList) {
    if (!Number.isInteger(netDays) || netDays < 0 || netDays > 365) {
      return fail("each net term must be an integer between 0 and 365");
    }
    if (seen.has(netDays)) {
      return fail(`duplicate net term: ${netDays}`);
    }
    seen.add(netDays);
    const balanceCents = Math.round((annualRevenueCents * netDays) / 365);
    rows.push({
      netDays,
      balanceCents,
      shareOfRevenueBps: divide(balanceCents, annualRevenueCents),
    });
  }
  return ok(rows);
}

/** Days sales outstanding: receivables / annual revenue x 365. */
export function dsoDays(
  receivableCents: Cents,
  annualRevenueCents: Cents,
): Result<number> {
  if (!Number.isInteger(receivableCents) || receivableCents < 0) {
    return fail("receivable must be a non-negative integer amount in cents");
  }
  if (!Number.isInteger(annualRevenueCents) || annualRevenueCents <= 0) {
    return fail("annual revenue must be a positive integer amount in cents");
  }
  return ok(Math.round((receivableCents * 365) / annualRevenueCents));
}

/** Positive means actual collection is slower than the stated net term. */
export function dsoGapDays(
  actualDsoDays: number,
  netDays: number,
): Result<number> {
  if (!Number.isInteger(actualDsoDays) || actualDsoDays < 0) {
    return fail("actual DSO must be a non-negative integer");
  }
  if (!Number.isInteger(netDays) || netDays < 0) {
    return fail("net days must be a non-negative integer");
  }
  return ok(actualDsoDays - netDays);
}

/**
 * Simple, pro-rata late fee: amount x monthly rate x days late / 30. The
 * contract must state whether the fee is simple or compounding; this helper
 * only covers the simple case.
 */
export function lateFeeCents(
  amountCents: Cents,
  lateFeeBpsPerMonth: Bps,
  daysLate: number,
): Result<Cents> {
  if (!Number.isInteger(amountCents) || amountCents <= 0) {
    return fail("amount must be a positive integer amount in cents");
  }
  if (!isBps(lateFeeBpsPerMonth)) {
    return fail("late fee must be between 0 and 10000 bps per month");
  }
  if (!Number.isInteger(daysLate) || daysLate < 0) {
    return fail("days late must be a non-negative integer");
  }
  return ok(
    Math.round((amountCents * lateFeeBpsPerMonth * daysLate) / 300000),
  );
}