《移动游戏产品的架构·客户端与移动运行时》13.1 模块矩阵与依赖报告

// file: src/lab/module-matrix.ts
// tier: L1
// verify: node --test test/lab/module-matrix.test.ts

import { ISOLATED_CAPABILITIES, isSharedCapability } from "../core/layers.ts";
import type { Layer } from "../core/layers.ts";

export type Sharing = "shared" | "isolated" | "product";

export interface ModuleRecord {
  readonly id: string;
  readonly layer: Layer;
  readonly capability: string;
  readonly owner: string;
}

export interface MatrixRow extends ModuleRecord {
  readonly sharing: Sharing;
}

export interface MatrixAudit {
  readonly rows: readonly MatrixRow[];
  readonly byLayer: Readonly<Record<Layer, number>>;
  readonly problems: readonly string[];
}

const LAYERS: readonly Layer[] = ["platform", "system", "gameplay", "presentation"];
const SHARED_LAYERS: readonly Layer[] = ["platform", "system"];

export function classifySharing(capability: string): Sharing {
  if (isSharedCapability(capability)) {
    return "shared";
  }
  if ((ISOLATED_CAPABILITIES as readonly string[]).includes(capability)) {
    return "isolated";
  }
  return "product";
}

export function buildMatrix(modules: readonly ModuleRecord[]): MatrixAudit {
  const seen = new Set<string>();
  const problems: string[] = [];
  const byLayer: Record<Layer, number> = {
    platform: 0,
    system: 0,
    gameplay: 0,
    presentation: 0,
  };
  const rows: MatrixRow[] = [];

  for (const module of modules) {
    if (seen.has(module.id)) {
      problems.push(`duplicate module: ${module.id}`);
      continue;
    }
    seen.add(module.id);

    if (!LAYERS.includes(module.layer)) {
      problems.push(`unknown layer: ${module.id} -> ${module.layer}`);
      continue;
    }
    if (module.owner.trim() === "" || module.capability.trim() === "") {
      problems.push(`empty owner or capability: ${module.id}`);
    }

    const sharing = classifySharing(module.capability);
    if (sharing === "shared" && !SHARED_LAYERS.includes(module.layer)) {
      problems.push(`shared capability in ${module.layer}: ${module.id}`);
    }
    if (sharing === "isolated" && module.layer === "platform") {
      problems.push(`isolated capability in platform: ${module.id}`);
    }

    byLayer[module.layer] += 1;
    rows.push({ ...module, sharing });
  }

  return { rows, byLayer, problems };
}

export function formatMatrix(audit: MatrixAudit): string {
  const header = "id\tlayer\tcapability\tsharing\towner";
  const body = audit.rows
    .map((row) => `${row.id}\t${row.layer}\t${row.capability}\t${row.sharing}\t${row.owner}`)
    .join("\n");
  return body === "" ? header : `${header}\n${body}`;
}

export function coverageGaps(audit: MatrixAudit): readonly Layer[] {
  return LAYERS.filter((layer) => audit.byLayer[layer] === 0);
}

export function sharedCount(audit: MatrixAudit): number {
  return audit.rows.filter((row) => row.sharing === "shared").length;
}

export const DEFAULT_MODULES: readonly ModuleRecord[] = [
  { id: "host", layer: "platform", capability: "engine-host", owner: "客户端" },
  { id: "channel", layer: "platform", capability: "channel-build", owner: "发行中台" },
  { id: "account", layer: "system", capability: "account", owner: "账号组" },
  { id: "payment", layer: "system", capability: "payment", owner: "支付组" },
  { id: "activity", layer: "system", capability: "activity-config", owner: "运营平台" },
  { id: "analytics", layer: "system", capability: "analytics", owner: "数据组" },
  { id: "match3-core", layer: "gameplay", capability: "gameplay-core", owner: "消消客户端" },
  { id: "ark-core", layer: "gameplay", capability: "gameplay-core", owner: "方舟客户端" },
  { id: "resource-packs", layer: "system", capability: "resource-packs", owner: "客户端" },
  { id: "perf-budget", layer: "system", capability: "perf-budget", owner: "性能组" },
  { id: "ui", layer: "presentation", capability: "screen-stack", owner: "客户端" },
];

id            layer         capability      sharing   owner
host          platform      engine-host     product   客户端
channel       platform      channel-build   shared    发行中台
account       system        account         shared    账号组
payment       system        payment         shared    支付组
activity      system        activity-config shared    运营平台
analytics     system        analytics       shared    数据组
match3-core   gameplay      gameplay-core   isolated  消消客户端
ark-core      gameplay      gameplay-core   isolated  方舟客户端
resource-packs system       resource-packs  isolated  客户端
perf-budget   system        perf-budget     isolated  性能组
ui            presentation  screen-stack    product   客户端