《互联网产品的客户端架构·规模化与架构演进》13.2 平台化验收：能力矩阵与治理清单

// file: src/summary/platform-matrix.ts
// tier: L1
// verify: node --test test/summary/platform-matrix.test.ts

export type DimensionId = "promise" | "component" | "delivery" | "observability" | "security" | "governance";

export const DIMENSIONS: DimensionId[] = [
  "promise", "component", "delivery", "observability", "security", "governance",
];

export const DIMENSION_TITLES: Record<DimensionId, string> = {
  promise: "承诺", component: "组件", delivery: "交付",
  observability: "观测", security: "安全", governance: "治理",
};

const WEIGHTS: Record<DimensionId, number> = {
  promise: 1.2, component: 1, delivery: 1, observability: 1, security: 1.3, governance: 1.1,
};

export type MaturityItem = {
  id: string;
  dimension: DimensionId;
  title: string;
  score: number;
  evidence: string;
  blocker?: boolean;
};

export type DimensionScore = {
  dimension: DimensionId;
  title: string;
  count: number;
  average: number;
  min: number;
  weak: string[];
};

export type GapSeverity = "blocker" | "major" | "minor";
export type Gap = {
  id: string;
  dimension: DimensionId;
  title: string;
  score: number;
  severity: GapSeverity;
};

export type AcceptancePolicy = {
  minDimensionAverage: number;
  minItemScore: number;
  minOverall: number;
  requireEvidence: boolean;
  requiredDimensions: DimensionId[];
};

export type AcceptanceResult = {
  passed: boolean;
  overall: number;
  dimensions: DimensionScore[];
  blockers: string[];
  warnings: string[];
  gaps: Gap[];
};

export const DEFAULT_POLICY: AcceptancePolicy = {
  minDimensionAverage: 3, minItemScore: 3, minOverall: 3.5,
  requireEvidence: true, requiredDimensions: DIMENSIONS,
};

export function validateItem(item: MaturityItem): string[] {
  const issues: string[] = [];
  if (item.id.trim() === "") issues.push("条目 id 不能为空");
  if (!Number.isInteger(item.score) || item.score < 0 || item.score > 5) {
    issues.push(`分值必须是 0 到 5 的整数：${item.id}`);
  }
  if (item.evidence.trim() === "") issues.push(`缺少证据：${item.id}`);
  if (!DIMENSIONS.includes(item.dimension)) issues.push(`未知维度：${item.id}`);
  return issues;
}

export function scoreDimension(
  items: MaturityItem[],
  dimension: DimensionId,
  minItemScore = 3,
): DimensionScore {
  const scoped = items.filter((item) => item.dimension === dimension);
  return {
    dimension,
    title: DIMENSION_TITLES[dimension],
    count: scoped.length,
    average: scoped.length === 0 ? 0 : scoped.reduce((acc, item) => acc + item.score, 0) / scoped.length,
    min: scoped.length === 0 ? 0 : Math.min(...scoped.map((item) => item.score)),
    weak: scoped.filter((item) => item.score < minItemScore).map((item) => item.id),
  };
}

export function maturityMatrix(items: MaturityItem[], minItemScore = 3): Record<DimensionId, DimensionScore> {
  const matrix = {} as Record<DimensionId, DimensionScore>;
  for (const dimension of DIMENSIONS) matrix[dimension] = scoreDimension(items, dimension, minItemScore);
  return matrix;
}

export function dimensionAverages(items: MaturityItem[]): Record<DimensionId, number> {
  const matrix = maturityMatrix(items);
  const averages = {} as Record<DimensionId, number>;
  for (const dimension of DIMENSIONS) averages[dimension] = matrix[dimension].average;
  return averages;
}

export function weightedOverall(items: MaturityItem[]): number {
  let weighted = 0;
  let weight = 0;
  for (const dimension of DIMENSIONS) {
    const score = scoreDimension(items, dimension);
    if (score.count === 0) continue;
    weighted += score.average * WEIGHTS[dimension];
    weight += WEIGHTS[dimension];
  }
  return weight === 0 ? 0 : Math.round((weighted / weight) * 100) / 100;
}

export function gapRanking(items: MaturityItem[], target = 4): Gap[] {
  const order = new Map(DIMENSIONS.map((dimension, index) => [dimension, index]));
  return items
    .filter((item) => item.score < target)
    .map((item) => ({
      id: item.id,
      dimension: item.dimension,
      title: item.title,
      score: item.score,
      severity: item.score < 3 ? "blocker" : item.score === 3 ? "major" : "minor",
    }))
    .sort((a, b) => a.score - b.score ||
      (order.get(a.dimension) ?? 99) - (order.get(b.dimension) ?? 99) ||
      a.id.localeCompare(b.id));
}

export function acceptanceGate(items: MaturityItem[], policy: AcceptancePolicy = DEFAULT_POLICY): AcceptanceResult {
  const blockers: string[] = [];
  const warnings: string[] = [];
  for (const item of items) {
    for (const issue of validateItem(item)) blockers.push(`invalid:${item.id}:${issue}`);
  }
  for (const dimension of policy.requiredDimensions) {
    const score = scoreDimension(items, dimension, policy.minItemScore);
    if (score.count === 0) blockers.push(`missing-dimension:${dimension}`);
    else if (score.average < policy.minDimensionAverage) {
      blockers.push(`dimension-average:${dimension}=${score.average.toFixed(2)}`);
    }
  }
  for (const item of items) {
    if (item.score < policy.minItemScore) blockers.push(`item:${item.id}=${item.score}`);
    else if (item.score === policy.minItemScore) warnings.push(`at-threshold:${item.id}`);
    if (policy.requireEvidence && item.evidence.trim() === "") blockers.push(`evidence:${item.id}`);
  }
  const overall = weightedOverall(items);
  if (overall < policy.minOverall) blockers.push(`overall:${overall.toFixed(2)}`);
  return {
    passed: blockers.length === 0,
    overall,
    dimensions: DIMENSIONS.map((dimension) => scoreDimension(items, dimension, policy.minItemScore)),
    blockers: [...new Set(blockers)],
    warnings: [...new Set(warnings)],
    gaps: gapRanking(items),
  };
}

export function topGaps(items: MaturityItem[], limit = 5): Gap[] {
  return gapRanking(items).slice(0, limit);
}

const item = (
  id: string, dimension: DimensionId, title: string, score: number, evidence: string,
): MaturityItem => ({ id, dimension, title, score, evidence });

export const PLATFORM_ITEMS: MaturityItem[] = [
  item("promise-matrix", "promise", "五端一致性承诺矩阵", 4, "承诺矩阵评审记录与跨端契约用例"),
  item("promise-enforcement", "promise", "承诺在发布门禁中强制执行", 3, "发布流水线中的字段断言结果"),
  item("component-contract", "component", "组件契约与版本兼容规则", 4, "契约测试与版本兼容矩阵"),
  item("theme-isolation", "component", "多品牌主题隔离", 2, "主题变量泄漏用例"),
  item("release-pipeline", "delivery", "多端统一发布流水线", 4, "流水线运行记录与灰度比例"),
  item("rollback-drill", "delivery", "灰度回滚演练", 3, "最近一次回滚演练报告"),
  item("field-contract", "observability", "端上观测字段最小契约", 4, "字段白名单与采样配置"),
  item("alert-loop", "observability", "从告警到定位的闭环", 3, "告警响应时长与复盘记录"),
  item("data-classification", "security", "数据分级与采集白名单", 3, "数据分级表与采集评审"),
  item("sdk-registry", "security", "第三方 SDK 登记与下线", 2, "SDK 清单与权限差异报告"),
  item("adr-log", "governance", "架构决策记录", 3, "ADR 目录与最近三次决策"),
  item("ownership-map", "governance", "代码所有权与评审责任", 2, "所有权表与评审覆盖率"),
];