《移动游戏产品的架构·网络、资源与热更新》4.3 冲突解决与可见性延迟

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

export type FieldPolicy = "max" | "server-authoritative" | "client-authoritative" | "lww";

export interface FieldRule {
  readonly policy: FieldPolicy;
  readonly min?: number;
  readonly max?: number;
}

export const PROFILE_RULES: Readonly<Record<string, FieldRule>> = {
  level: { policy: "max", min: 1, max: 999 },
  bestScore: { policy: "max", min: 0 },
  stars: { policy: "max", min: 0 },
  tutorialStep: { policy: "max", min: 0 },
  coins: { policy: "server-authoritative", min: 0 },
  nickname: { policy: "lww" },
  language: { policy: "client-authoritative" },
};

export interface ServerProfile {
  readonly fields: Readonly<Record<string, unknown>>;
  readonly updatedAt: Readonly<Record<string, number>>;
}

export interface OfflineChange {
  readonly field: string;
  readonly value: unknown;
  readonly at: number;
}

export type Decision = "kept-server" | "took-client" | "merged-max" | "rejected";

export interface FieldResolution {
  readonly field: string;
  readonly decision: Decision;
  readonly serverValue: unknown;
  readonly clientValue: unknown;
  readonly mergedValue: unknown;
  readonly reason: string;
}

export interface Resolution {
  readonly fields: readonly FieldResolution[];
  readonly conflicts: number;
  readonly applied: number;
  readonly rejected: number;
}

function inRange(value: number, rule: FieldRule): boolean {
  if (rule.min !== undefined && value < rule.min) return false;
  if (rule.max !== undefined && value > rule.max) return false;
  return true;
}

export function resolveOfflineChanges(
  server: ServerProfile,
  changes: readonly OfflineChange[],
): Resolution {
  const working = new Map<string, unknown>(Object.entries(server.fields));
  const updatedAt = new Map<string, number>(Object.entries(server.updatedAt));
  const byField = new Map<string, FieldResolution>();
  let conflicts = 0;
  let applied = 0;
  let rejected = 0;

  const ordered = [...changes].sort((a, b) => a.at - b.at);

  for (const change of ordered) {
    const rule = PROFILE_RULES[change.field];
    const serverValue = working.get(change.field);

    if (rule === undefined) {
      rejected += 1;
      byField.set(change.field, {
        field: change.field,
        decision: "rejected",
        serverValue,
        clientValue: change.value,
        mergedValue: serverValue,
        reason: "未登记的字段，按未知字段拒绝",
      });
      continue;
    }

    if (rule.policy === "server-authoritative") {
      const same = Object.is(serverValue, change.value);
      if (!same) conflicts += 1;
      byField.set(change.field, {
        field: change.field,
        decision: "kept-server",
        serverValue,
        clientValue: change.value,
        mergedValue: serverValue,
        reason: "服务端账本裁决，离线值只用于本地展示",
      });
      continue;
    }

    if (rule.policy === "client-authoritative") {
      working.set(change.field, change.value);
      updatedAt.set(change.field, change.at);
      applied += 1;
      byField.set(change.field, {
        field: change.field,
        decision: "took-client",
        serverValue,
        clientValue: change.value,
        mergedValue: change.value,
        reason: "客户端偏好字段，服务端接受覆盖",
      });
      continue;
    }

    if (rule.policy === "lww") {
      const serverAt = updatedAt.get(change.field) ?? Number.NEGATIVE_INFINITY;
      if (change.at > serverAt) {
        working.set(change.field, change.value);
        updatedAt.set(change.field, change.at);
        applied += 1;
        byField.set(change.field, {
          field: change.field,
          decision: "took-client",
          serverValue,
          clientValue: change.value,
          mergedValue: change.value,
          reason: `客户端时间 ${change.at} 晚于服务端 ${serverAt}`,
        });
      } else {
        if (!Object.is(serverValue, change.value)) conflicts += 1;
        byField.set(change.field, {
          field: change.field,
          decision: "kept-server",
          serverValue,
          clientValue: change.value,
          mergedValue: serverValue,
          reason: `客户端时间 ${change.at} 不晚于服务端 ${serverAt}，保留服务端`,
        });
      }
      continue;
    }

    if (typeof change.value !== "number" || !Number.isFinite(change.value)) {
      rejected += 1;
      byField.set(change.field, {
        field: change.field,
        decision: "rejected",
        serverValue,
        clientValue: change.value,
        mergedValue: serverValue,
        reason: "max 字段只接受有限数值",
      });
      continue;
    }
    if (!inRange(change.value, rule)) {
      rejected += 1;
      byField.set(change.field, {
        field: change.field,
        decision: "rejected",
        serverValue,
        clientValue: change.value,
        mergedValue: serverValue,
        reason: `数值 ${change.value} 超出允许区间`,
      });
      continue;
    }

    const base = typeof serverValue === "number" && Number.isFinite(serverValue) ? serverValue : rule.min ?? 0;
    if (change.value > base) {
      working.set(change.field, change.value);
      applied += 1;
      byField.set(change.field, {
        field: change.field,
        decision: "merged-max",
        serverValue,
        clientValue: change.value,
        mergedValue: change.value,
        reason: `取较大值 ${change.value} 覆盖 ${base}`,
      });
    } else {
      if (!Object.is(serverValue, change.value)) conflicts += 1;
      byField.set(change.field, {
        field: change.field,
        decision: "kept-server",
        serverValue,
        clientValue: change.value,
        mergedValue: serverValue,
        reason: `服务端值 ${base} 不小于客户端 ${change.value}`,
      });
    }
  }

  return { fields: [...byField.values()], conflicts, applied, rejected };
}

export interface VisibleProjection {
  readonly fields: Readonly<Record<string, unknown>>;
  readonly pendingFields: readonly string[];
  readonly heldFields: readonly string[];
}

export function projectVisible(
  server: ServerProfile,
  pending: readonly OfflineChange[],
): VisibleProjection {
  const fields: Record<string, unknown> = { ...server.fields };
  const pendingFields: string[] = [];
  const heldFields: string[] = [];
  const seen = new Set<string>();

  for (const change of pending) {
    const rule = PROFILE_RULES[change.field];
    if (rule === undefined) continue;
    if (!seen.has(change.field)) {
      seen.add(change.field);
      pendingFields.push(change.field);
    }
    if (rule.policy === "server-authoritative") {
      heldFields.push(change.field);
      continue;
    }
    fields[change.field] = change.value;
  }

  return { fields, pendingFields, heldFields };
}

export interface VisibilityConfig {
  readonly rttP95Ms: number;
  readonly batchWindowMs: number;
  readonly batchSize: number;
}

export function estimateVisibilityDelayMs(
  pendingCount: number,
  config: VisibilityConfig,
): number {
  if (!Number.isInteger(pendingCount) || pendingCount < 0) {
    throw new RangeError(`pendingCount must be a non-negative integer: ${pendingCount}`);
  }
  if (pendingCount === 0) return 0;
  const batchSize = Math.max(1, config.batchSize);
  const batches = Math.ceil(pendingCount / batchSize);
  return config.rttP95Ms * (batches + 1) + config.batchWindowMs * batches;
}

export function describeResolution(resolution: Resolution): string {
  const kept = resolution.fields.filter((field) => field.decision === "kept-server").length;
  const merged = resolution.fields.filter((field) => field.decision === "merged-max").length;
  const took = resolution.fields.filter((field) => field.decision === "took-client").length;
  return `应用 ${resolution.applied} 项（取大 ${merged}、客户端覆盖 ${took}），保留服务端 ${kept} 项，拒绝 ${resolution.rejected} 项，冲突 ${resolution.conflicts} 项`;
}