1. Mencegah Double Invoice di Sistem ERP: Dual-Layer Atomic Database Locking, Heartbeat, dan Point-of-No-Return Guard

Dalam membangun sistem Payment Orchestration yang terintegrasi langsung dengan sistem Core ERP, tantangan terbesar bukanlah sekadar menerima pembayaran, melainkan menjamin bahwa satu pembayaran yang sah hanya menghasilkan tepat satu faktur (invoice) dan satu jurnal pelunasan di ERP—tidak peduli seberapa buruk kondisi jaringan atau seberapa sering Payment Gateway mengirimkan webhook duplikat.

Masalah menjadi jauh lebih kompleks ketika kita berhadapan dengan dua kenyataan di lapangan:

1. Webhook Callback Masuk Berbarengan dengan Scheduler: Payment Gateway mengirimkan retry webhook hampir bersamaan dengan proses polling scheduler internal yang sedang memeriksa status transaksi.
2. Eksekusi RPC Core ERP Berjalan Sangat Lama: Rantai pembuatan invoice hingga pelunasan jurnal di Core ERP melibatkan beberapa panggilan Remote Procedure Call (RPC) berurutan yang pada jam sibuk bisa memakan waktu lebih dari 200 detik (3+ menit).

Jika kita hanya menggunakan in-memory lock sederhana atau pengecekan if (status === 'PENDING'), sistem akan gagal saat dijalankan pada lebih dari satu worker atau saat proses RPC mengalami timeout di tengah jalan.

Artikel ini membedah bagaimana saya merancang arsitektur Dual-Layer Atomic Database Locking beserta Point-of-No-Return Guard dan Active Lock Heartbeat untuk menyelesaikan masalah ini secara tuntas.

1. Anatomi Masalah: Mengapa Lock Biasa Gagal?

Di lingkungan produksi dengan trafik tinggi, terdapat tiga skenario kritis yang menyebabkan mekanisme penguncian standar gagal mencegah duplikasi:

Skenario A: Race Condition Antara Webhook vs Inquiry Scheduler

Ketika pengguna baru saja membayar, Payment Gateway menembakkan webhook ke endpoint kita. Pada detik yang sama persis, background cron job juga mengambil transaksi yang sama. Tanpa koordinasi atomik di tingkat database, kedua proses lolos pengecekan awal dan memicu pembuatan dua invoice berbeda di Core ERP.

Skenario B: False-Positive Stale Lock Akibat ERP Lambat (200+ Detik)

Untuk mencegah deadlock jika server crash saat memegang lock, setiap mekanisme lock harus memiliki batas waktu kedaluwarsa (stale lock timeout), misalnya 3 menit.
Masalahnya: ketika beban Core ERP sedang tinggi, rangkaian panggilan RPC bisa memakan waktu 200 hingga 240 detik. Jika batas stale lock adalah 180 detik, maka pada detik ke-181 proses lain akan mengira proses pertama sudah mati (crash), lalu mengambil alih lock dan memanggil pembuatan invoice sekali lagi padahal proses pertama masih bekerja!

Skenario C: Ambiguitas Timeout ("Apakah ERP Sudah Membuat Invoice atau Belum?")

Bayangkan backend mengirim perintah RPC createInvoice ke Core ERP. Di detik ke-60, koneksi jaringan terputus (socket hang up) sebelum nomor invoice sempat diterima dan disimpan ke database lokal.
Sebenarnya, di sisi Core ERP invoice tersebut sudah berhasil terbuat. Jika proses retry berikutnya langsung memanggil createInvoice lagi karena melihat kolom nomor invoice di database lokal masih kosong (null), maka akan tercipta invoice duplikat di Core ERP.

2. Arsitektur Solusi: Dual-Layer Atomic Locking

Untuk mengatasi ketiga skenario di atas sekaligus, saya memisahkan mekanisme penguncian menjadi dua lapisan independen di database PostgreSQL menggunakan operasi atomic conditional update:

1. Layer 1: Transaction Lock — Melindungi mutasi status transaksi dengan Exponential Backoff + Jitter dan Ownership Validation.
2. Layer 2: Invoice ERP Lock — Melindungi eksekusi rantai RPC ke Core ERP dengan Active Heartbeat dan Permanent Attempted Flag.

3. Desain Lapisan 1: Atomic Lock dengan Jitter & Ownership Validation

Pada lapisan pertama, kita memanfaatkan sifat atomik dari klausa UPDATE ... WHERE di database relasional. Saat dua proses mengeksekusi query secara bersamaan, PostgreSQL menjamin hanya satu proses yang berhasil mengubah baris tersebut (affectedRows === 1).

Selain itu, ada dua mekanisme penting yang saya tambahkan:

1. Exponential Backoff + Random Jitter: Jika proses gagal mendapatkan lock pada percobaan pertama, proses tidak langsung memborbardir database, melainkan menunggu dengan jeda eksponensial ditambah angka acak (jitter) untuk mencegah efek thundering herd.
2. Validasi Kepemilikan (Ownership Validation) Saat Release: Saat melepas lock, klausa WHERE wajib memeriksa locked_by = currentOwnerId. Ini mencegah skenario berbahaya di mana Proses A yang sempat hang terlalu lama tiba-tiba bangun dan menghapus lock yang sudah diambil alih secara sah oleh Proses B.

// Prototype Konseptual: Atomic Database Lock dengan Jitter & Ownership Check
async function acquireResourceLock(
  id: string,
  ownerId: string,
  maxRetries = 5,
): Promise<boolean> {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    const staleCutoff = new Date(Date.now() - 3 * 60 * 1000); // 3 menit

    // Atomic conditional update di level database
    const result = await db.orders.updateMany({
      where: {
        id,
        OR: [
          { isLocked: false },
          { isLocked: true, updatedAt: { lt: staleCutoff } }, // Ambil alih jika lock macet
        ],
      },
      data: { isLocked: true, lockedBy: ownerId, updatedAt: new Date() },
    });

    if (result.count === 1) return true;

    // Exponential Backoff + Random Jitter (Max 2 detik)
    const backoff = Math.min(
      200 * Math.pow(2, attempt - 1) + Math.random() * 200,
      2000,
    );
    await sleep(backoff);
  }
  return false;
}

async function releaseResourceLock(id: string, ownerId: string): Promise<void> {
  // Hanya lepas lock jika proses ini masih menjadi pemilik sah!
  await db.orders.updateMany({
    where: { id, lockedBy: ownerId },
    data: { isLocked: false, lockedBy: null },
  });
}

4. Desain Lapisan 2: Point-of-No-Return Guard & Active Heartbeat

Untuk menangani panggilan RPC ke Core ERP yang bisa berjalan lebih dari 200 detik, saya merancang tiga pengaman khusus pada tabel tagihan (BillingRecord):

A. Encoding Metadata Percobaan Permanen

Sebelum mengeksekusi panggilan RPC pembuatan invoice ke Core ERP, kita menuliskan penanda Point-of-No-Return ke dalam kolom metadata dengan format: ATTEMPTED-{workerId}-r{retryCount}-t{timestamp}

Ketika fungsi releaseLock dipanggil di blok finally (misal karena terjadi network timeout di tengah jalan), status isLocked memang dikembalikan menjadi false, tetapi string metadata ATTEMPTED-... sengaja dipertahankan (tidak dihapus)!

Dengan mempertahankan jejak tersebut lintas proses, worker berikutnya yang membaca record ini dapat mengevaluasi dua aturan:

• Cooldown Period (10 Menit): Jika percobaan terakhir baru saja terjadi kurang dari 10 menit yang lalu, tahan proses retry untuk memberi waktu bagi Core ERP menyelesaikan antrean internalnya.
• Max Retry Cap (5x Percobaan): Jika sudah pernah dicoba sebanyak 5 kali dan tetap gagal mendapatkan nomor invoice, hentikan retry otomatis dan tandai untuk pemeriksaan manual agar tidak memicu duplikasi di Core ERP.

B. Active Lock Heartbeat (withHeartbeat)

Agar proses RPC yang masih aktif bekerja selama 200+ detik tidak dianggap stale (macet) oleh cron job lain, eksekusi RPC dibungkus dengan heartbeat timer yang menyegarkan kolom updatedAt setiap 60 detik:

// Prototype Konseptual: Active Heartbeat & Persistent Attempt Guard
async function executeWithHeartbeat<T>(
  recordId: string,
  task: () => Promise<T>,
): Promise<T> {
  // Perbarui timestamp setiap 60 detik selama task utama masih berjalan
  const timer = setInterval(() => {
    db.billings
      .update({ where: { id: recordId }, data: { updatedAt: new Date() } })
      .catch(() => {});
  }, 60_000);

  try {
    return await task();
  } finally {
    clearInterval(timer);
  }
}

5. Pelajaran Utama (Key Takeaways)

1. Gunakan Database-Level Atomic Lock untuk Arsitektur Multi-Worker:
   Operasi updateMany dengan klausa kondisi state dan batas waktu stale memberikan jaminan mutual exclusion langsung di tingkat PostgreSQL tanpa bergantung pada memori satu proses aplikasi.
2. Jangan Pernah Melepas Lock Tanpa Memeriksa Pemiliknya (Lock Ownership):
   Selalu sertakan identitas worker (lockedBy: ownerId) pada klausa WHERE saat melepas lock agar proses yang terlambat selesai tidak merusak lock milik proses baru.
3. Pasang Heartbeat untuk Operasi Eksternal Berdurasi Panjang:
   Jika downstream system Anda bisa memakan waktu menit untuk merespons, kombinasikan stale lock timeout dengan periodic heartbeat refresh agar tidak terjadi pengambilalihan lock prematur.
4. Pisahkan Status Lock Sementara dari Riwayat Percobaan Permanen:
   Mempertahankan metadata ATTEMPTED-r{count}-t{time} setelah lock dilepas adalah kunci untuk menerapkan cooldown dan batas retry yang aman lintas proses.

Pada Part 2 dari seri portofolio ini, kita akan membedah bagaimana saya mengoptimalkan query pencarian dan laporan transaksi dari Sequential Scan + Subquery EXISTS menjadi pencarian milidetik menggunakan kombinasi PostgreSQL GIN Trigram Index (pg_trgm), Pre-Lookup Relasi O(1), dan Case-Variant B-Tree Matching.