《移动游戏产品的架构·商业化与发行工程》11.3 召回活动的频控与退订合规

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

export type RecallChannel = "push" | "sms" | "inapp" | "email";
export type RecallDecision = "send" | "defer" | "suppress";

export interface ConsentState {
  readonly push: boolean;
  readonly sms: boolean;
  readonly inapp: boolean;
  readonly email: boolean;
  readonly globalOptOut: boolean;
}

export interface RecallCandidate {
  readonly userId: string;
  readonly lastActiveAtMs: number;
  readonly timezoneOffsetMinutes: number;
  readonly consent: ConsentState;
  readonly sentThisWeek: number;
}

export interface RecallPolicy {
  readonly weeklyCap: number;
  readonly quietStartHour: number;
  readonly quietEndHour: number;
  readonly inactiveDays: number;
  readonly allowedChannels: readonly RecallChannel[];
}

export interface RecallCampaign {
  readonly id: string;
  readonly channel: RecallChannel;
}

export interface RecallPlan {
  readonly userId: string;
  readonly campaign: string;
  readonly channel: RecallChannel;
  readonly decision: RecallDecision;
  readonly reason: string;
  readonly localHour: number;
}

export interface RecallSummary {
  readonly send: number;
  readonly defer: number;
  readonly suppress: number;
  readonly total: number;
}

const DAY_MS = 86_400_000;
const HOUR_MS = 3_600_000;
const KNOWN_CHANNELS: readonly RecallChannel[] = ["push", "sms", "inapp", "email"];

function assertInteger(name: string, value: number, min: number, max: number): void {
  if (!Number.isInteger(value) || value < min || value > max) {
    throw new RangeError(`${name} must be an integer between ${min} and ${max}, got ${value}`);
  }
}

function assertFinite(name: string, value: number): void {
  if (!Number.isFinite(value)) {
    throw new RangeError(`${name} must be a finite number, got ${value}`);
  }
}

function validatePolicy(policy: RecallPolicy): void {
  assertInteger("weeklyCap", policy.weeklyCap, 0, 100);
  assertInteger("quietStartHour", policy.quietStartHour, 0, 23);
  assertInteger("quietEndHour", policy.quietEndHour, 0, 23);
  assertInteger("inactiveDays", policy.inactiveDays, 0, 3_650);
  for (const channel of policy.allowedChannels) {
    if (!KNOWN_CHANNELS.includes(channel)) {
      throw new RangeError(`allowedChannels contains an unknown channel: ${channel}`);
    }
  }
}

function hasConsent(consent: ConsentState, channel: RecallChannel): boolean {
  switch (channel) {
    case "push":
      return consent.push;
    case "sms":
      return consent.sms;
    case "inapp":
      return consent.inapp;
    case "email":
      return consent.email;
  }
}

export function localHourAt(nowMs: number, offsetMinutes: number): number {
  assertFinite("nowMs", nowMs);
  assertInteger("offsetMinutes", offsetMinutes, -720, 840);
  const shifted = nowMs + offsetMinutes * 60_000;
  const hours = Math.floor(shifted / HOUR_MS);
  return ((hours % 24) + 24) % 24;
}

export function isQuietHour(hour: number, startHour: number, endHour: number): boolean {
  assertInteger("hour", hour, 0, 23);
  assertInteger("startHour", startHour, 0, 23);
  assertInteger("endHour", endHour, 0, 23);
  if (startHour === endHour) {
    return false;
  }
  if (startHour < endHour) {
    return hour >= startHour && hour < endHour;
  }
  return hour >= startHour || hour < endHour;
}

export function evaluateCandidate(
  candidate: RecallCandidate,
  campaign: RecallCampaign,
  policy: RecallPolicy,
  nowMs: number,
): RecallPlan {
  validatePolicy(policy);
  assertFinite("nowMs", nowMs);
  assertFinite("lastActiveAtMs", candidate.lastActiveAtMs);
  if (candidate.lastActiveAtMs > nowMs) {
    throw new RangeError("lastActiveAtMs cannot be in the future");
  }
  assertInteger("sentThisWeek", candidate.sentThisWeek, 0, 10_000);
  if (!KNOWN_CHANNELS.includes(campaign.channel)) {
    throw new RangeError(`unknown recall channel: ${campaign.channel}`);
  }
  const localHour = localHourAt(nowMs, candidate.timezoneOffsetMinutes);
  const base = {
    userId: candidate.userId,
    campaign: campaign.id,
    channel: campaign.channel,
    localHour,
  };
  if (candidate.consent.globalOptOut) {
    return { ...base, decision: "suppress", reason: "global-opt-out" };
  }
  if (!hasConsent(candidate.consent, campaign.channel)) {
    return { ...base, decision: "suppress", reason: "channel-opt-out" };
  }
  if (!policy.allowedChannels.includes(campaign.channel)) {
    return { ...base, decision: "suppress", reason: "channel-disabled" };
  }
  if (candidate.sentThisWeek >= policy.weeklyCap) {
    return { ...base, decision: "suppress", reason: "weekly-cap" };
  }
  if (nowMs - candidate.lastActiveAtMs < policy.inactiveDays * DAY_MS) {
    return { ...base, decision: "suppress", reason: "recently-active" };
  }
  if (isQuietHour(localHour, policy.quietStartHour, policy.quietEndHour)) {
    return { ...base, decision: "defer", reason: "quiet-hours" };
  }
  return { ...base, decision: "send", reason: "eligible" };
}

export function planRecall(
  candidates: readonly RecallCandidate[],
  campaign: RecallCampaign,
  policy: RecallPolicy,
  nowMs: number,
): readonly RecallPlan[] {
  return candidates.map((candidate) => evaluateCandidate(candidate, campaign, policy, nowMs));
}

export function summarizeRecall(plans: readonly RecallPlan[]): RecallSummary {
  return {
    send: plans.filter((plan) => plan.decision === "send").length,
    defer: plans.filter((plan) => plan.decision === "defer").length,
    suppress: plans.filter((plan) => plan.decision === "suppress").length,
    total: plans.length,
  };
}

export function formatRecallPlan(
  campaign: RecallCampaign,
  plans: readonly RecallPlan[],
): string {
  const summary = summarizeRecall(plans);
  return `campaign=${campaign.id} channel=${campaign.channel} total=${summary.total} send=${summary.send} defer=${summary.defer} suppress=${summary.suppress}`;
}