《互联网产品的 AI 架构·平台化与治理》7.1 预算、账单与归因的分工

// file: src/gov/chargeback.ts
// tier: L2
// verify: node --test test/gov/chargeback.test.ts

import { AiError } from "../core/errors.ts";

/** 三本账回答三个不同的问题，不能互相替代。 */
export type LedgerKind = "budget" | "bill" | "attribution";
export type CostGrain = "team" | "team-capability" | "team-capability-route";

export interface LedgerRole {
  question: string;
  timing: string;
  unit: string;
  owner: string;
  artifact: string;
}

/** 预算是事前承诺，账单是事后事实，归因是差异解释。 */
export const LEDGER_ROLES: Record<LedgerKind, LedgerRole> = {
  budget: {
    question: "这个团队最多可以花多少", timing: "事前", unit: "分配额度（微元）",
    owner: "团队负责人 + 财务", artifact: "预算单",
  },
  bill: {
    question: "这个账期实际花了多少", timing: "事后", unit: "计费事件（微元）",
    owner: "平台计量 + 供应商", artifact: "账单",
  },
  attribution: {
    question: "为什么花得比预期多或少", timing: "事后", unit: "差异因子（可正可负）",
    owner: "平台 + 责任团队", artifact: "归因报告",
  },
};

export const GRAIN_DEPTH: Record<CostGrain, number> = {
  team: 1, "team-capability": 2, "team-capability-route": 3,
};

export interface CostEntry {
  teamId: string;
  capability: string;
  route?: string;
  micros: number;
  /** 归因账专用：这一行解释的是量、结构、单价还是范围差异。 */
  driver?: "volume" | "mix" | "rate" | "scope" | "credit";
}

export interface Ledger {
  kind: LedgerKind;
  grain: CostGrain;
  entries: readonly CostEntry[];
}

export type ReconFlag =
  | "aligned" | "over-budget" | "unspent" | "unbudgeted" | "unattributed" | "attribution-over";

export interface ReconRow {
  teamId: string;
  capability: string;
  budgetMicros: number;
  billedMicros: number;
  attributedMicros: number;
  /** 账单减预算；正数是超支。 */
  varianceMicros: number;
  /** 账单减归因；正数是尚未解释的部分。 */
  gapMicros: number;
  flags: ReconFlag[];
}

export interface ReconTotals {
  budgetMicros: number;
  billedMicros: number;
  attributedMicros: number;
  varianceMicros: number;
  netGapMicros: number;
  grossGapMicros: number;
  overBudgetMicros: number;
  unspentMicros: number;
  coverageBps: number;
}

export interface Reconciliation {
  grain: CostGrain;
  rows: ReconRow[];
  totals: ReconTotals;
  /** 每本账被压掉的明细数量，提示对账的粒度损失。 */
  collapsed: Record<LedgerKind, number>;
  balanced: boolean;
  overBudget: boolean;
}

export interface ReconcileOptions {
  /** 实际支出低于预算多少算“明显未用完”，默认 20%。 */
  unspentThresholdBps?: number;
}

function fail(message: string): never {
  throw new AiError("invalid-request", `chargeback: ${message}`);
}

function text(value: string, field: string): string {
  if (typeof value !== "string" || value.trim() === "") fail(`${field} is required`);
  return value;
}

function integer(value: number, field: string, min = Number.MIN_SAFE_INTEGER): number {
  if (!Number.isSafeInteger(value) || value < min) fail(`${field} must be an integer >= ${min}`);
  return value;
}

function grainDepth(grain: CostGrain): number {
  const depth = GRAIN_DEPTH[grain];
  if (depth === undefined) fail(`unknown grain ${String(grain)}`);
  return depth;
}

function keyAt(entry: CostEntry, grain: CostGrain): string {
  const depth = grainDepth(grain);
  const parts = [entry.teamId];
  if (depth >= 2) parts.push(entry.capability);
  if (depth >= 3) parts.push(entry.route ?? "*");
  return parts.join("\u0000");
}

function aggregate(ledger: Ledger, grain: CostGrain): Map<string, ReconRow> {
  const buckets = new Map<string, ReconRow>();
  const depth = grainDepth(grain);
  for (const entry of ledger.entries) {
    text(entry.teamId, "entry.teamId");
    text(entry.capability, "entry.capability");
    if (depth >= 3) text(entry.route ?? "", "entry.route");
    const min = ledger.kind === "attribution" ? Number.MIN_SAFE_INTEGER : 0;
    integer(entry.micros, "entry.micros", min);
    const key = keyAt(entry, grain);
    const bucket = buckets.get(key);
    if (bucket === undefined) {
      buckets.set(key, {
        teamId: entry.teamId,
        capability: depth >= 2 ? entry.capability : "*",
        budgetMicros: ledger.kind === "budget" ? entry.micros : 0,
        billedMicros: ledger.kind === "bill" ? entry.micros : 0,
        attributedMicros: ledger.kind === "attribution" ? entry.micros : 0,
        varianceMicros: 0, gapMicros: 0, flags: [],
      });
    } else if (ledger.kind === "budget") bucket.budgetMicros += entry.micros;
    else if (ledger.kind === "bill") bucket.billedMicros += entry.micros;
    else bucket.attributedMicros += entry.micros;
  }
  return buckets;
}

/**
 * 三本账只能在对齐到最粗粒度后相减。
 * 谁更细，谁的明细就在对齐时被压掉；对账报告必须把损失写出来。
 */
export function reconcileCostLedgers(
  budget: Ledger,
  bill: Ledger,
  attribution: Ledger,
  options: ReconcileOptions = {},
): Reconciliation {
  if (budget.kind !== "budget") fail("first ledger must be budget");
  if (bill.kind !== "bill") fail("second ledger must be bill");
  if (attribution.kind !== "attribution") fail("third ledger must be attribution");
  const threshold = integer(options.unspentThresholdBps ?? 2_000, "unspentThresholdBps", 0);
  if (threshold > 10_000) fail("unspentThresholdBps must not exceed 10000");

  const ledgers = [budget, bill, attribution];
  for (const ledger of ledgers) {
    const seen = new Set<string>();
    for (const entry of ledger.entries) {
      const key = keyAt(entry, ledger.grain);
      if (seen.has(key)) fail(`${ledger.kind}: duplicate entry ${key.replaceAll("\u0000", "/")}`);
      seen.add(key);
    }
  }

  const depth = Math.min(...ledgers.map((ledger) => grainDepth(ledger.grain)));
  const grain = (Object.keys(GRAIN_DEPTH) as CostGrain[]).find((item) => GRAIN_DEPTH[item] === depth);
  if (grain === undefined) fail("cannot determine common grain");
  const maps = {
    budget: aggregate(budget, grain),
    bill: aggregate(bill, grain),
    attribution: aggregate(attribution, grain),
  };

  const keys = [...new Set([...maps.budget.keys(), ...maps.bill.keys(), ...maps.attribution.keys()])].sort();
  const rows = keys.map((key): ReconRow => {
    const fromBudget = maps.budget.get(key);
    const fromBill = maps.bill.get(key);
    const fromAttribution = maps.attribution.get(key);
    const source = fromBudget ?? fromBill ?? fromAttribution;
    if (source === undefined) fail(`missing row ${key}`);
    const row: ReconRow = {
      teamId: source.teamId, capability: source.capability,
      budgetMicros: fromBudget?.budgetMicros ?? 0,
      billedMicros: fromBill?.billedMicros ?? 0,
      attributedMicros: fromAttribution?.attributedMicros ?? 0,
      varianceMicros: 0, gapMicros: 0, flags: [],
    };
    row.varianceMicros = row.billedMicros - row.budgetMicros;
    row.gapMicros = row.billedMicros - row.attributedMicros;
    if (row.budgetMicros === 0 && row.billedMicros > 0) row.flags.push("unbudgeted");
    if (row.billedMicros > row.budgetMicros) row.flags.push("over-budget");
    if (row.budgetMicros > 0 && row.billedMicros * 10_000 < row.budgetMicros * (10_000 - threshold)) {
      row.flags.push("unspent");
    }
    if (row.gapMicros > 0) row.flags.push("unattributed");
    if (row.gapMicros < 0) row.flags.push("attribution-over");
    if (row.flags.length === 0) row.flags.push("aligned");
    return row;
  });

  const totals: ReconTotals = {
    budgetMicros: 0, billedMicros: 0, attributedMicros: 0, varianceMicros: 0,
    netGapMicros: 0, grossGapMicros: 0, overBudgetMicros: 0, unspentMicros: 0, coverageBps: 10_000,
  };
  for (const row of rows) {
    totals.budgetMicros += row.budgetMicros;
    totals.billedMicros += row.billedMicros;
    totals.attributedMicros += row.attributedMicros;
    totals.varianceMicros += row.varianceMicros;
    totals.netGapMicros += row.gapMicros;
    totals.grossGapMicros += Math.abs(row.gapMicros);
    totals.overBudgetMicros += Math.max(0, row.varianceMicros);
    totals.unspentMicros += Math.max(0, -row.varianceMicros);
  }
  if (totals.billedMicros !== 0) {
    totals.coverageBps = Math.round((totals.attributedMicros * 10_000) / totals.billedMicros);
  }

  return {
    grain, rows, totals,
    collapsed: {
      budget: budget.entries.length - maps.budget.size,
      bill: bill.entries.length - maps.bill.size,
      attribution: attribution.entries.length - maps.attribution.size,
    },
    balanced: totals.grossGapMicros === 0,
    overBudget: rows.some((row) => row.flags.includes("over-budget") || row.flags.includes("unbudgeted")),
  };
}