Modul Domain dan Model Data

hydro-app memisahkan domain menjadi enam app Django yang terdaftar di INSTALLED_APPS: inti, akun, produk, stok, pembelian, dan laporan (backend/config/settings.py:26-45¹). Setiap model menetapkan db_table sendiri di dalam Meta, sehingga nama tabel memakai bahasa Indonesia bertanda garis bawah, bukan pola bawaan Django app_model. Model pengguna kustom ditunjuk lewat AUTH_USER_MODEL = "akun.Pengguna" (backend/config/settings.py:89²), dan kolom jejak pelaku seperti dibuat_oleh selalu memakai settings.AUTH_USER_MODEL, bukan User bawaan.

Arah ketergantungan model dijaga satu arah. App stok mengimpor Produk dan SatuanProduk milik produk (backend/stok/models.py:5³), lalu pembelian mengimpor model produk dan stok (backend/pembelian/models.py:8-9⁴). App laporan tidak punya models.py; ia hanya membaca ItemTransaksi, Retur, ReturItem, Transaksi, Produk, dan BatchProduk yang didefinisikan app lain (backend/laporan/data.py:11-14⁵).

Relasi dan kardinalitas tabel

Diagram berikut memperlihatkan kunci, arah foreign key, dan kardinalitas antartabel domain. Semua foreign key memakai on_delete=models.PROTECT, kecuali StokOpnameItem.opname yang memakai CASCADE (backend/stok/models.py:115-126⁶). Konsekuensinya, produk, satuan, batch, dan pengguna tidak bisa dihapus selama masih dirujuk baris lain. Penerapan strategi penghapusan ini terlihat pada Transaksi.pelanggan yang menunjuk Pelanggan dengan PROTECT (backend/pembelian/models.py:40-57⁷).

erDiagram
    KATEGORI ||--o{ PRODUK : "kategori"
    PRODUK ||--o{ SATUAN_PRODUK : "satuan"
    SATUAN_PRODUK ||--o{ HARGA_PRODUK : "riwayat_harga"
    PRODUK ||--o{ BATCH_PRODUK : "batch"
    SATUAN_PRODUK ||--o{ BARANG_MASUK : "diterima"
    BARANG_MASUK ||--|| BATCH_PRODUK : "barang_masuk"
    BATCH_PRODUK ||--o{ MUTASI_STOK : "mutasi"
    PELANGGAN ||--o{ TRANSAKSI : "transaksi"
    TRANSAKSI ||--o{ ITEM_TRANSAKSI : "items"
    ITEM_TRANSAKSI ||--o{ ITEM_TRANSAKSI_BATCH : "alokasi"
    BATCH_PRODUK ||--o{ ITEM_TRANSAKSI_BATCH : "alokasi"
    PERAN ||--o{ PENGGUNA : "peran"
    PENGGUNA ||--o{ TRANSAKSI : "transaksi_dibuat"

    PRODUK {
        varchar40 sku UK
        varchar160 nama
        integer kategori_id FK
        integer stok_minimum
    }
    SATUAN_PRODUK {
        integer produk_id FK
        varchar30 nama
        integer isi_botol
    }
    HARGA_PRODUK {
        integer satuan_id FK
        decimal18_2 harga
        date berlaku_mulai
    }
    BATCH_PRODUK {
        integer produk_id FK
        integer barang_masuk_id FK
        date kedaluwarsa
        integer jumlah_awal
        integer sisa
    }
    MUTASI_STOK {
        integer batch_id FK
        varchar20 jenis
        integer jumlah
        integer sisa_sesudah
    }
    TRANSAKSI {
        varchar30 nomor UK
        uuid kunci_idempoten UK
        varchar16 status
        decimal18_2 total
        decimal18_2 sisa_tagihan
    }
    ITEM_TRANSAKSI {
        integer transaksi_id FK
        integer satuan_id FK
        integer jumlah
        integer isi_botol
        decimal18_2 subtotal
    }
    ITEM_TRANSAKSI_BATCH {
        integer item_id FK
        integer batch_id FK
        integer jumlah_botol
        integer jumlah_diretur
    }
    PENGGUNA {
        varchar120 nama
        varchar30 peran_id FK
    }
%% fig: Relasi tabel domain Hydro
%% desc: Satu produk memuat banyak satuan dan batch, mutasi stok menempel ke batch, dan alokasi penjualan menghubungkan item transaksi ke batch yang dipakai.

Beberapa kardinalitas perlu dibaca lebih teliti:

• Produk menyimpan sku unik dan stok_minimum yang dihitung dalam botol (backend/produk/models.py:26-43⁸). Satu produk memiliki banyak SatuanProduk dengan related_name="satuan", dan satu satuan memiliki banyak baris HargaProduk dengan related_name="riwayat_harga".
• BatchProduk.barang_masuk adalah OneToOneField, jadi satu BarangMasuk menghasilkan tepat satu batch. BatchProduk.produk tetap disimpan terpisah agar batch bisa dibaca per produk tanpa menelusuri BarangMasuk (backend/stok/models.py:34-51⁹).
• MutasiStok hanya menunjuk batch dan menyimpan jumlah bertanda: positif untuk barang masuk, negatif untuk barang keluar, dalam botol (backend/stok/models.py:67-79¹⁰). Tujuh nilai JenisMutasi yang sah adalah masuk, penjualan, retur, rusak, kedaluwarsa, opname, dan batal (backend/stok/models.py:57-64¹¹).
• ItemTransaksiBatch berdiri di antara item dan batch. Pasangan (item, batch) unik, dan jumlah_diretur tidak boleh melebihi jumlah_botol (backend/pembelian/models.py:120-135¹²). Mekanisme yang memilih batch dan mengisi tabel ini dibahas di Stok per Batch dan Alokasi FEFO.
• Peran memakai kode sebagai primary key, dan Pengguna merujuknya lewat foreign key peran dengan PROTECT; properti izin membaca peta IZIN_PERAN berdasarkan peran_id (backend/akun/models.py:8-30¹³). Pemberian izin dan 2FA dijelaskan di Autentikasi, 2FA, dan Izin.

Constraint yang menjaga angka tetap sah

Tabel berikut memuat nama constraint yang benar-benar tertulis di kode. Hampir semuanya dipasang di Meta.constraints, jadi database ikut menolak baris yang melanggar, bukan hanya serializer.

Tiga aturan angka yang paling sering menahan kesalahan:

• Nilai isi_botol dijaga dua kali: MinValueValidator(1) di level field dan CheckConstraint bernama isi_botol_positif di level tabel (backend/produk/models.py:56-70¹⁵). Harga produk disimpan sebagai DecimalField(max_digits=18, decimal_places=2) dan dijaga harga_tidak_negatif (backend/produk/models.py:76-91¹⁶).
• BatchProduk.sisa bertipe IntegerField karena harus bisa berkurang, bukan PositiveIntegerField. Batas bawahnya dipasang sebagai constraint sisa_tidak_minus, dan BatchQuerySet.layak_jual menyaring batch dengan sisa__gt=0 serta kedaluwarsa__gte=timezone.localdate() (backend/stok/models.py:29-31²⁰).
• Transaksi menyimpan total, total_retur, dan terbayar, lalu sisa_tagihan dihitung database sebagai GeneratedField dengan db_persist=True dari total - total_retur - terbayar; properti sisa menghitung ulang nilai yang sama di memori agar aman dipakai setelah objek diubah (backend/pembelian/models.py:40-57⁷). Constraint tagihan_tidak_minus menolak baris dengan total < total_retur + terbayar (backend/pembelian/models.py:83-89¹⁸).

Properti sisa itu dipakai untuk piutang dan retur; alur lengkapnya ada di Transaksi Penjualan, Retur, dan Piutang.

⚠️ MutasiStok.sisa_sesudah hanya menyimpan hasil perhitungan saat mutasi dicatat; ia tidak dijaga constraint apa pun. Sumber kebenaran sisa stok tetap BatchProduk.sisa yang dijaga sisa_tidak_minus (backend/stok/models.py:34-51⁹). Jangan memakai sisa_sesudah sebagai dasar keputusan stok. Urutan penulisan mutasi dan penguncian batch dibahas di Mutasi Stok dan Stok Opname.

⚠️ sisa_tagihan adalah GeneratedField yang dihitung dan disimpan database. Menulis nilai ke kolom itu langsung tidak mengubah apa pun; ubah total, total_retur, atau terbayar (backend/pembelian/models.py:40-57⁷).

ItemTransaksi sengaja menyimpan salinan nama_produk, nama_satuan, isi_botol, dan harga_satuan saat transaksi dibuat, di samping foreign key ke Produk dan SatuanProduk (backend/pembelian/models.py:100-117²¹). Karena itu, mengubah nama produk atau menambah harga baru tidak menulis ulang nilai transaksi lama. Aturan riwayat harga dan satuannya dijelaskan di Produk, Satuan, dan Riwayat Harga.

Pembacaan turunan harga per tanggal

SatuanQuerySet.dengan_harga(tanggal) mengannotate setiap satuan dengan harga terbaru yang berlaku_mulai__lte tanggal tersebut, memakai Subquery berurut -berlaku_mulai dan diambil satu baris (backend/produk/models.py:46-53²²). Daftar produk memakainya di dalam Prefetch("satuan", SatuanProduk.objects.dengan_harga(hari_ini)) (backend/produk/views.py:67-73²³). Nilai harga hasil annotate ini data turunan, bukan kolom tabel, jadi tidak pernah masuk citations constraint harga_produk.

Nomor dokumen dan kunci idempoten

Nomor dokumen tidak memakai sequence per tabel, melainkan satu baris NomorUrut per awalan. Fungsi nomor_berikutnya melakukan get_or_create pada kunci, mengambil ulang baris dengan select_for_update(), menaikkan terakhir, lalu mengembalikan f"{awalan}-{baris.terakhir:0{lebar}d}" dengan lebar bawaan 4. Docstring-nya menegaskan fungsi ini harus dipanggil di dalam transaksi database (backend/inti/models.py:12-18²⁴). Tabel nomor_urut dibuat pada migration pertama app inti (backend/inti/migrations/0001_initial.py:14-23¹⁹).

graph LR
    BM["stok.layanan.catat_barang_masuk"] --> N["nomor_berikutnya(awalan, lebar)"]
    TRX["pembelian.layanan.buat_transaksi"] --> N
    N --> L["NomorUrut.select_for_update()"]
    L --> DB[("nomor_urut")]
    style BM fill:#2d7d46,color:#fff
    style TRX fill:#2d7d46,color:#fff
    style N fill:#f59e0b,color:#000
    style L fill:#f59e0b,color:#000
    style DB fill:#336791,color:#fff
%% fig: Nomor dokumen berurutan per awalan
%% desc: Barang masuk dan transaksi meminta nomor ke abstraksi NomorUrut, yang mengunci satu baris nomor_urut sebelum menaikkan nilai terakhir.

Pemanggil memilih awalan dan lebar sendiri. stok.layanan.catat_barang_masuk memakai nomor_berikutnya(f"BM-{tanggal:%Y%m%d}", 3) sehingga nomor barang masuk berbentuk BM-20260101-001 (backend/stok/layanan.py:66²⁵). pembelian.layanan.buat_transaksi memakai nomor_berikutnya(f"TRX-{tanggal:%Y%m%d}") tanpa argumen lebar, sehingga lebar yang dipakai adalah 4 (backend/pembelian/layanan.py:119-120²⁶).

Di sisi transaksi penjualan, pengulangan request ditahan oleh kunci_idempoten, sebuah UUIDField unik dengan default=uuid.uuid4 dan editable=False (backend/pembelian/models.py:40-57⁷). Kolom ini yang membuat satu penekanan tombol dua kali tidak menjadi dua transaksi; penanganannya dijelaskan di Transaksi Penjualan, Retur, dan Piutang.

Kebiasaan yang konsisten di seluruh model

• Setiap Meta menetapkan db_table eksplisit, misalnya satuan_produk dan item_transaksi_batch (backend/produk/models.py:56-70¹⁵, backend/pembelian/models.py:120-135¹²).
• Setiap tabel transaksi mengurutkan bawaan lewat ordering menurun pada waktu dibuat, misalnya ["-dibuat_pada", "-id"] untuk mutasi_stok (backend/stok/models.py:67-79¹⁰).
• dibuat_oleh selalu non-null kecuali pada HargaProduk yang membolehkan null=True (backend/produk/models.py:76-91¹⁶), dan seluruh field itu memakai settings.AUTH_USER_MODEL yang berujung ke akun.Pengguna (backend/config/settings.py:89²).
• Perubahan stok tidak disimpan sebagai kolom biasa di Produk; sisa hidup di BatchProduk dan jejaknya di MutasiStok (backend/stok/models.py:34-51⁹). Cara membacanya lewat laporan ada di Laporan dan Ekspor Berkas.