《互联网产品的客户端架构·交易、增长与平台化》6.1 端上如何避免重复支付

// file: src/reconcile/double-pay.ts
// tier: L2
// verify: node --test test/reconcile/double-pay.test.ts

export type PayPhase = "creating" | "paying" | "unknown" | "paid" | "failed" | "closed";

export interface PayAttempt {
  key: string; payId: string | null; orderId: string; channel: string;
  amountCents: number; phase: PayPhase; createdAt: number; updatedAt: number;
  channelTxnId: string | null; reason: string | null; polls: number;
}

export interface PaySnapshot { orderId: string; attempts: PayAttempt[]; }

export interface EntryResult {
  ok: boolean; action: "create" | "query" | "none";
  key: string | null; payId: string | null; reason: string;
}

export type QueryView =
  | { status: "found"; channelTxnId: string; amountCents: number }
  | { status: "not_found" }
  | { status: "unknown" };

const ACTIVE: PayPhase[] = ["creating", "paying", "unknown"];

function assertCents(cents: number): void {
  if (!Number.isSafeInteger(cents) || cents <= 0) throw new Error("支付金额必须是正整数分");
}

// 支付单是订单的一对多关系：可以换渠道重试，但同一时刻只允许一个在途支付单。
export class DoublePayGuard {
  orderId: string;
  attempts: PayAttempt[];
  now: () => number;
  returned: Set<string>;

  constructor(orderId: string, now: () => number) {
    const id = orderId.trim();
    if (id === "") throw new Error("订单号不能为空");
    this.orderId = id;
    this.attempts = [];
    this.now = now;
    this.returned = new Set();
  }

  snapshot(): PaySnapshot {
    return { orderId: this.orderId, attempts: this.attempts.map((item) => ({ ...item })) };
  }

  hasPaid(): boolean {
    return this.attempts.some((item) => item.phase === "paid");
  }

  activeAttempt(): PayAttempt | null {
    return this.attempts.find((item) => ACTIVE.includes(item.phase)) ?? null;
  }

  findByKey(key: string): PayAttempt {
    const attempt = this.attempts.find((item) => item.key === key);
    if (!attempt) throw new Error(`支付意图不存在：${key}`);
    return attempt;
  }

  findByPayId(payId: string): PayAttempt | null {
    return this.attempts.find((item) => item.payId === payId) ?? null;
  }

  beginClick(channel: string, amountCents: number): EntryResult {
    if (this.hasPaid()) return { ok: false, action: "none", key: null, payId: null, reason: "already_paid" };
    const active = this.activeAttempt();
    if (active) {
      return {
        ok: false,
        action: active.phase === "unknown" ? "query" : "none",
        key: active.key,
        payId: active.payId,
        reason: active.phase === "unknown" ? "need_query" : "attempt_active",
      };
    }
    const name = channel.trim();
    if (name === "") throw new Error("支付渠道不能为空");
    assertCents(amountCents);
    const at = this.now();
    const key = `pay-${this.orderId}-${this.attempts.length + 1}`;
    this.attempts.push({
      key,
      payId: null,
      orderId: this.orderId,
      channel: name,
      amountCents,
      phase: "creating",
      createdAt: at,
      updatedAt: at,
      channelTxnId: null,
      reason: null,
      polls: 0,
    });
    return { ok: true, action: "create", key, payId: null, reason: "started" };
  }

  markCreated(key: string, payId: string): PayAttempt {
    const attempt = this.findByKey(key);
    if (attempt.phase !== "creating") throw new Error("只有创建中的支付意图可以回填支付单号");
    const id = payId.trim();
    if (id === "") throw new Error("支付单号不能为空");
    if (this.attempts.some((item) => item.payId === id)) throw new Error("支付单号重复");
    attempt.payId = id;
    attempt.phase = "paying";
    attempt.updatedAt = this.now();
    return { ...attempt };
  }

  // 创建或支付超时都只能落到未知，不允许直接判失败。
  timeout(key: string): PayAttempt {
    const attempt = this.findByKey(key);
    if (attempt.phase === "creating") {
      attempt.phase = "unknown";
      attempt.reason = "create_timeout";
    } else if (attempt.phase === "paying") {
      attempt.phase = "unknown";
      attempt.reason = "pay_timeout";
    }
    attempt.updatedAt = this.now();
    return { ...attempt };
  }

  onReturn(payId: string): EntryResult {
    const attempt = this.findByPayId(payId);
    if (!attempt) return { ok: false, action: "query", key: null, payId, reason: "unknown_pay_id" };
    if (attempt.phase === "paid" || this.returned.has(payId)) {
      return { ok: false, action: "none", key: attempt.key, payId, reason: "duplicate_return" };
    }
    this.returned.add(payId);
    attempt.updatedAt = this.now();
    return { ok: true, action: "query", key: attempt.key, payId, reason: "returned" };
  }

  // 轮询按支付单号幂等：重复轮询只增加计数，不创建新的支付单。
  onPoll(payId: string): EntryResult {
    const attempt = this.findByPayId(payId);
    if (!attempt) return { ok: false, action: "query", key: null, payId, reason: "unknown_pay_id" };
    attempt.polls += 1;
    attempt.updatedAt = this.now();
    if (attempt.phase === "paid") {
      return { ok: false, action: "none", key: attempt.key, payId, reason: "already_paid" };
    }
    return { ok: true, action: "query", key: attempt.key, payId, reason: "polling" };
  }

  applyQuery(payId: string, view: QueryView): PayAttempt {
    const attempt = this.findByPayId(payId);
    if (!attempt) throw new Error(`支付单不存在：${payId}`);
    if (view.status === "found") return this.markPaid(payId, view.channelTxnId, view.amountCents).attempt;
    if (view.status === "not_found") {
      if (attempt.phase !== "paid") {
        attempt.phase = "failed";
        attempt.reason = "channel_not_found";
        attempt.updatedAt = this.now();
      }
      return { ...attempt };
    }
    if (attempt.phase === "paying") attempt.phase = "unknown";
    attempt.reason = "query_pending";
    attempt.updatedAt = this.now();
    return { ...attempt };
  }

  // 渠道确认入账。金额必须与支付单一致，重复回调按流水号幂等。
  markPaid(payId: string, channelTxnId: string, amountCents: number): { attempt: PayAttempt; duplicate: boolean } {
    const attempt = this.findByPayId(payId);
    if (!attempt) throw new Error(`支付单不存在：${payId}`);
    const txn = channelTxnId.trim();
    if (txn === "") throw new Error("渠道流水号不能为空");
    assertCents(amountCents);
    if (amountCents !== attempt.amountCents) {
      throw new Error(`入账金额与支付单不一致：${amountCents} != ${attempt.amountCents}`);
    }
    if (attempt.phase === "paid") {
      if (attempt.channelTxnId === txn) return { attempt: { ...attempt }, duplicate: true };
      throw new Error("同一支付单出现不同的渠道流水号");
    }
    if (this.attempts.some((item) => item.phase === "paid" && item.key !== attempt.key)) {
      throw new Error("订单已存在已支付支付单，拒绝重复入账");
    }
    const at = this.now();
    attempt.phase = "paid";
    attempt.channelTxnId = txn;
    attempt.reason = null;
    attempt.updatedAt = at;
    for (const other of this.attempts) {
      if (other.key !== attempt.key && ACTIVE.includes(other.phase)) {
        other.phase = "closed";
        other.reason = "superseded_by_paid";
        other.updatedAt = at;
      }
    }
    return { attempt: { ...attempt }, duplicate: false };
  }
}

export function openDoublePay(orderId: string, now: () => number): DoublePayGuard {
  return new DoublePayGuard(orderId, now);
}

// 进程被杀后恢复：没有拿到终态的请求一律降级为未知并等待查询。
export function resumeDoublePay(orderId: string, saved: PaySnapshot, now: () => number): DoublePayGuard {
  const id = orderId.trim();
  if (saved.orderId !== id) throw new Error("订单号不一致，不能恢复支付会话");
  const guard = new DoublePayGuard(id, now);
  guard.attempts = saved.attempts.map((attempt) => {
    const restored = { ...attempt };
    if (restored.orderId !== id) throw new Error("支付意图归属其他订单");
    if (restored.phase === "creating") {
      restored.phase = "unknown";
      restored.reason = "resumed_creating";
    } else if (restored.phase === "paying") {
      restored.phase = "unknown";
      restored.reason = "resumed_in_flight";
    }
    restored.updatedAt = now();
    return restored;
  });
  return guard;
}

$ node --test --test-concurrency=1 test/reconcile/double-pay.test.ts
✔ 新订单没有任何支付意图 (0.583833ms)
✔ 首次点击创建支付意图 (0.4745ms)
✔ 创建中重复点击被挡且不产生第二张支付单 (0.08675ms)
✔ 创建超时转为未知并禁止再次发起 (0.108125ms)
✔ 创建成功后进入支付中并保留支付单号 (0.115375ms)
✔ 支付中重复点击同样被挡 (0.075958ms)
✔ 支付超时转为未知，轮询只触发查询 (0.107416ms)
✔ 查询确认支付单不存在后可以换渠道新建 (0.101708ms)
✔ 查询命中后按支付单号入账 (0.131708ms)
✔ 重复回跳只处理一次 (0.129542ms)
✔ 重复轮询不新建支付单 (0.074458ms)
✔ 已支付后拒绝再次发起支付 (0.058958ms)
✔ 迟到的成功回调关闭其他在途支付单 (0.080375ms)
✔ 入账金额与支付单不一致时拒绝 (0.320833ms)
✔ 渠道流水号为空时拒绝入账 (0.10575ms)
✔ 同一流水重复入账是幂等的 (0.077208ms)
✔ 已支付订单不接受第二张支付单入账 (0.086834ms)
✔ 崩溃恢复时创建中的意图降级为未知 (0.116083ms)
✔ 崩溃恢复时支付中的意图保留支付单号并等待查询 (0.06175ms)
✔ 崩溃恢复保留已支付结果 (0.053ms)
✔ 未知支付单号的回跳只要求查询，不创建新单 (0.036959ms)
ℹ tests 21
ℹ suites 0
ℹ pass 21
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 158.359333