《移动游戏产品的架构·商业化与发行工程》9.1 活动配置、时间窗口与灰度

now < start          → upcoming
start <= now < end   → active
now >= end           → ended

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

export type Platform = "ios" | "android" | "tapTap" | "googlePlay";
export type CampaignPhase = "upcoming" | "active" | "ended";
export type ExposureReason =
  | "paused"
  | "before-window"
  | "after-window"
  | "platform-excluded"
  | "version-excluded"
  | "whitelist"
  | "bucket-in"
  | "bucket-out";

export interface CampaignConfig {
  readonly id: string;
  readonly startAt: string;
  readonly endAt: string;
  readonly platforms: readonly Platform[];
  readonly minAppVersion: string;
  readonly grayPercent: number;
  readonly whitelist: readonly string[];
  readonly paused: boolean;
}

export interface PlayerContext {
  readonly playerId: string;
  readonly platform: Platform;
  readonly appVersion: string;
}

export interface ExposureDecision {
  readonly campaignId: string;
  readonly phase: CampaignPhase;
  readonly exposed: boolean;
  readonly bucket: number;
  readonly cutoff: number;
  readonly reason: ExposureReason;
}

const BUCKETS = 10_000;
const VERSION_PATTERN = /^\d+\.\d+\.\d+$/;
const PLATFORMS: ReadonlySet<string> = new Set(["ios", "android", "tapTap", "googlePlay"]);

function windowOf(config: CampaignConfig): { start: number; end: number } {
  const start = Date.parse(config.startAt);
  const end = Date.parse(config.endAt);
  if (!Number.isFinite(start) || !Number.isFinite(end)) {
    throw new RangeError(`campaign ${config.id} has an invalid time window`);
  }
  if (start >= end) {
    throw new RangeError(`campaign ${config.id} must start before it ends`);
  }
  return { start, end };
}

export function validateCampaign(config: CampaignConfig): CampaignConfig {
  if (config.id.trim() === "") {
    throw new RangeError("campaign id must not be empty");
  }
  windowOf(config);
  if (config.platforms.length === 0) {
    throw new RangeError("campaign must target at least one platform");
  }
  for (const platform of config.platforms) {
    if (!PLATFORMS.has(platform)) {
      throw new RangeError(`unsupported platform: ${platform}`);
    }
  }
  if (new Set(config.platforms).size !== config.platforms.length) {
    throw new RangeError("campaign platforms must be unique");
  }
  if (!VERSION_PATTERN.test(config.minAppVersion)) {
    throw new RangeError(`minAppVersion must look like 1.2.3, got ${config.minAppVersion}`);
  }
  if (
    !Number.isFinite(config.grayPercent) ||
    config.grayPercent < 0 ||
    config.grayPercent > 100
  ) {
    throw new RangeError(`grayPercent must be between 0 and 100, got ${config.grayPercent}`);
  }
  if (new Set(config.whitelist).size !== config.whitelist.length) {
    throw new RangeError("campaign whitelist must not contain duplicates");
  }
  return config;
}

export function campaignPhase(config: CampaignConfig, nowMs: number): CampaignPhase {
  if (!Number.isFinite(nowMs)) {
    throw new RangeError(`nowMs must be finite, got ${nowMs}`);
  }
  const { start, end } = windowOf(config);
  if (nowMs < start) return "upcoming";
  if (nowMs >= end) return "ended";
  return "active";
}

export function bucketCutoff(grayPercent: number): number {
  if (!Number.isFinite(grayPercent) || grayPercent < 0 || grayPercent > 100) {
    throw new RangeError(`grayPercent must be between 0 and 100, got ${grayPercent}`);
  }
  return Math.floor((grayPercent * BUCKETS) / 100);
}

export function assignBucket(playerId: string, salt: string): number {
  if (playerId.trim() === "" || salt.trim() === "") {
    throw new RangeError("playerId and salt must not be empty");
  }
  let hash = 0x811c9dc5;
  const input = `${salt}:${playerId}`;
  for (let index = 0; index < input.length; index += 1) {
    hash ^= input.charCodeAt(index);
    hash = Math.imul(hash, 0x01000193);
  }
  return (hash >>> 0) % BUCKETS;
}

export function compareVersions(left: string, right: string): number {
  if (!VERSION_PATTERN.test(left) || !VERSION_PATTERN.test(right)) {
    throw new RangeError(`versions must look like 1.2.3, got ${left} and ${right}`);
  }
  const a = left.split(".").map(Number);
  const b = right.split(".").map(Number);
  for (let index = 0; index < 3; index += 1) {
    if (a[index] !== b[index]) return a[index] - b[index];
  }
  return 0;
}

export function decideExposure(
  config: CampaignConfig,
  player: PlayerContext,
  nowMs: number,
): ExposureDecision {
  validateCampaign(config);
  if (player.playerId.trim() === "") {
    throw new RangeError("playerId must not be empty");
  }
  if (!PLATFORMS.has(player.platform)) {
    throw new RangeError(`unsupported player platform: ${player.platform}`);
  }
  if (!VERSION_PATTERN.test(player.appVersion)) {
    throw new RangeError(`appVersion must look like 1.2.3, got ${player.appVersion}`);
  }

  const { start, end } = windowOf(config);
  const phase: CampaignPhase = nowMs < start ? "upcoming" : nowMs >= end ? "ended" : "active";
  const bucket = assignBucket(player.playerId, config.id);
  const cutoff = bucketCutoff(config.grayPercent);
  let exposed = false;
  let reason: ExposureReason;

  if (config.paused) {
    reason = "paused";
  } else if (phase === "upcoming") {
    reason = "before-window";
  } else if (phase === "ended") {
    reason = "after-window";
  } else if (!config.platforms.includes(player.platform)) {
    reason = "platform-excluded";
  } else if (compareVersions(player.appVersion, config.minAppVersion) < 0) {
    reason = "version-excluded";
  } else if (config.whitelist.includes(player.playerId)) {
    exposed = true;
    reason = "whitelist";
  } else if (bucket < cutoff) {
    exposed = true;
    reason = "bucket-in";
  } else {
    reason = "bucket-out";
  }

  return { campaignId: config.id, phase, exposed, bucket, cutoff, reason };
}

export function formatExposure(decision: ExposureDecision): string {
  return `${decision.campaignId} phase=${decision.phase} exposed=${decision.exposed} bucket=${decision.bucket} cutoff=${decision.cutoff} reason=${decision.reason}`;
}