《移动游戏产品的架构·网络、资源与热更新》4.1 离线可做与不可做：队列边界

// file: src/net/offline-policy.ts
// tier: L1
// verify: node --test test/net/offline-policy.test.ts

export type OfflineVerdict = "queue" | "queue-refresh" | "online";

export interface OperationKindSpec {
  readonly verdict: OfflineVerdict;
  readonly maxAgeMs: number;
  readonly reason: string;
}

const HOUR = 3_600_000;

export const OPERATION_KINDS: Readonly<Record<string, OperationKindSpec>> = {
  "level-start": { verdict: "queue", maxAgeMs: 12 * HOUR, reason: "本地开局，服务端只记进度" },
  "level-complete": { verdict: "queue-refresh", maxAgeMs: 24 * HOUR, reason: "进度可合并，排行榜需要重拉" },
  "star-collect": { verdict: "queue", maxAgeMs: 24 * HOUR, reason: "收集结果幂等，可合并" },
  "friend-help": { verdict: "queue-refresh", maxAgeMs: 6 * HOUR, reason: "助力次数有限，提交后需刷新余额" },
  "shop-purchase": { verdict: "online", maxAgeMs: 0, reason: "支付与发货必须在线" },
  "gacha-pull": { verdict: "online", maxAgeMs: 0, reason: "概率与库存由服务端裁决" },
  "rank-claim": { verdict: "online", maxAgeMs: 0, reason: "排行榜奖励按服务端结算" },
};

export interface QueueRequest {
  readonly opId: string;
  readonly kind: string;
  readonly createdAt: number;
  readonly expiresAt?: number;
  readonly payloadBytes: number;
}

export interface QueuePolicy {
  readonly maxOps: number;
  readonly maxAgeMs: number;
  readonly maxPayloadBytes: number;
  readonly totalBytes: number;
}

export const DEFAULT_QUEUE_POLICY: QueuePolicy = {
  maxOps: 32,
  maxAgeMs: 24 * HOUR,
  maxPayloadBytes: 4 * 1024,
  totalBytes: 64 * 1024,
};

export type RejectCode =
  | "unknown-kind"
  | "online-only"
  | "expired"
  | "stale"
  | "payload-too-large"
  | "budget-exceeded"
  | "queue-full";

export interface AcceptedRequest extends QueueRequest {
  readonly verdict: OfflineVerdict;
}

export interface RejectedRequest {
  readonly opId: string;
  readonly code: RejectCode;
  readonly detail: string;
}

export interface QueuePlan {
  readonly accepted: readonly AcceptedRequest[];
  readonly rejected: readonly RejectedRequest[];
  readonly queuedBytes: number;
  readonly oldestAgeMs: number;
}

export function classifyOperation(kind: string): OperationKindSpec | null {
  return Object.hasOwn(OPERATION_KINDS, kind) ? OPERATION_KINDS[kind] : null;
}

export function planOfflineQueue(
  requests: readonly QueueRequest[],
  now: number,
  policy: QueuePolicy = DEFAULT_QUEUE_POLICY,
): QueuePlan {
  const accepted: AcceptedRequest[] = [];
  const rejected: RejectedRequest[] = [];
  let queuedBytes = 0;
  let oldestAgeMs = 0;

  for (const request of requests) {
    const spec = classifyOperation(request.kind);
    if (spec === null) {
      rejected.push({ opId: request.opId, code: "unknown-kind", detail: `未登记的离线操作类型：${request.kind}` });
      continue;
    }
    if (spec.verdict === "online") {
      rejected.push({ opId: request.opId, code: "online-only", detail: spec.reason });
      continue;
    }
    if (request.expiresAt !== undefined && request.expiresAt <= now) {
      rejected.push({ opId: request.opId, code: "expired", detail: `过期时间 ${request.expiresAt} 已到` });
      continue;
    }
    const age = Math.max(0, now - request.createdAt);
    const maxAge = Math.min(policy.maxAgeMs, spec.maxAgeMs);
    if (age > maxAge) {
      rejected.push({ opId: request.opId, code: "stale", detail: `已等待 ${age}ms，超过上限 ${maxAge}ms` });
      continue;
    }
    if (!Number.isInteger(request.payloadBytes) || request.payloadBytes <= 0 || request.payloadBytes > policy.maxPayloadBytes) {
      rejected.push({ opId: request.opId, code: "payload-too-large", detail: `负载 ${request.payloadBytes}B 不在 1..${policy.maxPayloadBytes}B` });
      continue;
    }
    if (accepted.length >= policy.maxOps) {
      rejected.push({ opId: request.opId, code: "queue-full", detail: `队列已有 ${accepted.length} 条` });
      continue;
    }
    if (queuedBytes + request.payloadBytes > policy.totalBytes) {
      rejected.push({ opId: request.opId, code: "budget-exceeded", detail: `再写入将超过 ${policy.totalBytes}B` });
      continue;
    }
    accepted.push({ ...request, verdict: spec.verdict });
    queuedBytes += request.payloadBytes;
    oldestAgeMs = Math.max(oldestAgeMs, age);
  }

  return { accepted, rejected, queuedBytes, oldestAgeMs };
}

export function describeQueuePlan(plan: QueuePlan): string {
  const refresh = plan.accepted.filter((item) => item.verdict === "queue-refresh").length;
  const tags = new Map<RejectCode, number>();
  for (const item of plan.rejected) {
    tags.set(item.code, (tags.get(item.code) ?? 0) + 1);
  }
  const reasons = [...tags.entries()]
    .sort(([a], [b]) => a.localeCompare(b))
    .map(([code, count]) => `${code}×${count}`)
    .join("、");
  const ageMinutes = Math.round(plan.oldestAgeMs / 60_000);
  const rejectPart = plan.rejected.length === 0 ? "无拒绝" : `拒绝 ${plan.rejected.length} 条（${reasons}）`;
  return `采纳 ${plan.accepted.length} 条（需刷新 ${refresh} 条），${rejectPart}；占用 ${plan.queuedBytes}B，最老 ${ageMinutes} 分钟`;
}