《互联网产品的客户端架构·端形态与体验基础》13.3 质量属性场景与风险清单

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

export type QualityAttribute =
  | "performance"
  | "reliability"
  | "security"
  | "maintainability";

export type RiskStatus = "open" | "mitigated" | "accepted";
export type RiskLevel = "high" | "medium" | "low";
export type Score = 1 | 2 | 3 | 4 | 5;

export interface RiskScenario {
  id: string;
  title: string;
  attribute: QualityAttribute;
  /** 可观察的触发条件与期望响应 */
  scenario: string;
  /** 影响面：1 可忽略，5 阻断核心任务 */
  impact: Score;
  /** 发生概率：1 罕见，5 几乎每天发生 */
  likelihood: Score;
  /** 发现难度：1 一眼可见，5 只能靠用户投诉 */
  detectability: Score;
  mitigation: string;
  owner: string;
  status: RiskStatus;
}

export interface ScoredRisk extends RiskScenario {
  score: number;
  level: RiskLevel;
  rank: number;
}

export interface RiskRegister {
  entries: ScoredRisk[];
  counts: Record<RiskLevel, number>;
  openHigh: string[];
  verdict: "pass" | "fail";
}

const HIGH_SCORE = 60;
const MEDIUM_SCORE = 25;

function isScore(value: number): value is Score {
  return Number.isInteger(value) && value >= 1 && value <= 5;
}

function levelOf(score: number): RiskLevel {
  if (score >= HIGH_SCORE) return "high";
  if (score >= MEDIUM_SCORE) return "medium";
  return "low";
}

/**
 * 把质量属性场景转成可比较的分数：影响 × 概率 × 发现难度。
 * 发现难度单独乘一次，是因为“用户先发现”的风险不能按低概率处理。
 */
export function scoreRisk(input: RiskScenario): Omit<ScoredRisk, "rank"> {
  if (input.id.trim().length === 0 || input.title.trim().length === 0) {
    throw new Error("风险条目必须有 id 与 title");
  }
  if (input.mitigation.trim().length === 0) {
    throw new Error(`风险 ${input.id} 必须写明缓解措施`);
  }
  for (const [name, value] of [
    ["impact", input.impact],
    ["likelihood", input.likelihood],
    ["detectability", input.detectability],
  ] as const) {
    if (!isScore(value)) {
      throw new Error(`风险 ${input.id} 的 ${name} 必须是 1-5 的整数，收到 ${value}`);
    }
  }
  const score = input.impact * input.likelihood * input.detectability;
  return { ...input, score, level: levelOf(score) };
}

/** 按分数降序、同分按 id 升序生成排名；只有 open 的高风险会阻塞结论。 */
export function buildRiskRegister(scenarios: RiskScenario[]): RiskRegister {
  const seen = new Set<string>();
  for (const scenario of scenarios) {
    if (seen.has(scenario.id)) throw new Error(`重复风险编号: ${scenario.id}`);
    seen.add(scenario.id);
  }

  const entries: ScoredRisk[] = scenarios
    .map(scoreRisk)
    .sort((a, b) => b.score - a.score || a.id.localeCompare(b.id))
    .map((risk, index) => ({ ...risk, rank: index + 1 }));

  const counts: Record<RiskLevel, number> = { high: 0, medium: 0, low: 0 };
  for (const entry of entries) counts[entry.level] += 1;

  const openHigh = entries
    .filter((entry) => entry.status === "open" && entry.level === "high")
    .map((entry) => entry.id);

  return {
    entries,
    counts,
    openHigh,
    verdict: openHigh.length === 0 ? "pass" : "fail",
  };
}

/** 固定格式的评审输出：第一行是分布，中间是排名，最后一行是结论。 */
export function formatRiskRegister(register: RiskRegister): string[] {
  const { high, medium, low } = register.counts;
  const lines = [
    `风险清单：${register.entries.length} 条，high ${high} / medium ${medium} / low ${low}`,
  ];
  for (const entry of register.entries) {
    lines.push(
      `${entry.rank}. [${entry.level} ${entry.score}] ${entry.id} ${entry.title} / ${entry.attribute} / ${entry.status} / owner=${entry.owner}`,
    );
  }
  lines.push(
    register.verdict === "pass"
      ? "评审结论：pass"
      : `评审结论：fail，未关闭高风险：${register.openHigh.join(",")}`,
  );
  return lines;
}

node --test test/summary/risk-register.test.ts

✔ 四个场景按影响×概率×发现难度排序，只有 open 高风险阻塞结论 (0.958917ms)
✔ 高风险全部关闭后结论转为 pass，medium 未关闭不阻塞 (0.101084ms)
✔ 评分维度越界或非整数时直接拒绝，不静默截断 (0.277292ms)
✔ 重复风险编号在进入排名前被拒绝 (0.075167ms)
✔ 评审输出固定为分布、排名、结论三段 (0.111875ms)
ℹ tests 5
ℹ suites 0
ℹ pass 5
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 176.362208

风险清单：4 条，high 2 / medium 2 / low 0
1. [high 80] R-03 支付回调重复 / security / open / owner=支付组
2. [high 60] R-02 进程回收恢复 / reliability / open / owner=客户端组
3. [medium 48] R-01 弱网打开 / performance / open / owner=客户端组
4. [medium 30] R-04 包体超限 / maintainability / mitigated / owner=构建组
评审结论：fail，未关闭高风险：R-03,R-02