《互联网产品的 AI 架构·平台化与治理》12.2 技术债与退出条件

// file: src/gov/tech-debt.ts
// tier: L2
// verify: node --test test/gov/evolution-gov.test.ts

/** 债的类型决定退出动作，不允许只写一句“以后清理”。 */
export type DebtKind =
  | "compat-shim" | "legacy-prompt" | "duplicate-capability"
  | "deprecated-model" | "manual-workaround";

export type ExitKind = "delete-shim" | "retire-prompt" | "merge-capability" | "offboard-model";

export type EvidenceId =
  | "caller-scan" | "release-scan" | "traffic-report"
  | "migration-signoff" | "eval-regression";

export interface ExitCondition {
  kind: ExitKind;
  activeCallersMax: number;
  activeReleasesMax: number;
  trafficShareMax: number;
  /** 连续多少天没有新增使用，才算“安静”。 */
  quietDays: number;
  requiredEvidence: readonly EvidenceId[];
}

/** 接受不还的债也要记账：谁批的、为什么、年化成本、下一次复核日。 */
export interface AcceptanceRecord {
  approver: string;
  rationale: string;
  annualReviewOn: string;
  annualCarryMicros: number;
}

export type Permanence = "repayable" | "accepted" | "permanent";

export interface DebtItem {
  id: string;
  kind: DebtKind;
  capability: string;
  owner: string;
  openedOn: string;
  reviewBy: string;
  permanence: Permanence;
  /** 每月维持成本，整数微元；永久的债也要折算成月度口径。 */
  carryMicrosPerMonth: number;
  exit?: ExitCondition;
  acceptance?: AcceptanceRecord;
}

export interface DebtObservation {
  activeCallers: number; activeReleases: number; trafficShare: number;
  quietDays: number; evidence: readonly EvidenceId[]; migrationComplete: boolean;
}

export type DebtState = "payable" | "blocked" | "review-overdue" | "accepted" | "invalid";

export interface DebtVerdict { id: string; state: DebtState; reasons: string[]; missingEvidence: EvidenceId[] }

export type DebtIssueCode =
  | "empty-field" | "invalid-date" | "date-order" | "invalid-carry"
  | "missing-exit" | "unexpected-exit" | "exit-kind-mismatch"
  | "missing-acceptance" | "acceptance-incomplete" | "carry-mismatch";

export interface DebtIssue { id: string; code: DebtIssueCode; detail: string }

const EXIT_FOR_KIND: Record<DebtKind, ExitKind> = {
  "compat-shim": "delete-shim",
  "legacy-prompt": "retire-prompt",
  "duplicate-capability": "merge-capability",
  "deprecated-model": "offboard-model",
  "manual-workaround": "delete-shim",
};

function isIsoDate(value: string): boolean {
  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
  if (match === null) return false;
  const time = Date.UTC(Number(match[1]), Number(match[2]) - 1, Number(match[3]));
  return new Date(time).toISOString().slice(0, 10) === value;
}

function issue(id: string, code: DebtIssueCode, detail: string): DebtIssue {
  return { id, code, detail };
}

/** 一条债的静态校验；动态条件留给 debtVerdict。 */
export function validateDebtItem(item: DebtItem): DebtIssue[] {
  const issues: DebtIssue[] = [];
  for (const field of ["id", "capability", "owner"] as const) {
    if (item[field].trim() === "") issues.push(issue(item.id, "empty-field", `${field} is empty`));
  }
  if (!isIsoDate(item.openedOn)) issues.push(issue(item.id, "invalid-date", `openedOn ${item.openedOn}`));
  if (!isIsoDate(item.reviewBy)) issues.push(issue(item.id, "invalid-date", `reviewBy ${item.reviewBy}`));
  else if (item.reviewBy < item.openedOn) issues.push(issue(item.id, "date-order", "reviewBy precedes openedOn"));
  if (!Number.isInteger(item.carryMicrosPerMonth) || item.carryMicrosPerMonth < 0) {
    issues.push(issue(item.id, "invalid-carry", "carry must be a non-negative integer"));
  }
  if (item.permanence === "repayable") {
    if (item.exit === undefined) {
      issues.push(issue(item.id, "missing-exit", "repayable debt needs an exit condition"));
    } else {
      if (item.exit.kind !== EXIT_FOR_KIND[item.kind]) {
        issues.push(issue(item.id, "exit-kind-mismatch", `${item.kind} must exit with ${EXIT_FOR_KIND[item.kind]}`));
      }
    }
  } else {
    if (item.exit !== undefined) {
      issues.push(issue(item.id, "unexpected-exit", `${item.permanence} debt must not carry an exit date`));
    }
    const acceptance = item.acceptance;
    if (acceptance === undefined) {
      issues.push(issue(item.id, "missing-acceptance", "accepted debt needs an approval record"));
    } else {
      if (acceptance.approver.trim() === "" || acceptance.rationale.trim() === "") {
        issues.push(issue(item.id, "acceptance-incomplete", "approver and rationale are required"));
      }
      if (!isIsoDate(acceptance.annualReviewOn) || acceptance.annualReviewOn < item.openedOn) {
        issues.push(issue(item.id, "acceptance-incomplete", "annualReviewOn is invalid"));
      }
      if (!Number.isInteger(acceptance.annualCarryMicros) || acceptance.annualCarryMicros < 0) {
        issues.push(issue(item.id, "acceptance-incomplete", "annualCarryMicros is invalid"));
      } else if (Math.round(acceptance.annualCarryMicros / 12) !== item.carryMicrosPerMonth) {
        issues.push(issue(item.id, "carry-mismatch", `monthly ${item.carryMicrosPerMonth} != annual/12`));
      }
    }
  }
  return issues;
}

function meetsExit(
  exit: ExitCondition, observation: DebtObservation,
): { missing: EvidenceId[]; reasons: string[] } {
  const reasons: string[] = [];
  if (observation.activeCallers > exit.activeCallersMax) {
    reasons.push(`活跃调用方 ${observation.activeCallers} > ${exit.activeCallersMax}`);
  }
  if (observation.activeReleases > exit.activeReleasesMax) {
    reasons.push(`活跃发布 ${observation.activeReleases} > ${exit.activeReleasesMax}`);
  }
  if (observation.trafficShare > exit.trafficShareMax) {
    reasons.push(`流量占比 ${(observation.trafficShare * 100).toFixed(2)}% > ${(exit.trafficShareMax * 100).toFixed(2)}%`);
  }
  if (observation.quietDays < exit.quietDays) {
    reasons.push(`静默 ${observation.quietDays} 天 < ${exit.quietDays}`);
  }
  if ((exit.kind === "merge-capability" || exit.kind === "offboard-model")
    && !observation.migrationComplete) {
    reasons.push("迁移尚未完成");
  }
  const missing = exit.requiredEvidence.filter((evidence) => !observation.evidence.includes(evidence));
  return { missing, reasons };
}

/** 判定一条债此刻能不能还；不能还时给出缺的证据与未满足的条件。 */
export function debtVerdict(
  item: DebtItem, observation: DebtObservation, today: string,
): DebtVerdict {
  const issues = validateDebtItem(item);
  if (issues.length > 0) {
    return { id: item.id, state: "invalid", reasons: issues.map((entry) => entry.code), missingEvidence: [] };
  }
  if (item.permanence !== "repayable") {
    const acceptance = item.acceptance;
    if (acceptance === undefined) {
      return { id: item.id, state: "invalid", reasons: ["missing-acceptance"], missingEvidence: [] };
    }
    return today > acceptance.annualReviewOn
      ? { id: item.id, state: "review-overdue", reasons: [`年度复核日 ${acceptance.annualReviewOn} 已过`], missingEvidence: [] }
      : { id: item.id, state: "accepted", reasons: [], missingEvidence: [] };
  }
  const exit = item.exit;
  if (exit === undefined) {
    return { id: item.id, state: "invalid", reasons: ["missing-exit"], missingEvidence: [] };
  }
  if (today > item.reviewBy) {
    return { id: item.id, state: "review-overdue", reasons: [`复核日 ${item.reviewBy} 已过`], missingEvidence: [] };
  }
  const { missing, reasons } = meetsExit(exit, observation);
  if (missing.length > 0) reasons.push(`缺证据 ${missing.join("/")}`);
  return reasons.length > 0
    ? { id: item.id, state: "blocked", reasons, missingEvidence: missing }
    : { id: item.id, state: "payable", reasons: [], missingEvidence: [] };
}

export interface DebtLedger {
  asOf: string;
  total: number;
  payable: number;
  blocked: number;
  reviewOverdue: number;
  accepted: number;
  invalid: number;
  /** 所有可还债的月度维持成本：还掉就能省下的钱。 */
  repayableCarryMicrosPerMonth: number;
  /** 条件已满足、可以立刻还的债的月度成本。 */
  payableCarryMicrosPerMonth: number;
  /** 接受不还的债的年化维持成本，必须单独入账。 */
  acceptedCarryMicrosPerYear: number;
  nextReview: { id: string; date: string } | null;
  rows: DebtVerdict[];
}

/** 台账按状态分桶，并把“永远不还”的债单独累计，避免它沉进 backlog。 */
export function debtLedger(
  items: readonly DebtItem[],
  observations: ReadonlyMap<string, DebtObservation>,
  today: string,
): DebtLedger {
  const rows: DebtVerdict[] = [];
  let repayableCarry = 0;
  let payableCarry = 0;
  let acceptedCarry = 0;
  let overdue = 0;
  let nextReview: { id: string; date: string } | null = null;

  for (const item of items) {
    const observation = observations.get(item.id);
    if (observation === undefined) {
      rows.push({ id: item.id, state: "invalid", reasons: ["missing-observation"], missingEvidence: [] });
      continue;
    }
    const verdict = debtVerdict(item, observation, today);
    rows.push(verdict);
    if (item.permanence === "repayable") {
      repayableCarry += item.carryMicrosPerMonth;
      if (verdict.state === "payable") payableCarry += item.carryMicrosPerMonth;
    } else if (item.acceptance !== undefined) {
      acceptedCarry += item.acceptance.annualCarryMicros;
    }
    if (verdict.state === "review-overdue") overdue += 1;
    const reviewDate = item.permanence === "repayable" ? item.reviewBy : item.acceptance?.annualReviewOn;
    if (reviewDate !== undefined && (nextReview === null || reviewDate < nextReview.date)) {
      nextReview = { id: item.id, date: reviewDate };
    }
  }

  const count = (state: DebtState): number => rows.filter((row) => row.state === state).length;
  return {
    asOf: today, total: items.length,
    payable: count("payable"), blocked: count("blocked"), reviewOverdue: overdue,
    accepted: count("accepted"), invalid: count("invalid"),
    repayableCarryMicrosPerMonth: repayableCarry,
    payableCarryMicrosPerMonth: payableCarry,
    acceptedCarryMicrosPerYear: acceptedCarry,
    nextReview, rows,
  };
}