《移动游戏产品的架构·网络、资源与热更新》8.3 打包策略与冗余控制

// file: src/resource/pack-plan.ts
// tier: L1
// verify: node --test test/resource/pack-plan.test.ts

export type PackTier = "first" | "required" | "optional";

export interface AssetRef {
  readonly id: string;
  readonly bytes: number;
}

export interface PackSpec {
  readonly id: string;
  readonly tier: PackTier;
  readonly requires: readonly string[];
  readonly assets: readonly AssetRef[];
}

export interface DuplicateAsset {
  readonly id: string;
  readonly packs: readonly string[];
  readonly bytes: number;
  readonly wastedBytes: number;
}

export interface NormalizedPacks {
  readonly packs: readonly PackSpec[];
  readonly duplicates: readonly DuplicateAsset[];
  readonly redundancyBytes: number;
}

export interface PackPlan {
  readonly packs: readonly PackSpec[];
  readonly order: readonly string[];
  readonly stages: readonly (readonly string[])[];
  readonly firstBytes: number;
  readonly requiredBytes: number;
  readonly optionalBytes: number;
  readonly duplicates: readonly DuplicateAsset[];
  readonly redundancyBytes: number;
  readonly budgetExceeded: boolean;
  readonly warnings: readonly string[];
}

export const DEFAULT_FIRST_BUDGET = 350 * 1024 * 1024;
export const MB = 1024 * 1024;

const TIER_RANK: Record<PackTier, number> = {
  first: 0,
  required: 1,
  optional: 2,
};

function comparePacks(a: PackSpec, b: PackSpec): number {
  const rank = TIER_RANK[a.tier] - TIER_RANK[b.tier];
  if (rank !== 0) return rank;
  return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
}

interface Occurrence {
  readonly pack: string;
  readonly tier: PackTier;
  readonly bytes: number;
}

export function applyOwnership(packs: readonly PackSpec[]): NormalizedPacks {
  const byId = new Map<string, PackSpec>();
  for (const pack of packs) {
    if (byId.has(pack.id)) throw new Error(`duplicate pack: ${pack.id}`);
    byId.set(pack.id, pack);
  }

  const occurrences = new Map<string, Occurrence[]>();
  for (const pack of packs) {
    const local = new Set<string>();
    for (const asset of pack.assets) {
      if (local.has(asset.id)) {
        throw new Error(`asset listed twice in ${pack.id}: ${asset.id}`);
      }
      local.add(asset.id);
      if (!Number.isInteger(asset.bytes) || asset.bytes < 0) {
        throw new Error(`invalid bytes for ${asset.id}: ${asset.bytes}`);
      }
      const list = occurrences.get(asset.id) ?? [];
      list.push({ pack: pack.id, tier: pack.tier, bytes: asset.bytes });
      occurrences.set(asset.id, list);
    }
  }

  const owner = new Map<string, string>();
  const duplicates: DuplicateAsset[] = [];
  let redundancyBytes = 0;

  for (const [id, list] of [...occurrences.entries()].sort()) {
    const sizes = new Set(list.map((item) => item.bytes));
    if (sizes.size > 1) {
      throw new Error(`asset size mismatch: ${id}`);
    }
    const sorted = [...list].sort((a, b) => {
      const rank = TIER_RANK[a.tier] - TIER_RANK[b.tier];
      if (rank !== 0) return rank;
      return a.pack < b.pack ? -1 : a.pack > b.pack ? 1 : 0;
    });
    owner.set(id, sorted[0].pack);
    if (sorted.length > 1) {
      const bytes = sorted[0].bytes;
      const wastedBytes = bytes * (sorted.length - 1);
      duplicates.push({
        id,
        packs: sorted.map((item) => item.pack).sort(),
        bytes,
        wastedBytes,
      });
      redundancyBytes += wastedBytes;
    }
  }

  const normalized = packs.map((pack) => ({
    ...pack,
    assets: pack.assets.filter((asset) => owner.get(asset.id) === pack.id),
  }));

  return { packs: normalized, duplicates, redundancyBytes };
}

function computeStages(packs: readonly PackSpec[]): {
  stages: string[][];
  order: string[];
} {
  if (packs.length === 0) return { stages: [], order: [] };

  const byId = new Map(packs.map((pack) => [pack.id, pack]));
  const stage = new Map<string, number>();
  const visiting = new Set<string>();

  const stageOf = (id: string): number => {
    const cached = stage.get(id);
    if (cached !== undefined) return cached;
    if (visiting.has(id)) {
      throw new Error(`cycle detected: pack requirements loop at ${id}`);
    }
    visiting.add(id);
    const pack = byId.get(id);
    if (pack === undefined) throw new Error(`unknown pack: ${id}`);
    let value = 0;
    for (const requirement of pack.requires) {
      if (!byId.has(requirement)) {
        throw new Error(`unknown requirement: ${id} -> ${requirement}`);
      }
      value = Math.max(value, stageOf(requirement) + 1);
    }
    visiting.delete(id);
    stage.set(id, value);
    return value;
  };

  for (const pack of packs) stageOf(pack.id);

  const maxStage = Math.max(...stage.values());
  const stages: string[][] = [];
  for (let index = 0; index <= maxStage; index += 1) stages.push([]);
  for (const pack of [...packs].sort(comparePacks)) {
    stages[stage.get(pack.id) ?? 0].push(pack.id);
  }
  return { stages, order: stages.flat() };
}

export function planPacks(
  packs: readonly PackSpec[],
  options: { readonly firstBudgetBytes?: number } = {},
): PackPlan {
  const budget = options.firstBudgetBytes ?? DEFAULT_FIRST_BUDGET;
  if (!Number.isInteger(budget) || budget < 0) {
    throw new Error(`invalid first budget: ${budget}`);
  }

  const normalized = applyOwnership(packs);
  const { stages, order } = computeStages(normalized.packs);

  let firstBytes = 0;
  let requiredBytes = 0;
  let optionalBytes = 0;
  for (const pack of normalized.packs) {
    const bytes = pack.assets.reduce((sum, asset) => sum + asset.bytes, 0);
    if (pack.tier === "first") firstBytes += bytes;
    else if (pack.tier === "required") requiredBytes += bytes;
    else optionalBytes += bytes;
  }

  const warnings: string[] = [];
  if (firstBytes > budget) {
    warnings.push(
      `first package ${(firstBytes / MB).toFixed(2)}MB exceeds budget ${(budget / MB).toFixed(2)}MB`,
    );
  }
  if (normalized.redundancyBytes > 0) {
    warnings.push(
      `${normalized.duplicates.length} duplicated assets waste ${(normalized.redundancyBytes / MB).toFixed(2)}MB`,
    );
  }

  return {
    packs: normalized.packs,
    order,
    stages,
    firstBytes,
    requiredBytes,
    optionalBytes,
    duplicates: normalized.duplicates,
    redundancyBytes: normalized.redundancyBytes,
    budgetExceeded: firstBytes > budget,
    warnings,
  };
}

export function formatPackPlan(plan: PackPlan): string {
  const stageOf = new Map<string, number>();
  for (let index = 0; index < plan.stages.length; index += 1) {
    for (const id of plan.stages[index]) stageOf.set(id, index);
  }
  const lines = ["pack\ttier\tstage\tbytes"];
  for (const pack of plan.packs) {
    const bytes = pack.assets.reduce((sum, asset) => sum + asset.bytes, 0);
    lines.push(`${pack.id}\t${pack.tier}\t${stageOf.get(pack.id) ?? 0}\t${bytes}`);
  }
  lines.push(
    `summary\tfirst=${plan.firstBytes}B\trequired=${plan.requiredBytes}B\toptional=${plan.optionalBytes}B\tredundancy=${plan.redundancyBytes}B\tbudget=${plan.budgetExceeded ? "exceeded" : "ok"}`,
  );
  return lines.join("\n");
}

pack  tier  stage  bytes
base  first  0  10
battle  required  1  120
character  required  1  30
voice  optional  2  50
summary  first=10B  required=150B  optional=50B  redundancy=40B  budget=ok