《互联网产品的客户端架构·内容、社交与实时互动》2.3 刷新策略：下拉、自动、回到前台该不该拉

interface RefreshRuntime {
  inFlight: boolean;
  queuedTrigger: "pull" | "poll" | "foreground" | null;
  lastRefreshAt: number | null;
  epoch: number;
}

// file: src/feed/refresh-policy.ts
// tier: L1
// verify: node --test test/feed/refresh-policy.test.ts
export type RefreshTrigger = "pull" | "poll" | "foreground";
export type RefreshAction = "start" | "queue" | "skip";

export interface RefreshState {
  trigger: RefreshTrigger;
  now: number;
  lastRefreshAt: number | null;
  inFlight: boolean;
  scrolledScreens: number;
  unseenCount: number;
}

export interface RefreshPolicy {
  pollInterval: number;
  foregroundStale: number;
  pullCooldown: number;
  readingScreens: number;
}

export const DEFAULT_REFRESH_POLICY: RefreshPolicy = {
  pollInterval: 30_000,
  foregroundStale: 5 * 60_000,
  pullCooldown: 2_000,
  readingScreens: 1,
};

export function decideRefresh(
  state: RefreshState,
  policy: RefreshPolicy = DEFAULT_REFRESH_POLICY,
): RefreshAction {
  if (state.inFlight) return "queue";
  const since = state.lastRefreshAt === null ? Number.POSITIVE_INFINITY : state.now - state.lastRefreshAt;
  if (state.trigger === "pull") {
    // 用户意图优先于位置保护，但仍要挡住连点造成的重复请求。
    return since < policy.pullCooldown ? "skip" : "start";
  }
  if (state.trigger === "poll") {
    if (since < policy.pollInterval) return "skip";
    // 已经读进去一屏以上时，自动刷新会打断阅读，改为排队。
    return state.scrolledScreens >= policy.readingScreens ? "queue" : "start";
  }
  // 回到前台：有实时未读数就立即合并，否则只在过期后刷新。
  if (state.unseenCount > 0) return "start";
  return since < policy.foregroundStale ? "skip" : "start";
}

export interface RefreshRuntime {
  inFlight: boolean;
  queuedTrigger: RefreshTrigger | null;
  lastRefreshAt: number | null;
  epoch: number;
}

export const IDLE_RUNTIME: RefreshRuntime = {
  inFlight: false,
  queuedTrigger: null,
  lastRefreshAt: null,
  epoch: 0,
};

export interface RefreshStep {
  runtime: RefreshRuntime;
  action: RefreshAction;
}

export function requestRefresh(
  runtime: RefreshRuntime,
  state: RefreshState,
  policy: RefreshPolicy = DEFAULT_REFRESH_POLICY,
): RefreshStep {
  const action = decideRefresh({ ...state, inFlight: runtime.inFlight }, policy);
  if (action === "skip") return { runtime, action };
  if (action === "queue") {
    // 多次排队只保留最新一次触发，合并成一次后续刷新。
    return { runtime: { ...runtime, queuedTrigger: state.trigger }, action };
  }
  return { runtime: { ...runtime, inFlight: true, epoch: runtime.epoch + 1 }, action };
}

// 阅读停下来后，把排队的刷新真正启动。
export function startQueued(runtime: RefreshRuntime): RefreshStep {
  if (runtime.inFlight || runtime.queuedTrigger === null) {
    return { runtime, action: "skip" };
  }
  return {
    runtime: { ...runtime, inFlight: true, queuedTrigger: null, epoch: runtime.epoch + 1 },
    action: "start",
  };
}

export interface CompleteStep {
  runtime: RefreshRuntime;
  followUp: RefreshTrigger | null;
}

export function completeRefresh(runtime: RefreshRuntime, now: number): CompleteStep {
  const followUp = runtime.queuedTrigger;
  if (followUp === null) {
    return { runtime: { ...runtime, inFlight: false, lastRefreshAt: now }, followUp };
  }
  return {
    runtime: { ...runtime, inFlight: true, queuedTrigger: null, lastRefreshAt: now, epoch: runtime.epoch + 1 },
    followUp,
  };
}

export interface Anchor {
  id: string | null;
  offset: number;
}

export interface AnchorResolution {
  index: number;
  offset: number;
  found: boolean;
}

export function captureAnchor(
  items: ReadonlyArray<{ id: string }>,
  index: number,
  offset: number,
): Anchor {
  const item = items[index];
  return { id: item?.id ?? null, offset };
}

export function resolveAnchor(
  items: ReadonlyArray<{ id: string }>,
  anchor: Anchor,
  hintIndex = 0,
): AnchorResolution {
  if (anchor.id !== null) {
    const index = items.findIndex((item) => item.id === anchor.id);
    if (index !== -1) return { index, offset: anchor.offset, found: true };
  }
  const capped = Math.max(0, Math.min(hintIndex, Math.max(0, items.length - 1)));
  return { index: capped, offset: anchor.offset, found: false };
}

$ node --test test/feed/refresh-policy.test.ts
✔ 下拉：从未刷新立即开始，冷却期内连点被跳过 (0.505917ms)
✔ 自动轮询未到间隔时跳过 (0.067583ms)
✔ 用户已读进一屏时轮询改为排队 (0.540958ms)
✔ 回到前台时有未读内容就立即刷新 (0.120917ms)
✔ 回到前台且无未读时按过期阈值判断 (0.083666ms)
✔ 刷新期间的多次触发合并成一次后续刷新 (0.144417ms)
✔ 排队中的刷新在阅读停止后启动 (0.079292ms)
✔ 锚点按 id 恢复位置，锚点消失时回退到提示下标 (0.559042ms)
ℹ tests 8
ℹ suites 0
ℹ pass 8
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 139.396417