《互联网产品的 AI 架构·平台化与治理》12.3 治理的度量：不是流程数量

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

/** 五个度量都描述“改变发生了什么”，不描述“开了几次会”。 */
export type MetricId =
  | "capability-lead-time" | "change-failure-rate" | "quota-idle-rate"
  | "review-turnaround" | "process-exemption-rate";

export type MetricUnit = "days" | "ratio" | "hours";

export interface MetricDefinition {
  id: MetricId;
  label: string;
  unit: MetricUnit;
  direction: "lower-better" | "target-band";
  /** lower-better 的上限；target-band 时用 band。 */
  target: number;
  band?: readonly [number, number];
  denominator: string;
}

export const METRIC_CATALOG: readonly MetricDefinition[] = [
  { id: "capability-lead-time", label: "能力上线周期", unit: "days", direction: "lower-better", target: 14, denominator: "批准到上线的能力条目数" },
  { id: "change-failure-rate", label: "变更失败率", unit: "ratio", direction: "lower-better", target: 0.1, denominator: "本周期部署的变更数" },
  { id: "quota-idle-rate", label: "配额闲置率", unit: "ratio", direction: "lower-better", target: 0.25, denominator: "本周期分配的配额总额（微元）" },
  { id: "review-turnaround", label: "评审平均耗时", unit: "hours", direction: "lower-better", target: 48, denominator: "本周期提交的变更评审数" },
  { id: "process-exemption-rate", label: "流程豁免率", unit: "ratio", direction: "target-band", target: 0.1, band: [0.05, 0.15], denominator: "本周期应走流程的变更数" },
];

export type NonMetric = "process-count" | "approval-count" | "meeting-count" | "document-count";

export const NON_METRICS: readonly NonMetric[] = [
  "process-count", "approval-count", "meeting-count", "document-count",
];

export type MetricLookup =
  | { ok: true; definition: MetricDefinition }
  | { ok: false; reason: "non-metric" | "unknown"; detail: string };

/** 流程数量不是度量：它只证明动作发生过，不证明结果变好。 */
export function lookupMetric(id: string): MetricLookup {
  const definition = METRIC_CATALOG.find((entry) => entry.id === id);
  if (definition !== undefined) return { ok: true, definition };
  if ((NON_METRICS as readonly string[]).includes(id)) {
    return { ok: false, reason: "non-metric", detail: `${id} counts activity, not outcome` };
  }
  return { ok: false, reason: "unknown", detail: `${id} is not registered` };
}

export interface LaunchRecord { id: string; capability: string; approvedOn: string; liveOn: string }

export interface ChangeRecord {
  id: string; capability: string; deployedOn: string;
  failed: boolean; reviewHours: number; exempt: boolean;
}

export interface QuotaRecord { tenant: string; allocatedMicros: number; usedMicros: number }

export interface GovernanceSample {
  period: string;
  launches: readonly LaunchRecord[];
  changes: readonly ChangeRecord[];
  quotas: readonly QuotaRecord[];
}

export interface MetricValue {
  id: MetricId;
  value: number;
  unit: MetricUnit;
  numerator: number;
  denominator: number;
}

export interface GovernanceSnapshot {
  period: string;
  metrics: MetricValue[];
  launchCount: number;
  changeCount: number;
}

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 daysBetween(from: string, to: string): number {
  return Math.round((Date.parse(`${to}T00:00:00Z`) - Date.parse(`${from}T00:00:00Z`)) / 86_400_000);
}

function median(values: readonly number[]): number {
  if (values.length === 0) throw new Error("gov-metrics: median of an empty set");
  const sorted = [...values].sort((left, right) => left - right);
  const middle = Math.floor(sorted.length / 2);
  return sorted.length % 2 === 1 ? sorted[middle] : (sorted[middle - 1] + sorted[middle]) / 2;
}

function validateSample(sample: GovernanceSample): void {
  if (sample.launches.length === 0) throw new Error("gov-metrics: at least one launch is required");
  if (sample.changes.length === 0) throw new Error("gov-metrics: at least one change is required");
  if (sample.quotas.length === 0) throw new Error("gov-metrics: at least one quota record is required");
  for (const launch of sample.launches) {
    if (!isIsoDate(launch.approvedOn) || !isIsoDate(launch.liveOn)) {
      throw new Error(`gov-metrics: launch ${launch.id} has an invalid date`);
    }
    if (launch.liveOn < launch.approvedOn) {
      throw new Error(`gov-metrics: launch ${launch.id} goes live before approval`);
    }
  }
  for (const change of sample.changes) {
    if (!isIsoDate(change.deployedOn)) throw new Error(`gov-metrics: change ${change.id} has an invalid date`);
    if (!(change.reviewHours >= 0) || Number.isNaN(change.reviewHours)) {
      throw new Error(`gov-metrics: change ${change.id} has invalid review hours`);
    }
  }
  for (const quota of sample.quotas) {
    if (!Number.isInteger(quota.allocatedMicros) || quota.allocatedMicros <= 0) {
      throw new Error(`gov-metrics: quota ${quota.tenant} must be a positive integer`);
    }
    if (!Number.isInteger(quota.usedMicros) || quota.usedMicros < 0
      || quota.usedMicros > quota.allocatedMicros) {
      throw new Error(`gov-metrics: quota ${quota.tenant} used outside 0..allocated`);
    }
  }
}

/** 每个度量都写明分子与分母；比例一律是小数值，不乘 100。 */
export function computeMetrics(sample: GovernanceSample): GovernanceSnapshot {
  validateSample(sample);
  const leadTimes = sample.launches.map((launch) => daysBetween(launch.approvedOn, launch.liveOn));
  const failed = sample.changes.filter((change) => change.failed).length;
  const exempt = sample.changes.filter((change) => change.exempt).length;
  const allocated = sample.quotas.reduce((sum, quota) => sum + quota.allocatedMicros, 0);
  const used = sample.quotas.reduce((sum, quota) => sum + quota.usedMicros, 0);
  const reviews = sample.changes.map((change) => change.reviewHours);
  const metrics: MetricValue[] = [
    { id: "capability-lead-time", value: median(leadTimes), unit: "days",
      numerator: leadTimes.reduce((sum, days) => sum + days, 0), denominator: leadTimes.length },
    { id: "change-failure-rate", value: failed / sample.changes.length, unit: "ratio",
      numerator: failed, denominator: sample.changes.length },
    { id: "quota-idle-rate", value: (allocated - used) / allocated, unit: "ratio",
      numerator: allocated - used, denominator: allocated },
    { id: "review-turnaround", value: median(reviews), unit: "hours",
      numerator: reviews.reduce((sum, hours) => sum + hours, 0), denominator: reviews.length },
    { id: "process-exemption-rate", value: exempt / sample.changes.length, unit: "ratio",
      numerator: exempt, denominator: sample.changes.length },
  ];
  return { period: sample.period, metrics, launchCount: sample.launches.length, changeCount: sample.changes.length };
}

export function metricValue(snapshot: GovernanceSnapshot, id: MetricId): number {
  const metric = snapshot.metrics.find((entry) => entry.id === id);
  if (metric === undefined) throw new Error(`gov-metrics: ${id} missing from snapshot`);
  return metric.value;
}

export type MetricStatus = "on-target" | "off-target";

export function metricStatus(definition: MetricDefinition, value: number): MetricStatus {
  if (definition.direction === "target-band") {
    const band = definition.band;
    if (band === undefined) throw new Error(`gov-metrics: ${definition.id} has no band`);
    return value >= band[0] && value <= band[1] ? "on-target" : "off-target";
  }
  return value <= definition.target ? "on-target" : "off-target";
}

export type Trend = "improving" | "stable" | "worsening" | "out-of-band";

export interface TrendVerdict {
  id: MetricId;
  current: number;
  previous: number;
  delta: number;
  trend: Trend;
}

const DEFAULT_TOLERANCE: Record<MetricId, number> = {
  "capability-lead-time": 1,
  "change-failure-rate": 0.01,
  "quota-idle-rate": 0.02,
  "review-turnaround": 2,
  "process-exemption-rate": 0,
};

/** 趋势判定只比较两个周期；豁免率看是否落在目标带内，不看涨跌。 */
export function compareTrend(
  current: GovernanceSnapshot,
  previous: GovernanceSnapshot,
  tolerances: Partial<Record<MetricId, number>> = {},
): TrendVerdict[] {
  const verdicts: TrendVerdict[] = [];
  for (const definition of METRIC_CATALOG) {
    const now = metricValue(current, definition.id);
    const before = metricValue(previous, definition.id);
    const delta = now - before;
    if (definition.direction === "target-band") {
      const band = definition.band;
      if (band === undefined) throw new Error(`gov-metrics: ${definition.id} has no band`);
      const inside = now >= band[0] && now <= band[1];
      const wasInside = before >= band[0] && before <= band[1];
      verdicts.push({ id: definition.id, current: now, previous: before, delta,
        trend: !inside ? "out-of-band" : wasInside ? "stable" : "improving" });
      continue;
    }
    const tolerance = tolerances[definition.id] ?? DEFAULT_TOLERANCE[definition.id];
    const trend: Trend = Math.abs(delta) <= tolerance ? "stable" : delta < 0 ? "improving" : "worsening";
    verdicts.push({ id: definition.id, current: now, previous: before, delta, trend });
  }
  return verdicts;
}

export interface ScorecardRow {
  definition: MetricDefinition;
  value: number;
  status: MetricStatus;
  trend?: Trend;
}

export interface Scorecard {
  period: string;
  rows: ScorecardRow[];
  overall: "healthy" | "watch" | "degraded";
}

/** 结论只看结果指标；流程数量永远不进入这张表。 */
export function scorecard(
  current: GovernanceSnapshot,
  previous?: GovernanceSnapshot,
): Scorecard {
  const trends = previous === undefined
    ? new Map<MetricId, Trend>()
    : new Map(compareTrend(current, previous).map((entry) => [entry.id, entry.trend]));
  const rows = METRIC_CATALOG.map((definition): ScorecardRow => {
    const trend = trends.get(definition.id);
    return {
      definition,
      value: metricValue(current, definition.id),
      status: metricStatus(definition, metricValue(current, definition.id)),
      ...(trend === undefined ? {} : { trend }),
    };
  });
  const failure = metricValue(current, "change-failure-rate");
  const leadTime = metricValue(current, "capability-lead-time");
  const degraded = failure > 0.15 || leadTime > 21;
  const watching = rows.some((row) => row.status === "off-target"
    || row.trend === "worsening" || row.trend === "out-of-band");
  return { period: current.period, rows, overall: degraded ? "degraded" : watching ? "watch" : "healthy" };
}