《互联网产品的客户端架构·端形态与体验基础》3.3 不可能三角与优先级

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

export type QualityAxis = "startup" | "features" | "size";

export interface OptionProfile {
  id: string;
  /** 首屏耗时，越低越好 */
  startupMs: number;
  /** 已覆盖的核心功能数，越高越好 */
  featureCount: number;
  /** 首包体积，越低越好 */
  bundleKb: number;
}

export interface QualityTargets {
  startupMs: number;
  minFeatures: number;
  maxBundleKb: number;
}

export interface PriorityWeight {
  axis: QualityAxis;
  weight: number;
}

export interface RankedOption {
  id: string;
  score: number;
  feasible: boolean;
  deficits: string[];
  normalized: Record<QualityAxis, number>;
}

interface Range {
  min: number;
  max: number;
}

function rangeOf(values: readonly number[]): Range {
  return { min: Math.min(...values), max: Math.max(...values) };
}

/** 越小越好的指标：集合内最慢得 0，最快得 1。 */
function inverseScore(value: number, range: Range): number {
  if (range.max === range.min) {
    return 1;
  }
  return (range.max - value) / (range.max - range.min);
}

/** 越大越好的指标：集合内最少得 0，最多得 1。 */
function directScore(value: number, range: Range): number {
  if (range.max === range.min) {
    return 1;
  }
  return (value - range.min) / (range.max - range.min);
}

export function findDeficits(
  option: OptionProfile,
  targets: QualityTargets,
): string[] {
  const deficits: string[] = [];
  if (option.startupMs > targets.startupMs) {
    deficits.push(`首屏 ${option.startupMs}ms 超过上限 ${targets.startupMs}ms`);
  }
  if (option.featureCount < targets.minFeatures) {
    deficits.push(`功能 ${option.featureCount} 项低于下限 ${targets.minFeatures} 项`);
  }
  if (option.bundleKb > targets.maxBundleKb) {
    deficits.push(`首包 ${option.bundleKb}KB 超过上限 ${targets.maxBundleKb}KB`);
  }
  return deficits;
}

function validateWeights(weights: readonly PriorityWeight[]): void {
  const seen = new Set<QualityAxis>();
  let total = 0;
  for (const item of weights) {
    if (item.weight < 0) {
      throw new Error(`权重不能为负：${item.axis}`);
    }
    if (seen.has(item.axis)) {
      throw new Error(`权重轴重复：${item.axis}`);
    }
    seen.add(item.axis);
    total += item.weight;
  }
  if (seen.size !== 3) {
    throw new Error("权重必须覆盖 startup、features、size 三个轴");
  }
  if (Math.abs(total - 1) > 1e-9) {
    throw new Error(`权重之和必须为 1，当前为 ${total}`);
  }
}

/**
 * 三个维度先在候选人集合内做 min-max 归一化，再加权求和。
 * 归一化是相对当前候选人，不是相对绝对标准：
 * 这样即使所有方案都“不够快”，排序仍然能回答“谁相对更快”。
 * feasible 只标记是否满足目标，不直接否决；否决权留给评审。
 */
export function rankOptions(
  options: readonly OptionProfile[],
  targets: QualityTargets,
  weights: readonly PriorityWeight[],
): RankedOption[] {
  validateWeights(weights);
  if (options.length === 0) {
    return [];
  }
  const ids = new Set(options.map((option) => option.id));
  if (ids.size !== options.length) {
    throw new Error("候选人 id 必须唯一");
  }

  const startupRange = rangeOf(options.map((option) => option.startupMs));
  const featureRange = rangeOf(options.map((option) => option.featureCount));
  const sizeRange = rangeOf(options.map((option) => option.bundleKb));

  const ranked = options.map((option) => {
    const normalized: Record<QualityAxis, number> = {
      startup: inverseScore(option.startupMs, startupRange),
      features: directScore(option.featureCount, featureRange),
      size: inverseScore(option.bundleKb, sizeRange),
    };
    const score = weights.reduce(
      (sum, item) => sum + normalized[item.axis] * item.weight,
      0,
    );
    const deficits = findDeficits(option, targets);
    return {
      id: option.id,
      score,
      feasible: deficits.length === 0,
      deficits,
      normalized,
    };
  });

  return ranked.sort((left, right) => {
    if (right.score !== left.score) {
      return right.score - left.score;
    }
    if (left.feasible !== right.feasible) {
      return left.feasible ? -1 : 1;
    }
    return left.id.localeCompare(right.id);
  });
}

node --test test/quality/tradeoff.test.ts

✔ 三个目标可以分别指出缺口 (0.834917ms)
✔ 首屏优先时 fast 排第一 (0.271667ms)
✔ 功能优先时 full 排第一 (0.084291ms)
✔ 体积优先时 small 排第一 (0.0895ms)
✔ 完全相同的方案同时可行时按 id 稳定排序 (8.632417ms)
✔ 权重缺失、重复、为负或和不为 1 都会抛错 (0.331958ms)
✔ 候选人 id 重复会抛错 (0.077ms)
ℹ tests 7
ℹ suites 0
ℹ pass 7
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 139.349416

A-首屏优先	score=0.500	feasible=false	缺口=功能 8 项低于下限 10 项；首包 420KB 超过上限 300KB
C-体积优先	score=0.400	feasible=false	缺口=首屏 2100ms 超过上限 2000ms
B-功能优先	score=0.335	feasible=false	缺口=首屏 2400ms 超过上限 2000ms；首包 380KB 超过上限 300KB