《移动游戏产品的架构·客户端与移动运行时》1.2 移动端约束清单：内存、电量、发热、网络、机型

// file: src/core/constraints.ts
// tier: L1
// verify: node --test test/core/constraints.test.ts

export interface ConstraintProfile {
  readonly name: string;
  readonly steadyMemoryMb: number;
  readonly memoryWatermarkMb: number;
  readonly targetFps: number;
  readonly firstPackageMb: number;
  readonly totalResourceMb: number;
  readonly lowEndSharePercent: number;
  readonly weakNetwork: boolean;
  readonly crashRateBp: number;
  readonly anrRateBp: number;
  readonly jankRateBp: number;
}

export const MATCH3_BUDGET: ConstraintProfile = {
  name: "潮汐消消",
  steadyMemoryMb: 420,
  memoryWatermarkMb: 520,
  targetFps: 30,
  firstPackageMb: 120,
  totalResourceMb: 480,
  lowEndSharePercent: 35,
  weakNetwork: true,
  crashRateBp: 18,
  anrRateBp: 5,
  jankRateBp: 210,
};

export const ARK_BUDGET: ConstraintProfile = {
  name: "潮汐方舟",
  steadyMemoryMb: 1150,
  memoryWatermarkMb: 1450,
  targetFps: 60,
  firstPackageMb: 350,
  totalResourceMb: 1800,
  lowEndSharePercent: 15,
  weakNetwork: false,
  crashRateBp: 12,
  anrRateBp: 3,
  jankRateBp: 140,
};

export interface ConstraintLine {
  readonly key: string;
  readonly value: number | boolean;
  readonly unit: string;
}

export function frameBudgetMicros(fps: number): number {
  if (!Number.isInteger(fps) || fps <= 0) {
    throw new RangeError("fps must be a positive integer");
  }
  return Math.floor(1_000_000 / fps);
}

export function memoryHeadroomMb(profile: ConstraintProfile): number {
  return profile.memoryWatermarkMb - profile.steadyMemoryMb;
}

export function resourceToFirstPermille(profile: ConstraintProfile): number {
  return Math.floor((profile.totalResourceMb * 1_000) / profile.firstPackageMb);
}

export function jankFramesPerThousand(profile: ConstraintProfile): number {
  return profile.jankRateBp / 10;
}

export function crashSessionsPerHundredThousand(profile: ConstraintProfile): number {
  return profile.crashRateBp * 10;
}

export function anrSessionsPerHundredThousand(profile: ConstraintProfile): number {
  return profile.anrRateBp * 10;
}

export function constraintLines(profile: ConstraintProfile): readonly ConstraintLine[] {
  return [
    { key: "frameBudgetMicros", value: frameBudgetMicros(profile.targetFps), unit: "us" },
    { key: "memoryWatermarkMb", value: profile.memoryWatermarkMb, unit: "MB" },
    { key: "memoryHeadroomMb", value: memoryHeadroomMb(profile), unit: "MB" },
    { key: "firstPackageMb", value: profile.firstPackageMb, unit: "MB" },
    { key: "resourceToFirstPermille", value: resourceToFirstPermille(profile), unit: "permille" },
    { key: "lowEndSharePercent", value: profile.lowEndSharePercent, unit: "%" },
    { key: "jankFramesPerThousand", value: jankFramesPerThousand(profile), unit: "frames/1000" },
    {
      key: "crashSessionsPerHundredThousand",
      value: crashSessionsPerHundredThousand(profile),
      unit: "sessions/100000",
    },
    {
      key: "anrSessionsPerHundredThousand",
      value: anrSessionsPerHundredThousand(profile),
      unit: "sessions/100000",
    },
  ];
}

export interface ConstraintDelta {
  readonly key: string;
  readonly base: number | boolean;
  readonly next: number | boolean;
  readonly higher: "base" | "next" | "equal";
}

function rank(value: number | boolean): number {
  return typeof value === "boolean" ? Number(value) : value;
}

export function compareConstraints(
  base: ConstraintProfile,
  next: ConstraintProfile,
): readonly ConstraintDelta[] {
  const baseLines = new Map(constraintLines(base).map((line) => [line.key, line.value]));
  return constraintLines(next).map((line) => {
    const baseValue = baseLines.get(line.key);
    if (baseValue === undefined) {
      throw new Error(`missing constraint line: ${line.key}`);
    }
    const difference = rank(line.value) - rank(baseValue);
    const higher = difference > 0 ? "next" : difference < 0 ? "base" : "equal";
    return { key: line.key, base: baseValue, next: line.value, higher };
  });
}

// file: test/core/constraints.test.ts
// tier: L1
// verify: node --test test/core/constraints.test.ts

import { test } from "node:test";
import assert from "node:assert/strict";

import {
  ARK_BUDGET,
  MATCH3_BUDGET,
  anrSessionsPerHundredThousand,
  compareConstraints,
  constraintLines,
  crashSessionsPerHundredThousand,
  frameBudgetMicros,
  jankFramesPerThousand,
  memoryHeadroomMb,
  resourceToFirstPermille,
} from "../../src/core/constraints.ts";

test("frame budget stays in integer microseconds", () => {
  assert.equal(frameBudgetMicros(30), 33_333);
  assert.equal(frameBudgetMicros(60), 16_666);
  assert.equal(frameBudgetMicros(120), 8_333);
  assert.throws(() => frameBudgetMicros(0), RangeError);
  assert.throws(() => frameBudgetMicros(59.94), RangeError);
});

test("memory headroom follows the watermark minus steady state", () => {
  assert.equal(memoryHeadroomMb(MATCH3_BUDGET), 100);
  assert.equal(memoryHeadroomMb(ARK_BUDGET), 300);
});

test("resource ratios and rate conversions use integers", () => {
  assert.equal(resourceToFirstPermille(MATCH3_BUDGET), 4_000);
  assert.equal(resourceToFirstPermille(ARK_BUDGET), 5_142);

  assert.equal(jankFramesPerThousand(MATCH3_BUDGET), 21);
  assert.equal(jankFramesPerThousand(ARK_BUDGET), 14);
  assert.equal(crashSessionsPerHundredThousand(MATCH3_BUDGET), 180);
  assert.equal(crashSessionsPerHundredThousand(ARK_BUDGET), 120);
  assert.equal(anrSessionsPerHundredThousand(MATCH3_BUDGET), 50);
  assert.equal(anrSessionsPerHundredThousand(ARK_BUDGET), 30);
});

test("the constraint list has one line per checked dimension", () => {
  const keys = constraintLines(MATCH3_BUDGET).map((line) => line.key);
  assert.deepEqual(keys, [
    "frameBudgetMicros",
    "memoryWatermarkMb",
    "memoryHeadroomMb",
    "firstPackageMb",
    "resourceToFirstPermille",
    "lowEndSharePercent",
    "jankFramesPerThousand",
    "crashSessionsPerHundredThousand",
    "anrSessionsPerHundredThousand",
  ]);
});

test("comparison reports which product sits higher", () => {
  const deltas = compareConstraints(MATCH3_BUDGET, ARK_BUDGET);
  const byKey = new Map(deltas.map((delta) => [delta.key, delta]));

  assert.equal(byKey.get("memoryHeadroomMb")?.higher, "next");
  assert.equal(byKey.get("lowEndSharePercent")?.higher, "base");
  assert.equal(byKey.get("frameBudgetMicros")?.higher, "base");
  assert.equal(byKey.get("firstPackageMb")?.higher, "next");
  assert.equal(byKey.get("memoryWatermarkMb")?.higher, "next");
});