《互联网产品的 AI 架构·平台化与治理》7.2 成本分摊与内部计价

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

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

/** 计价单位决定“谁在为什么付费”，不是单纯的价格标签。 */
export type PriceUnit = "micros-per-call" | "micros-per-1k-tokens" | "period-fixed";

export interface PriceCard {
  capability: string;
  unit: PriceUnit;
  /** 每次调用、每千 token 或每账期的整数微元。 */
  priceMicros: number;
}

export const UNIT_GUIDANCE: Record<PriceUnit, string> = {
  "micros-per-call": "动作类能力按次计价，调用方容易预估单次成本",
  "micros-per-1k-tokens": "生成类能力按 token 计价，成本随输入输出长度变化",
  "period-fixed": "共享基础设施按期计价，必须再用分摊键分到团队",
};

export interface Usage {
  calls: number;
  tokens: number;
}

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

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

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

/** 按价格卡计价；按 token 计价时向上取整到下一个千 token。 */
export function priceUsage(card: PriceCard, usage: Usage): number {
  text(card.capability, "card.capability");
  integer(card.priceMicros, "card.priceMicros");
  integer(usage.calls, "usage.calls");
  integer(usage.tokens, "usage.tokens");
  if (card.unit === "micros-per-call") return usage.calls * card.priceMicros;
  if (card.unit === "micros-per-1k-tokens") {
    return Math.ceil((usage.tokens * card.priceMicros) / 1_000);
  }
  return card.priceMicros;
}

export interface PoolParticipant {
  teamId: string;
  /** 已按价格卡算出的直接用量成本，作为 usage 分摊键。 */
  usageMicros: number;
  /** 收益口径：节省的人力分钟、带来的收入增量等，由各方预先认同。 */
  benefitUnits: number;
  /** 合同约定的固定比例权重。 */
  fixedWeight: number;
}

export type AllocationMethod = "usage" | "benefit" | "fixed";

export interface Allocation {
  teamId: string;
  weight: number;
  allocatedMicros: number;
}

function weightOf(participant: PoolParticipant, method: AllocationMethod): number {
  const weight = method === "usage"
    ? participant.usageMicros
    : method === "benefit" ? participant.benefitUnits : participant.fixedWeight;
  return integer(weight, `weight of ${participant.teamId}`);
}

/**
 * 最大余数法：先按权重取整，再把余下的微元分给余数最大的参与者。
 * 分摊结果必须精确等于池子总额，否则每个月都会留下几微元的悬账。
 */
export function allocatePool(
  poolMicros: number,
  participants: readonly PoolParticipant[],
  method: AllocationMethod,
): Allocation[] {
  integer(poolMicros, "poolMicros", 1);
  if (participants.length === 0) fail("participants must not be empty");
  const seen = new Set<string>();
  const rows = participants.map((participant) => {
    text(participant.teamId, "participant.teamId");
    if (seen.has(participant.teamId)) fail(`duplicate participant ${participant.teamId}`);
    seen.add(participant.teamId);
    return { teamId: participant.teamId, weight: weightOf(participant, method) };
  });
  const totalWeight = rows.reduce((sum, row) => sum + row.weight, 0);
  if (totalWeight === 0) fail(`total ${method} weight must be positive`);

  const exact = rows.map((row) => (poolMicros * row.weight) / totalWeight);
  const allocated = exact.map((value) => Math.floor(value));
  let remainder = poolMicros - allocated.reduce((sum, value) => sum + value, 0);
  const order = rows.map((row, index) => ({
    index, fraction: exact[index] - allocated[index], teamId: row.teamId,
  })).sort((left, right) => {
    if (right.fraction !== left.fraction) return right.fraction - left.fraction;
    return left.teamId.localeCompare(right.teamId);
  });
  for (const item of order) {
    if (remainder === 0) break;
    allocated[item.index] += 1;
    remainder -= 1;
  }

  return rows.map((row, index) => ({
    teamId: row.teamId, weight: row.weight, allocatedMicros: allocated[index],
  })).sort((left, right) => {
    if (right.allocatedMicros !== left.allocatedMicros) {
      return right.allocatedMicros - left.allocatedMicros;
    }
    return left.teamId.localeCompare(right.teamId);
  });
}

export function allocationTotal(allocations: readonly Allocation[]): number {
  return allocations.reduce((sum, allocation) => sum + allocation.allocatedMicros, 0);
}

export type DisputeReason = "metering" | "attribution" | "rate-card" | "allocation-key";

export interface DisputePolicy {
  owner: string;
  slaDays: number;
  evidence: string;
}

/** 争议先按类别找对责任人；把四类争议都丢给财务是最常见的失效方式。 */
export const DISPUTE_POLICIES: Record<DisputeReason, DisputePolicy> = {
  metering: { owner: "平台计量", slaDays: 3, evidence: "请求 id、原始用量与计费事件" },
  attribution: { owner: "平台 + 财务", slaDays: 5, evidence: "归因行、维度假设与基线" },
  "rate-card": { owner: "商务 + 财务", slaDays: 10, evidence: "合同价版本与生效日期" },
  "allocation-key": { owner: "治理委员会", slaDays: 10, evidence: "分摊键变更对各方的影响测算" },
};

export interface ChargebackDispute {
  id: string;
  teamId: string;
  amountMicros: number;
  reason: DisputeReason;
  evidence: string;
  openedDay: string;
}

export interface DisputeScreening {
  accepted: boolean;
  owner: string;
  slaDays: number;
  dueDay: string | null;
  overdue: boolean;
  problems: string[];
}

function isDay(value: string): boolean {
  return /^\d{4}-\d{2}-\d{2}$/.test(value) && !Number.isNaN(Date.parse(`${value}T00:00:00Z`));
}

function addDays(day: string, offset: number): string {
  const date = new Date(`${day}T00:00:00Z`);
  date.setUTCDate(date.getUTCDate() + offset);
  return date.toISOString().slice(0, 10);
}

/** 受理争议只做三件事：查类别、查证据、算到期日；它不判断谁对。 */
export function screenDispute(dispute: ChargebackDispute, todayDay: string): DisputeScreening {
  const policy = DISPUTE_POLICIES[dispute.reason];
  const problems: string[] = [];
  if (policy === undefined) fail(`unknown dispute reason ${String(dispute.reason)}`);
  if (dispute.id.trim() === "") problems.push("missing id");
  if (dispute.teamId.trim() === "") problems.push("missing team");
  if (!Number.isSafeInteger(dispute.amountMicros) || dispute.amountMicros <= 0) {
    problems.push("amount must be a positive integer");
  }
  if (dispute.evidence.trim() === "") problems.push(`missing evidence: ${policy.evidence}`);
  if (!isDay(dispute.openedDay)) problems.push("openedDay must be YYYY-MM-DD");
  if (!isDay(todayDay)) fail("todayDay must be YYYY-MM-DD");
  const accepted = problems.length === 0;
  const dueDay = accepted ? addDays(dispute.openedDay, policy.slaDays) : null;
  return {
    accepted,
    owner: policy.owner,
    slaDays: policy.slaDays,
    dueDay,
    overdue: dueDay !== null && todayDay > dueDay,
    problems,
  };
}

/** 争议成立时只在参与者之间转移，池子总额不变。 */
export function transferAllocation(
  allocations: readonly Allocation[],
  fromTeamId: string,
  toTeamId: string,
  micros: number,
): Allocation[] {
  integer(micros, "micros", 1);
  if (fromTeamId === toTeamId) fail("from and to must differ");
  const from = allocations.find((item) => item.teamId === fromTeamId);
  const to = allocations.find((item) => item.teamId === toTeamId);
  if (from === undefined || to === undefined) fail("unknown participant");
  if (from.allocatedMicros < micros) fail("transfer exceeds allocation");
  return allocations.map((item): Allocation => {
    if (item.teamId === fromTeamId) return { ...item, allocatedMicros: item.allocatedMicros - micros };
    if (item.teamId === toTeamId) return { ...item, allocatedMicros: item.allocatedMicros + micros };
    return { ...item };
  }).sort((left, right) => {
    if (right.allocatedMicros !== left.allocatedMicros) {
      return right.allocatedMicros - left.allocatedMicros;
    }
    return left.teamId.localeCompare(right.teamId);
  });
}