《移动游戏产品的架构·客户端与移动运行时》8.2 机型分档与画质策略配置化

// file: src/input/device-tiers.ts
// tier: L1
// verify: node --test test/input/device-tiers.test.ts

export type Tier = "low" | "mid" | "high";
export type Platform = "android" | "ios";
export type GpuTier = 0 | 1 | 2 | 3;

export interface DeviceProfile {
  readonly id: string; readonly platform: Platform; readonly ramMb: number;
  readonly gpuTier: GpuTier; readonly refreshHz: number; readonly osMajor: number;
}

export interface TierThresholds {
  readonly ramMb: readonly [number, number]; readonly gpuTier: readonly [number, number];
  readonly refreshHz: readonly [number, number]; readonly minRamMb: number;
  readonly minOsMajor: Readonly<Record<Platform, number>>;
  readonly lowMaxScore: number; readonly highMinScore: number;
}

export const DEFAULT_TIER_THRESHOLDS: TierThresholds = {
  ramMb: [4096, 6144], gpuTier: [1, 3], refreshHz: [90, 120],
  minRamMb: 3072, minOsMajor: { android: 9, ios: 14 }, lowMaxScore: 2, highMinScore: 5,
};

export interface TierDecision {
  readonly tier: Tier; readonly score: number;
  readonly factors: Readonly<Record<"ram" | "gpu" | "refresh", number>>;
  readonly cappedBy: "ram-floor" | "unsupported-os" | null; readonly reasons: readonly string[];
}

function band(value: number, floor: number, ceiling: number): number {
  if (value < floor) {
    return 0;
  }
  return value < ceiling ? 1 : 2;
}

export function decideTier(
  profile: DeviceProfile,
  thresholds: TierThresholds = DEFAULT_TIER_THRESHOLDS,
): TierDecision {
  const ram = band(profile.ramMb, thresholds.ramMb[0], thresholds.ramMb[1]);
  const gpu = band(profile.gpuTier, thresholds.gpuTier[0], thresholds.gpuTier[1]);
  const refresh = band(profile.refreshHz, thresholds.refreshHz[0], thresholds.refreshHz[1]);
  const score = ram + gpu + refresh;
  const reasons = [
    `ram=${profile.ramMb}->${ram}`, `gpu=${profile.gpuTier}->${gpu}`,
    `hz=${profile.refreshHz}->${refresh}`, `os=${profile.platform}-${profile.osMajor}`,
  ];
  const factors = { ram, gpu, refresh };
  if (profile.osMajor < thresholds.minOsMajor[profile.platform]) {
    return { tier: "low", score, factors, cappedBy: "unsupported-os", reasons };
  }
  if (profile.ramMb < thresholds.minRamMb) {
    return { tier: "low", score, factors, cappedBy: "ram-floor", reasons };
  }
  const tier: Tier = score <= thresholds.lowMaxScore ? "low"
    : score >= thresholds.highMinScore ? "high" : "mid";
  return { tier, score, factors, cappedBy: null, reasons };
}

export interface QualityPreset {
  readonly id: string; readonly targetFps: 30 | 60; readonly renderScale: number;
  readonly particleLevel: 0 | 1 | 2; readonly shadow: boolean; readonly textureLevel: 0 | 1 | 2;
}

export interface CanaryConfig {
  readonly percent: number; readonly presetId: string;
  readonly tiers: readonly Tier[]; readonly salt: string;
}

export interface QualityPolicy {
  readonly version: string;
  readonly tierPresets: Readonly<Record<Tier, string>>;
  readonly presets: Readonly<Record<string, QualityPreset>>;
  readonly canary: CanaryConfig | null;
}

export const DEFAULT_POLICY: QualityPolicy = {
  version: "2026.10.31-1",
  tierPresets: { low: "low-30", mid: "mid-30", high: "high-60" },
  presets: {
    "low-30": { id: "low-30", targetFps: 30, renderScale: 0.75, particleLevel: 0, shadow: false, textureLevel: 0 },
    "mid-30": { id: "mid-30", targetFps: 30, renderScale: 1, particleLevel: 1, shadow: false, textureLevel: 1 },
    "high-60": { id: "high-60", targetFps: 60, renderScale: 1, particleLevel: 2, shadow: true, textureLevel: 2 },
  },
  canary: null,
};

export interface QualityDecision {
  readonly tier: Tier; readonly score: number; readonly presetId: string;
  readonly preset: QualityPreset; readonly canary: boolean; readonly bucket: number;
  readonly policyVersion: string; readonly reasons: readonly string[];
}

export function bucketOf(deviceId: string, salt: string): number {
  let hash = 0x811c9dc5;
  const text = `${deviceId}:${salt}`;
  for (let index = 0; index < text.length; index += 1) {
    hash ^= text.charCodeAt(index);
    hash = Math.imul(hash, 0x01000193);
  }
  return (hash >>> 0) % 100;
}

export function resolveQuality(
  profile: DeviceProfile,
  policy: QualityPolicy = DEFAULT_POLICY,
  thresholds: TierThresholds = DEFAULT_TIER_THRESHOLDS,
): QualityDecision {
  const tierDecision = decideTier(profile, thresholds);
  const baseId = policy.tierPresets[tierDecision.tier];
  const base = policy.presets[baseId];
  if (!base) {
    throw new Error(`policy ${policy.version} has no preset ${baseId}`);
  }
  const canary = policy.canary;
  const bucket = canary ? bucketOf(profile.id, canary.salt) : 100;
  const canaryHit = canary !== null && canary.tiers.includes(tierDecision.tier)
    && bucket < canary.percent && policy.presets[canary.presetId] !== undefined;
  const preset = canaryHit ? policy.presets[canary.presetId] : base;
  const reasons = canaryHit
    ? [...tierDecision.reasons, `canary=${bucket}<${canary.percent}`]
    : tierDecision.reasons;
  return {
    tier: tierDecision.tier, score: tierDecision.score, presetId: preset.id, preset,
    canary: canaryHit, bucket, policyVersion: policy.version, reasons,
  };
}

export function validatePolicy(policy: QualityPolicy): readonly string[] {
  const errors: string[] = [];
  if (policy.version.trim().length === 0) {
    errors.push("version is empty");
  }
  for (const tier of ["low", "mid", "high"] as const) {
    const id = policy.tierPresets[tier];
    if (!id) {
      errors.push(`tierPresets.${tier} is missing`);
    } else if (!policy.presets[id]) {
      errors.push(`tierPresets.${tier} references unknown preset ${id}`);
    }
  }
  for (const [id, preset] of Object.entries(policy.presets)) {
    if (preset.id !== id) {
      errors.push(`preset key ${id} does not match id ${preset.id}`);
    }
    if (preset.targetFps !== 30 && preset.targetFps !== 60) {
      errors.push(`preset ${id} targetFps must be 30 or 60`);
    }
    if (!(preset.renderScale >= 0.5 && preset.renderScale <= 1)) {
      errors.push(`preset ${id} renderScale must be within [0.5, 1]`);
    }
  }
  if (policy.canary) {
    if (!(policy.canary.percent >= 0 && policy.canary.percent <= 100)) {
      errors.push("canary.percent must be within [0, 100]");
    }
    if (!policy.presets[policy.canary.presetId]) {
      errors.push(`canary references unknown preset ${policy.canary.presetId}`);
    }
    if (policy.canary.tiers.length === 0) {
      errors.push("canary.tiers must not be empty");
    }
  }
  return errors;
}

export interface PolicyApplyResult {
  readonly ok: boolean; readonly active: QualityPolicy;
  readonly errors: readonly string[]; readonly rolledBack: boolean;
}

export class PolicyRegistry {
  #active: QualityPolicy;
  readonly #history: QualityPolicy[] = [];

  constructor(initial: QualityPolicy = DEFAULT_POLICY) {
    const errors = validatePolicy(initial);
    if (errors.length > 0) {
      throw new Error(`invalid initial policy: ${errors.join("; ")}`);
    }
    this.#active = initial;
  }

  get active(): QualityPolicy {
    return this.#active;
  }

  apply(next: QualityPolicy): PolicyApplyResult {
    const errors = validatePolicy(next);
    if (errors.length > 0) {
      return { ok: false, active: this.#active, errors, rolledBack: true };
    }
    this.#history.push(this.#active);
    this.#active = next;
    return { ok: true, active: this.#active, errors: [], rolledBack: false };
  }

  rollback(): PolicyApplyResult | null {
    const previous = this.#history.pop();
    if (!previous) {
      return null;
    }
    this.#active = previous;
    return { ok: true, active: previous, errors: [], rolledBack: true };
  }
}

export interface FleetImpact {
  readonly total: number; readonly byTier: Readonly<Record<Tier, number>>;
  readonly byPreset: Readonly<Record<string, number>>;
  readonly lowTierShare: number; readonly canaryShare: number;
}

export function fleetImpact(decisions: readonly QualityDecision[]): FleetImpact {
  const byTier: Record<Tier, number> = { low: 0, mid: 0, high: 0 };
  const byPreset: Record<string, number> = {};
  let canary = 0;
  for (const decision of decisions) {
    byTier[decision.tier] += 1;
    byPreset[decision.presetId] = (byPreset[decision.presetId] ?? 0) + 1;
    if (decision.canary) {
      canary += 1;
    }
  }
  const total = decisions.length;
  return {
    total, byTier, byPreset,
    lowTierShare: total === 0 ? 0 : byTier.low / total,
    canaryShare: total === 0 ? 0 : canary / total,
  };
}

export interface CanaryMetrics { readonly sessions: number; readonly jankRate: number; readonly crashRate: number; }
export interface Guardrail { readonly minSessions: number; readonly maxJankRate: number; readonly maxCrashRate: number; }

export const DEFAULT_GUARDRAIL: Guardrail = {
  minSessions: 5000, maxJankRate: 0.03, maxCrashRate: 0.002,
};

export interface RollbackVerdict { readonly rollback: boolean; readonly reasons: readonly string[]; }

export function shouldRollback(
  metrics: CanaryMetrics,
  guardrail: Guardrail = DEFAULT_GUARDRAIL,
): RollbackVerdict {
  if (metrics.sessions < guardrail.minSessions) {
    return { rollback: false, reasons: ["insufficient-sessions"] };
  }
  const reasons: string[] = [];
  if (metrics.jankRate > guardrail.maxJankRate) {
    reasons.push(`jank-rate=${metrics.jankRate}>${guardrail.maxJankRate}`);
  }
  if (metrics.crashRate > guardrail.maxCrashRate) {
    reasons.push(`crash-rate=${metrics.crashRate}>${guardrail.maxCrashRate}`);
  }
  return { rollback: reasons.length > 0, reasons };
}