《移动游戏产品的架构·网络、资源与热更新》13.3 卷二评审与进入卷三

// file: src/lab/review-gate-net.ts
// tier: L1
// verify: node --test test/lab/review-gate-net.test.ts
export type ReviewStatus = "pass" | "partial" | "fail";

export interface ReviewItem {
  readonly id: string;
  readonly group: string;
  readonly status: ReviewStatus;
  readonly evidence: string;
}

export interface GroupSummary {
  readonly group: string;
  readonly pass: number;
  readonly partial: number;
  readonly fail: number;
}

export interface GateResult {
  readonly passed: boolean;
  readonly total: number;
  readonly counts: Readonly<Record<ReviewStatus, number>>;
  readonly groups: readonly GroupSummary[];
  readonly blockers: readonly ReviewItem[];
  readonly openGroups: readonly string[];
  readonly reasons: readonly string[];
}

export const REVIEW_GROUPS = [
  "协议与兼容",
  "连接与重连",
  "离线与冲突",
  "同步与预测",
  "战报与赛季",
  "流量与心跳",
  "资源与分包",
  "热更与灰度",
  "下载与 CDN",
] as const;

export function evaluateGate(items: readonly ReviewItem[]): GateResult {
  const reasons: string[] = [];
  const normalized: ReviewItem[] = [];

  for (const item of items) {
    if (item.status === "pass" && item.evidence.trim() === "") {
      reasons.push(`${item.id}: pass without evidence counts as partial`);
      normalized.push({ ...item, status: "partial" });
      continue;
    }
    normalized.push(item);
  }

  const counts: Record<ReviewStatus, number> = { pass: 0, partial: 0, fail: 0 };
  for (const item of normalized) {
    counts[item.status] += 1;
  }

  const groups = REVIEW_GROUPS.map((group) => {
    const scoped = normalized.filter((item) => item.group === group);
    return {
      group,
      pass: scoped.filter((item) => item.status === "pass").length,
      partial: scoped.filter((item) => item.status === "partial").length,
      fail: scoped.filter((item) => item.status === "fail").length,
    };
  });

  const blockers = normalized.filter((item) => item.status !== "pass");
  const openGroups = groups.filter((group) => group.pass === 0).map((group) => group.group);

  if (normalized.length === 0) {
    reasons.push("no review items");
  }
  if (counts.partial > 0) {
    reasons.push(`${counts.partial} partial item(s) block the gate`);
  }
  if (counts.fail > 0) {
    reasons.push(`${counts.fail} failed item(s) block the gate`);
  }

  return {
    passed: normalized.length > 0 && blockers.length === 0,
    total: normalized.length,
    counts,
    groups,
    blockers,
    openGroups,
    reasons,
  };
}

export function failingGroups(result: GateResult): readonly string[] {
  return result.groups.filter((group) => group.fail > 0).map((group) => group.group);
}

export function formatGate(result: GateResult): string {
  const header = "group\tpass\tpartial\tfail";
  const rows = result.groups.map(
    (group) => `${group.group}\t${group.pass}\t${group.partial}\t${group.fail}`,
  );
  return [header, ...rows].join("\n");
}

export const DEFAULT_REVIEW: readonly ReviewItem[] = [
  { id: "protocol", group: "协议与兼容", status: "pass", evidence: "src/net/message-envelope.ts" },
  { id: "contract", group: "协议与兼容", status: "pass", evidence: "src/net/contract-check.ts" },
  { id: "reconnect", group: "连接与重连", status: "pass", evidence: "src/net/connection-fsm.ts" },
  { id: "backoff", group: "连接与重连", status: "pass", evidence: "src/net/backoff.ts" },
  { id: "offline", group: "离线与冲突", status: "pass", evidence: "src/net/offline-queue.ts" },
  { id: "sync", group: "同步与预测", status: "pass", evidence: "src/net/predict.ts" },
  { id: "report", group: "战报与赛季", status: "pass", evidence: "src/net/battle-report.ts" },
  { id: "traffic", group: "流量与心跳", status: "pass", evidence: "src/net/traffic-ledger.ts" },
  { id: "pack", group: "资源与分包", status: "pass", evidence: "src/resource/pack-plan.ts" },
  { id: "hotfix", group: "热更与灰度", status: "pass", evidence: "src/hotfix/rollout.ts" },
  { id: "cdn", group: "下载与 CDN", status: "pass", evidence: "src/cdn/downloader.ts" },
  { id: "telemetry", group: "下载与 CDN", status: "pass", evidence: "src/net/heartbeat.ts" },
];