《移动游戏产品的架构·商业化与发行工程》6.1 广告位设计与激励视频边界

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

export type SlotKind = "rewarded" | "interstitial" | "banner";

export interface SlotSpec {
  readonly kind: SlotKind;
  readonly label: string;
  readonly userInitiated: boolean;
  readonly interrupting: boolean;
  readonly grantsReward: boolean;
}

export const SLOT_SPECS: Record<SlotKind, SlotSpec> = {
  rewarded: {
    kind: "rewarded",
    label: "激励视频",
    userInitiated: true,
    interrupting: false,
    grantsReward: true,
  },
  interstitial: {
    kind: "interstitial",
    label: "插屏",
    userInitiated: false,
    interrupting: true,
    grantsReward: false,
  },
  banner: {
    kind: "banner",
    label: "Banner",
    userInitiated: false,
    interrupting: false,
    grantsReward: false,
  },
};

export interface AdProfile {
  readonly product: string;
  readonly slots: readonly SlotKind[];
  readonly rewardedPerDauPerDay: number;
  readonly rewardedEcpm: number;
}

export const AD_PROFILES: Record<"chaoxi" | "ark", AdProfile> = {
  chaoxi: {
    product: "潮汐消消",
    slots: ["rewarded", "interstitial", "banner"],
    rewardedPerDauPerDay: 3.5,
    rewardedEcpm: 45,
  },
  ark: {
    product: "潮汐方舟",
    slots: ["rewarded"],
    rewardedPerDauPerDay: 1.5,
    rewardedEcpm: 80,
  },
};

export interface RewardPolicy {
  readonly dailyCap: number;
  readonly cooldownSec: number;
}

export interface RewardRequest {
  readonly watchedToday: number;
  readonly secondsSinceLast: number;
  readonly fillAvailable: boolean;
}

export type RewardRejection = "daily-cap" | "cooldown" | "no-fill";

export interface RewardDecision {
  readonly allow: boolean;
  readonly reason: "ok" | RewardRejection;
  readonly remainingToday: number;
  readonly retryAfterSec: number;
}

function assertNonNegativeInteger(value: number, name: string): void {
  if (!Number.isInteger(value) || value < 0) {
    throw new Error(`${name} must be a non-negative integer, got ${value}`);
  }
}

export function checkReward(request: RewardRequest, policy: RewardPolicy): RewardDecision {
  assertNonNegativeInteger(policy.dailyCap, "dailyCap");
  assertNonNegativeInteger(policy.cooldownSec, "cooldownSec");
  assertNonNegativeInteger(request.watchedToday, "watchedToday");
  assertNonNegativeInteger(request.secondsSinceLast, "secondsSinceLast");

  const remainingToday = Math.max(0, policy.dailyCap - request.watchedToday);
  if (remainingToday === 0) {
    return { allow: false, reason: "daily-cap", remainingToday: 0, retryAfterSec: 0 };
  }
  if (request.secondsSinceLast < policy.cooldownSec) {
    return {
      allow: false,
      reason: "cooldown",
      remainingToday,
      retryAfterSec: policy.cooldownSec - request.secondsSinceLast,
    };
  }
  if (!request.fillAvailable) {
    return { allow: false, reason: "no-fill", remainingToday, retryAfterSec: 0 };
  }
  return { allow: true, reason: "ok", remainingToday, retryAfterSec: 0 };
}

export function validateSlotPlan(slots: readonly SlotKind[]): string[] {
  const errors: string[] = [];
  if (slots.length === 0) {
    errors.push("广告位组合不能为空");
  }
  if (new Set(slots).size !== slots.length) {
    errors.push("广告位不能重复");
  }
  return errors;
}

export function assertSlotPlan(slots: readonly SlotKind[]): void {
  const errors = validateSlotPlan(slots);
  if (errors.length > 0) {
    throw new Error(errors.join("; "));
  }
}

export function formatProfile(profile: AdProfile): string {
  return `${profile.product} slots=${profile.slots.join("+")} reward/day=${profile.rewardedPerDauPerDay} ecpm=¥${profile.rewardedEcpm}`;
}

export function formatReward(decision: RewardDecision): string {
  if (decision.allow) {
    return `allow remaining=${decision.remainingToday}`;
  }
  return `deny reason=${decision.reason} remaining=${decision.remainingToday} retry=${decision.retryAfterSec}s`;
}