《移动游戏产品的架构·客户端与移动运行时》3.3 双案例壳层差异：轻壳与重壳

// file: src/platform/shell-profiles.ts
// tier: L2
// verify: node --test test/platform/shell-profiles.test.ts

import type { Host, Platform } from "./host.ts";
import { createMockHost } from "./host-mock.ts";

export type Capability =
  | "lifecycle"
  | "permissions"
  | "consent"
  | "account"
  | "billing"
  | "ads"
  | "analytics"
  | "push"
  | "anti-addiction"
  | "channel-sdk";

export const BASE_CONTRACT: readonly Capability[] = [
  "lifecycle",
  "permissions",
  "consent",
  "account",
  "billing",
  "analytics",
];

export type Fallback = "none" | "guest" | "stub" | "deferred";

export interface BootStep {
  readonly capability: Capability;
  readonly blocking: boolean;
  readonly fallback: Fallback;
  readonly adapter: string;
}

export interface ShellProfile {
  readonly name: string;
  readonly weight: "light" | "heavy";
  readonly platformHost: Host;
  readonly backed: readonly Capability[];
  readonly steps: readonly BootStep[];
}

export const LIGHT_SHELL_STEPS: readonly BootStep[] = [
  { capability: "lifecycle", blocking: true, fallback: "none", adapter: "ActivityLifecycleAdapter" },
  { capability: "consent", blocking: true, fallback: "none", adapter: "ConsentDialogAdapter" },
  { capability: "permissions", blocking: false, fallback: "deferred", adapter: "RuntimePermissionAdapter" },
  { capability: "account", blocking: false, fallback: "guest", adapter: "AccountBridge" },
  { capability: "billing", blocking: false, fallback: "stub", adapter: "StoreBillingAdapter" },
  { capability: "ads", blocking: false, fallback: "stub", adapter: "AdMediationAdapter" },
  { capability: "analytics", blocking: false, fallback: "deferred", adapter: "AnalyticsAdapter" },
];

export const HEAVY_SHELL_STEPS: readonly BootStep[] = [
  { capability: "lifecycle", blocking: true, fallback: "none", adapter: "ActivityLifecycleAdapter" },
  { capability: "consent", blocking: true, fallback: "none", adapter: "ConsentDialogAdapter" },
  { capability: "permissions", blocking: true, fallback: "none", adapter: "RuntimePermissionAdapter" },
  { capability: "account", blocking: true, fallback: "none", adapter: "ChannelAccountAdapter" },
  { capability: "anti-addiction", blocking: true, fallback: "none", adapter: "AntiAddictionAdapter" },
  { capability: "channel-sdk", blocking: true, fallback: "none", adapter: "ChannelSdkAdapter" },
  { capability: "billing", blocking: true, fallback: "none", adapter: "ChannelBillingAdapter" },
  { capability: "push", blocking: false, fallback: "deferred", adapter: "PushAdapter" },
  { capability: "analytics", blocking: false, fallback: "deferred", adapter: "AnalyticsAdapter" },
  { capability: "ads", blocking: false, fallback: "stub", adapter: "AdMediationAdapter" },
];

export function createShellProfile(
  name: string,
  weight: "light" | "heavy",
  steps: readonly BootStep[],
  platform: Platform = "android",
): ShellProfile {
  return {
    name,
    weight,
    platformHost: createMockHost({ platform }),
    backed: steps.map((step) => step.capability),
    steps,
  };
}

export function createLightShell(platform: Platform = "android"): ShellProfile {
  return createShellProfile("潮汐消消", "light", LIGHT_SHELL_STEPS, platform);
}

export function createHeavyShell(platform: Platform = "ios"): ShellProfile {
  return createShellProfile("潮汐方舟", "heavy", HEAVY_SHELL_STEPS, platform);
}

export function contractGaps(
  profile: ShellProfile,
  required: readonly Capability[] = BASE_CONTRACT,
): readonly Capability[] {
  return required.filter((capability) => !profile.backed.includes(capability));
}

export function blockingCapabilities(profile: ShellProfile): readonly Capability[] {
  return profile.steps.filter((step) => step.blocking).map((step) => step.capability);
}

export function bootOrder(profile: ShellProfile): readonly Capability[] {
  return profile.steps.map((step) => step.capability);
}

export function fallbackFor(profile: ShellProfile, capability: Capability): Fallback | "missing" {
  const step = profile.steps.find((item) => item.capability === capability);
  return step ? step.fallback : "missing";
}

// file: test/platform/shell-profiles.test.ts
// tier: L2
// verify: node --test test/platform/shell-profiles.test.ts

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

import { BASE_CONTRACT } from "../../src/platform/shell-profiles.ts";
import {
  blockingCapabilities,
  bootOrder,
  contractGaps,
  createHeavyShell,
  createLightShell,
  fallbackFor,
} from "../../src/platform/shell-profiles.ts";

test("both shells satisfy the same base contract", () => {
  const light = createLightShell("android");
  const heavy = createHeavyShell("ios");
  assert.deepEqual(contractGaps(light), []);
  assert.deepEqual(contractGaps(heavy), []);
  assert.equal(light.weight, "light");
  assert.equal(heavy.weight, "heavy");
});

test("the light shell blocks only lifecycle and consent", () => {
  const light = createLightShell("android");
  assert.deepEqual(blockingCapabilities(light), ["lifecycle", "consent"]);
  assert.equal(fallbackFor(light, "account"), "guest");
  assert.equal(fallbackFor(light, "billing"), "stub");
  assert.equal(light.platformHost.shell, "activity");
});

test("the heavy shell blocks account, anti-addiction and channel sdk", () => {
  const heavy = createHeavyShell("ios");
  const blocking = blockingCapabilities(heavy);
  assert.ok(blocking.includes("account"));
  assert.ok(blocking.includes("anti-addiction"));
  assert.ok(blocking.includes("channel-sdk"));
  assert.equal(fallbackFor(heavy, "account"), "none");
  assert.equal(heavy.platformHost.shell, "ui-view-controller");
});

test("heavy-only capabilities do not leak into the light shell", () => {
  const light = createLightShell("android");
  const heavy = createHeavyShell("android");
  for (const capability of ["push", "anti-addiction", "channel-sdk"] as const) {
    assert.equal(light.backed.includes(capability), false);
    assert.equal(heavy.backed.includes(capability), true);
  }
});

test("contract gaps are reported per capability", () => {
  const light = createLightShell("android");
  const narrowed = { ...light, backed: light.backed.filter((item) => item !== "consent") };
  assert.deepEqual(contractGaps(narrowed), ["consent"]);
  assert.deepEqual(contractGaps(light, [...BASE_CONTRACT, "push"]), ["push"]);
});

test("boot order starts with lifecycle and every step has an adapter", () => {
  for (const profile of [createLightShell("android"), createHeavyShell("ios")]) {
    assert.equal(bootOrder(profile)[0], "lifecycle");
    for (const step of profile.steps) {
      assert.notEqual(step.adapter, "");
    }
  }
});

test("a capability outside the profile reports missing", () => {
  const light = createLightShell("android");
  assert.equal(fallbackFor(light, "anti-addiction"), "missing");
});