《移动游戏产品的架构·网络、资源与热更新》8.2 资源分组：共享、场景与产品

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

export type ResourceKind =
  | "texture"
  | "model"
  | "animation"
  | "audio"
  | "config"
  | "other";

export type ResourceScope = "shared" | "scene" | "product";

export interface ResourceEntry {
  readonly id: string;
  readonly kind: ResourceKind;
  readonly bytes: number;
  readonly scope: ResourceScope;
  readonly scenes?: readonly string[];
  readonly products?: readonly string[];
}

export interface GroupOptions {
  readonly sharedThreshold: number;
  readonly maxGroupBytes: number;
}

export const DEFAULT_GROUP_OPTIONS: GroupOptions = {
  sharedThreshold: 3,
  maxGroupBytes: 90 * 1024 * 1024,
};

export interface GroupPlan {
  readonly id: string;
  readonly resources: readonly string[];
  readonly bytes: number;
}

export interface Duplication {
  readonly id: string;
  readonly groups: readonly string[];
  readonly extraBytes: number;
}

export interface GroupPlanResult {
  readonly groups: readonly GroupPlan[];
  readonly assignments: ReadonlyMap<string, readonly string[]>;
  readonly duplicated: readonly Duplication[];
  readonly promoted: readonly string[];
  readonly totalBytes: number;
  readonly sharedBytes: number;
  readonly redundancyBytes: number;
  readonly oversized: readonly string[];
}

interface Bucket {
  readonly resources: string[];
  bytes: number;
}

export function planGroups(
  entries: readonly ResourceEntry[],
  options: GroupOptions = DEFAULT_GROUP_OPTIONS,
): GroupPlanResult {
  if (!Number.isInteger(options.sharedThreshold) || options.sharedThreshold < 1) {
    throw new Error(`sharedThreshold must be >= 1: ${options.sharedThreshold}`);
  }
  if (!Number.isInteger(options.maxGroupBytes) || options.maxGroupBytes < 1) {
    throw new Error(`maxGroupBytes must be >= 1: ${options.maxGroupBytes}`);
  }

  const seen = new Set<string>();
  const buckets = new Map<string, Bucket>();
  const assignments = new Map<string, readonly string[]>();
  const duplicated: Duplication[] = [];
  const promoted: string[] = [];
  let totalBytes = 0;
  let sharedBytes = 0;
  let redundancyBytes = 0;

  const add = (group: string, entry: ResourceEntry): void => {
    const bucket = buckets.get(group);
    if (bucket === undefined) {
      buckets.set(group, { resources: [entry.id], bytes: entry.bytes });
      return;
    }
    bucket.resources.push(entry.id);
    bucket.bytes += entry.bytes;
  };

  const sorted = [...entries].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
  for (const entry of sorted) {
    if (entry.id.length === 0) throw new Error("resource id must not be empty");
    if (seen.has(entry.id)) throw new Error(`duplicate resource: ${entry.id}`);
    seen.add(entry.id);
    if (!Number.isInteger(entry.bytes) || entry.bytes < 0) {
      throw new Error(`invalid bytes for ${entry.id}: ${entry.bytes}`);
    }

    let groups: string[];
    if (entry.scope === "shared") {
      groups = ["shared"];
    } else if (entry.scope === "product") {
      const products = [...new Set(entry.products ?? [])].sort();
      if (products.length === 0) {
        throw new Error(`product resource needs at least one product: ${entry.id}`);
      }
      groups = products.map((product) => `product:${product}`);
    } else {
      const scenes = [...new Set(entry.scenes ?? [])].sort();
      if (scenes.length === 0) {
        throw new Error(`scene resource needs at least one scene: ${entry.id}`);
      }
      if (scenes.length >= options.sharedThreshold) {
        groups = ["shared"];
        promoted.push(entry.id);
      } else {
        groups = scenes.map((scene) => `scene:${scene}`);
      }
    }

    for (const group of groups) add(group, entry);
    assignments.set(entry.id, groups);
    totalBytes += entry.bytes;

    if (groups.includes("shared")) sharedBytes += entry.bytes;
    if (entry.scope === "scene" && groups.length > 1) {
      const extraBytes = entry.bytes * (groups.length - 1);
      redundancyBytes += extraBytes;
      duplicated.push({ id: entry.id, groups, extraBytes });
    }
  }

  const groups: GroupPlan[] = [...buckets.entries()]
    .map(([id, bucket]) => ({
      id,
      resources: [...bucket.resources].sort(),
      bytes: bucket.bytes,
    }))
    .sort((a, b) => {
      if (a.id === "shared") return -1;
      if (b.id === "shared") return 1;
      return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
    });

  const oversized = groups
    .filter((group) => group.bytes > options.maxGroupBytes)
    .map((group) => group.id);

  return {
    groups,
    assignments,
    duplicated,
    promoted,
    totalBytes,
    sharedBytes,
    redundancyBytes,
    oversized,
  };
}

export function formatGroupPlan(result: GroupPlanResult): string {
  const lines = ["group\tfiles\tbytes"];
  for (const group of result.groups) {
    lines.push(`${group.id}\t${group.resources.length}\t${group.bytes}`);
  }
  lines.push(
    `total=${result.totalBytes}B shared=${result.sharedBytes}B redundancy=${result.redundancyBytes}B promoted=${result.promoted.length} oversized=${result.oversized.length}`,
  );
  return lines.join("\n");
}

group  files  bytes
shared  2  150
product:cn  2  50
product:global  1  40
scene:s1  1  30
scene:s2  2  50
total=250B shared=150B redundancy=30B promoted=1 oversized=1