《互联网产品的客户端架构·内容、社交与实时互动》13.3 质量场景与风险清单：进入卷三

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

export type QualityAttribute =
  | "first-paint"
  | "weak-network"
  | "disconnect"
  | "memory"
  | "moderation"
  | "multi-device";

export type EvidenceLevel = "L1" | "L2" | "L3" | "none";
export type RiskLevel = "low" | "medium" | "high";

export interface QualityScenario {
  id: QualityAttribute;
  name: string;
  stimulus: string;
  response: string;
  metric: string;
  budget: string;
  evidence: EvidenceLevel;
  evidenceNote: string;
  likelihood: 1 | 2 | 3 | 4 | 5;
  impact: 1 | 2 | 3 | 4 | 5;
  mitigation: string;
}

// 六条场景只描述“刺激—响应—度量”，不承诺任何未跑过的数字。
export const SCENARIOS: readonly QualityScenario[] = [
  {
    id: "first-paint",
    name: "首屏可见",
    stimulus: "冷启动后从通知进入首页，网络可用",
    response: "先渲染骨架与缓存中的首屏条目，再补全正文与计数",
    metric: "首屏可交互时间、骨架稳定时间",
    budget: "P75 ≤ 2.5s（示例值，本卷未实测）",
    evidence: "none",
    evidenceNote: "本卷只有场景模型，未跑浏览器或真机，不能引用为实测结论",
    likelihood: 4,
    impact: 5,
    mitigation: "首屏拆成骨架、缓存快照与增量三段，分别埋点",
  },
  {
    id: "weak-network",
    name: "弱网可用",
    stimulus: "往返时延 300ms、1% 丢包，用户连续下拉与翻页",
    response: "保留已加载条目，分页失败进入重试，不把整页清空",
    metric: "分页成功率、单页重试次数、首屏缓存命中率",
    budget: "P95 单页重试 ≤ 3 次（示例值）",
    evidence: "L2",
    evidenceNote: "13.2 的慢网适配器验证排队与重放，不模拟真实 RTT 与丢包",
    likelihood: 4,
    impact: 4,
    mitigation: "缓存快照兜底，失败只影响当前页，不触发全量刷新",
  },
  {
    id: "disconnect",
    name: "断线恢复",
    stimulus: "长连接断开 60 秒，期间产生 30 条新消息",
    response: "退避重连，按连续高水位补拉，补拉与实时推送共用去重容器",
    metric: "恢复后剩余空洞数、重连耗时、重复应用条数",
    budget: "可补空洞为 0，重复应用为 0（示例值）",
    evidence: "L2",
    evidenceNote: "13.2 用假时钟与脚本化响应验证补拉，未跑真实 socket",
    likelihood: 3,
    impact: 5,
    mitigation: "补拉报告保留 remainingGaps，补不全时交给 UI 明示",
  },
  {
    id: "memory",
    name: "长会话内存",
    stimulus: "连续滑动 30 分钟，跨越数千条内容",
    response: "窗口按上限淘汰，淘汰条目同步移出去重集合，锚点不被误删",
    metric: "窗口条目数、去重集合大小、JS 堆增长",
    budget: "窗口 ≤ 200 条，堆增长 ≤ 20%（示例值）",
    evidence: "L2",
    evidenceNote: "1.2 的容器淘汰用例验证计数与去重集合，未测真机堆与图片缓存",
    likelihood: 3,
    impact: 3,
    mitigation: "上限可配置，淘汰与去重清理放在同一个方法里",
  },
  {
    id: "moderation",
    name: "审核态不闪正文",
    stimulus: "发布内容命中审核，随后被下架",
    response: "详情显示审核占位，信息流显示标记，不提前渲染正文",
    metric: "审核态正文泄露次数、占位切换抖动次数",
    budget: "正文泄露 0 次（示例值）",
    evidence: "none",
    evidenceNote: "本卷只有内容状态模型，没有审核 UI 与申诉链路的实测",
    likelihood: 3,
    impact: 5,
    mitigation: "渲染前先判 state，审核态只走占位分支",
  },
  {
    id: "multi-device",
    name: "多端一致",
    stimulus: "两端同时收到同一批通知，其中一端先读",
    response: "以服务端 ackSeq 为准，旧快照不回退角标，已读事件幂等",
    metric: "两端未读角标差值、旧快照回退次数",
    budget: "最终差值 0，回退 0 次（示例值）",
    evidence: "none",
    evidenceNote: "第 10 章的未读合并只在单端建模，跨端一致性未在本卷验证",
    likelihood: 2,
    impact: 4,
    mitigation: "快照带 ackSeq，端上只接受不小于当前水位的响应",
  },
];

export function riskScore(scenario: QualityScenario): number {
  return scenario.likelihood * scenario.impact;
}

export function riskLevel(score: number): RiskLevel {
  if (!Number.isInteger(score) || score < 1 || score > 25) {
    throw new RangeError("风险分必须是 1 到 25 的整数");
  }
  if (score >= 15) return "high";
  if (score >= 8) return "medium";
  return "low";
}

export interface RankedRisk {
  id: QualityAttribute;
  name: string;
  score: number;
  level: RiskLevel;
}

export function rankedRisks(scenarios: readonly QualityScenario[] = SCENARIOS): RankedRisk[] {
  return scenarios
    .map((scenario) => {
      const score = riskScore(scenario);
      return { id: scenario.id, name: scenario.name, score, level: riskLevel(score) };
    })
    .sort((a, b) => b.score - a.score || a.id.localeCompare(b.id));
}

export interface CoverageReport {
  total: number;
  verified: number;
  unverified: number;
  byEvidence: Record<EvidenceLevel, number>;
  unverifiedIds: QualityAttribute[];
  topRisk: QualityAttribute | null;
}

export function coverage(scenarios: readonly QualityScenario[] = SCENARIOS): CoverageReport {
  const byEvidence: Record<EvidenceLevel, number> = { L1: 0, L2: 0, L3: 0, none: 0 };
  const unverifiedIds: QualityAttribute[] = [];
  for (const scenario of scenarios) {
    byEvidence[scenario.evidence] += 1;
    if (scenario.evidence === "none") unverifiedIds.push(scenario.id);
  }
  const risks = rankedRisks(scenarios);
  return {
    total: scenarios.length,
    verified: scenarios.length - unverifiedIds.length,
    unverified: unverifiedIds.length,
    byEvidence,
    unverifiedIds,
    topRisk: risks.length > 0 ? risks[0].id : null,
  };
}

export function scenarioOf(id: QualityAttribute): QualityScenario {
  const found = SCENARIOS.find((scenario) => scenario.id === id);
  if (!found) throw new Error(`未知质量场景: ${id}`);
  return { ...found };
}

// 交接不是“以后再说”，而是把本卷证明不了的部分写成卷三的输入。
export const VOLUME3_HANDOFF: readonly string[] = [
  "交易一致性会收紧乐观更新：支付、下单与库存不能沿用点赞的本地先行（见 5.3 的四档策略）",
  "多端一致需要服务端 ackSeq、版本号与冲突解决，端上合并只能保证单端收敛",
  "审核态需要真实审核链路、申诉状态机与证据留存，本卷只有内容状态模型",
  "首屏、内存与弱网预算需要真机与浏览器基线，L2 假时钟不能替代",
];

$ node --test test/summary/quality.test.ts
✔ 质量场景目录包含六条且 id 唯一 (1.298416ms)
✔ 每条场景都给出刺激、响应、度量、预算与证据说明 (0.288125ms)
✔ 风险等级在 8 与 15 两个边界切换 (0.378834ms)
✔ 风险排序按分数降序，同分时 id 字典序稳定 (8.907541ms)
✔ 覆盖率报告区分已验证与未验证场景 (0.220791ms)
✔ 按 id 取场景返回副本，未知 id 直接报错 (0.126584ms)
✔ 交接到卷三的风险清单非空且覆盖交易一致性 (0.079667ms)
ℹ tests 7
ℹ suites 0
ℹ pass 7
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 139.879709