Arsitektur Database & Single Source of Truth: Modul Perdagangan

Dokumen ini menjelaskan rancangan arsitektur data (Data Architecture) pada modul Perdagangan (Trading) di dalam ERP BUMDes, yang juga mengadopsi prinsip Single Source of Truth (SSOT).

1. Single Source of Truth (SSOT) melalui Database Triggers#

Untuk mencegah terjadinya anomali data (seperti duplikasi pemotongan stok atau penjurnalan ganda), aplikasi web (Next.js / Server Actions) DILARANG KERAS melakukan operasi INSERT atau UPDATE secara langsung ke tabel accounting_journals atau inventory_stock setiap kali ada transaksi baru.

Satu-satunya tabel yang boleh di-insert oleh aplikasi saat ada aktivitas perdagangan adalah:

• trading_transactions (Tabel Induk Transaksi)
• trading_transaction_items (Tabel Rincian Barang)

Automasi Jurnal & Stok

Setelah data masuk ke trading_transaction_items, PostgreSQL Database Triggers akan secara otomatis dan sinkron menjalankan efek samping (side-effects) berikut:

1. Memotong/Menambah Stok Gudang
2. Membuat Jurnal Akuntansi (Debit/Kredit)

Karena dilakukan di level database (Supabase/PostgreSQL), konsistensi data terjamin mutlak terlepas dari seberapa lambat koneksi internet pengguna atau jika server aplikasi Next.js mengalami crash di tengah-tengah proses.

2. Pemetaan Akun Dinamis (Account Mappings)#

Agar jurnal akuntansi otomatis dapat bekerja dengan benar, modul ini menggunakan tabel pemetaan dinamis: unit_account_mappings.

Setiap unit usaha (misalnya Unit Perdagangan Hasil Bumi) harus memetakan 6 jenis Chart of Accounts (COA) dasar:

1. Akun Kas/Bank (Untuk penerimaan & pembayaran)
2. Akun Piutang (Jika pelanggan berhutang)
3. Akun Hutang (Jika BUMDes berhutang pada supplier)
4. Akun Persediaan (Nilai aset barang di gudang)
5. Akun HPP (Harga Pokok Penjualan) (Beban pokok saat barang terjual)
6. Akun Penjualan (Pendapatan atas transaksi penjualan)

Catatan Penting untuk Developer: Trigger database (seperti auto_journal_on_trading_purchase dan auto_journal_on_trading_sales) akan selalu look up ke tabel unit_account_mappings berdasarkan ID Unit. Tidak ada lagi sistem hardcode nama akun teks (string matching) di dalam fungsi SQL.

3. Pencegahan Race Condition dengan Sequences#

Nomor referensi transaksi (contoh: TRX-IN-20260608-00001) tidak lagi di-generate menggunakan UNIX Timestamp (Date.now()) pada level Node.js/Browser, melainkan di-generate langsung oleh fungsi database menggunakan objek SEQUENCE PostgreSQL.

Ini menjamin bahwa meskipun ada 10 kasir yang menginput transaksi pada milidetik yang sama, nomor urut yang dihasilkan akan selalu unik (Aman dari Race Condition).