《移动游戏产品的架构·客户端与移动运行时》1.1 一个 IP 两款产品：为什么客户端架构不能按品类复制

// file: src/core/layers.ts
// tier: L1
// verify: node --test test/core/layers.test.ts test/core/layer-contracts.test.ts

export const LAYER_ORDER = ["platform", "system", "gameplay", "presentation"] as const;

export type Layer = (typeof LAYER_ORDER)[number];

const ALLOWED_LOWER: Record<Layer, readonly Layer[]> = {
  platform: [],
  system: ["platform"],
  gameplay: ["platform", "system"],
  presentation: ["platform", "system", "gameplay"],
};

export function canDependOn(from: Layer, to: Layer): boolean {
  return ALLOWED_LOWER[from].includes(to);
}

export interface LayerEdge {
  readonly from: Layer;
  readonly to: Layer;
}

export function findUpwardEdges(edges: readonly LayerEdge[]): readonly LayerEdge[] {
  return edges.filter((edge) => !canDependOn(edge.from, edge.to));
}

export const SHARED_CAPABILITIES = [
  "account",
  "payment",
  "activity-config",
  "analytics",
  "channel-build",
] as const;

export const ISOLATED_CAPABILITIES = [
  "gameplay-core",
  "resource-packs",
  "perf-budget",
  "release-window",
] as const;

export type SharedCapability = (typeof SHARED_CAPABILITIES)[number];
export type IsolatedCapability = (typeof ISOLATED_CAPABILITIES)[number];

export function isSharedCapability(name: string): name is SharedCapability {
  return (SHARED_CAPABILITIES as readonly string[]).includes(name);
}

export interface ProductShape {
  readonly name: string;
  readonly sessionSecondsMin: number;
  readonly sessionSecondsMax: number;
  readonly firstPackageMb: number;
  readonly totalResourceMb: number;
  readonly targetFps: number;
  readonly lowEndSharePercent: number;
  readonly weakNetwork: boolean;
}

export const MATCH3_SHAPE: ProductShape = {
  name: "潮汐消消",
  sessionSecondsMin: 90,
  sessionSecondsMax: 90,
  firstPackageMb: 120,
  totalResourceMb: 480,
  targetFps: 30,
  lowEndSharePercent: 35,
  weakNetwork: true,
};

export const ARK_SHAPE: ProductShape = {
  name: "潮汐方舟",
  sessionSecondsMin: 480,
  sessionSecondsMax: 720,
  firstPackageMb: 350,
  totalResourceMb: 1800,
  targetFps: 60,
  lowEndSharePercent: 15,
  weakNetwork: false,
};

export type DriverField = Exclude<keyof ProductShape, "name">;

export const DRIVER_LAYERS: Record<DriverField, readonly Layer[]> = {
  sessionSecondsMin: ["gameplay", "presentation"],
  sessionSecondsMax: ["gameplay", "presentation"],
  firstPackageMb: ["system", "presentation"],
  totalResourceMb: ["system", "presentation"],
  targetFps: ["presentation"],
  lowEndSharePercent: ["platform", "presentation"],
  weakNetwork: ["platform", "system"],
};

export function changedDrivers(a: ProductShape, b: ProductShape): readonly DriverField[] {
  const fields = Object.keys(DRIVER_LAYERS) as DriverField[];
  return fields.filter((field) => a[field] !== b[field]);
}

export function impactedLayers(changed: readonly DriverField[]): readonly Layer[] {
  const touched = new Set<Layer>();
  for (const field of changed) {
    for (const layer of DRIVER_LAYERS[field]) {
      touched.add(layer);
    }
  }
  return LAYER_ORDER.filter((layer) => touched.has(layer));
}

export interface LayerContract {
  readonly layer: Layer;
  readonly duty: string;
  readonly inputs: readonly string[];
  readonly outputs: readonly string[];
  readonly misuse: readonly string[];
}

export const LAYER_CONTRACTS: Record<Layer, LayerContract> = {
  platform: {
    layer: "platform",
    duty: "把引擎、原生壳、渠道 SDK、文件、网络与传感器包装成稳定的 Host 接口",
    inputs: ["设备能力查询", "生命周期事件", "渠道回调"],
    outputs: ["Host 接口", "平台事件", "原始资源句柄"],
    misuse: ["向上读取玩法状态", "把渠道差异直接泄漏给表现层", "在平台层缓存业务配置"],
  },
  system: {
    layer: "system",
    duty: "把账号、支付、配置、埋点、资源索引与存档组织成可替换的能力客户端",
    inputs: ["Host 接口", "配置版本", "账号与订单状态"],
    outputs: ["会话快照", "配置快照", "存档读写能力"],
    misuse: ["直接操作界面节点", "把玩法结算写进支付回调", "在系统层判断关卡胜负"],
  },
  gameplay: {
    layer: "gameplay",
    duty: "维护纯玩法状态机、规则、结算与可重放的事件序列",
    inputs: ["规则配置", "玩家输入意图", "注入的 Clock 与 Random"],
    outputs: ["状态迁移", "结算结果", "玩法事件"],
    misuse: ["直接播放动画或音效", "读取平台文件句柄", "用 Date.now 或 Math.random 代替注入"],
  },
  presentation: {
    layer: "presentation",
    duty: "把玩法状态映射为界面、场景、动画、输入反馈与可访问性提示",
    inputs: ["玩法状态与事件", "系统快照", "平台安全区与语言"],
    outputs: ["渲染指令", "输入意图", "界面事件"],
    misuse: ["绕过意图直接改玩法状态", "在视图里做结算", "把平台分支散落在组件里"],
  },
};

export function layerContract(layer: Layer): LayerContract {
  return LAYER_CONTRACTS[layer];
}

export function allowedTargets(layer: Layer): readonly Layer[] {
  return ALLOWED_LOWER[layer];
}

export type DependencyKind = "same-layer" | "downward" | "upward";

export function classifyDependency(from: Layer, to: Layer): DependencyKind {
  if (from === to) {
    return "same-layer";
  }
  return canDependOn(from, to) ? "downward" : "upward";
}

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

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

import {
  ARK_SHAPE,
  LAYER_ORDER,
  MATCH3_SHAPE,
  canDependOn,
  changedDrivers,
  findUpwardEdges,
  impactedLayers,
  isSharedCapability,
} from "../../src/core/layers.ts";

test("shared capabilities follow the studio split", () => {
  for (const name of ["account", "payment", "activity-config", "analytics", "channel-build"]) {
    assert.equal(isSharedCapability(name), true, name);
  }
  for (const name of ["gameplay-core", "resource-packs", "perf-budget", "release-window"]) {
    assert.equal(isSharedCapability(name), false, name);
  }
});

test("layer dependencies only point downward", () => {
  assert.equal(canDependOn("presentation", "gameplay"), true);
  assert.equal(canDependOn("gameplay", "system"), true);
  assert.equal(canDependOn("system", "platform"), true);
  assert.equal(canDependOn("platform", "system"), false);
  assert.equal(canDependOn("gameplay", "presentation"), false);

  const edges = [
    { from: "presentation" as const, to: "gameplay" as const },
    { from: "platform" as const, to: "system" as const },
    { from: "system" as const, to: "gameplay" as const },
  ];
  assert.deepEqual(findUpwardEdges(edges), [edges[1], edges[2]]);
});

test("the two products differ on every architectural driver", () => {
  const changed = changedDrivers(MATCH3_SHAPE, ARK_SHAPE);
  assert.equal(changed.length, 7);
  assert.deepEqual(impactedLayers(changed), [...LAYER_ORDER]);
});

test("a product compared with itself touches no layer", () => {
  assert.deepEqual(changedDrivers(MATCH3_SHAPE, { ...MATCH3_SHAPE }), []);
  assert.deepEqual(impactedLayers([]), []);
});