《移动游戏产品的架构·商业化与发行工程》3.2 渠道 SDK 接入契约与初始化顺序

SdkSpec = id + priority + provides + requires + timeoutMs + policy

// file: src/biz/sdk-contract.ts
// tier: L1
// verify: node --test test/biz/sdk-contract.test.ts

export type FailurePolicy = "block" | "degrade" | "retry";

export interface SdkSpec {
  readonly id: string;
  readonly priority: number;
  readonly provides: readonly string[];
  readonly requires: readonly string[];
  readonly timeoutMs: number;
  readonly policy: FailurePolicy;
}

export interface InitStep {
  readonly index: number;
  readonly id: string;
  readonly timeoutMs: number;
  readonly policy: FailurePolicy;
  readonly requires: readonly string[];
}

export interface InitPlan {
  readonly order: readonly string[];
  readonly steps: readonly InitStep[];
  readonly blockingMs: number;
  readonly degradableCapabilities: readonly string[];
  readonly blockingCapabilities: readonly string[];
}

export interface OrderViolation {
  readonly sdk: string;
  readonly missingBefore: readonly string[];
}

function compareSpecs(a: SdkSpec, b: SdkSpec): number {
  return a.priority - b.priority || a.id.localeCompare(b.id);
}

function validateSpecs(specs: readonly SdkSpec[]): Map<string, SdkSpec> {
  if (specs.length === 0) {
    throw new Error("at least one sdk spec is required");
  }
  const byId = new Map<string, SdkSpec>();
  for (const spec of specs) {
    if (typeof spec.id !== "string" || spec.id.length === 0) {
      throw new Error("sdk id is required");
    }
    if (byId.has(spec.id)) {
      throw new Error(`duplicate sdk id: ${spec.id}`);
    }
    if (!Number.isFinite(spec.priority)) {
      throw new RangeError(`priority must be finite for ${spec.id}`);
    }
    if (!Number.isInteger(spec.timeoutMs) || spec.timeoutMs <= 0) {
      throw new RangeError(`timeoutMs must be a positive integer for ${spec.id}`);
    }
    if (spec.provides.length === 0) {
      throw new Error(`sdk must provide at least one capability: ${spec.id}`);
    }
    if (spec.policy !== "block" && spec.policy !== "degrade" && spec.policy !== "retry") {
      throw new Error(`unknown failure policy for ${spec.id}: ${spec.policy}`);
    }
    byId.set(spec.id, spec);
  }
  for (const spec of specs) {
    for (const dependency of spec.requires) {
      if (dependency === spec.id) {
        throw new Error(`sdk cannot depend on itself: ${spec.id}`);
      }
      if (!byId.has(dependency)) {
        throw new Error(`unknown dependency ${dependency} required by ${spec.id}`);
      }
    }
  }
  return byId;
}

export function orderSdks(specs: readonly SdkSpec[]): readonly string[] {
  const byId = validateSpecs(specs);
  const remaining = new Map<string, Set<string>>();
  const dependents = new Map<string, string[]>();
  for (const spec of specs) {
    remaining.set(spec.id, new Set(spec.requires));
    for (const dependency of spec.requires) {
      const list = dependents.get(dependency) ?? [];
      list.push(spec.id);
      dependents.set(dependency, list);
    }
  }

  const ready = specs.filter((spec) => remaining.get(spec.id)?.size === 0);
  const order: string[] = [];
  while (ready.length > 0) {
    ready.sort(compareSpecs);
    const spec = ready.shift() as SdkSpec;
    order.push(spec.id);
    for (const dependentId of dependents.get(spec.id) ?? []) {
      const dependencies = remaining.get(dependentId);
      if (dependencies === undefined) {
        continue;
      }
      dependencies.delete(spec.id);
      if (dependencies.size === 0) {
        ready.push(byId.get(dependentId) as SdkSpec);
      }
    }
  }

  if (order.length !== specs.length) {
    const unresolved = specs.filter((spec) => !order.includes(spec.id)).map((spec) => spec.id);
    throw new Error(`sdk dependency cycle: ${unresolved.join(", ")}`);
  }
  return order;
}

export function checkOrder(order: readonly string[], specs: readonly SdkSpec[]): readonly OrderViolation[] {
  const byId = validateSpecs(specs);
  if (order.length !== specs.length) {
    throw new Error(`order must contain exactly ${specs.length} sdk ids`);
  }
  const seen = new Set<string>();
  const violations: OrderViolation[] = [];
  for (const id of order) {
    const spec = byId.get(id);
    if (spec === undefined) {
      throw new Error(`unknown sdk in order: ${id}`);
    }
    if (seen.has(id)) {
      throw new Error(`duplicate sdk in order: ${id}`);
    }
    const missingBefore = spec.requires.filter((dependency) => !seen.has(dependency));
    if (missingBefore.length > 0) {
      violations.push({ sdk: id, missingBefore });
    }
    seen.add(id);
  }
  return violations;
}

export function planInit(specs: readonly SdkSpec[], consentGranted: boolean): InitPlan {
  if (!consentGranted) {
    throw new Error("privacy consent must be granted before sdk init");
  }
  const byId = validateSpecs(specs);
  const order = orderSdks(specs);
  const steps: InitStep[] = order.map((id, index) => {
    const spec = byId.get(id) as SdkSpec;
    return {
      index,
      id,
      timeoutMs: spec.timeoutMs,
      policy: spec.policy,
      requires: [...spec.requires],
    };
  });

  let blockingMs = 0;
  const degradable: string[] = [];
  const blocking: string[] = [];
  for (const spec of specs) {
    if (spec.policy === "block") {
      blockingMs += spec.timeoutMs;
      blocking.push(...spec.provides);
    }
    if (spec.policy === "degrade") {
      degradable.push(...spec.provides);
    }
  }

  return {
    order,
    steps,
    blockingMs,
    degradableCapabilities: [...new Set(degradable)],
    blockingCapabilities: [...new Set(blocking)],
  };
}

export function formatInitPlan(plan: InitPlan): string {
  const degrade = plan.degradableCapabilities.join(",") || "none";
  return `order=${plan.order.join(">")} blocking=${plan.blockingMs}ms degrade=${degrade}`;
}

order=login>stats>pay>ad>push>share blocking=16000ms degrade=analytics,rewarded-ad,share