《互联网产品的客户端架构·规模化与架构演进》12.3 迁移的退出条件与回滚

// file: src/migration/exit-criteria.ts
// tier: L1
// verify: node --test test/migration/exit-criteria.test.ts

export type ExitCriterion =
  | "new-traffic"
  | "legacy-traffic"
  | "error"
  | "consistency"
  | "observation";

export type ExitThresholds = {
  minNewTrafficPercent: number;
  maxLegacyTrafficPercent: number;
  maxErrorRate: number;
  minConsistencyRate: number;
  minObservationMs: number;
};

export type ExitObservation = {
  newTrafficPercent: number;
  legacyTrafficPercent: number;
  errorRate: number;
  consistencyRate: number;
  observedMs: number;
  samples: number;
};

export type CriterionResult = {
  id: ExitCriterion;
  passed: boolean;
  actual: number;
  threshold: number;
  mode: "min" | "max";
};

export type ExitReason = "ready" | "criteria" | "insufficient-samples";

export type ExitVerdict = {
  ready: boolean;
  reason: ExitReason;
  results: CriterionResult[];
  blockers: ExitCriterion[];
};

export type RollbackKind = "artifact" | "config" | "data" | "runbook";

export type RollbackAsset = {
  id: string;
  kind: RollbackKind;
  owner: string;
  verifiedAt: number | null;
};

export type RollbackReadiness = {
  ready: boolean;
  missing: RollbackKind[];
  stale: string[];
  unowned: string[];
};

export type RetirementStatus = "draft" | "announced" | "removed";

export type RetirementState = {
  feature: string;
  legacyPaths: string[];
  announcedAt: number | null;
  removedAt: number | null;
};

export type RetirementReason =
  | "allowed"
  | "already-announced"
  | "already-removed"
  | "not-ready"
  | "rollback-not-ready"
  | "not-announced"
  | "grace-period";

export type RetirementDecision = {
  allowed: boolean;
  reason: RetirementReason;
  state: RetirementState;
};

export const EXIT_CRITERIA: ExitCriterion[] = [
  "new-traffic",
  "legacy-traffic",
  "error",
  "consistency",
  "observation",
];

export const REQUIRED_ROLLBACK_KINDS: RollbackKind[] = [
  "artifact",
  "config",
  "data",
  "runbook",
];

function roundValue(value: number): number {
  return Math.round(value * 100) / 100;
}

function cloneState(state: RetirementState): RetirementState {
  return {
    feature: state.feature,
    legacyPaths: [...state.legacyPaths],
    announcedAt: state.announcedAt,
    removedAt: state.removedAt,
  };
}

export function evaluateExit(
  observation: ExitObservation,
  thresholds: ExitThresholds,
  minSamples: number = 1000,
): ExitVerdict {
  const results: CriterionResult[] = [
    {
      id: "new-traffic",
      passed: observation.newTrafficPercent >= thresholds.minNewTrafficPercent,
      actual: roundValue(observation.newTrafficPercent),
      threshold: thresholds.minNewTrafficPercent,
      mode: "min",
    },
    {
      id: "legacy-traffic",
      passed: observation.legacyTrafficPercent <= thresholds.maxLegacyTrafficPercent,
      actual: roundValue(observation.legacyTrafficPercent),
      threshold: thresholds.maxLegacyTrafficPercent,
      mode: "max",
    },
    {
      id: "error",
      passed: observation.errorRate <= thresholds.maxErrorRate,
      actual: roundValue(observation.errorRate),
      threshold: thresholds.maxErrorRate,
      mode: "max",
    },
    {
      id: "consistency",
      passed: observation.consistencyRate >= thresholds.minConsistencyRate,
      actual: roundValue(observation.consistencyRate),
      threshold: thresholds.minConsistencyRate,
      mode: "min",
    },
    {
      id: "observation",
      passed: observation.observedMs >= thresholds.minObservationMs,
      actual: observation.observedMs,
      threshold: thresholds.minObservationMs,
      mode: "min",
    },
  ];
  const blockers = results
    .filter((item) => !item.passed)
    .map((item) => item.id);
  let reason: ExitReason = "ready";
  if (observation.samples < minSamples) reason = "insufficient-samples";
  else if (blockers.length > 0) reason = "criteria";
  return {
    ready: reason === "ready",
    reason,
    results,
    blockers,
  };
}

export function checkRollback(
  assets: RollbackAsset[],
  now: number,
  maxAgeMs: number = 7 * 24 * 60 * 60 * 1000,
): RollbackReadiness {
  const missing = REQUIRED_ROLLBACK_KINDS.filter(
    (kind) => !assets.some((asset) => asset.kind === kind),
  );
  const relevant = assets.filter((asset) =>
    REQUIRED_ROLLBACK_KINDS.includes(asset.kind),
  );
  const stale = relevant
    .filter(
      (asset) =>
        asset.verifiedAt === null || now - asset.verifiedAt > maxAgeMs,
    )
    .map((asset) => asset.id);
  const unowned = relevant
    .filter((asset) => asset.owner.trim() === "")
    .map((asset) => asset.id);
  return {
    ready: missing.length === 0 && stale.length === 0 && unowned.length === 0,
    missing,
    stale,
    unowned,
  };
}

export function retirementStatus(state: RetirementState): RetirementStatus {
  if (state.removedAt !== null) return "removed";
  if (state.announcedAt !== null) return "announced";
  return "draft";
}

export function announceRetirement(
  state: RetirementState,
  verdict: ExitVerdict,
  rollback: RollbackReadiness,
  now: number,
): RetirementDecision {
  if (state.removedAt !== null) {
    return { allowed: false, reason: "already-removed", state: cloneState(state) };
  }
  if (state.announcedAt !== null) {
    return { allowed: false, reason: "already-announced", state: cloneState(state) };
  }
  if (!verdict.ready) {
    return { allowed: false, reason: "not-ready", state: cloneState(state) };
  }
  if (!rollback.ready) {
    return {
      allowed: false,
      reason: "rollback-not-ready",
      state: cloneState(state),
    };
  }
  return {
    allowed: true,
    reason: "allowed",
    state: { ...cloneState(state), announcedAt: now },
  };
}

export function removeLegacy(
  state: RetirementState,
  input: {
    now: number;
    graceMs: number;
    verdict: ExitVerdict;
    rollback: RollbackReadiness;
  },
): RetirementDecision {
  if (state.removedAt !== null) {
    return { allowed: false, reason: "already-removed", state: cloneState(state) };
  }
  if (state.announcedAt === null) {
    return { allowed: false, reason: "not-announced", state: cloneState(state) };
  }
  if (input.now - state.announcedAt < input.graceMs) {
    return { allowed: false, reason: "grace-period", state: cloneState(state) };
  }
  if (!input.verdict.ready) {
    return { allowed: false, reason: "not-ready", state: cloneState(state) };
  }
  if (!input.rollback.ready) {
    return {
      allowed: false,
      reason: "rollback-not-ready",
      state: cloneState(state),
    };
  }
  return {
    allowed: true,
    reason: "allowed",
    state: {
      ...cloneState(state),
      legacyPaths: [],
      removedAt: input.now,
    },
  };
}