《互联网产品的 AI 架构·平台化与治理》3.3 版本矩阵与弃用窗口

// file: src/gov/version-matrix.ts
// tier: L2
// verify: node --test test/gov/versions.test.ts

import { compareSemver, parseSemver } from "../orch/platform.ts";

export type SupportStatus = "active" | "dual-run" | "deprecated" | "retired";

export interface MatrixCell { capability: string; model: string; status: SupportStatus }

export interface VersionMatrix { cells: readonly MatrixCell[] }

export interface MatrixSummary {
  total: number;
  capabilities: number;
  models: number;
  active: number;
  "dual-run": number;
  deprecated: number;
  retired: number;
}

export function summarizeMatrix(matrix: VersionMatrix): MatrixSummary {
  const summary: MatrixSummary = {
    total: matrix.cells.length,
    capabilities: new Set(matrix.cells.map((cell) => cell.capability)).size,
    models: new Set(matrix.cells.map((cell) => cell.model)).size,
    active: 0,
    "dual-run": 0,
    deprecated: 0,
    retired: 0,
  };
  for (const cell of matrix.cells) summary[cell.status] += 1;
  return summary;
}

export interface ConvergencePlan {
  keepModels: string[]; capabilities: string[]; totalCells: number; targetCells: number;
  closedCells: number; migrate: MatrixCell[]; forceOff: MatrixCell[]; alreadyRetired: MatrixCell[];
}

/** 收敛不是把旧格子删掉，而是把每个旧格子分配到一个动作：迁移、强制下线或已退役。 */
export function planConvergence(matrix: VersionMatrix, keepModels: readonly string[]): ConvergencePlan {
  const keep = [...new Set(keepModels)].sort();
  const keepSet = new Set(keep);
  const capabilities = [...new Set(matrix.cells.map((cell) => cell.capability))].sort();
  const migrate = matrix.cells.filter(
    (cell) => !keepSet.has(cell.model) && (cell.status === "active" || cell.status === "dual-run"),
  );
  const forceOff = matrix.cells.filter(
    (cell) => !keepSet.has(cell.model) && cell.status === "deprecated",
  );
  const alreadyRetired = matrix.cells.filter((cell) => cell.status === "retired");
  const totalCells = matrix.cells.length;
  const targetCells = capabilities.length * keep.length;
  return { keepModels: keep, capabilities, totalCells, targetCells, closedCells: totalCells - targetCells, migrate, forceOff, alreadyRetired };
}

export interface DeprecationPolicy { announceDays: number; dualRunDays: number; forceOffDays: number }

export interface DeprecationSchedule {
  announce: string; dualRunStart: string; forceOffStart: string; offline: string; totalDays: number;
}

const DAY_MS = 86_400_000;

function parseDate(value: string): number {
  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
  if (match === null) throw new Error(`version-matrix: invalid date ${value}`);
  return Date.UTC(Number(match[1]), Number(match[2]) - 1, Number(match[3]));
}

function formatDate(value: number): string {
  return new Date(value).toISOString().slice(0, 10);
}

export function planDeprecation(startDate: string, policy: DeprecationPolicy): DeprecationSchedule {
  for (const [name, days] of Object.entries(policy)) {
    if (!Number.isInteger(days) || days < 0) {
      throw new Error(`version-matrix: invalid ${name} ${days}`);
    }
  }
  const start = parseDate(startDate);
  const dualRunStart = start + policy.announceDays * DAY_MS;
  const forceOffStart = dualRunStart + policy.dualRunDays * DAY_MS;
  const offline = forceOffStart + policy.forceOffDays * DAY_MS;
  return {
    announce: formatDate(start), dualRunStart: formatDate(dualRunStart),
    forceOffStart: formatDate(forceOffStart), offline: formatDate(offline),
    totalDays: Math.round((offline - start) / DAY_MS),
  };
}

export type WindowPhase = "announced" | "dual-running" | "force-off" | "offline";

export function windowPhase(date: string, schedule: DeprecationSchedule): WindowPhase {
  const at = parseDate(date);
  if (at < parseDate(schedule.dualRunStart)) return "announced";
  if (at < parseDate(schedule.forceOffStart)) return "dual-running";
  if (at < parseDate(schedule.offline)) return "force-off";
  return "offline";
}

export interface CallerUsage { team: string; capability: string; version: string; lastSeenDaysAgo: number }

export type CallerState = "on-target" | "behind" | "stale";

export interface CallerRow { team: string; version: string; lastSeenDaysAgo: number; state: CallerState }

export interface CallerScan {
  capability: string; target: string; total: number; onTarget: number; behind: number;
  stale: number; behindTeams: string[]; readyToForceOff: boolean; rows: CallerRow[];
}

/** 落后版本按调用方逐条判定；静默超过窗口的调用方单独标出，避免误判为已迁移。 */
export function scanCallers(
  usages: readonly CallerUsage[],
  capability: string,
  targetVersion: string,
  staleDays = 30,
): CallerScan {
  if (parseSemver(targetVersion) === null) {
    throw new Error(`version-matrix: invalid target ${targetVersion}`);
  }
  const rows: CallerRow[] = [];
  for (const usage of usages) {
    if (usage.capability !== capability) continue;
    if (parseSemver(usage.version) === null) {
      throw new Error(`version-matrix: invalid version ${usage.version}`);
    }
    const behind = compareSemver(usage.version, targetVersion) < 0;
    const state: CallerState = behind ? (usage.lastSeenDaysAgo > staleDays ? "stale" : "behind") : "on-target";
    rows.push({ team: usage.team, version: usage.version, lastSeenDaysAgo: usage.lastSeenDaysAgo, state });
  }
  rows.sort((left, right) => {
    if (left.team !== right.team) return left.team < right.team ? -1 : 1;
    return compareSemver(right.version, left.version);
  });
  const behind = rows.filter((row) => row.state !== "on-target").length;
  const stale = rows.filter((row) => row.state === "stale").length;
  const behindTeams = [...new Set(rows.filter((row) => row.state !== "on-target").map((row) => row.team))].sort();
  return {
    capability, target: targetVersion, total: rows.length, onTarget: rows.length - behind,
    behind, stale, behindTeams, readyToForceOff: behind === 0, rows,
  };
}

export function migrationChecklist(scan: CallerScan, schedule: DeprecationSchedule): string[] {
  const steps = [`公告 ${schedule.announce}：目标版本 ${scan.target}`];
  if (scan.behind > 0) {
    steps.push(`迁移 ${scan.behind} 个调用方：${scan.behindTeams.join("、")}`);
  } else {
    steps.push("没有落后调用方，可以按计划强制下线");
  }
  if (scan.stale > 0) {
    steps.push(`确认 ${scan.stale} 个静默调用方，避免误判为已迁移`);
  }
  steps.push(`双跑截止 ${schedule.forceOffStart}，下线 ${schedule.offline}`);
  return steps;
}