《移动游戏产品的架构·商业化与发行工程》10.3 数据质量：丢失、重复与口径漂移

// file: src/biz/data-quality.ts
// tier: L1
// verify: node --test test/biz/data-quality.test.ts

export type FieldType = "string" | "number" | "boolean";

export interface Contract {
  readonly name: string;
  readonly version: number;
  readonly required: readonly string[];
  readonly fields: Readonly<Record<string, FieldType>>;
}

export type MeasureCode =
  | "bad-sent"
  | "received-exceeds-sent"
  | "bad-total"
  | "distinct-exceeds-total"
  | "bad-amount"
  | "bad-tolerance";

export type Measure =
  | { readonly ok: true; readonly value: number }
  | { readonly ok: false; readonly code: MeasureCode; readonly detail: string };

export type ReconcileStatus = "within" | "over" | "under";

export type ReconcileResult =
  | {
      readonly ok: true;
      readonly diffCents: number;
      readonly diffPct: number;
      readonly status: ReconcileStatus;
      readonly tolerancePct: number;
    }
  | { readonly ok: false; readonly code: MeasureCode; readonly detail: string };

export type DriftKind =
  | "name-changed"
  | "field-removed"
  | "required-added"
  | "type-changed"
  | "field-added"
  | "version-not-bumped";

export interface Drift {
  readonly kind: DriftKind;
  readonly field: string;
  readonly breaking: boolean;
  readonly detail: string;
}

export interface DriftResult {
  readonly ok: boolean;
  readonly drifts: readonly Drift[];
}

export const CASE_QUALITY: Readonly<
  Record<"xiaoxiao" | "fangzhou", { readonly lossPct: number; readonly duplicatePct: number; readonly events: number }>
> = {
  xiaoxiao: { lossPct: 2.5, duplicatePct: 0.8, events: 38 },
  fangzhou: { lossPct: 1.2, duplicatePct: 0.4, events: 46 },
};

export function lossRatePct(sent: number, received: number): Measure {
  if (!Number.isInteger(sent) || sent <= 0) {
    return { ok: false, code: "bad-sent", detail: `${sent} is not a positive batch size` };
  }
  if (!Number.isInteger(received) || received < 0) {
    return { ok: false, code: "bad-sent", detail: `${received} is not a received count` };
  }
  if (received > sent) {
    return {
      ok: false,
      code: "received-exceeds-sent",
      detail: `received ${received} exceeds sent ${sent}; count duplicates before computing loss`,
    };
  }
  return { ok: true, value: round4(((sent - received) / sent) * 100) };
}

export function duplicateRatePct(total: number, distinct: number): Measure {
  if (!Number.isInteger(total) || total <= 0) {
    return { ok: false, code: "bad-total", detail: `${total} is not a positive total` };
  }
  if (!Number.isInteger(distinct) || distinct < 0) {
    return { ok: false, code: "bad-total", detail: `${distinct} is not a distinct count` };
  }
  if (distinct > total) {
    return {
      ok: false,
      code: "distinct-exceeds-total",
      detail: `distinct ${distinct} exceeds total ${total}`,
    };
  }
  return { ok: true, value: round4(((total - distinct) / total) * 100) };
}

export function reconcileCents(
  ledgerCents: number,
  reportedCents: number,
  tolerancePct: number,
): ReconcileResult {
  if (!Number.isFinite(ledgerCents) || ledgerCents <= 0) {
    return { ok: false, code: "bad-amount", detail: `ledger ${ledgerCents} must be positive` };
  }
  if (!Number.isFinite(reportedCents) || reportedCents < 0) {
    return { ok: false, code: "bad-amount", detail: `reported ${reportedCents} must be non-negative` };
  }
  if (!Number.isFinite(tolerancePct) || tolerancePct < 0) {
    return { ok: false, code: "bad-tolerance", detail: `tolerance ${tolerancePct} must be non-negative` };
  }
  const diffCents = Math.round(reportedCents - ledgerCents);
  const diffPct = round4((diffCents / ledgerCents) * 100);
  if (Math.abs(diffPct) <= tolerancePct) {
    return { ok: true, diffCents, diffPct, status: "within", tolerancePct };
  }
  return {
    ok: true,
    diffCents,
    diffPct,
    status: diffPct > 0 ? "over" : "under",
    tolerancePct,
  };
}

export function detectDrift(baseline: Contract, candidate: Contract): DriftResult {
  const drifts: Drift[] = [];
  if (baseline.name !== candidate.name) {
    drifts.push({
      kind: "name-changed",
      field: "name",
      breaking: true,
      detail: `${baseline.name} became ${candidate.name}`,
    });
  }
  for (const [field, type] of Object.entries(baseline.fields)) {
    const next = candidate.fields[field];
    if (next === undefined) {
      drifts.push({
        kind: "field-removed",
        field,
        breaking: true,
        detail: `${field} disappeared from v${candidate.version}`,
      });
      continue;
    }
    if (next !== type) {
      drifts.push({
        kind: "type-changed",
        field,
        breaking: true,
        detail: `${field} changed from ${type} to ${next}`,
      });
    }
  }
  for (const field of Object.keys(candidate.fields)) {
    if (baseline.fields[field] === undefined) {
      drifts.push({
        kind: "field-added",
        field,
        breaking: false,
        detail: `${field} is new in v${candidate.version}`,
      });
    }
  }
  for (const field of candidate.required) {
    if (!baseline.required.includes(field)) {
      drifts.push({
        kind: "required-added",
        field,
        breaking: true,
        detail: `${field} became required in v${candidate.version}`,
      });
    }
  }
  if (drifts.length > 0 && candidate.version <= baseline.version) {
    drifts.push({
      kind: "version-not-bumped",
      field: "version",
      breaking: true,
      detail: `schema changed but version stayed at ${candidate.version}`,
    });
  }
  return { ok: drifts.every((drift) => !drift.breaking), drifts };
}

export function formatQualityReport(
  label: string,
  loss: Measure,
  duplicate: Measure,
  reconcile: ReconcileResult,
): string {
  const lossText = loss.ok ? `${loss.value}%` : `error:${loss.code}`;
  const duplicateText = duplicate.ok ? `${duplicate.value}%` : `error:${duplicate.code}`;
  const reconcileText = reconcile.ok
    ? `${reconcile.status}(${reconcile.diffPct > 0 ? "+" : ""}${reconcile.diffPct}%)`
    : `error:${reconcile.code}`;
  return `quality ${label} loss=${lossText} dup=${duplicateText} reconcile=${reconcileText}`;
}

function round4(value: number): number {
  return Math.round(value * 10000) / 10000;
}