Kebenaran Stok: Buku Besar Pergerakan, Bukan Kolom

Suatu pagi seorang manajer cabang menelepon karena aplikasi menyebut stok tire shine kami minus tiga botol. Bukan nol, minus tiga. Angka semacam itu hanya muncul saat beberapa orang memperbarui kolom kuantitas yang sama nyaris bersamaan dan satu tulisan menimpa yang lain. Awalnya saya membangun modul inventory dengan cara paling jelas: Product.stockQty adalah integer biasa, dan setiap penjualan atau restock melakukan UPDATE yang menambah atau mengurangi nilainya. Itu jalan saat demo dan membusuk di produksi.

Perbaikannya adalah berhenti memperlakukan kuantitas sebagai nilai yang saya miliki dan mulai memperlakukannya sebagai nilai yang saya hitung. Alih-alih satu angka yang bisa diubah, saya mencatat baris yang tidak dapat diubah untuk setiap peristiwa yang mengubah stok: penjualan dua unit adalah qtyDelta minus dua, penerimaan pembelian satu karton adalah qtyDelta plus dua puluh empat. Kuantitas saat ini menjadi sekadar hasil agregasi. Ini adalah ide append-only dan event-sourced yang sama yang dipakai sistem inventory besar, dan penting memahami alasannya sebelum menirunya.

Mengapa kolom kuantitas yang bisa diubah membusuk

Sebuah integer tunggal yang bisa diubah tampak efisien, tetapi menghancurkan informasi di setiap tulisan. UPDATE yang mengubah stockQty dari sepuluh menjadi delapan hanya memberi nilai baru dan menghapus alasan, pelakunya, dan kondisi sebelumnya. Dalam pengaturan multi-cabang dan multi-terminal, itu pertukaran yang merugikan. Berikut yang dibebankan kolom yang bisa diubah kepada saya dalam praktik.

• Jejak audit hilang: begitu angka berubah, tidak ada cara bawaan untuk menanyakan bagaimana itu terjadi. Men-debug hitungan yang salah berarti menebak, karena buktinya sudah tertimpa.
• Kondisi balapan lost-update: dua siklus baca-ubah-tulis bersamaan pada baris yang sama menghasilkan hantu minus tiga, karena tulisan kedua didasarkan pada bacaan yang basi.
• Kerusakan yang tak bisa diperbaiki: jika suatu bug menulis nilai salah, nilai salah itu kini menjadi kebenaran. Tidak ada yang bisa diputar ulang dan tidak ada pembanding untuk rekonsiliasi.
• Tidak ada tempat alami untuk konteks: nomor batch, dokumen sumber, dan cabang yang memindahkan stok tidak punya tempat pada kolom skalar.

Buku besar StockMovement yang append-only

Setiap hal fisik yang memindahkan stok menulis tepat satu baris yang tidak dapat diubah. Tidak ada perintah UPDATE dan DELETE terhadap tabel ini di kode aplikasi. Setiap baris membawa qtyDelta bertanda, cabang pemiliknya, tipe pergerakan, dan referensi ke dokumen penyebabnya. Perhatikan qtyDelta adalah integer unit utuh, disiplin integer yang sama yang saya pakai untuk uang, di mana semua nominal IDR adalah integer dan tidak pernah float.

// prisma/schema.prisma
model StockMovement {
  id          String   @id @default(cuid())
  branchId    String            // every query scopes by this
  productId   String
  qtyDelta    Int               // signed: -2 sale, +24 receipt
  type        MovementType      // SALE | PURCHASE | ADJUSTMENT | TRANSFER
  refType     String            // 'Order' | 'Purchase' | 'StockOpname'
  refId       String
  createdAt   DateTime @default(now())

  product     Product  @relation(fields: [productId], references: [id])
  branch      Branch   @relation(fields: [branchId], references: [id])

  @@index([branchId, productId])   // fast per-product SUM
  @@index([branchId, createdAt])
}

model Product {
  id        String @id @default(cuid())
  branchId  String
  name      String
  stockQty  Int    @default(0)   // CACHE ONLY - derived, never trusted
}

Kuantitas otoritatif untuk sebuah produk adalah satu agregasi atas tabel itu, di-scope berdasarkan branchId persis seperti setiap query daftar dan detail lain di API. Scoping berdasarkan branchId juga merupakan perbaikan IDOR yang saya terapkan di mana-mana, sehingga terminal di satu cabang tidak akan pernah bisa membaca atau memindahkan stok cabang lain. Di Prisma, bacaannya adalah penjumlahan yang dikelompokkan.

// The source of truth: SUM(qtyDelta), never Product.stockQty
async function trueStock(branchId: string, productId: string) {
  const agg = await prisma.stockMovement.aggregate({
    where: { branchId, productId },
    _sum: { qtyDelta: true },
  });
  return agg._sum.qtyDelta ?? 0;
}

// Recording a sale is an INSERT, never an UPDATE of a quantity
await prisma.stockMovement.create({
  data: { branchId, productId, qtyDelta: -qtySold,
          type: 'SALE', refType: 'Order', refId: order.id },
});

Buku besar versus kolom yang bisa diubah, berdampingan

Pertukarannya tidak gratis. Buku besar memakan penyimpanan dan butuh cache agar tetap cepat. Berikut perbandingan jujur yang saya pakai untuk meyakinkan diri sendiri melakukan penulisan ulang.

Membangun ulang dan merekonsiliasi cache

Membaca SUM yang dikelompokkan pada setiap daftar produk akan membebani basis data, jadi Product.stockQty tetap ada, tetapi hanya sebagai cache. Ia ditulis dalam transaksi yang sama dengan insert pergerakan, dan bersifat sekali pakai. Jika suatu saat salah, buku besar membangunnya ulang. Pembangunan ulang adalah proyeksi murni: baca buku besar, tulis cache, selesai.

1. Agregasikan buku besar per produk untuk cabang, dikelompokkan berdasarkan productId dengan penjumlahan qtyDelta.
2. Bandingkan setiap total terhitung dengan Product.stockQty yang di-cache dan kumpulkan selisihnya.
3. Dalam satu transaksi, timpa setiap nilai cache yang basi dengan kebenaran terhitung dari buku besar.
4. Tulis satu baris AuditLog per produk yang dikoreksi agar rekonsiliasinya sendiri dapat dilacak.

// scripts/reconcile-stock.ts - safe to run any time, idempotent
const truth = await prisma.stockMovement.groupBy({
  by: ['productId'],
  where: { branchId },
  _sum: { qtyDelta: true },
});

for (const row of truth) {
  const computed = row._sum.qtyDelta ?? 0;
  await prisma.product.update({
    where: { id: row.productId },
    data: { stockQty: computed },      // cache := source of truth
  });
}
// Because it only ever overwrites the cache FROM the ledger,
// re-running it changes nothing once caches already match.

Deteksi drift di produksi

Karena cache secara teoretis bisa melenceng dari buku besar, saya tidak menunggu telepon untuk mengetahuinya. Sebuah job terjadwal menjalankan agregasi yang sama seperti perekonsiliasi, tetapi dalam mode baca-saja: ia membandingkan kebenaran terhitung dengan stockQty yang di-cache dan memancarkan metrik untuk produk mana pun yang berbeda. Dalam enam bulan sejak penulisan ulang, drift nyata praktis nol, dan itulah intinya. Cache kini terbukti merupakan proyeksi buku besar, dan hantu minus tiga tidak bisa kembali, karena tidak ada kuantitas bersama untuk ditimpa dua penulis. Saat drift bukan nol, peringatan memberi tahu persis produk dan cabang mana yang harus diperiksa, dan perekonsiliasi menjadikan perbaikannya operasi satu perintah alih-alih tebak-tebakan tengah malam.