《互联网产品的客户端架构·交易、增长与平台化》13.1 端到端：选品、下单、支付、退款

// file: src/summary/e2e-scenario.ts
// tier: L2
// verify: node --test test/summary/e2e-scenario.test.ts
import { summarize } from "../cart/selection.ts";
import { buildBreakdown } from "../cart/price-breakdown.ts";

export type E2eStage = "browse" | "cart" | "submit" | "pay" | "refund";

export interface TraceEntry { stage: E2eStage; at: number; action: string }

export interface Quote {
  skuId: string; unitCents: number; available: number; maxPerOrder: number;
}

export interface SubmitCommand {
  key: string; skuId: string; quantity: number; payableCents: number;
}

export type SubmitReceipt =
  | { status: "accepted"; orderId: string; payableCents: number }
  | { status: "unknown"; queryKey: string }
  | { status: "rejected"; reason: string };

export type PayReceipt =
  | { status: "succeeded"; payId: string }
  | { status: "failed"; reason: string }
  | { status: "unknown"; payId: string }
  | { status: "rejected"; reason: string };

export type PayQuery =
  | { status: "succeeded"; payId: string }
  | { status: "failed"; reason: string }
  | { status: "pending" };

export type RefundReceipt =
  | { status: "accepted"; refundId: string; amountCents: number }
  | { status: "rejected"; reason: string };

// 场景只依赖五个窄接口；支付与对账实现可以随时替换。
export interface TradePorts {
  quote(skuId: string, quantity: number, now: number): Quote | null;
  submit(command: SubmitCommand, now: number): SubmitReceipt;
  findOrder(key: string): { orderId: string; payableCents: number } | null;
  pay(orderId: string, amountCents: number, now: number): PayReceipt;
  queryPay(payId: string): PayQuery;
  refund(orderId: string, payId: string, amountCents: number, now: number): RefundReceipt;
  refundedCents(orderId: string): number;
  stats(): { orders: number; payAttempts: number; refunds: number };
}

export interface ScenarioClock { now(): number; advance(ms: number): number }

export interface ScenarioInput {
  skuId: string; quantity: number; submitKey: string; now: number;
  discountCents?: number; shippingCents?: number;
}

export type ScenarioOutcome = "refunded" | "paid" | "payment_failed" | "blocked";

export interface ScenarioResult {
  ok: boolean; outcome: ScenarioOutcome; payableCents: number | null;
  orderId: string | null; payId: string | null; refundId: string | null;
  refundedCents: number; trace: TraceEntry[]; problems: string[];
}

function note(
  rows: TraceEntry[], stage: E2eStage, at: number, action: string,
): void {
  rows.push({ stage, at, action });
}

// 一条主线：选品 → 加购 → 下单 → 支付 → 退款。每一步只做一次，失败立即停。
export function runScenario(
  ports: TradePorts,
  input: ScenarioInput,
  clock: ScenarioClock,
  refundCents?: number,
): ScenarioResult {
  const rows: TraceEntry[] = [];
  const problems: string[] = [];
  const now = (): number => clock.now();
  const quote = ports.quote(input.skuId, input.quantity, now());
  note(rows, "browse", now(), "quote");
  if (quote === null) {
    problems.push("商品不可售或数量超出限购");
    return finish("blocked", null, null, null, null, rows, problems, ports);
  }
  if (quote.available < input.quantity) {
    problems.push("可售库存不足");
    return finish("blocked", null, null, null, null, rows, problems, ports);
  }

  const cart = summarize([{
    skuId: quote.skuId, unitCents: quote.unitCents, quantity: input.quantity,
    maxQuantity: quote.maxPerOrder, status: "active", selected: true,
  }]);
  const breakdown = buildBreakdown({
    version: 1,
    lines: [{ skuId: quote.skuId, unitCents: quote.unitCents, quantity: input.quantity }],
    discountCents: input.discountCents ?? 0,
    shippingCents: input.shippingCents ?? 0,
    taxCents: 0,
    source: "server",
  });
  note(rows, "cart", now(), "summarize");
  if (breakdown.payableCents !==
    cart.selectedSubtotalCents + (input.shippingCents ?? 0) -
    (input.discountCents ?? 0)) {
    problems.push("购物车小计与价格明细不一致");
  }

  const receipt = ports.submit({
    key: input.submitKey, skuId: input.skuId, quantity: input.quantity,
    payableCents: breakdown.payableCents,
  }, now());
  note(rows, "submit", now(), `submit:${receipt.status}`);
  if (receipt.status === "rejected") {
    problems.push(`下单被拒绝：${receipt.reason}`);
    return finish("blocked", breakdown.payableCents, null, null, null, rows, problems, ports);
  }
  let orderId: string;
  let payableCents: number;
  if (receipt.status === "accepted") {
    orderId = receipt.orderId;
    payableCents = receipt.payableCents;
  } else {
    const found = ports.findOrder(receipt.queryKey);
    note(rows, "submit", now(), "query_order");
    if (found === null) {
      problems.push("提交结果未知且查询不到订单");
      return finish("blocked", breakdown.payableCents, null, null, null, rows, problems, ports);
    }
    orderId = found.orderId;
    payableCents = found.payableCents;
  }
  if (payableCents !== breakdown.payableCents) {
    problems.push("订单实付与结算明细不一致");
  }

  const paid = ports.pay(orderId, payableCents, now());
  note(rows, "pay", now(), `pay:${paid.status}`);
  let payId: string;
  if (paid.status === "succeeded") {
    payId = paid.payId;
  } else if (paid.status === "failed") {
    return finish("payment_failed", payableCents, orderId, null, null, rows, problems, ports);
  } else if (paid.status === "rejected") {
    problems.push(`支付被拒绝：${paid.reason}`);
    return finish("blocked", payableCents, orderId, null, null, rows, problems, ports);
  } else {
    payId = paid.payId;
    let resolved: PayQuery | null = null;
    for (let i = 0; i < 3; i += 1) {
      clock.advance(1_000);
      resolved = ports.queryPay(payId);
      note(rows, "pay", now(), `query:${resolved.status}`);
      if (resolved.status !== "pending") break;
    }
    if (resolved === null || resolved.status === "pending") {
      problems.push("支付结果三次查询仍未确认");
      return finish("payment_failed", payableCents, orderId, payId, null, rows, problems, ports);
    }
    if (resolved.status === "failed") {
      return finish("payment_failed", payableCents, orderId, payId, null, rows, problems, ports);
    }
  }

  const amount = refundCents ?? payableCents;
  if (amount <= 0 || amount > payableCents) {
    problems.push("退款金额不在可退范围内");
    return finish("paid", payableCents, orderId, payId, null, rows, problems, ports);
  }
  const refund = ports.refund(orderId, payId, amount, now());
  note(rows, "refund", now(), `refund:${refund.status}`);
  if (refund.status === "rejected") {
    problems.push(`退款被拒绝：${refund.reason}`);
    return finish("paid", payableCents, orderId, payId, null, rows, problems, ports);
  }
  return finish("refunded", payableCents, orderId, payId, refund.refundId, rows, problems, ports);
}

function finish(
  outcome: ScenarioOutcome,
  payableCents: number | null,
  orderId: string | null,
  payId: string | null,
  refundId: string | null,
  rows: TraceEntry[],
  problems: string[],
  ports: TradePorts,
): ScenarioResult {
  const stats = ports.stats();
  if (stats.orders > 1) problems.push(`产生了 ${stats.orders} 笔订单`);
  const refunded = orderId === null ? 0 : ports.refundedCents(orderId);
  if (refunded > 0 && (payId === null || outcome === "payment_failed")) {
    problems.push("未确认支付却发生了退款");
  }
  return {
    ok: problems.length === 0, outcome, payableCents, orderId, payId, refundId,
    refundedCents: refunded, trace: rows, problems,
  };
}

export function stageOrder(result: ScenarioResult): E2eStage[] {
  return result.trace.map((entry) => entry.stage);
}

$ node --test --test-concurrency=1 test/summary/e2e-scenario.test.ts
✔ 选品到退款的完整主线全部成功 (1.05ms)
✔ 场景按浏览、购物车、提交、支付、退款推进 (0.438125ms)
✔ 服务端无该商品时停在浏览阶段 (0.112792ms)
✔ 购买数量超过限购时不下单 (0.063042ms)
✔ 可售库存不足时停在浏览阶段 (0.070208ms)
✔ 同一个幂等键重复提交只产生一笔订单 (0.101375ms)
✔ 不同幂等键会各自产生订单，场景能识别 (0.103666ms)
✔ 提交结果未知时通过查询键找回同一张订单 (0.093417ms)
✔ 支付超时后查询成功再退款 (0.175083ms)
✔ 支付超时后查询失败则不退款 (0.136333ms)
✔ 渠道明确失败时不进入退款阶段 (0.088542ms)
✔ 退款金额超过实付时被拒绝 (0.072ms)
✔ 退款金额必须为正 (0.058375ms)
✔ 部分退款只记录实际退款金额 (0.051542ms)
ℹ tests 14
ℹ suites 0
ℹ pass 14
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 179.81375