《移动游戏产品的架构·网络、资源与热更新》6.1 战报结构：可复盘的最小数据集

// file: src/net/battle-report.ts
// tier: L1
// verify: node --test test/net/battle-report.test.ts
/**
 * 战报最小数据集模型（mga-net-lab）。
 * 事件配额、分桶窗口与体积估算均为实验设定，不是案例事实。
 */

export type EventKind =
  | "kill"
  | "death"
  | "skill"
  | "objective"
  | "disconnect"
  | "resync";

export type BattleResult = "win" | "lose" | "draw";

export interface BattleMeta {
  readonly battleId: string;
  readonly seasonId: string;
  readonly mode: string;
  readonly startedAt: number;
  readonly durationMs: number;
  readonly result: BattleResult;
  readonly snapshotSeq: number;
}

export interface BattleEvent {
  readonly seq: number;
  readonly atMs: number;
  readonly kind: EventKind;
  readonly actor: string;
  readonly target?: string;
  readonly detail?: string;
}

export interface ReportLimits {
  readonly maxEvents: number;
  readonly maxPerKind: number;
  readonly bucketMs: number;
}

export interface ReportBucket {
  readonly startMs: number;
  readonly endMs: number;
  readonly events: number;
  readonly kills: number;
  readonly objectives: number;
}

export interface BattleReport {
  readonly meta: BattleMeta;
  readonly events: readonly BattleEvent[];
  readonly dropped: number;
  readonly digest: string;
  readonly buckets: readonly ReportBucket[];
}

export const DEFAULT_LIMITS: ReportLimits = {
  maxEvents: 64,
  maxPerKind: 12,
  bucketMs: 30_000,
};

const BASE_BYTES = 180;
const EVENT_BYTES = 42;
const BUCKET_BYTES = 18;

const KIND_ORDER: readonly EventKind[] = [
  "objective",
  "death",
  "disconnect",
  "resync",
  "kill",
  "skill",
];

function assertInteger(value: number, label: string, min: number): void {
  if (!Number.isInteger(value) || value < min) {
    throw new RangeError(`${label} 必须是不小于 ${min} 的整数，收到 ${value}`);
  }
}

function assertLimits(limits: ReportLimits): void {
  assertInteger(limits.maxEvents, "maxEvents", 1);
  assertInteger(limits.maxPerKind, "maxPerKind", 1);
  assertInteger(limits.bucketMs, "bucketMs", 1);
}

function validateMeta(meta: BattleMeta): void {
  if (meta.battleId.trim() === "") {
    throw new Error("battleId 不能为空");
  }
  assertInteger(meta.startedAt, "startedAt", 0);
  assertInteger(meta.durationMs, "durationMs", 1);
  assertInteger(meta.snapshotSeq, "snapshotSeq", 0);
}

function validateEvents(meta: BattleMeta, events: readonly BattleEvent[]): void {
  let previousSeq = -1;
  let previousAt = -1;
  for (const event of events) {
    assertInteger(event.seq, "event.seq", 0);
    assertInteger(event.atMs, "event.atMs", 0);
    if (event.seq <= previousSeq) {
      throw new Error(`事件 seq 必须严格递增：${previousSeq} → ${event.seq}`);
    }
    if (event.atMs < previousAt) {
      throw new Error(`事件时间不能倒退：${previousAt}ms → ${event.atMs}ms`);
    }
    if (event.atMs > meta.durationMs) {
      throw new Error(
        `事件时间 ${event.atMs}ms 超出战斗时长 ${meta.durationMs}ms`,
      );
    }
    if (event.actor.trim() === "") {
      throw new Error(`事件 ${event.seq} 缺少 actor`);
    }
    previousSeq = event.seq;
    previousAt = event.atMs;
  }
}

function fnv1a(input: string): string {
  let hash = 0x811c9dc5;
  for (let index = 0; index < input.length; index += 1) {
    hash ^= input.charCodeAt(index);
    hash = Math.imul(hash, 0x01000193) >>> 0;
  }
  return hash.toString(16).padStart(8, "0");
}

export function digestEvents(events: readonly BattleEvent[]): string {
  const canonical = events
    .map((event) =>
      [
        event.seq,
        event.atMs,
        event.kind,
        event.actor,
        event.target ?? "",
        event.detail ?? "",
      ].join("\u0001"),
    )
    .join("\u0000");
  return fnv1a(canonical);
}

function pickEvenly<T>(items: readonly T[], limit: number): T[] {
  if (limit <= 0 || items.length === 0) {
    return [];
  }
  if (items.length <= limit) {
    return [...items];
  }
  if (limit === 1) {
    return [items[0]];
  }
  const picked: T[] = [];
  for (let index = 0; index < limit; index += 1) {
    const position = Math.round((index * (items.length - 1)) / (limit - 1));
    const item = items[position];
    if (!picked.includes(item)) {
      picked.push(item);
    }
  }
  return picked;
}

export function selectEvents(
  events: readonly BattleEvent[],
  limits: ReportLimits = DEFAULT_LIMITS,
): readonly BattleEvent[] {
  assertLimits(limits);
  const selected = new Set<BattleEvent>();
  if (events.length > 0) {
    selected.add(events[0]);
    selected.add(events[events.length - 1]);
  }
  for (const kind of KIND_ORDER) {
    if (selected.size >= limits.maxEvents) {
      break;
    }
    const pool = events.filter((event) => event.kind === kind);
    for (const event of pickEvenly(pool, limits.maxPerKind)) {
      if (selected.size >= limits.maxEvents) {
        break;
      }
      selected.add(event);
    }
  }
  return [...selected].sort((left, right) => left.seq - right.seq);
}

function buildBuckets(
  meta: BattleMeta,
  events: readonly BattleEvent[],
  bucketMs: number,
): readonly ReportBucket[] {
  const count = Math.ceil(meta.durationMs / bucketMs);
  const totals = new Array<number>(count).fill(0);
  const kills = new Array<number>(count).fill(0);
  const objectives = new Array<number>(count).fill(0);
  for (const event of events) {
    const index = Math.min(count - 1, Math.floor(event.atMs / bucketMs));
    totals[index] += 1;
    if (event.kind === "kill") {
      kills[index] += 1;
    }
    if (event.kind === "objective") {
      objectives[index] += 1;
    }
  }
  return totals.map((total, index) => ({
    startMs: index * bucketMs,
    endMs: Math.min((index + 1) * bucketMs, meta.durationMs),
    events: total,
    kills: kills[index],
    objectives: objectives[index],
  }));
}

export function buildBattleReport(
  meta: BattleMeta,
  events: readonly BattleEvent[],
  limits: ReportLimits = DEFAULT_LIMITS,
): BattleReport {
  validateMeta(meta);
  validateEvents(meta, events);
  assertLimits(limits);
  const kept = selectEvents(events, limits);
  return {
    meta,
    events: kept,
    dropped: events.length - kept.length,
    digest: digestEvents(events),
    buckets: buildBuckets(meta, events, limits.bucketMs),
  };
}

export function estimateReportBytes(report: BattleReport): number {
  let detailBytes = 0;
  for (const event of report.events) {
    detailBytes += (event.target?.length ?? 0) + (event.detail?.length ?? 0);
  }
  return (
    BASE_BYTES +
    report.events.length * EVENT_BYTES +
    report.buckets.length * BUCKET_BYTES +
    detailBytes
  );
}

export function describeReport(report: BattleReport): string {
  const total = report.events.length + report.dropped;
  return `战报 ${report.meta.battleId}：${report.meta.result}，时长 ${report.meta.durationMs}ms，事件 ${report.events.length}/${total}，桶 ${report.buckets.length}，摘要 ${report.digest}，估算 ${estimateReportBytes(report)} 字节`;
}