《互联网产品的客户端架构·交易、增长与平台化》13.3 质量场景与风险清单：进入卷四

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

export type QualityTier = "L1" | "L2" | "L3";
export type RiskLevel = "high" | "medium" | "low";
export type Volume4Area = "multi-client" | "scale" | "platform";

export interface QualityScenario {
  id: string; chapter: number; title: string; assertion: string;
  tier: QualityTier; risk: RiskLevel; evidence: string; volume4: Volume4Area | null;
}

// 前 12 章的关键约束，每条都必须能变成一条可执行断言。
export const QUALITY_SCENARIOS: QualityScenario[] = [
  {
    id: "money-integer-cents", chapter: 1, title: "金额只用整数分",
    assertion: "任意金额运算前后都是安全整数，渲染只在边界转元",
    tier: "L1", risk: "high", evidence: "金额边界用例 + 溢出拒绝用例", volume4: null,
  },
  {
    id: "field-ownership", chapter: 1, title: "金额与订单状态归服务端",
    assertion: "端上不能写服务端字段，合并时服务端覆盖并记录差异",
    tier: "L1", risk: "high", evidence: "所有权查表与合并差异用例", volume4: "multi-client",
  },
  {
    id: "three-sources", chapter: 2, title: "价格、库存、时效同源",
    assertion: "结算页的价格与库存来自同一版本快照，不拼接旧缓存",
    tier: "L1", risk: "high", evidence: "版本号绑定与过期标注用例", volume4: null,
  },
  {
    id: "stock-server-confirm", chapter: 2, title: "库存以下单结果为准",
    assertion: "端上只判断可尝试，扣减结果由服务端返回",
    tier: "L1", risk: "high", evidence: "降级状态与 requiresServerConfirm 用例", volume4: "scale",
  },
  {
    id: "single-breakdown", chapter: 3, title: "价格明细单一版本",
    assertion: "所有展示读同一个明细对象，同版本金额冲突直接报错",
    tier: "L1", risk: "high", evidence: "版本合并与金额不一致用例", volume4: "scale",
  },
  {
    id: "idempotent-submit", chapter: 4, title: "提交幂等",
    assertion: "同幂等键重试得到同一订单，结果未知时先查询",
    tier: "L2", risk: "high", evidence: "重复提交与超时查询时间线", volume4: null,
  },
  {
    id: "order-state-whitelist", chapter: 4, title: "订单状态白名单",
    assertion: "未知状态不猜测语义，不开放支付、取消、退款入口",
    tier: "L1", risk: "high", evidence: "未知状态与非法迁移拒绝用例", volume4: null,
  },
  {
    id: "payment-timeout", chapter: 4, title: "支付超时先查后重试",
    assertion: "超时不是失败，查询确认前不允许再次发起支付",
    tier: "L3", risk: "high", evidence: "回调延迟与查询确认用例", volume4: "platform",
  },
  {
    id: "pay-orchestration", chapter: 5, title: "支付编排只产生一条支付单",
    assertion: "拉起、轮询、回跳共享同一支付单，重复动作不新建支付",
    tier: "L3", risk: "high", evidence: "回跳丢失与轮询确认时间线", volume4: "platform",
  },
  {
    id: "no-double-pay", chapter: 6, title: "禁止重复支付",
    assertion: "成功支付后任何重试入口关闭，渠道重复通知只生效一次",
    tier: "L3", risk: "high", evidence: "重复通知与重试拒绝用例", volume4: null,
  },
  {
    id: "coupon-eligibility", chapter: 7, title: "优惠券资格与叠加",
    assertion: "不满足门槛或互斥的券不可选，叠加顺序固定",
    tier: "L1", risk: "medium", evidence: "门槛边界与互斥组合用例", volume4: "platform",
  },
  {
    id: "member-benefit", chapter: 8, title: "会员价与积分账本",
    assertion: "会员价由服务端下发，积分只增不减地展示账本，到期时间统一口径",
    tier: "L1", risk: "medium", evidence: "会员价来源与积分账本汇总用例", volume4: "multi-client",
  },
  {
    id: "share-attribution", chapter: 9, title: "分享参数与邀请绑定",
    assertion: "分享参数完整透传，邀请关系只绑定一次，降级页不丢关键参数",
    tier: "L1", risk: "medium", evidence: "参数透传与重复绑定用例", volume4: "multi-client",
  },
  {
    id: "experiment-split", chapter: 10, title: "实验分流可复现",
    assertion: "同一用户与实验配置得到同一分组，配置变更可追溯",
    tier: "L1", risk: "medium", evidence: "分流稳定性与配置版本用例", volume4: "platform",
  },
  {
    id: "aftersale-evidence", chapter: 11, title: "售后上下文与证据留存",
    assertion: "售后页读订单快照，证据本地留存，提交失败可恢复且不改写历史",
    tier: "L2", risk: "medium", evidence: "断网恢复与快照不可变用例", volume4: null,
  },
  {
    id: "attribution-boundary", chapter: 12, title: "漏斗与归因的端上边界",
    assertion: "端上只上报白名单字段，去重键由服务端下发，不本地补归因",
    tier: "L2", risk: "medium", evidence: "字段白名单与重复上报用例", volume4: "multi-client",
  },
];

const RISK_RANK: Record<RiskLevel, number> = { high: 0, medium: 1, low: 2 };

export function validateScenario(scenario: QualityScenario): string[] {
  const issues: string[] = [];
  if (scenario.id.trim() === "") issues.push("场景 id 不能为空");
  if (!Number.isInteger(scenario.chapter) || scenario.chapter < 1) {
    issues.push(`章节号非法：${scenario.id}`);
  }
  if (scenario.assertion.trim().length < 8) {
    issues.push(`断言不可执行：${scenario.id}`);
  }
  if (scenario.evidence.trim() === "") {
    issues.push(`缺少证据要求：${scenario.id}`);
  }
  return issues;
}

export interface LedgerSummary {
  total: number; executable: number; highRisk: number; volume4: number;
  issues: string[];
}

export function evaluateLedger(list: QualityScenario[]): LedgerSummary {
  const seen = new Set<string>();
  const issues: string[] = [];
  let highRisk = 0;
  let volume4 = 0;
  for (const scenario of list) {
    if (seen.has(scenario.id)) issues.push(`场景 id 重复：${scenario.id}`);
    seen.add(scenario.id);
    issues.push(...validateScenario(scenario));
    if (scenario.risk === "high") highRisk += 1;
    if (scenario.volume4 !== null) volume4 += 1;
  }
  return {
    total: list.length,
    executable: list.filter(
      (scenario) =>
        scenario.assertion.trim().length >= 8 && scenario.evidence.trim() !== "",
    ).length,
    highRisk,
    volume4,
    issues,
  };
}

export function chapterCoverage(list: QualityScenario[]): number[] {
  return [...new Set(list.map((scenario) => scenario.chapter))].sort((a, b) => a - b);
}

export function missingChapters(list: QualityScenario[], expected: number[]): number[] {
  const covered = new Set(chapterCoverage(list));
  return expected.filter((chapter) => !covered.has(chapter));
}

export function volume4Items(
  list: QualityScenario[],
): Record<Volume4Area, QualityScenario[]> {
  const grouped: Record<Volume4Area, QualityScenario[]> = {
    "multi-client": [], scale: [], platform: [],
  };
  for (const scenario of list) {
    if (scenario.volume4 !== null) grouped[scenario.volume4].push(scenario);
  }
  return grouped;
}

export interface GateResult { passed: boolean; blocked: string[]; warnings: string[] }

// 高风险失败阻断发布；中风险失败进入警告；未知场景按阻断处理。
export function releaseGate(list: QualityScenario[], failedIds: string[]): GateResult {
  const byId = new Map(list.map((scenario) => [scenario.id, scenario]));
  const blocked: string[] = [];
  const warnings: string[] = [];
  for (const id of failedIds) {
    const scenario = byId.get(id);
    if (scenario === undefined) blocked.push(`未知场景：${id}`);
    else if (scenario.risk === "high") blocked.push(id);
    else warnings.push(id);
  }
  return { passed: blocked.length === 0, blocked, warnings };
}

export interface RiskRow {
  id: string; chapter: number; risk: RiskLevel;
  tier: QualityTier; volume4: Volume4Area | null;
}

export function riskLedger(list: QualityScenario[]): RiskRow[] {
  return [...list]
    .sort((a, b) => RISK_RANK[a.risk] - RISK_RANK[b.risk] ||
      a.chapter - b.chapter || a.id.localeCompare(b.id))
    .map((scenario) => ({
      id: scenario.id, chapter: scenario.chapter, risk: scenario.risk,
      tier: scenario.tier, volume4: scenario.volume4,
    }));
}

export function countByTier(list: QualityScenario[]): Record<QualityTier, number> {
  return {
    L1: list.filter((scenario) => scenario.tier === "L1").length,
    L2: list.filter((scenario) => scenario.tier === "L2").length,
    L3: list.filter((scenario) => scenario.tier === "L3").length,
  };
}

$ node --test --test-concurrency=1 test/summary/quality-scenarios.test.ts
✔ 完整台账没有校验问题 (2.475ms)
✔ 场景 id 不重复 (0.102708ms)
✔ 第 1 到 12 章都有覆盖 (0.199583ms)
✔ 高风险场景不少于十个 (0.110125ms)
✔ 缺少断言时校验失败 (0.1545ms)
✔ 缺少证据时校验失败 (0.09275ms)
✔ 章节号非法时校验失败 (0.067625ms)
✔ 空 id 与合法场景分别被拒绝和接受 (0.065083ms)
✔ 重复 id 进入台账问题 (0.08125ms)
✔ 卷四移交项按三个方向分组且总数一致 (0.165833ms)
✔ 高风险失败阻断发布 (0.107458ms)
✔ 中风险失败只产生警告 (0.062708ms)
✔ 没有失败项时门禁通过 (0.045041ms)
✔ 未知失败项按阻断处理 (0.043667ms)
✔ 风险台账高风险排在低风险之前 (8.93775ms)
✔ 三级数量之和等于场景总数 (0.125625ms)
✔ 支付相关场景至少有一条 L3 (0.072375ms)
✔ 每条场景都有可读标题与证据 (0.066292ms)
ℹ tests 18
ℹ suites 0
ℹ pass 18
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 161.870708