《互联网产品的客户端架构·交易、增长与平台化》3.2 价格明细的端上重算边界

// file: src/cart/price-breakdown.ts
// tier: L1
// verify: node --test test/cart/price-breakdown.test.ts
import type { Money } from "../core/trade-model.ts";

export type BreakdownSource = "server" | "preview";
export type BreakdownKey = "subtotal" | "discount" | "shipping" | "tax" | "payable";

export interface BreakdownLine { skuId: string; unitCents: number; quantity: number; }
export interface LineShare { skuId: string; subtotalCents: number; discountCents: number; }
export interface BreakdownRow { key: BreakdownKey; label: string; cents: number; }
export interface BreakdownInput {
  version: number;
  lines: BreakdownLine[];
  discountCents: number;
  shippingCents: number;
  taxCents: number;
  source?: BreakdownSource;
}

export interface PriceBreakdown {
  version: number;
  currency: Money["currency"];
  source: BreakdownSource;
  subtotalCents: number;
  discountCents: number;
  shippingCents: number;
  taxCents: number;
  payableCents: number;
  lines: LineShare[];
}

// 五段明细只在这里组装一次；任何展示层都读这个对象，不各自拼金额。
export function buildBreakdown(input: BreakdownInput): PriceBreakdown {
  if (!Number.isInteger(input.version) || input.version < 0) {
    throw new Error("明细版本号必须是非负整数");
  }
  assertInt(input.discountCents, "优惠金额");
  assertInt(input.shippingCents, "运费");
  assertInt(input.taxCents, "税费");
  const source = input.source ?? "server";
  if (source !== "server" && source !== "preview") {
    throw new Error(`未知的明细来源：${String(source)}`);
  }

  const subtotals: number[] = [];
  for (const line of input.lines) {
    assertInt(line.unitCents, `单价 ${line.skuId}`);
    if (!Number.isInteger(line.quantity) || line.quantity < 1) {
      throw new Error(`数量非法：${line.skuId}`);
    }
    const lineTotal = line.unitCents * line.quantity;
    if (!Number.isSafeInteger(lineTotal)) {
      throw new Error(`行金额溢出：${line.skuId}`);
    }
    subtotals.push(lineTotal);
  }
  const subtotalCents = subtotals.reduce((sum, value) => sum + value, 0);
  if (!Number.isSafeInteger(subtotalCents)) throw new Error("商品小计溢出");
  if (input.discountCents > subtotalCents) {
    throw new Error("优惠金额不能超过商品小计");
  }

  const shares = allocateDiscount(subtotals, input.discountCents);
  const payableCents =
    subtotalCents - input.discountCents + input.shippingCents + input.taxCents;
  if (!Number.isSafeInteger(payableCents) || payableCents < 0) {
    throw new Error("实付金额非法");
  }
  return {
    version: input.version,
    currency: "CNY",
    source,
    subtotalCents,
    discountCents: input.discountCents,
    shippingCents: input.shippingCents,
    taxCents: input.taxCents,
    payableCents,
    lines: input.lines.map((line, index) => ({
      skuId: line.skuId,
      subtotalCents: subtotals[index],
      discountCents: shares[index],
    })),
  };
}

// 展示层分摊：最大余数法，保证各行分摊之和精确等于优惠总额。
export function allocateDiscount(subtotals: number[], discountCents: number): number[] {
  assertInt(discountCents, "优惠金额");
  let total = 0;
  for (const value of subtotals) {
    assertInt(value, "行小计");
    total += value;
    if (!Number.isSafeInteger(total)) throw new Error("行小计累加溢出");
  }
  if (discountCents > total) throw new Error("优惠金额不能超过商品小计");
  if (discountCents === 0 || subtotals.length === 0) return subtotals.map(() => 0);

  const shares = subtotals.map((value) => Math.floor((discountCents * value) / total));
  let remainder = discountCents - shares.reduce((sum, value) => sum + value, 0);
  const order = subtotals
    .map((value, index) => ({ index, fraction: (discountCents * value) % total }))
    .sort((a, b) => b.fraction - a.fraction || a.index - b.index);
  for (const entry of order) {
    if (remainder === 0) break;
    shares[entry.index] += 1;
    remainder -= 1;
  }
  return shares;
}

// 税费按整数分计算，0.5 分向上进位；不使用浮点乘法。
export function roundTax(netCents: number, rateBps: number): number {
  assertInt(netCents, "计税基数");
  if (!Number.isInteger(rateBps) || rateBps < 0 || rateBps > 10_000) {
    throw new Error("税率必须在 0 到 10000 个基点之间");
  }
  const numerator = netCents * rateBps;
  if (!Number.isSafeInteger(numerator)) throw new Error("税费计算溢出");
  return Math.floor((numerator + 5_000) / 10_000);
}

export function breakdownRows(breakdown: PriceBreakdown): BreakdownRow[] {
  return [
    { key: "subtotal", label: "商品小计", cents: breakdown.subtotalCents },
    { key: "discount", label: "优惠", cents: -breakdown.discountCents },
    { key: "shipping", label: "运费", cents: breakdown.shippingCents },
    { key: "tax", label: "税费", cents: breakdown.taxCents },
    { key: "payable", label: "实付", cents: breakdown.payableCents },
  ];
}

// 合计的是四个组成段，payable 是结果行，不能再加一次。
export function sumRows(rows: BreakdownRow[]): number {
  return rows.filter((row) => row.key !== "payable")
    .reduce((sum, row) => sum + row.cents, 0);
}

// 端上只做预演：沿用服务端版本号，标记 preview，提交前必须换成服务端明细。
export function previewBreakdown(
  server: PriceBreakdown,
  lines: BreakdownLine[],
): PriceBreakdown {
  const subtotalCents = lines.reduce(
    (sum, line) => sum + line.unitCents * line.quantity,
    0,
  );
  return buildBreakdown({
    version: server.version,
    lines,
    discountCents: Math.min(server.discountCents, subtotalCents),
    shippingCents: server.shippingCents,
    taxCents: server.taxCents,
    source: "preview",
  });
}

export function canSubmit(breakdown: PriceBreakdown): boolean {
  return breakdown.source === "server";
}

export function sameSnapshot(a: PriceBreakdown, b: PriceBreakdown): boolean {
  return a.version === b.version && sameAmounts(a, b);
}

export function assertSnapshot(breakdown: PriceBreakdown, expectedVersion: number): void {
  if (breakdown.version !== expectedVersion) {
    throw new Error(`明细版本不一致：期望 ${expectedVersion}，实际 ${breakdown.version}`);
  }
}

// 服务端明细按版本号单调推进；同版本不同金额说明服务端自相矛盾，必须报错。
export function mergeBreakdown(
  current: PriceBreakdown,
  incoming: PriceBreakdown,
): { breakdown: PriceBreakdown; discarded: boolean } {
  if (incoming.version < current.version) return { breakdown: current, discarded: true };
  if (incoming.version === current.version) {
    if (!sameAmounts(current, incoming)) {
      throw new Error(`版本 ${incoming.version} 的明细金额不一致`);
    }
    return { breakdown: current, discarded: false };
  }
  return { breakdown: incoming, discarded: false };
}

function sameAmounts(a: PriceBreakdown, b: PriceBreakdown): boolean {
  return a.subtotalCents === b.subtotalCents &&
    a.discountCents === b.discountCents &&
    a.shippingCents === b.shippingCents &&
    a.taxCents === b.taxCents &&
    a.payableCents === b.payableCents;
}

function assertInt(value: number, name: string): void {
  if (!Number.isSafeInteger(value) || value < 0) {
    throw new Error(`${name} 必须是非负安全整数`);
  }
}

$ node --test test/cart/price-breakdown.test.ts
✔ 五段明细按固定公式计算出实付 (0.742375ms)
✔ 行小计等于单价乘数量 (0.432208ms)
✔ 优惠不能超过商品小计 (0.212458ms)
✔ 非整数单价被拒绝 (0.082625ms)
✔ 空明细允许只有运费与税费 (0.073833ms)
✔ 等额小计按最大余数分摊，余数给靠前的行 (0.07075ms)
✔ 整除时分摊与比例完全一致 (0.064792ms)
✔ 有余数时按小数部分从大到小分配 (0.052333ms)
✔ 零优惠分摊全为零，零小计不允许有优惠 (0.08475ms)
✔ 展示行固定五段且合计等于实付 (0.172042ms)
✔ 税费按整数分计算，半分向上进位 (0.0805ms)
✔ 税率的零值与全额边界 (0.0585ms)
✔ 预览沿用服务端版本号并标记 preview (0.094167ms)
✔ 预览时优惠自动收敛到新小计 (0.07275ms)
✔ 只有服务端明细允许提交 (0.042166ms)
✔ 同一版本号但金额不同时拒绝合并 (0.133041ms)
✔ 旧版本明细被丢弃 (0.051333ms)
✔ 新版本明细覆盖当前值 (0.048625ms)
✔ 同版本且金额一致视为同一快照 (0.050792ms)
✔ 快照版本不一致时断言失败 (0.108916ms)
✔ 非法版本号被拒绝 (0.046709ms)
ℹ tests 21
ℹ suites 0
ℹ pass 21
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 126.461