《移动游戏产品的架构·商业化与发行工程》11.1 推送通道与到达率

覆盖率 = 各通道用户占比之和
目标数 = 用户数 × 覆盖率
预计送达 = 目标数 × 通道到达率 × (1 - 重叠系数)

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

export type PushChannel = "apns" | "fcm" | "oem" | "inapp";
export type TokenStatus = "active" | "stale" | "invalid";
export type TokenEvent = "refreshed" | "aged" | "rejected";

export interface PushToken {
  readonly channel: PushChannel;
  readonly value: string;
  readonly status: TokenStatus;
  readonly lastSeenAtMs: number;
}

export interface ChannelPolicy {
  readonly arrivalRate: number;
  readonly overlapFactor: number;
  readonly maxSilenceMs: number;
  readonly fallbackChannel: PushChannel;
}

export interface AudienceSegment {
  readonly name: string;
  readonly users: number;
  readonly channelMix: Readonly<Partial<Record<PushChannel, number>>>;
}

export interface ReachEstimate {
  readonly segment: string;
  readonly users: number;
  readonly targeted: number;
  readonly expectedDelivered: number;
  readonly untargeted: number;
  readonly undelivered: number;
  readonly arrivalRate: number;
}

export interface ReachReport {
  readonly estimates: readonly ReachEstimate[];
  readonly totalUsers: number;
  readonly totalTargeted: number;
  readonly totalDelivered: number;
  readonly blendedRate: number;
}

const KNOWN_CHANNELS: readonly PushChannel[] = ["apns", "fcm", "oem", "inapp"];

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

function assertRate(name: string, value: number): void {
  assertFinite(name, value);
  if (value < 0 || value > 1) {
    throw new RangeError(`${name} must be between 0 and 1, got ${value}`);
  }
}

function assertChannel(name: string, channel: string): void {
  if (!KNOWN_CHANNELS.includes(channel as PushChannel)) {
    throw new RangeError(`${name} must be a known push channel, got ${channel}`);
  }
}

export function normalizeChannelMix(
  mix: Readonly<Partial<Record<PushChannel, number>>>,
): Readonly<Record<PushChannel, number>> {
  const normalized: Record<PushChannel, number> = { apns: 0, fcm: 0, oem: 0, inapp: 0 };
  let total = 0;
  for (const channel of KNOWN_CHANNELS) {
    const value = mix[channel] ?? 0;
    assertRate(`channelMix.${channel}`, value);
    normalized[channel] = value;
    total += value;
  }
  if (total > 1 + 1e-9) {
    throw new RangeError(`channel mix must not exceed 1, got ${total}`);
  }
  return normalized;
}

export function advanceToken(
  token: PushToken,
  event: TokenEvent,
  nowMs: number,
  policy: ChannelPolicy,
): PushToken {
  if (token.value.trim() === "") {
    throw new RangeError("token value must not be empty");
  }
  assertChannel("token.channel", token.channel);
  assertFinite("nowMs", nowMs);
  assertFinite("token.lastSeenAtMs", token.lastSeenAtMs);
  if (token.lastSeenAtMs < 0) {
    throw new RangeError("token.lastSeenAtMs must not be negative");
  }
  if (nowMs < token.lastSeenAtMs) {
    throw new RangeError("nowMs cannot be earlier than token.lastSeenAtMs");
  }
  if (!Number.isFinite(policy.maxSilenceMs) || policy.maxSilenceMs <= 0) {
    throw new RangeError("maxSilenceMs must be a positive finite number");
  }
  if (token.status === "invalid") {
    return token;
  }
  if (event === "rejected") {
    return { ...token, status: "invalid" };
  }
  if (event === "refreshed") {
    return { ...token, status: "active", lastSeenAtMs: nowMs };
  }
  const silence = nowMs - token.lastSeenAtMs;
  if (silence > policy.maxSilenceMs * 2) {
    return { ...token, status: "invalid" };
  }
  if (silence > policy.maxSilenceMs) {
    return { ...token, status: "stale" };
  }
  return token.status === "stale" ? token : { ...token, status: "active" };
}

export function estimateReach(segment: AudienceSegment, policy: ChannelPolicy): ReachEstimate {
  assertFinite("segment.users", segment.users);
  if (segment.users < 0) {
    throw new RangeError(`segment.users must not be negative, got ${segment.users}`);
  }
  assertRate("arrivalRate", policy.arrivalRate);
  assertRate("overlapFactor", policy.overlapFactor);
  const mix = normalizeChannelMix(segment.channelMix);
  const coverage = KNOWN_CHANNELS.reduce((sum, channel) => sum + mix[channel], 0);
  const targeted = Math.round(segment.users * coverage);
  const expectedDelivered = Math.round(targeted * policy.arrivalRate * (1 - policy.overlapFactor));
  return {
    segment: segment.name,
    users: segment.users,
    targeted,
    expectedDelivered,
    untargeted: segment.users - targeted,
    undelivered: targeted - expectedDelivered,
    arrivalRate: policy.arrivalRate,
  };
}

export function summarizeReach(
  segments: readonly AudienceSegment[],
  policy: ChannelPolicy,
): ReachReport {
  const estimates = segments.map((segment) => estimateReach(segment, policy));
  const totalUsers = estimates.reduce((sum, item) => sum + item.users, 0);
  const totalTargeted = estimates.reduce((sum, item) => sum + item.targeted, 0);
  const totalDelivered = estimates.reduce((sum, item) => sum + item.expectedDelivered, 0);
  return {
    estimates,
    totalUsers,
    totalTargeted,
    totalDelivered,
    blendedRate: totalUsers === 0 ? 0 : totalDelivered / totalUsers,
  };
}

export function chooseFallback(token: PushToken, policy: ChannelPolicy): PushChannel {
  assertChannel("token.channel", token.channel);
  assertChannel("fallbackChannel", policy.fallbackChannel);
  if (token.status === "active") {
    return token.channel;
  }
  return policy.fallbackChannel;
}

export function formatReachReport(report: ReachReport): string {
  const rate = (report.blendedRate * 100).toFixed(1);
  return `segments=${report.estimates.length} users=${report.totalUsers} targeted=${report.totalTargeted} delivered=${report.totalDelivered} rate=${rate}%`;
}