《独立开发者的商业指南·合同、应收与风险》4.1 坏账准备：计提、核销与转回

逾期 30 天以上 = 12,000 × 6% = 720
坏账准备       = 12,000 × 1% = 120
净应收         = 12,000 − 120 = 11,880

应提准备 = Σ(各档余额 × 各档损失率)
本期计提 = 应提准备 − 期初准备余额

逾期 30 天以上 = 11,264 × 8% = 901
坏账准备       = 11,264 × 2% = 225
净应收         = 11,264 − 225 = 11,039

借：现金 60
贷：收回已核销坏账 60

// file: src/contract/bad-debt.ts
// tier: L1
// verify: node --test test/contract/bad-debt.test.ts

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

export type AgingBucket = {
  label: string;
  balanceCents: Cents;
  lossRateBps: Bps;
};

export type BucketProvision = {
  label: string;
  balanceCents: Cents;
  lossRateBps: Bps;
  provisionCents: Cents;
};

export type ProvisionResult = {
  totalCents: Cents;
  requiredAllowanceCents: Cents;
  existingAllowanceCents: Cents;
  provisionExpenseCents: Cents;
  netReceivablesCents: Cents;
  byBucket: BucketProvision[];
};

export type WriteOffResult = {
  receivablesCents: Cents;
  allowanceCents: Cents;
  writeOffCents: Cents;
  additionalProvisionCents: Cents;
};

export type RecoveryResult = {
  recoveredCents: Cents;
  reversalIncomeCents: Cents;
  remainingWrittenOffCents: Cents;
};

function checkNonNegative(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);
}

/**
 * Provision is an income-statement expense: it raises a contra-asset
 * allowance without removing the receivable. A negative expense is a
 * reversal and appears when the required allowance falls below the balance
 * already booked.
 */
export function provisionByAging(
  buckets: AgingBucket[],
  existingAllowanceCents: Cents = 0,
): Result<ProvisionResult> {
  if (buckets.length === 0) {
    return fail("at least one aging bucket is required");
  }
  const existing = checkNonNegative(existingAllowanceCents, "existing allowance");
  if (!existing.ok) {
    return existing;
  }
  const byBucket: BucketProvision[] = [];
  let totalCents = 0;
  let requiredAllowanceCents = 0;
  for (const bucket of buckets) {
    if (bucket.label.trim() === "") {
      return fail("bucket label cannot be empty");
    }
    const balance = checkNonNegative(bucket.balanceCents, `${bucket.label} balance`);
    if (!balance.ok) {
      return balance;
    }
    const rate = checkRate(bucket.lossRateBps, `${bucket.label} loss rate`);
    if (!rate.ok) {
      return rate;
    }
    const provisionCents = applyRate(bucket.balanceCents, bucket.lossRateBps);
    totalCents = add(totalCents, bucket.balanceCents);
    requiredAllowanceCents = add(requiredAllowanceCents, provisionCents);
    byBucket.push({
      label: bucket.label,
      balanceCents: bucket.balanceCents,
      lossRateBps: bucket.lossRateBps,
      provisionCents,
    });
  }
  return ok({
    totalCents,
    requiredAllowanceCents,
    existingAllowanceCents,
    provisionExpenseCents: sub(requiredAllowanceCents, existingAllowanceCents),
    netReceivablesCents: sub(totalCents, requiredAllowanceCents),
    byBucket,
  });
}

/**
 * Write-off is a balance-sheet event: receivables and the allowance fall by
 * the same amount. If the allowance is too small, the shortfall is booked as
 * an additional provision first, so profit takes the hit before the asset
 * disappears. With an adequate allowance, net receivables do not move.
 */
export function writeOff(input: {
  receivablesCents: Cents;
  allowanceCents: Cents;
  writeOffCents: Cents;
}): Result<WriteOffResult> {
  const receivables = checkNonNegative(input.receivablesCents, "receivables");
  if (!receivables.ok) {
    return receivables;
  }
  const allowance = checkNonNegative(input.allowanceCents, "allowance");
  if (!allowance.ok) {
    return allowance;
  }
  const amount = checkNonNegative(input.writeOffCents, "write-off amount");
  if (!amount.ok) {
    return amount;
  }
  if (input.writeOffCents === 0) {
    return fail("write-off amount must be greater than zero");
  }
  if (input.writeOffCents > input.receivablesCents) {
    return fail("write-off cannot exceed receivables");
  }
  const additionalProvisionCents = Math.max(
    0,
    sub(input.writeOffCents, input.allowanceCents),
  );
  const fundedAllowance = add(input.allowanceCents, additionalProvisionCents);
  return ok({
    receivablesCents: sub(input.receivablesCents, input.writeOffCents),
    allowanceCents: sub(fundedAllowance, input.writeOffCents),
    writeOffCents: input.writeOffCents,
    additionalProvisionCents,
  });
}

/**
 * A recovery after write-off is not a new receivable. Cash arrives and the
 * earlier write-off is reversed through income; the receivable stays off the
 * books so the same balance cannot be collected twice.
 */
export function recoverWrittenOff(input: {
  writtenOffCents: Cents;
  recoveredCents: Cents;
}): Result<RecoveryResult> {
  const writtenOff = checkNonNegative(input.writtenOffCents, "written-off amount");
  if (!writtenOff.ok) {
    return writtenOff;
  }
  const recovered = checkNonNegative(input.recoveredCents, "recovered amount");
  if (!recovered.ok) {
    return recovered;
  }
  if (input.recoveredCents === 0) {
    return fail("recovered amount must be greater than zero");
  }
  if (input.recoveredCents > input.writtenOffCents) {
    return fail("recovery cannot exceed the written-off amount");
  }
  return ok({
    recoveredCents: input.recoveredCents,
    reversalIncomeCents: input.recoveredCents,
    remainingWrittenOffCents: sub(input.writtenOffCents, input.recoveredCents),
  });
}