《移动游戏产品的架构·客户端与移动运行时》12.1 崩溃、ANR 与卡顿的采集边界

// file: src/obs/crash-model.ts
// tier: L1
// verify: node --test test/obs/crash-model.test.ts

export type CrashClass =
  | "managed-exception"
  | "native-signal"
  | "script-error"
  | "anr"
  | "oom-kill"
  | "background-kill";

export type CollectWindow = "at-crash" | "next-launch" | "sampled" | "never";
export type Severity = "fatal" | "degraded" | "informational";

export interface CollectionRule {
  readonly crashClass: CrashClass;
  readonly window: CollectWindow;
  readonly severity: Severity;
  readonly countsInCrashRate: boolean;
  readonly note: string;
}

export const COLLECTION_RULES: readonly CollectionRule[] = [
  { crashClass: "managed-exception", window: "at-crash", severity: "fatal", countsInCrashRate: true, note: "进程内处理器捕获，先落盘，下次启动上传" },
  { crashClass: "native-signal", window: "at-crash", severity: "fatal", countsInCrashRate: true, note: "信号处理器只写最小转储，不能分配内存或调用业务代码" },
  { crashClass: "script-error", window: "sampled", severity: "degraded", countsInCrashRate: false, note: "脚本未捕获异常按会话采样，避免同一错误刷满配额" },
  { crashClass: "anr", window: "next-launch", severity: "fatal", countsInCrashRate: false, note: "主线程无响应时应用无法执行上传，只能下次启动补报" },
  { crashClass: "oom-kill", window: "next-launch", severity: "informational", countsInCrashRate: false, note: "系统杀进程没有回调，只能靠退出标记推断，不能算崩溃" },
  { crashClass: "background-kill", window: "next-launch", severity: "informational", countsInCrashRate: false, note: "用户或系统清理后台，不属于质量事故" },
];

export function collectionRuleFor(crashClass: CrashClass): CollectionRule {
  const rule = COLLECTION_RULES.find((item) => item.crashClass === crashClass);
  if (!rule) {
    throw new Error(`unknown crash class: ${crashClass}`);
  }
  return rule;
}

export type InitPhase = "process-start" | "after-consent" | "after-first-frame";
export type FieldClass = "operational" | "quasi-identifier" | "personal" | "secret";
export type FieldMode = "keep" | "hash" | "drop";

export interface FieldRule {
  readonly field: string;
  readonly fieldClass: FieldClass;
  readonly beforeConsent: FieldMode;
  readonly afterConsent: FieldMode;
}

export const FIELD_RULES: readonly FieldRule[] = [
  { field: "crashClass", fieldClass: "operational", beforeConsent: "keep", afterConsent: "keep" },
  { field: "appVersion", fieldClass: "operational", beforeConsent: "keep", afterConsent: "keep" },
  { field: "osVersion", fieldClass: "operational", beforeConsent: "keep", afterConsent: "keep" },
  { field: "stack", fieldClass: "operational", beforeConsent: "keep", afterConsent: "keep" },
  { field: "deviceModel", fieldClass: "quasi-identifier", beforeConsent: "keep", afterConsent: "keep" },
  { field: "sessionId", fieldClass: "quasi-identifier", beforeConsent: "hash", afterConsent: "hash" },
  { field: "userId", fieldClass: "personal", beforeConsent: "drop", afterConsent: "hash" },
  { field: "deviceId", fieldClass: "personal", beforeConsent: "drop", afterConsent: "hash" },
  { field: "ip", fieldClass: "personal", beforeConsent: "drop", afterConsent: "hash" },
  { field: "advertisingId", fieldClass: "personal", beforeConsent: "drop", afterConsent: "drop" },
  { field: "freeText", fieldClass: "secret", beforeConsent: "drop", afterConsent: "drop" },
];

export interface InitPlan {
  readonly phase: InitPhase;
  readonly consent: boolean;
  readonly installHandler: boolean;
  readonly collectFatal: boolean;
  readonly collectNonFatal: boolean;
  readonly upload: boolean;
  readonly spoolToDisk: boolean;
  readonly personalData: boolean;
}

export function planInit(phase: InitPhase, consent: boolean): InitPlan {
  const consented = consent && phase !== "process-start";
  return {
    phase,
    consent,
    installHandler: true,
    collectFatal: true,
    collectNonFatal: consented,
    upload: consented,
    spoolToDisk: true,
    personalData: consented,
  };
}

export function fnv1a(text: string): number {
  let hash = 0x811c9dc5;
  for (let index = 0; index < text.length; index += 1) {
    hash ^= text.charCodeAt(index);
    hash = Math.imul(hash, 0x01000193) >>> 0;
  }
  return hash >>> 0;
}

export function pseudonym(value: string, salt: string): string {
  const left = fnv1a(`${salt}:${value}`).toString(16).padStart(8, "0");
  const right = fnv1a(`${value}:${salt}`).toString(16).padStart(8, "0");
  return `${left}${right}`;
}

export interface SanitizedDraft {
  readonly fields: Readonly<Record<string, string>>;
  readonly dropped: readonly string[];
}

export function sanitizeDraft(
  draft: Readonly<Record<string, unknown>>,
  phase: InitPhase,
  consent: boolean,
  salt = "mga",
): SanitizedDraft {
  const fields: Record<string, string> = {};
  const dropped: string[] = [];
  const consented = consent && phase !== "process-start";
  for (const [key, value] of Object.entries(draft)) {
    const rule = FIELD_RULES.find((item) => item.field === key);
    if (!rule) {
      dropped.push(key);
      continue;
    }
    const mode = consented ? rule.afterConsent : rule.beforeConsent;
    if (mode === "drop") {
      dropped.push(key);
      continue;
    }
    const text = String(value);
    fields[key] = mode === "hash" ? pseudonym(text, salt) : text;
  }
  return { fields, dropped };
}

export type SdkStatus = "ok" | "handler-missing" | "storage-full" | "network-blocked" | "disabled";
export type Fallback = "none" | "memory-only" | "disk-spool" | "noop";

export interface SdkHealth {
  readonly status: SdkStatus;
  readonly canRecord: boolean;
  readonly canUpload: boolean;
  readonly fallback: Fallback;
  readonly note: string;
}

export function healthOf(status: SdkStatus): SdkHealth {
  switch (status) {
    case "ok": return { status, canRecord: true, canUpload: true, fallback: "none", note: "采集与上传均可用" };
    case "handler-missing": return { status, canRecord: false, canUpload: false, fallback: "noop", note: "无法安装处理器，游戏必须继续运行" };
    case "storage-full": return { status, canRecord: true, canUpload: false, fallback: "memory-only", note: "只保留内存中的最近一条，重启即丢失" };
    case "network-blocked": return { status, canRecord: true, canUpload: false, fallback: "disk-spool", note: "落盘等待下一次可用网络" };
    case "disabled": return { status, canRecord: false, canUpload: false, fallback: "noop", note: "被策略关闭或隐私未同意" };
  }
}

export interface CrashHost {
  installHandler(crashClass: CrashClass): boolean;
  writeSpool(payload: string): boolean;
}

export interface HostReport {
  readonly status: SdkStatus;
  readonly installed: readonly CrashClass[];
}

export function installCrashHandlers(host: CrashHost): HostReport {
  const wanted: readonly CrashClass[] = ["managed-exception", "native-signal"];
  const installed = wanted.filter((crashClass) => host.installHandler(crashClass));
  return {
    status: installed.length === wanted.length ? "ok" : "handler-missing",
    installed,
  };
}

export type UploadTier = "full" | "summary" | "suppressed";

export function uploadTier(reportsToday: number, fullLimit = 3, summaryLimit = 20): UploadTier {
  if (!Number.isInteger(reportsToday) || reportsToday < 0) {
    throw new RangeError("reportsToday must be a non-negative integer");
  }
  if (reportsToday < fullLimit) {
    return "full";
  }
  if (reportsToday < summaryLimit) {
    return "summary";
  }
  return "suppressed";
}

export type SessionOutcome = "normal" | "crash" | "anr" | "kill" | "unresolved";

export interface SessionRecord {
  readonly sessionId: string;
  readonly outcome: SessionOutcome;
  readonly renderedFrames: number;
  readonly jankyFrames: number;
}

export interface RateReport {
  readonly numerator: number;
  readonly denominator: number;
  readonly value: number;
  readonly unresolvedShare: number;
  readonly precise: boolean;
}

export const MIN_SESSION_SAMPLE = 1000;
export const MIN_FRAME_SAMPLE = 30_000;
export const MAX_UNRESOLVED_SHARE = 0.1;

function makeReport(
  numerator: number,
  denominator: number,
  unresolved: number,
  minDenominator: number,
): RateReport {
  if (denominator <= 0) {
    throw new RangeError("denominator must be positive");
  }
  const unresolvedShare = unresolved / denominator;
  return {
    numerator,
    denominator,
    value: numerator / denominator,
    unresolvedShare,
    precise: unresolvedShare <= MAX_UNRESOLVED_SHARE && denominator >= minDenominator,
  };
}

export function crashRate(sessions: readonly SessionRecord[]): RateReport {
  const numerator = sessions.filter((session) => session.outcome === "crash").length;
  const unresolved = sessions.filter((session) => session.outcome === "unresolved").length;
  return makeReport(numerator, sessions.length, unresolved, MIN_SESSION_SAMPLE);
}

export function anrRate(sessions: readonly SessionRecord[]): RateReport {
  const numerator = sessions.filter((session) => session.outcome === "anr").length;
  const unresolved = sessions.filter((session) => session.outcome === "unresolved").length;
  return makeReport(numerator, sessions.length, unresolved, MIN_SESSION_SAMPLE);
}

export function crashFreeSessions(sessions: readonly SessionRecord[]): RateReport {
  const base = crashRate(sessions);
  return {
    ...base,
    numerator: base.denominator - base.numerator,
    value: 1 - base.value,
  };
}

export function jankRate(sessions: readonly SessionRecord[]): RateReport {
  let rendered = 0;
  let janky = 0;
  for (const session of sessions) {
    if (session.jankyFrames > session.renderedFrames) {
      throw new RangeError(`session ${session.sessionId} reports more janky frames than rendered frames`);
    }
    rendered += session.renderedFrames;
    janky += session.jankyFrames;
  }
  return makeReport(janky, rendered, 0, MIN_FRAME_SAMPLE);
}