《移动游戏产品的架构·客户端与移动运行时》11.2 时区、服务器时间与本地时间

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

export interface TimeSource {
  wallMs(): number;
  monotonicMs(): number;
}

export class SystemTimeSource implements TimeSource {
  wallMs(): number { return Date.now(); }
  monotonicMs(): number { return globalThis.performance.now(); }
}

export interface Handshake {
  readonly serverEpochMs: number; readonly clientWallMs: number;
  readonly clientMonoMs: number; readonly rttMs: number;
}

export type ClockState = "ok" | "device-clock-jump" | "wide-uncertainty";

export interface ClockStats {
  readonly state: ClockState; readonly serverNowMs: number; readonly deviceWallMs: number;
  readonly deviceJumpMs: number; readonly uncertaintyMs: number; readonly resyncCount: number;
}

export interface ClockOptions { readonly jumpThresholdMs?: number; readonly maxUncertaintyMs?: number }

export class ServerClock {
  readonly #source: TimeSource;
  readonly #jumpThresholdMs: number;
  readonly #maxUncertaintyMs: number;
  #offsetMs = 0;
  #uncertaintyMs = 0;
  #monoAtAnchorMs = 0;
  #wallAtAnchorMs = 0;
  #resyncCount = 0;
  #synced = false;

  constructor(source: TimeSource, options: ClockOptions = {}) {
    this.#source = source;
    this.#jumpThresholdMs = options.jumpThresholdMs ?? 2_000;
    this.#maxUncertaintyMs = options.maxUncertaintyMs ?? 5_000;
  }

  resync(handshake: Handshake): void {
    if (!Number.isFinite(handshake.serverEpochMs) || !Number.isFinite(handshake.rttMs) || handshake.rttMs < 0) {
      throw new RangeError(`invalid handshake: ${JSON.stringify(handshake)}`);
    }
    this.#offsetMs = handshake.serverEpochMs + handshake.rttMs / 2 - handshake.clientMonoMs;
    this.#uncertaintyMs = handshake.rttMs / 2;
    this.#monoAtAnchorMs = handshake.clientMonoMs;
    this.#wallAtAnchorMs = handshake.clientWallMs;
    this.#resyncCount += 1;
    this.#synced = true;
  }

  nowMs(): number {
    if (!this.#synced) throw new Error("server clock is not synchronized");
    return this.#source.monotonicMs() + this.#offsetMs;
  }

  deviceJumpMs(): number {
    if (!this.#synced) return 0;
    const elapsed = this.#source.monotonicMs() - this.#monoAtAnchorMs;
    return this.#source.wallMs() - (this.#wallAtAnchorMs + elapsed);
  }

  stats(): ClockStats {
    const deviceJumpMs = this.deviceJumpMs();
    const state: ClockState = Math.abs(deviceJumpMs) > this.#jumpThresholdMs
      ? "device-clock-jump"
      : this.#uncertaintyMs > this.#maxUncertaintyMs ? "wide-uncertainty" : "ok";
    return {
      state, serverNowMs: this.#synced ? this.nowMs() : this.#source.wallMs(),
      deviceWallMs: this.#source.wallMs(), deviceJumpMs,
      uncertaintyMs: this.#uncertaintyMs, resyncCount: this.#resyncCount,
    };
  }
}

export interface ZonedParts {
  readonly year: number; readonly month: number; readonly day: number;
  readonly hour: number; readonly minute: number; readonly second: number;
}

const FORMATTERS = new Map<string, Intl.DateTimeFormat>();

function formatterFor(timeZone: string): Intl.DateTimeFormat {
  let formatter = FORMATTERS.get(timeZone);
  if (formatter === undefined) {
    formatter = new Intl.DateTimeFormat("en-US", {
      timeZone, year: "numeric", month: "2-digit", day: "2-digit",
      hour: "2-digit", minute: "2-digit", second: "2-digit", hourCycle: "h23",
    });
    FORMATTERS.set(timeZone, formatter);
  }
  return formatter;
}

export function zonedParts(epochMs: number, timeZone: string): ZonedParts {
  if (!Number.isFinite(epochMs)) throw new RangeError(`invalid epoch: ${epochMs}`);
  const fields: Record<string, number> = {};
  for (const part of formatterFor(timeZone).formatToParts(new Date(epochMs))) {
    if (part.type !== "literal") fields[part.type] = Number(part.value);
  }
  return {
    year: fields.year, month: fields.month, day: fields.day,
    hour: fields.hour, minute: fields.minute, second: fields.second,
  };
}

export function zoneOffsetMinutes(epochMs: number, timeZone: string): number {
  const parts = zonedParts(epochMs, timeZone);
  const asUtc = Date.UTC(parts.year, parts.month - 1, parts.day, parts.hour, parts.minute, parts.second);
  return Math.round((asUtc - Math.floor(epochMs / 1_000) * 1_000) / 60_000);
}

function pad(value: number): string { return String(value).padStart(2, "0"); }

export function dayKey(epochMs: number, timeZone: string): string {
  const parts = zonedParts(epochMs, timeZone);
  return `${parts.year}-${pad(parts.month)}-${pad(parts.day)}`;
}

export function businessDayKey(epochMs: number, timeZone: string, resetHour = 0): string {
  if (!Number.isInteger(resetHour) || resetHour < 0 || resetHour > 23) {
    throw new RangeError(`resetHour must be an integer within [0, 23]: ${resetHour}`);
  }
  const parts = zonedParts(epochMs, timeZone);
  let civilMs = Date.UTC(parts.year, parts.month - 1, parts.day);
  if (parts.hour < resetHour) civilMs -= 86_400_000;
  const civil = new Date(civilMs);
  return `${civil.getUTCFullYear()}-${pad(civil.getUTCMonth() + 1)}-${pad(civil.getUTCDate())}`;
}

export function civilDayStartEpoch(epochMs: number, timeZone: string): number {
  const parts = zonedParts(epochMs, timeZone);
  const guess = Date.UTC(parts.year, parts.month - 1, parts.day, 0, 0, 0);
  let candidate = guess - zoneOffsetMinutes(guess, timeZone) * 60_000;
  candidate = guess - zoneOffsetMinutes(candidate, timeZone) * 60_000;
  return candidate;
}

export interface OffsetChange {
  readonly atMs: number; readonly localHour: number;
  readonly fromOffsetMinutes: number; readonly toOffsetMinutes: number;
}

export function transitionsOnDay(epochMs: number, timeZone: string): readonly OffsetChange[] {
  const start = civilDayStartEpoch(epochMs, timeZone);
  const changes: OffsetChange[] = [];
  let previous = zoneOffsetMinutes(start, timeZone);
  for (let hour = 1; hour <= 24; hour += 1) {
    const atMs = start + hour * 3_600_000;
    const current = zoneOffsetMinutes(atMs, timeZone);
    if (current !== previous) {
      changes.push({ atMs, localHour: zonedParts(atMs, timeZone).hour, fromOffsetMinutes: previous, toOffsetMinutes: current });
      previous = current;
    }
  }
  return changes;
}

export type WindowStatus = "before" | "open" | "after";

export interface ActivityWindow {
  readonly id: string; readonly startMs: number; readonly endMs: number;
  readonly ruleTimeZone: string; readonly resetHour: number;
}

export interface WindowVerdict {
  readonly id: string; readonly status: WindowStatus; readonly serverNowMs: number;
  readonly remainingMs: number; readonly progress: number; readonly ruleDayKey: string;
  readonly displayStart: string; readonly displayEnd: string;
}

const DISPLAY_FORMATTERS = new Map<string, Intl.DateTimeFormat>();

export function formatInZone(epochMs: number, timeZone: string, locale = "en-US"): string {
  const key = `${locale}|${timeZone}`;
  let formatter = DISPLAY_FORMATTERS.get(key);
  if (formatter === undefined) {
    formatter = new Intl.DateTimeFormat(locale, { timeZone, dateStyle: "medium", timeStyle: "short" });
    DISPLAY_FORMATTERS.set(key, formatter);
  }
  return formatter.format(new Date(epochMs));
}

export function evaluateWindow(
  window: ActivityWindow, serverNowMs: number, playerTimeZone: string, locale = "en-US",
): WindowVerdict {
  if (window.endMs <= window.startMs) throw new RangeError(`window ${window.id} has a non-positive duration`);
  const status: WindowStatus = serverNowMs < window.startMs ? "before" : serverNowMs >= window.endMs ? "after" : "open";
  const remainingMs = status === "before" ? window.startMs - serverNowMs : status === "open" ? window.endMs - serverNowMs : 0;
  return {
    id: window.id, status, serverNowMs, remainingMs,
    progress: Math.min(1, Math.max(0, (serverNowMs - window.startMs) / (window.endMs - window.startMs))),
    ruleDayKey: businessDayKey(serverNowMs, window.ruleTimeZone, window.resetHour),
    displayStart: formatInZone(window.startMs, playerTimeZone, locale),
    displayEnd: formatInZone(window.endMs, playerTimeZone, locale),
  };
}