《移动游戏产品的架构·商业化与发行工程》2.1 游客、账号与三端互通的标识设计

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

export type Platform = "android_cn" | "ios" | "taptap" | "google_play" | "overseas";
export type AccountKind = "guest" | "registered";

export interface IdentityBinding {
  readonly platform: Platform;
  readonly openId: string;
}

export interface PlayerIdentity {
  readonly playerId: string;
  readonly kind: AccountKind;
  readonly region: string;
  readonly bindings: readonly IdentityBinding[];
}

export class IdentityError extends Error {
  readonly code: string;

  constructor(code: string, message: string) {
    super(message);
    this.name = "IdentityError";
    this.code = code;
  }
}

const PLATFORM_PREFIX: Record<Platform, string> = {
  android_cn: "ac",
  ios: "ios",
  taptap: "tt",
  google_play: "gp",
  overseas: "ov",
};

const REGION_PATTERN = /^[a-z0-9-]{2,12}$/;

function fail(code: string, message: string): never {
  throw new IdentityError(code, message);
}

export function normalizeRegion(region: string): string {
  const value = region.trim().toLowerCase();
  if (!REGION_PATTERN.test(value)) {
    fail("INVALID_REGION", `region must match ${REGION_PATTERN.source}`);
  }
  return value;
}

export function bindingKey(binding: IdentityBinding): string {
  const openId = binding.openId.trim();
  if (openId.length === 0) {
    fail("EMPTY_OPEN_ID", "openId must not be empty");
  }
  return `${binding.platform}:${openId}`;
}

export function createGuestIdentity(region: string, sequence: number): PlayerIdentity {
  if (!Number.isInteger(sequence) || sequence < 1) {
    fail("INVALID_SEQUENCE", "sequence must be a positive integer");
  }
  const normalized = normalizeRegion(region);
  const playerId = `g-${normalized}-${String(sequence).padStart(6, "0")}`;
  return { playerId, kind: "guest", region: normalized, bindings: [] };
}

export function assertIdentity(identity: PlayerIdentity): void {
  if (!/^g-[a-z0-9-]+-\d{6,}$/.test(identity.playerId)) {
    fail("INVALID_PLAYER_ID", `invalid playerId: ${identity.playerId}`);
  }
  normalizeRegion(identity.region);
  const seenPlatforms = new Set<Platform>();
  const seenKeys = new Set<string>();
  for (const binding of identity.bindings) {
    const key = bindingKey(binding);
    if (seenPlatforms.has(binding.platform)) {
      fail("DUPLICATE_PLATFORM", `platform already bound: ${binding.platform}`);
    }
    if (seenKeys.has(key)) {
      fail("DUPLICATE_BINDING", `binding already present: ${key}`);
    }
    seenPlatforms.add(binding.platform);
    seenKeys.add(key);
  }
  if (identity.kind === "guest" && identity.bindings.length > 0) {
    fail("GUEST_HAS_BINDING", "guest identity must not carry platform bindings");
  }
  if (identity.kind === "registered" && identity.bindings.length === 0) {
    fail("REGISTERED_WITHOUT_BINDING", "registered identity needs at least one binding");
  }
}

export function bindPlatform(identity: PlayerIdentity, binding: IdentityBinding): PlayerIdentity {
  assertIdentity(identity);
  if (identity.kind !== "registered") {
    fail("NOT_REGISTERED", "only registered identities can bind more platforms");
  }
  bindingKey(binding);
  if (identity.bindings.some((item) => item.platform === binding.platform)) {
    fail("PLATFORM_ALREADY_BOUND", `platform already bound: ${binding.platform}`);
  }
  const next: PlayerIdentity = {
    ...identity,
    bindings: [...identity.bindings, { platform: binding.platform, openId: binding.openId.trim() }],
  };
  assertIdentity(next);
  return next;
}

export function upgradeGuest(identity: PlayerIdentity, binding: IdentityBinding): PlayerIdentity {
  assertIdentity(identity);
  if (identity.kind !== "guest") {
    fail("NOT_GUEST", "only a guest identity can be upgraded");
  }
  bindingKey(binding);
  const next: PlayerIdentity = {
    ...identity,
    kind: "registered",
    bindings: [{ platform: binding.platform, openId: binding.openId.trim() }],
  };
  assertIdentity(next);
  return next;
}

export function indexIdentities(identities: readonly PlayerIdentity[]): Map<string, string> {
  const index = new Map<string, string>();
  const players = new Set<string>();
  for (const identity of identities) {
    assertIdentity(identity);
    if (players.has(identity.playerId)) {
      fail("DUPLICATE_PLAYER", `playerId appears twice: ${identity.playerId}`);
    }
    players.add(identity.playerId);
    for (const binding of identity.bindings) {
      const key = bindingKey(binding);
      const owner = index.get(key);
      if (owner !== undefined) {
        fail("BINDING_TAKEN", `binding ${key} already owned by ${owner}`);
      }
      index.set(key, identity.playerId);
    }
  }
  return index;
}

export function findPlayerByIdentity(
  identities: readonly PlayerIdentity[],
  binding: IdentityBinding,
): PlayerIdentity | null {
  const key = bindingKey(binding);
  for (const identity of identities) {
    if (identity.bindings.some((item) => bindingKey(item) === key)) {
      return identity;
    }
  }
  return null;
}

export function formatIdentity(identity: PlayerIdentity): string {
  const bindings = identity.bindings
    .map((binding) => `${PLATFORM_PREFIX[binding.platform]}=${binding.openId.trim()}`)
    .sort()
    .join(",");
  return `${identity.playerId} ${identity.kind} region=${identity.region} bindings=${bindings || "none"}`;
}