系統設計

1type Entry = { paymentId: string; account: string; debit: number; credit: number };
2 
3interface Provider {
4  // Charges once per key, however often it is asked.
5  charge(key: string, amount: number): void;
6}
7 
8class PaymentService {
9  private intents = new Map<string, { amount: number; paymentId?: string }>();
10  private running = new Set<string>(); // live claims, separate from persisted intents
11  ledger: Entry[] = [];
12  outbox: { paymentId: string; sent: boolean }[] = [];
13 
14  constructor(private provider: Provider) {}
15 
16  pay(key: string, amount: number): string {
17    const intent = this.intents.get(key);
18    if (intent && intent.amount !== amount) throw new Error("idempotency key used with a different amount");
19    if (intent?.paymentId) return intent.paymentId;
20    if (this.running.has(key)) throw new Error("payment in progress");
21    // Production: an atomic DB claim; ledger and outbox also have unique payment IDs.
22    this.intents.set(key, intent ?? { amount });
23    this.running.add(key);
24    try {
25      const paymentId = "pay_" + key;
26      this.provider.charge(key, amount);
27      const fee = Math.round(amount * 0.029) + 30;
28      // One database transaction: ledger lines, outbox row, stored result.
29      this.ledger.push(
30      { paymentId, account: "psp_clearing", debit: amount, credit: 0 },
31      { paymentId, account: "merchant_payable", debit: 0, credit: amount - fee },
32      { paymentId, account: "fee_revenue", debit: 0, credit: fee },
33      );
34      this.outbox.push({ paymentId, sent: false });
35      this.intents.set(key, { amount, paymentId });
36      return paymentId;
37    } finally {
38      this.running.delete(key); // failed attempt stopped; preserve its intent for recovery
39    }
40  }
41 
42  relay(publish: (paymentId: string) => void): void {
43    for (const row of this.outbox) {
44      if (row.sent) continue;
45      publish(row.paymentId);
46      row.sent = true;
47    }
48  }
49}
50 
51function reconcile(ledger: Entry[], settlement: { paymentId: string; amount: number }[]): string[] {
52  const booked = new Map<string, number>();
53  for (const e of ledger) {
54    if (e.account === "psp_clearing") booked.set(e.paymentId, (booked.get(e.paymentId) ?? 0) + e.debit);
55  }
56  const captured = new Map<string, number>();
57  for (const s of settlement) captured.set(s.paymentId, (captured.get(s.paymentId) ?? 0) + s.amount);
58  const problems: string[] = [];
59  for (const [paymentId, amount] of captured) {
60    if (booked.get(paymentId) !== amount) problems.push(paymentId);
61  }
62  return problems;
63}