《互联网产品的 AI 架构·平台化与治理》12.1 模型换代与迁移计划

// file: src/gov/migration-plan.ts
// tier: L2
// verify: node --test test/gov/evolution-gov.test.ts

/** 影子阶段复制流量但不向用户返回结果，因此对客占比仍是 0。 */
export type MigrationStage =
  | "assess" | "shadow" | "canary-10" | "canary-50" | "full" | "retired";

export const STAGE_ORDER: readonly MigrationStage[] = [
  "assess", "shadow", "canary-10", "canary-50", "full", "retired",
];

export const STAGE_TRAFFIC_SHARE: Record<MigrationStage, number> = {
  assess: 0, shadow: 0, "canary-10": 0.1, "canary-50": 0.5, full: 1, retired: 0,
};

export interface MigrationGates {
  minSamples: number;
  /** 成功率允许下降的百分点。 */
  maxSuccessDropPct: number;
  maxP95GrowthPct: number;
  maxCostGrowthPct: number;
  maxQualityDrop: number;
  /** 越过红线直接回滚，不再观察。 */
  rollbackSuccessDropPct: number;
  rollbackQualityDrop: number;
}


export const DEFAULT_GATES: MigrationGates = {
  minSamples: 2000, maxSuccessDropPct: 0.5, maxP95GrowthPct: 10, maxCostGrowthPct: 8,
  maxQualityDrop: 0.01, rollbackSuccessDropPct: 1, rollbackQualityDrop: 0.02,
};

export interface MigrationObservation {
  stage: MigrationStage; samples: number;
  successRate: number; baselineSuccessRate: number;
  p95Ms: number; baselineP95Ms: number;
  costMicrosPerCall: number; baselineCostMicrosPerCall: number;
  qualityScore: number; baselineQualityScore: number;
}

export type GateCode =
  | "insufficient-samples" | "success-drop" | "success-collapse"
  | "p95-growth" | "cost-growth" | "quality-drop" | "quality-collapse";

export interface GateFinding { code: GateCode; severity: "hold" | "rollback"; detail: string }

export interface StageDecision {
  stage: MigrationStage;
  next: MigrationStage;
  action: "advance" | "hold" | "rollback";
  findings: GateFinding[];
  /** 推进后生效的对客流量占比；回滚时为 0。 */
  trafficShare: number;
}

function rate(value: number, field: string): void {
  if (!(value >= 0 && value <= 1)) throw new Error(`migration-plan: ${field} must be within 0..1`);
}

function checkObservation(observation: MigrationObservation): void {
  if (!STAGE_ORDER.includes(observation.stage)) {
    throw new Error(`migration-plan: unknown stage ${observation.stage}`);
  }
  if (!Number.isInteger(observation.samples) || observation.samples < 0) {
    throw new Error("migration-plan: samples must be a non-negative integer");
  }
  for (const field of ["successRate", "baselineSuccessRate", "qualityScore", "baselineQualityScore"] as const) {
    rate(observation[field], field);
  }
  if (!(observation.p95Ms > 0) || !(observation.baselineP95Ms > 0)) {
    throw new Error("migration-plan: p95 must be positive");
  }
  for (const field of ["costMicrosPerCall", "baselineCostMicrosPerCall"] as const) {
    if (!Number.isInteger(observation[field]) || observation[field] < 0) {
      throw new Error(`migration-plan: ${field} must be a non-negative integer`);
    }
  }
}

/** 单阶段判定：先看红线，再看预警线，最后看样本量。 */
export function decideStage(
  observation: MigrationObservation,
  gates: MigrationGates = DEFAULT_GATES,
): StageDecision {
  checkObservation(observation);
  const successDrop = (observation.baselineSuccessRate - observation.successRate) * 100;
  const p95Growth = (observation.p95Ms - observation.baselineP95Ms) / observation.baselineP95Ms * 100;
  const costGrowth = (observation.costMicrosPerCall - observation.baselineCostMicrosPerCall)
    / observation.baselineCostMicrosPerCall * 100;
  const qualityDrop = observation.baselineQualityScore - observation.qualityScore;
  const findings: GateFinding[] = [];
  const hold = (code: GateCode, detail: string): void => {
    findings.push({ code, severity: "hold", detail });
  };
  if (successDrop >= gates.rollbackSuccessDropPct) {
    findings.push({ code: "success-collapse", severity: "rollback", detail: `成功率下降 ${successDrop.toFixed(2)} 个百分点` });
  } else if (successDrop > gates.maxSuccessDropPct) {
    hold("success-drop", `成功率下降 ${successDrop.toFixed(2)} 个百分点`);
  }
  if (qualityDrop >= gates.rollbackQualityDrop) {
    findings.push({ code: "quality-collapse", severity: "rollback", detail: `质量分下降 ${qualityDrop.toFixed(4)}` });
  } else if (qualityDrop > gates.maxQualityDrop) {
    hold("quality-drop", `质量分下降 ${qualityDrop.toFixed(4)}`);
  }
  if (p95Growth > gates.maxP95GrowthPct) hold("p95-growth", `P95 增长 ${p95Growth.toFixed(2)}%`);
  if (costGrowth > gates.maxCostGrowthPct) hold("cost-growth", `单次成本增长 ${costGrowth.toFixed(2)}%`);
  if (observation.samples < gates.minSamples) hold("insufficient-samples", `样本 ${observation.samples} 少于 ${gates.minSamples}`);

  const action = findings.some((finding) => finding.severity === "rollback")
    ? "rollback" : findings.length > 0 ? "hold" : "advance";
  const index = STAGE_ORDER.indexOf(observation.stage);
  const next = action === "advance"
    ? STAGE_ORDER[Math.min(index + 1, STAGE_ORDER.length - 1)] : observation.stage;
  const trafficShare = action === "advance" ? STAGE_TRAFFIC_SHARE[next]
    : action === "rollback" ? 0 : STAGE_TRAFFIC_SHARE[observation.stage];
  return { stage: observation.stage, next, action, findings, trafficShare };
}

export interface StageWindow { stage: MigrationStage; share: number; start: string; end: string }

export interface MigrationPlanInput {
  capability: string;
  fromModel: string;
  toModel: string;
  startDate: string;
  stageDays: Record<Exclude<MigrationStage, "retired">, number>;
  gates: MigrationGates;
  oldModelOfflineDate: string;
}

export interface MigrationPlan {
  capability: string;
  fromModel: string;
  toModel: string;
  gates: MigrationGates;
  windows: StageWindow[];
  oldModelOfflineDate: string;
}

export type PlanIssueCode =
  | "same-model" | "invalid-date" | "date-order" | "invalid-stage-days"
  | "invalid-gate" | "offline-before-full";

export interface PlanIssue { code: PlanIssueCode; detail: string }

const PLAN_STAGES: readonly Exclude<MigrationStage, "retired">[] = [
  "assess", "shadow", "canary-10", "canary-50", "full",
];

const DAY_MS = 86_400_000;

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

const formatDate = (time: number): string => new Date(time).toISOString().slice(0, 10);

/** 旧模型下线日不得早于全量阶段结束，否则计划自相矛盾。 */
export function planMigration(
  input: MigrationPlanInput,
): { ok: true; plan: MigrationPlan } | { ok: false; issues: PlanIssue[] } {
  const issues: PlanIssue[] = [];
  const add = (code: PlanIssueCode, detail: string): void => { issues.push({ code, detail }); };
  if (input.fromModel.trim() === "" || input.toModel.trim() === "") {
    add("same-model", "model ids must not be empty");
  } else if (input.fromModel === input.toModel) {
    add("same-model", "from and to model are identical");
  }
  const start = parseDate(input.startDate);
  const offline = parseDate(input.oldModelOfflineDate);
  if (start === null) add("invalid-date", `startDate ${input.startDate}`);
  if (offline === null) add("invalid-date", `oldModelOfflineDate ${input.oldModelOfflineDate}`);
  for (const stage of PLAN_STAGES) {
    const days = input.stageDays[stage];
    if (!Number.isInteger(days) || days < 1) add("invalid-stage-days", `${stage} must be a positive integer`);
  }
  const gates = input.gates;
  if (!Number.isInteger(gates.minSamples) || gates.minSamples < 1) add("invalid-gate", "minSamples must be positive");
  if (!(gates.rollbackSuccessDropPct > gates.maxSuccessDropPct)) {
    add("invalid-gate", "rollback success gate must exceed hold gate");
  }
  if (!(gates.rollbackQualityDrop > gates.maxQualityDrop)) {
    add("invalid-gate", "rollback quality gate must exceed hold gate");
  }
  if (issues.length > 0 || start === null || offline === null) return { ok: false, issues };

  const windows: StageWindow[] = [];
  let cursor = start;
  for (const stage of PLAN_STAGES) {
    const end = cursor + input.stageDays[stage] * DAY_MS;
    windows.push({ stage, share: STAGE_TRAFFIC_SHARE[stage], start: formatDate(cursor), end: formatDate(end) });
    cursor = end;
  }
  if (offline < cursor) {
    add("offline-before-full", `offline ${input.oldModelOfflineDate} precedes full end ${formatDate(cursor)}`);
    return { ok: false, issues };
  }
  return {
    ok: true,
    plan: {
      capability: input.capability, fromModel: input.fromModel, toModel: input.toModel,
      gates: { ...gates }, windows, oldModelOfflineDate: input.oldModelOfflineDate,
    },
  };
}

export type RetirementState = "not-due" | "blocked" | "ready" | "overdue";

export interface RetirementDecision {
  state: RetirementState;
  daysLeft: number;
  residualShare: number;
  detail: string;
}

/** 下线日只约束时间；能否关停还要求旧模型残余流量为 0。 */
export function retirementState(
  plan: MigrationPlan, today: string, residualShare: number,
): RetirementDecision {
  const now = parseDate(today);
  const offline = parseDate(plan.oldModelOfflineDate);
  if (now === null || offline === null) throw new Error("migration-plan: invalid date");
  if (!(residualShare >= 0 && residualShare <= 1)) {
    throw new Error("migration-plan: residualShare must be within 0..1");
  }
  const daysLeft = Math.round((offline - now) / DAY_MS);
  if (now < offline) {
    return { state: "not-due", daysLeft, residualShare, detail: `距下线日还有 ${daysLeft} 天` };
  }
  if (residualShare > 0) {
    return { state: "blocked", daysLeft, residualShare,
      detail: `已到下线日，旧模型仍有 ${(residualShare * 100).toFixed(1)}% 流量` };
  }
  return now === offline
    ? { state: "ready", daysLeft: 0, residualShare, detail: "下线日到达且残余流量为 0" }
    : { state: "overdue", daysLeft, residualShare, detail: `下线日已过 ${Math.abs(daysLeft)} 天` };
}