《互联网产品的 AI 架构·平台化与治理》6.3 质量报告与季度复盘

mix    = Σ (s1 - s0) × r0
rate   = Σ s0 × (r1 - r0)
inter  = Σ (s1 - s0) × (r1 - r0)
total  = mix + rate + inter

// file: src/gov/quality-review.ts
// tier: L2
// verify: node --test test/gov/quality-ops.test.ts

export interface SegmentQuality {
  segment: string;
  baselinePassed: number;
  baselineTotal: number;
  currentPassed: number;
  currentTotal: number;
}

export interface SegmentAttribution {
  segment: string;
  baselineShare: number;
  currentShare: number;
  baselineRate: number;
  currentRate: number;
  deltaPp: number;
  mixPp: number;
  ratePp: number;
  interactionPp: number;
}

export interface QualityAttribution {
  baselineRate: number;
  currentRate: number;
  deltaPp: number;
  mixEffectPp: number;
  rateEffectPp: number;
  interactionPp: number;
  segments: readonly SegmentAttribution[];
}

/**
 * 季度差异拆成三块：份额变化（mix）、分段合格率变化（rate）与交叉项。
 * 三项相加精确等于总差异；数值单位是百分点。
 */
export function decomposeQuality(segments: readonly SegmentQuality[]): QualityAttribution {
  if (segments.length === 0) throw new Error("quality-review: segments must not be empty");
  const seen = new Set<string>();
  for (const segment of segments) {
    if (segment.segment.trim() === "" || seen.has(segment.segment)) {
      throw new Error(`quality-review: invalid or duplicate segment ${segment.segment}`);
    }
    seen.add(segment.segment);
    for (const [passed, total] of [
      [segment.baselinePassed, segment.baselineTotal],
      [segment.currentPassed, segment.currentTotal],
    ]) {
      if (!Number.isInteger(total) || total <= 0 || !Number.isInteger(passed) || passed < 0 || passed > total) {
        throw new Error(`quality-review: invalid counts for ${segment.segment}`);
      }
    }
  }
  const baselineTotal = segments.reduce((sum, segment) => sum + segment.baselineTotal, 0);
  const currentTotal = segments.reduce((sum, segment) => sum + segment.currentTotal, 0);
  const baselinePassed = segments.reduce((sum, segment) => sum + segment.baselinePassed, 0);
  const currentPassed = segments.reduce((sum, segment) => sum + segment.currentPassed, 0);
  const baselineRate = baselinePassed / baselineTotal;
  const currentRate = currentPassed / currentTotal;
  let mix = 0;
  let rate = 0;
  const rows = segments.map((segment): SegmentAttribution => {
    const baselineShare = segment.baselineTotal / baselineTotal;
    const currentShare = segment.currentTotal / currentTotal;
    const baseRate = segment.baselinePassed / segment.baselineTotal;
    const currRate = segment.currentPassed / segment.currentTotal;
    const mixPp = (currentShare - baselineShare) * baseRate * 100;
    const ratePp = baselineShare * (currRate - baseRate) * 100;
    mix += mixPp;
    rate += ratePp;
    return {
      segment: segment.segment,
      baselineShare: round4(baselineShare),
      currentShare: round4(currentShare),
      baselineRate: round4(baseRate),
      currentRate: round4(currRate),
      deltaPp: round4((currRate - baseRate) * 100),
      mixPp: round4(mixPp),
      ratePp: round4(ratePp),
      interactionPp: round4((currentShare - baselineShare) * (currRate - baseRate) * 100),
    };
  });
  const deltaPp = round4((currentRate - baselineRate) * 100);
  const mixEffectPp = round4(mix);
  const rateEffectPp = round4(rate);
  return {
    baselineRate: round4(baselineRate),
    currentRate: round4(currentRate),
    deltaPp,
    mixEffectPp,
    rateEffectPp,
    interactionPp: round4(deltaPp - mixEffectPp - rateEffectPp),
    segments: rows,
  };
}

export interface ReviewAction {
  id: string;
  cause: string;
  change: string;
  owner: string;
  dueDate: string;
  verification: { metric: string; target: string };
  status: "proposed" | "in-progress" | "done";
}

export interface QuarterReview {
  quarter: string;
  baselineLabel: string;
  currentLabel: string;
  reviewDate: string;
  attribution: QualityAttribution;
  actions: readonly ReviewAction[];
}

export type ReviewIssueCode =
  | "invalid-quarter" | "unfrozen-baseline" | "missing-review-date" | "no-actions"
  | "missing-owner" | "missing-cause" | "missing-change" | "missing-verification"
  | "due-outside-window" | "duplicate-action-id";

export interface ReviewIssue {
  code: ReviewIssueCode;
  actionId?: string;
  detail: string;
}

const QUARTER_PATTERN = /^(\d{4})Q([1-4])$/;

/** 行动项最晚可以落到下一个季度末；再远就不是本季度复盘能跟踪的范围。 */
export function reviewWindowEnd(quarter: string): string {
  const match = QUARTER_PATTERN.exec(quarter);
  if (match === null) throw new Error(`quality-review: invalid quarter ${quarter}`);
  const index = Number(match[2]);
  const year = index === 4 ? Number(match[1]) + 1 : Number(match[1]);
  const endMonth = (index === 4 ? 1 : index + 1) * 3;
  return `${year}-${pad(endMonth)}-${lastDay(year, endMonth)}`;
}

export function validateReview(review: QuarterReview): ReviewIssue[] {
  const issues: ReviewIssue[] = [];
  if (!QUARTER_PATTERN.test(review.quarter)) {
    return [{ code: "invalid-quarter", detail: `季度 ${review.quarter} 不是 YYYYQn 格式` }];
  }
  const windowEnd = reviewWindowEnd(review.quarter);
  if (review.baselineLabel.trim() === "") {
    issues.push({ code: "unfrozen-baseline", detail: "基线没有冻结标签，季度中改口径会让差异无法解释" });
  }
  if (review.reviewDate.trim() === "") {
    issues.push({ code: "missing-review-date", detail: "缺少复盘日期" });
  }
  if (review.actions.length === 0) {
    issues.push({ code: "no-actions", detail: "复盘没有行动项，只是一次汇报" });
  }
  const ids = new Set<string>();
  for (const action of review.actions) {
    if (ids.has(action.id)) {
      issues.push({ code: "duplicate-action-id", actionId: action.id, detail: "行动项 id 重复" });
    }
    ids.add(action.id);
    if (action.owner.trim() === "") {
      issues.push({ code: "missing-owner", actionId: action.id, detail: "行动项没有负责人" });
    }
    if (action.cause.trim() === "") {
      issues.push({ code: "missing-cause", actionId: action.id, detail: "行动项没有对应的归因" });
    }
    if (action.change.trim() === "") {
      issues.push({ code: "missing-change", actionId: action.id, detail: "行动项没有具体改动" });
    }
    if (action.verification.metric.trim() === "" || action.verification.target.trim() === "") {
      issues.push({ code: "missing-verification", actionId: action.id, detail: "行动项没有复查指标或目标" });
    }
    if (action.dueDate.trim() === "" || action.dueDate < review.reviewDate || action.dueDate > windowEnd) {
      issues.push({
        code: "due-outside-window",
        actionId: action.id,
        detail: `截止日期必须落在 ${review.reviewDate} 到 ${windowEnd} 之间`,
      });
    }
  }
  return issues;
}

export type ReportMetricKind = "rate" | "count" | "event-count" | "duration" | "ordinal-mean" | "score";

export interface ReportMetric {
  name: string;
  kind: ReportMetricKind;
  numerator?: number;
  denominator?: number;
  scope?: string;
}

export type MetricIssueCode = "missing-denominator" | "count-as-quality" | "ordinal-mean" | "missing-scope";

export interface MetricIssue {
  name: string;
  code: MetricIssueCode;
  detail: string;
}

/**
 * 报告指标的准入检查。它不判断业务好坏，只拦三类无法解释的口径：
 * 没有分母的比率、没有分母的质量计数、以及把序数量表当连续量求平均。
 */
export function auditMetrics(metrics: readonly ReportMetric[]): MetricIssue[] {
  const issues: MetricIssue[] = [];
  for (const metric of metrics) {
    if (metric.scope === undefined || metric.scope.trim() === "") {
      issues.push({ name: metric.name, code: "missing-scope", detail: "指标没有说明能力、租户或链路范围" });
    }
    if (metric.kind === "rate") {
      if (
        metric.numerator === undefined || metric.denominator === undefined ||
        !Number.isFinite(metric.numerator) || !Number.isFinite(metric.denominator) ||
        metric.denominator <= 0 || metric.numerator < 0 || metric.numerator > metric.denominator
      ) {
        issues.push({ name: metric.name, code: "missing-denominator", detail: "比率必须给出有效的分子与分母" });
      }
    } else if (metric.kind === "count") {
      issues.push({ name: metric.name, code: "count-as-quality", detail: "质量结论不能用绝对计数，必须换算成带分母的比率" });
    } else if (metric.kind === "ordinal-mean") {
      issues.push({ name: metric.name, code: "ordinal-mean", detail: "满意度是序数量表，应报分布而不是直接求平均" });
    }
  }
  return issues;
}

function round4(value: number): number {
  return Math.round(value * 1e4) / 1e4;
}

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

function lastDay(year: number, month: number): number {
  return new Date(Date.UTC(year, month, 0)).getUTCDate();
}