《互联网产品的客户端架构·内容、社交与实时互动》8.1 presence 的近似语义：没有真正的「在线」

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

export type PresenceState = "online" | "away" | "offline" | "unknown";

export type PresenceSource = "signal" | "heartbeat" | "snapshot" | "none";

export interface PresenceSample {
  userId: string;
  lastActiveAt: number | null;
  source: PresenceSource;
}

export interface PresencePolicy {
  onlineWindowMs: number;
  awayWindowMs: number;
  retentionMs: number;
  maxFutureSkewMs: number;
}

export const DEFAULT_PRESENCE_POLICY: PresencePolicy = {
  onlineWindowMs: 60_000,
  awayWindowMs: 5 * 60_000,
  retentionMs: 60 * 60_000,
  maxFutureSkewMs: 30_000,
};

export type PresenceReason = "fresh" | "decayed" | "expired" | "missing" | "clock-skew";

export interface PresenceView {
  userId: string;
  state: PresenceState;
  reason: PresenceReason;
  label: string;
  lastActiveAt: number | null;
  ageMs: number | null;
  stale: boolean;
}

const LABELS: Record<PresenceState, string> = {
  online: "在线",
  away: "离开",
  offline: "离线",
  unknown: "状态未知",
};

export function classifyPresence(
  sample: PresenceSample,
  now: number,
  policy: PresencePolicy = DEFAULT_PRESENCE_POLICY,
): PresenceView {
  assertPolicy(policy);
  if (!Number.isFinite(now)) throw new Error("now 必须是有限数字");
  const make = (state: PresenceState, reason: PresenceReason, ageMs: number | null): PresenceView => ({
    userId: sample.userId,
    state,
    reason,
    label: LABELS[state],
    lastActiveAt: sample.lastActiveAt,
    ageMs,
    // 快照来自本地缓存，没有实时订阅兜底，必须让 UI 知道它可能已经过期。
    stale: state === "unknown" || sample.source === "snapshot",
  });

  if (sample.source === "none" || sample.lastActiveAt === null) {
    return make("unknown", "missing", null);
  }
  if (!Number.isFinite(sample.lastActiveAt)) {
    return make("unknown", "missing", null);
  }

  const rawAge = now - sample.lastActiveAt;
  if (rawAge < -policy.maxFutureSkewMs) {
    // 未来时间超过容忍范围时不可信；不能把负年龄当成「刚刚活跃」。
    return make("unknown", "clock-skew", null);
  }
  const ageMs = Math.max(0, rawAge);

  if (ageMs < policy.onlineWindowMs) return make("online", "fresh", ageMs);
  if (ageMs < policy.awayWindowMs) return make("away", "decayed", ageMs);
  if (ageMs < policy.retentionMs) return make("offline", "decayed", ageMs);
  return make("unknown", "expired", ageMs);
}

// 返回当前状态失效、需要重新判定的第一个毫秒；unknown 不再安排定时器。
export function nextTransitionAt(
  view: PresenceView,
  policy: PresencePolicy = DEFAULT_PRESENCE_POLICY,
): number | null {
  assertPolicy(policy);
  if (view.lastActiveAt === null || view.state === "unknown") return null;
  const at = view.lastActiveAt;
  if (view.state === "online") return at + policy.onlineWindowMs;
  if (view.state === "away") return at + policy.awayWindowMs;
  return at + policy.retentionMs;
}

export function formatLastSeen(view: PresenceView): string | null {
  if (view.lastActiveAt === null || view.state === "unknown" || view.state === "online") {
    return null;
  }
  const ageMs = view.ageMs ?? 0;
  if (ageMs < 60_000) return "1 分钟内活跃";
  const minutes = Math.floor(ageMs / 60_000);
  if (minutes < 60) return `${minutes} 分钟前活跃`;
  const hours = Math.floor(minutes / 60);
  return `${hours} 小时前活跃`;
}

function assertPolicy(policy: PresencePolicy): void {
  const values = [policy.onlineWindowMs, policy.awayWindowMs, policy.retentionMs, policy.maxFutureSkewMs];
  if (values.some((value) => !Number.isFinite(value) || value < 0)) {
    throw new Error("presence 窗口必须是非负有限数字");
  }
  if (!(policy.onlineWindowMs < policy.awayWindowMs && policy.awayWindowMs <= policy.retentionMs)) {
    throw new Error("presence 窗口必须满足 online < away <= retention");
  }
}

$ node --test test/presence/presence.test.ts
✔ 窗口内的最近活跃判为在线 (0.595041ms)
✔ 超过在线窗口按半开区间进入离开，边界值不再算在线 (0.086459ms)
✔ 超过离开窗口判为离线，并保留最后活跃时间 (0.070834ms)
✔ 超过保留期后不再声称离线，而是回到状态未知 (0.079375ms)
✔ 没有观测样本时直接判为未知，不猜测离线 (0.065916ms)
✔ 未来时间超过容忍范围时判为时钟异常，不产生负年龄 (0.114292ms)
✔ 缓存快照始终标记 stale，但状态仍按时间衰减 (0.080208ms)
✔ 下一次状态转换指向各窗口边界，非法窗口被拒绝 (0.285ms)
ℹ tests 8
ℹ suites 0
ℹ pass 8
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 107.552458