《移动游戏产品的架构·商业化与发行工程》5.3 渠道对账与收入确认

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

export type ChannelId = "apple-ios" | "google-play" | "android-channel" | "tap-tap";

export interface ChannelShare {
  readonly channel: ChannelId;
  readonly shareBps: number;
}

const COMMISSION_BPS: Readonly<Record<ChannelId, number>> = {
  "apple-ios": 3000,
  "google-play": 3000,
  "android-channel": 4000,
  "tap-tap": 1500,
};

export function commissionBps(channel: ChannelId): number {
  return COMMISSION_BPS[channel];
}

export function expectedFeeCents(channel: ChannelId, grossCents: number): number {
  return Math.round((grossCents * commissionBps(channel)) / 10000);
}

export type ProjectionCode = "ok" | "invalid-shares" | "negative-gross";

export interface ProjectionResult {
  readonly code: ProjectionCode;
  readonly blendedFeeBps: number;
  readonly grossCents: number;
  readonly feeCents: number;
  readonly netCents: number;
}

export function projectSettlement(
  grossCents: number,
  shares: readonly ChannelShare[],
): ProjectionResult {
  const totalBps = shares.reduce((sum, share) => sum + share.shareBps, 0);
  const invalidShares = totalBps !== 10000 || shares.some((share) => share.shareBps < 0);
  if (grossCents < 0 || invalidShares) {
    return {
      code: grossCents < 0 ? "negative-gross" : "invalid-shares",
      blendedFeeBps: 0,
      grossCents: 0,
      feeCents: 0,
      netCents: 0,
    };
  }
  const blendedFeeBps = Math.round(
    shares.reduce(
      (sum, share) => sum + (share.shareBps * commissionBps(share.channel)) / 10000,
      0,
    ),
  );
  const feeCents = Math.round((grossCents * blendedFeeBps) / 10000);
  return {
    code: "ok",
    blendedFeeBps,
    grossCents,
    feeCents,
    netCents: grossCents - feeCents,
  };
}

export interface LedgerOrder {
  readonly channel: ChannelId;
  readonly channelOrderId: string;
  readonly grossCents: number;
  readonly refundedCents: number;
}

export interface SettlementRow {
  readonly channel: ChannelId;
  readonly channelOrderId: string;
  readonly grossCents: number;
  readonly feeCents: number;
}

export type MatchCode =
  | "matched"
  | "amount-mismatch"
  | "fee-mismatch"
  | "missing-in-settlement"
  | "missing-in-ledger"
  | "duplicate-settlement";

export interface MatchLine {
  readonly key: string;
  readonly code: MatchCode;
  readonly expectedCents: number;
  readonly actualCents: number;
  readonly feeCents: number;
}

export interface ReconciliationReport {
  readonly lines: readonly MatchLine[];
  readonly matchedCount: number;
  readonly issueCount: number;
  readonly ledgerSettledCents: number;
  readonly statementGrossCents: number;
  readonly statementFeeCents: number;
  readonly statementNetCents: number;
  readonly varianceCents: number;
}

export function settlementKey(channel: ChannelId, channelOrderId: string): string {
  return `${channel}:${channelOrderId}`;
}

export function reconcile(
  ledger: readonly LedgerOrder[],
  statement: readonly SettlementRow[],
  toleranceCents = 0,
): ReconciliationReport {
  const rowsByKey = new Map<string, SettlementRow[]>();
  for (const row of statement) {
    const key = settlementKey(row.channel, row.channelOrderId);
    const rows = rowsByKey.get(key) ?? [];
    rows.push(row);
    rowsByKey.set(key, rows);
  }
  const lines: MatchLine[] = [];
  const seen = new Set<string>();
  for (const order of ledger) {
    const key = settlementKey(order.channel, order.channelOrderId);
    seen.add(key);
    const expected = order.grossCents - order.refundedCents;
    const rows = rowsByKey.get(key) ?? [];
    if (rows.length === 0) {
      lines.push({ key, code: "missing-in-settlement", expectedCents: expected, actualCents: 0, feeCents: 0 });
      continue;
    }
    if (rows.length > 1) {
      const fee = rows.reduce((sum, row) => sum + row.feeCents, 0);
      lines.push({
        key,
        code: "duplicate-settlement",
        expectedCents: expected,
        actualCents: rows[0]?.grossCents ?? 0,
        feeCents: fee,
      });
      continue;
    }
    const row = rows[0];
    if (row === undefined) continue;
    if (Math.abs(row.grossCents - expected) > toleranceCents) {
      lines.push({
        key,
        code: "amount-mismatch",
        expectedCents: expected,
        actualCents: row.grossCents,
        feeCents: row.feeCents,
      });
      continue;
    }
    const fee = expectedFeeCents(order.channel, row.grossCents);
    if (Math.abs(row.feeCents - fee) > toleranceCents) {
      lines.push({
        key,
        code: "fee-mismatch",
        expectedCents: fee,
        actualCents: row.feeCents,
        feeCents: row.feeCents,
      });
      continue;
    }
    lines.push({
      key,
      code: "matched",
      expectedCents: expected,
      actualCents: row.grossCents,
      feeCents: row.feeCents,
    });
  }
  for (const [key, rows] of rowsByKey) {
    if (seen.has(key)) continue;
    for (const row of rows) {
      lines.push({
        key,
        code: "missing-in-ledger",
        expectedCents: 0,
        actualCents: row.grossCents,
        feeCents: row.feeCents,
      });
    }
  }
  const matchedCount = lines.filter((line) => line.code === "matched").length;
  const issueCount = lines.length - matchedCount;
  const ledgerSettledCents = ledger.reduce(
    (sum, order) => sum + order.grossCents - order.refundedCents,
    0,
  );
  const statementGrossCents = statement.reduce((sum, row) => sum + row.grossCents, 0);
  const statementFeeCents = statement.reduce((sum, row) => sum + row.feeCents, 0);
  return {
    lines,
    matchedCount,
    issueCount,
    ledgerSettledCents,
    statementGrossCents,
    statementFeeCents,
    statementNetCents: statementGrossCents - statementFeeCents,
    varianceCents: statementGrossCents - ledgerSettledCents,
  };
}

export interface RecognitionPolicy {
  readonly maxIssueRatioBps: number;
  readonly maxVarianceCents: number;
}

export interface RevenueRecognition {
  readonly recognizable: boolean;
  readonly reason: string;
  readonly netCents: number;
  readonly issueRatioBps: number;
}

export function recognizeRevenue(
  report: ReconciliationReport,
  policy: RecognitionPolicy,
): RevenueRecognition {
  const total = report.matchedCount + report.issueCount;
  const issueRatioBps = total === 0 ? 0 : Math.round((report.issueCount * 10000) / total);
  const result = (recognizable: boolean, reason: string): RevenueRecognition => ({
    recognizable,
    reason,
    netCents: report.statementNetCents,
    issueRatioBps,
  });
  if (total === 0) return result(false, "empty statement");
  if (issueRatioBps > policy.maxIssueRatioBps) {
    return result(false, `issue ratio ${issueRatioBps}bps`);
  }
  if (Math.abs(report.varianceCents) > policy.maxVarianceCents) {
    return result(false, `variance ${report.varianceCents}c`);
  }
  return result(true, "reconciled");
}

export function formatReport(report: ReconciliationReport): string {
  return `matched=${report.matchedCount} issues=${report.issueCount} gross=${report.statementGrossCents} fee=${report.statementFeeCents} net=${report.statementNetCents} variance=${report.varianceCents}`;
}