《互联网产品的客户端架构·规模化与架构演进》11.3 技术债台账与治理节奏

// file: src/governance/tech-debt.ts
// tier: L1
// verify: node --test test/governance/tech-debt.test.ts

export type DebtSeverity = "low" | "medium" | "high" | "critical";
export type DebtStatus = "open" | "scheduled" | "paid" | "accepted";
export type DebtCategory = "architecture" | "quality" | "dependency" | "test" | "docs";

export type DebtItem = {
  id: string;
  title: string;
  severity: DebtSeverity;
  category: DebtCategory;
  impact: number;
  effortDays: number;
  createdOn: string;
  dueOn?: string;
  owner: string;
  status: DebtStatus;
};

export type QuarterOptions = {
  quarter: string;
  capacityDays: number;
  today: string;
};

export type QuarterPlan = {
  quarter: string;
  selected: DebtItem[];
  deferred: DebtItem[];
  skipped: DebtItem[];
  usedDays: number;
  remainingDays: number;
  overdue: string[];
};

export type DebtSummary = {
  open: number;
  scheduled: number;
  paid: number;
  accepted: number;
  overdue: number;
  openEffortDays: number;
  bySeverity: Record<DebtSeverity, number>;
};

export const DEBT_SEVERITIES: DebtSeverity[] = ["low", "medium", "high", "critical"];
export const DEBT_STATUSES: DebtStatus[] = ["open", "scheduled", "paid", "accepted"];

const SEVERITY_WEIGHTS: Record<DebtSeverity, number> = {
  low: 1,
  medium: 2,
  high: 4,
  critical: 8,
};

const DAY_MS = 24 * 60 * 60 * 1000;

export function isDebtSeverity(value: unknown): value is DebtSeverity {
  return (DEBT_SEVERITIES as unknown[]).includes(value);
}

export function isDebtStatus(value: unknown): value is DebtStatus {
  return (DEBT_STATUSES as unknown[]).includes(value);
}

export function isBacklog(item: DebtItem): boolean {
  return item.status === "open" || item.status === "scheduled";
}

export function priorityScore(item: DebtItem): number {
  const impact = Math.max(1, Math.min(5, item.impact));
  return SEVERITY_WEIGHTS[item.severity] * impact;
}

export function ageDays(createdOn: string, today: string): number {
  const start = Date.parse(`${createdOn}T00:00:00Z`);
  const end = Date.parse(`${today}T00:00:00Z`);
  if (Number.isNaN(start) || Number.isNaN(end)) {
    return 0;
  }
  return Math.max(0, Math.round((end - start) / DAY_MS));
}

export function isOverdue(item: DebtItem, today: string): boolean {
  return isBacklog(item) && item.dueOn !== undefined && item.dueOn < today;
}

export function overdueItems(items: DebtItem[], today: string): DebtItem[] {
  return items
    .filter((item) => isOverdue(item, today))
    .sort((a, b) => (a.dueOn ?? "").localeCompare(b.dueOn ?? "") || a.id.localeCompare(b.id));
}

export function quarterOf(date: string): string | undefined {
  const match = /^(\d{4})-(\d{2})-\d{2}$/.exec(date);
  if (match === null) {
    return undefined;
  }
  const month = Number(match[2]);
  if (month < 1 || month > 12) {
    return undefined;
  }
  return `${match[1]}-Q${Math.floor((month - 1) / 3) + 1}`;
}

export function nextQuarter(quarter: string): string | undefined {
  const match = /^(\d{4})-Q([1-4])$/.exec(quarter);
  if (match === null) {
    return undefined;
  }
  const year = Number(match[1]);
  const period = Number(match[2]);
  return period === 4 ? `${year + 1}-Q1` : `${year}-Q${period + 1}`;
}

function pad2(value: number): string {
  return value < 10 ? `0${value}` : String(value);
}

export function quarterBounds(quarter: string): { start: string; end: string } | undefined {
  const match = /^(\d{4})-Q([1-4])$/.exec(quarter);
  if (match === null) {
    return undefined;
  }
  const year = Number(match[1]);
  const period = Number(match[2]);
  const startMonth = (period - 1) * 3 + 1;
  const endMonth = startMonth + 2;
  const lastDay = new Date(Date.UTC(year, endMonth, 0)).getUTCDate();
  return {
    start: `${year}-${pad2(startMonth)}-01`,
    end: `${year}-${pad2(endMonth)}-${pad2(lastDay)}`,
  };
}

function compareBacklog(a: DebtItem, b: DebtItem, today: string): number {
  const aOverdue = isOverdue(a, today) ? 0 : 1;
  const bOverdue = isOverdue(b, today) ? 0 : 1;
  if (aOverdue !== bOverdue) {
    return aOverdue - bOverdue;
  }
  const score = priorityScore(b) - priorityScore(a);
  if (score !== 0) {
    return score;
  }
  if (a.createdOn !== b.createdOn) {
    return a.createdOn < b.createdOn ? -1 : 1;
  }
  return a.id.localeCompare(b.id);
}

export function planQuarter(items: DebtItem[], options: QuarterOptions): QuarterPlan {
  const skipped = items.filter((item) => !isBacklog(item));
  const backlog = items.filter(isBacklog).sort((a, b) => compareBacklog(a, b, options.today));
  const selected: DebtItem[] = [];
  const deferred: DebtItem[] = [];
  let usedDays = 0;
  for (const item of backlog) {
    if (item.effortDays <= options.capacityDays - usedDays) {
      selected.push(item);
      usedDays += item.effortDays;
    } else {
      deferred.push(item);
    }
  }
  return {
    quarter: options.quarter,
    selected,
    deferred,
    skipped,
    usedDays,
    remainingDays: options.capacityDays - usedDays,
    overdue: overdueItems(items, options.today).map((item) => item.id),
  };
}

export function debtSummary(items: DebtItem[], today: string): DebtSummary {
  const bySeverity: Record<DebtSeverity, number> = {
    low: 0,
    medium: 0,
    high: 0,
    critical: 0,
  };
  let open = 0;
  let scheduled = 0;
  let paid = 0;
  let accepted = 0;
  let openEffortDays = 0;
  for (const item of items) {
    bySeverity[item.severity] += 1;
    if (item.status === "open") {
      open += 1;
    } else if (item.status === "scheduled") {
      scheduled += 1;
    } else if (item.status === "paid") {
      paid += 1;
    } else {
      accepted += 1;
    }
    if (isBacklog(item)) {
      openEffortDays += item.effortDays;
    }
  }
  return {
    open,
    scheduled,
    paid,
    accepted,
    overdue: overdueItems(items, today).length,
    openEffortDays,
    bySeverity,
  };
}