《互联网产品的客户端架构·内容、社交与实时互动》10.3 推送降级：没有推送权限时怎么补

// file: src/notify/push-fallback.ts
// tier: L1
// verify: node --test test/notify/push-fallback.test.ts
export type PermissionState = "granted" | "denied" | "prompt";
export type TokenState = "valid" | "expired" | "missing";

export interface PushEnv {
  permission: PermissionState;
  systemEnabled: boolean;
  token: TokenState;
  appForeground: boolean;
}

export type PushChannel = "system" | "in-app";

export type PushAction =
  | "request-permission"
  | "open-settings"
  | "register-token"
  | "sync-on-open"
  | "foreground-poll";

export interface PushPlan {
  channel: PushChannel;
  systemReachable: boolean;
  actions: PushAction[];
  reason: string;
}

// 降级不是「没有推送就什么都不做」，而是按失败原因给出不同的恢复动作。
export function planPush(env: PushEnv): PushPlan {
  if (env.permission === "prompt") {
    return {
      channel: "in-app",
      systemReachable: false,
      actions: ["request-permission", "sync-on-open"],
      reason: "尚未授权，先向用户请求一次",
    };
  }
  if (env.permission === "denied") {
    return {
      channel: "in-app",
      systemReachable: false,
      actions: ["open-settings", "sync-on-open"],
      reason: "权限被拒，只有用户去系统设置才能恢复",
    };
  }
  if (!env.systemEnabled) {
    return {
      channel: "in-app",
      systemReachable: false,
      actions: ["open-settings", "sync-on-open"],
      reason: "系统通知开关关闭，应用内无法绕过",
    };
  }
  if (env.token !== "valid") {
    return {
      channel: "in-app",
      systemReachable: false,
      actions: ["register-token", "sync-on-open"],
      reason: env.token === "expired" ? "推送令牌过期，需要重新注册" : "推送令牌缺失，需要重新注册",
    };
  }
  if (env.appForeground) {
    return {
      channel: "in-app",
      systemReachable: false,
      actions: ["foreground-poll"],
      reason: "应用在前台，系统通知不展示，改用应用内提醒",
    };
  }
  return { channel: "system", systemReachable: true, actions: [], reason: "推送链路可用" };
}

export const SYNC_MAX_AGE_MS = 5 * 60_000;

export interface SyncDecision {
  shouldSync: boolean;
  full: boolean;
  reason: string;
}

// 推送只是加速器；只要链路不完整，打开应用就必须做一次完整补偿同步。
export function decideOpenSync(
  env: PushEnv,
  now: number,
  lastSyncAt: number,
  maxAgeMs = SYNC_MAX_AGE_MS,
): SyncDecision {
  if (!Number.isInteger(maxAgeMs) || maxAgeMs < 0) throw new Error("maxAgeMs 必须是非负整数");
  const degraded =
    env.permission !== "granted" || !env.systemEnabled || env.token !== "valid";
  if (degraded) {
    return { shouldSync: true, full: true, reason: "推送链路不可用，打开应用必须补偿同步" };
  }
  const age = Math.max(0, now - lastSyncAt);
  if (age >= maxAgeMs) {
    return { shouldSync: true, full: true, reason: "距上次同步超过阈值" };
  }
  return { shouldSync: false, full: false, reason: "推送可用且同步足够新" };
}

export interface BadgeState {
  total: number;
  updatedAt: number;
}

export interface PushBadgePayload {
  badge: number;
  sentAt: number;
}

// 推送携带的角标是发送时刻的快照。晚到的旧快照不能把用户刚读掉的数字重新点亮。
export function applyPushBadge(local: BadgeState, payload: PushBadgePayload): BadgeState {
  if (!Number.isInteger(local.total) || local.total < 0) throw new Error("local.total 必须是非负整数");
  if (!Number.isInteger(local.updatedAt) || local.updatedAt < 0) {
    throw new Error("local.updatedAt 必须是非负整数");
  }
  if (!Number.isInteger(payload.badge) || payload.badge < 0) {
    throw new Error("payload.badge 必须是非负整数");
  }
  if (!Number.isInteger(payload.sentAt) || payload.sentAt < 0) {
    throw new Error("payload.sentAt 必须是非负整数");
  }
  // 同一毫秒时本地优先：用户刚做的已读操作不应被一条同时刻的推送覆盖。
  if (payload.sentAt <= local.updatedAt) return { ...local };
  return { total: payload.badge, updatedAt: payload.sentAt };
}

$ node --test test/notify/push-fallback.test.ts
✔ 权限、系统开关、令牌都正常时走系统推送 (0.805667ms)
✔ 权限被拒时只能应用内提醒，并引导去系统设置 (0.116708ms)
✔ 尚未授权时先请求一次，而不是直接放弃 (0.06025ms)
✔ 系统通知开关关闭与权限被拒需要同样的设置引导 (0.060916ms)
✔ 令牌失效时先重新注册，注册完成前仍按降级处理 (0.542958ms)
✔ 应用在前台时不弹系统通知，改用应用内轮询 (0.131041ms)
✔ 推送链路不可用时打开应用强制补偿同步 (0.145833ms)
✔ 迟到的推送角标不覆盖更新的本地已读 (0.114ms)
ℹ tests 8
ℹ suites 0
ℹ pass 8
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 117.794583