07 — Standar & Konvensi Tim¶

Dibaca oleh: semua anggota tim, wajib, sebelum menulis kode apa pun. Tujuan: sistem tetap bisa dibaca & dipelihara siapa pun, bukan hanya pembuatnya. Inilah inti dari "agar bisa didelegasikan".

Aturan tertinggi: Kode dibaca jauh lebih sering daripada ditulis. Optimalkan untuk pembaca berikutnya — anggap dia pegawai baru yang tidak bisa bertanya ke siapa pun.

1. Standar Penamaan (tidak bisa ditawar)¶

Aturan	Benar	Salah
Bahasa Indonesia konsisten, kata lengkap	`barang`, `transaksi_detail`	`brg`, `d`, `t`
`snake_case`, huruf kecil	`nomor_transaksi`	`noTrans`, `NoTrans`
Tanpa singkatan misterius	`jenis_transaksi`	`datakode`, `kdtrans`
PK selalu `id`	`id`	`idtrans` di tabelnya sendiri
FK = `<entitas>_id`	`kontak_id`	`idktk`, `idkontak`
Boolean `is_`/sifat jelas	`is_aktif`, `pengaruh_stok`	`aktif int`, `cek`
Uang `numeric(18,2)`	`total numeric(18,2)`	`total double`
Waktu `_at timestamptz`	`created_at`, `updated_at`	`dibuat`, `aksesakhir`
Tanpa angka ajaib	`status = 'final'`	`cek = 56`

Dilarang keras: nama 1–3 huruf, SQL disimpan sebagai data, kolom multi-arti (arti berubah tergantung jenis transaksi tanpa dokumentasi).

Penemuan istilah/kolom baru → langsung dicatat di Dokumen 02 (Kamus Data).

2. Gaya SQL & PL/pgSQL¶

Kata kunci SQL huruf kecil (select, bukan SELECT) — konsisten satu gaya (tim boleh pilih, lalu paksa lewat linter, jangan campur).
Satu fungsi = satu tugas jelas. Maks. ±60 baris; lebih dari itu → pecah.
Nama fungsi = kata kerja: hitung_stok, ambil_hpp_fifo, posting_jurnal.
Wajib COMMENT ON untuk setiap tabel, fungsi, trigger: 1 kalimat — apa & kapan jalan.
Variabel lokal DECLARE — dilarang variabel sesi @x lintas statement.
Selalu COALESCE nilai yang mungkin NULL pada perhitungan uang/stok.
Fungsi idempoten bila memungkinkan (boleh dijalankan ulang tanpa merusak).
Komentar menjelaskan kenapa, bukan apa (kode sudah menjelaskan "apa").

Contoh header fungsi yang benar:

-- Hitung HPP barang keluar secara FIFO (rata-rata tertimbang lapisan terpakai).
-- Tidak mengubah data. Dipakai trigger BEFORE INSERT detail.
CREATE OR REPLACE FUNCTION logika.ambil_hpp_fifo(...) ...

3. Alur Perubahan Skema (Migrasi)¶

Tidak ada ALTER TABLE/CREATE FUNCTION manual langsung di server. Pernah.

Semua perubahan = file migrasi bernomor, di Git, di-review.
Penamaan: V<nnn>__deskripsi_singkat.sql (mis. V012__tambah_kolom_diskon.sql).
Idempoten/aman diulang bila memungkinkan.
Alat migrasi saat ini: runner psql internal database/scripts/jalankan_migrasi_tenant.sh untuk migrasi tenant bernomor di database/migrations/tenant/. Jika kelak pindah ke Flyway/dbmate, lakukan sebagai transisi resmi; jangan campur dua sistem diam-diam.
Runner menerapkan migrasi ke template + semua schema tenant + schema pusat/logika bila perlu (lihat Dokumen 04 §5). Catat versi di pusat.skema_versi.
Setiap migrasi punya pasangan uji: minimal uji asap + (untuk perubahan logika) uji rekonsiliasi pada data sampel.
Migrasi yang mengubah logika akuntansi → wajib review oleh Database Engineer senior + bukti jurnal tetap imbang.

4. Alur Git & Code Review¶

Branch per pekerjaan: fitur/..., perbaikan/..., migrasi/....
Commit message singkat, jelas, Bahasa Indonesia, jelaskan kenapa.
Wajib review sebelum merge. Minimal 1 reviewer; untuk perubahan skema/logika akuntansi: reviewer = DB Engineer.
Pull Request menyertakan: ringkasan, dampak ke tenant, rencana uji, rencana rollback (untuk migrasi).
Tidak ada push langsung ke main. Tidak ada force-push ke main.

Checklist reviewer (tempel di template PR): - [ ] Nama sesuai Standar §1 & terdaftar di Kamus (Dokumen 02)? - [ ] Ada COMMENT ON untuk objek DB baru? - [ ] Ada file migrasi bernomor + uji? - [ ] Untuk logika akuntansi/stok: ada bukti rekonsiliasi/jurnal imbang? - [ ] Tidak ada angka ajaib / SQL-as-data / variabel sesi? - [ ] Aman untuk semua tenant (bukan asumsi 1 DB)?

5. Aturan Dokumentasi (supaya tetap bisa didelegasikan)¶

Kode mendokumentasikan diri (nama jelas) + COMMENT ON untuk objek DB.
Dokumen docs/ ini hidup: setiap keputusan arsitektur baru → perbarui dokumen terkait di PR yang sama. Dokumen basi lebih berbahaya daripada tak ada.
Setiap fungsi/trigger logika inti → entri di Dokumen 05 §9.
Setiap istilah/kolom misterius yang ditemukan → Kamus Dokumen 02.
"Selesai" sebuah tugas = kode + uji + dokumen, bukan kode saja.

6. Larangan (anti-pola dari sistem lama yang TIDAK boleh diulang)¶

Jangan	Sebagai gantinya
Nama singkat (`t`,`d`,`brg`)	Nama lengkap (Dokumen 02)
ID manual `max(id)+1`	`GENERATED ALWAYS AS IDENTITY` / counter ber-lock
Angka ajaib (`cek=56`)	Kolom status/parameter bernama
SQL disimpan di kolom lalu di-`EXECUTE`	Fungsi PL/pgSQL bernama di Git
Tabel kembar baru ("barang_v3")	Perbaiki tabel kanonik + migrasi
Ubah skema manual di server	File migrasi bernomor + review
Uang pakai `double`	`numeric(18,2)`
Logika tpercecer tanpa komentar	`COMMENT ON` + entri Dokumen 05
Query lupa filter tenant (jika kelak ada model lain)	Tenant dari JWT, schema-per-tenant + pool per tenant (Dokumen 04)

7. Onboarding Anggota Tim Baru (target: produktif ≤ 1 minggu)¶

Hari 1–2 — Paham bisnis & peta: - [ ] Baca docs/README.md → 00 → 01 → 02. - [ ] Bisa menjelaskan ulang: apa itu transaksi/transaksi_detail/jenis_transaksi. - [ ] Hafal alur 1 transaksi (Dokumen 05 §2).

Hari 3–4 — Paham teknis: - [ ] Baca 03, 04, 05. - [ ] Setup lokal: PostgreSQL erp + schema tenant uji + jalankan migrasi. - [ ] Latihan: buat 1 PB & 1 PJ → buktikan stok, HPP FIFO, jurnal imbang.

Hari 5 — Kontribusi pertama: - [ ] Baca 06 & 07. - [ ] Ambil 1 tugas kecil (mis. lengkapi 1 entri Kamus / 1 sub-fungsi jurnal). - [ ] Buka PR sesuai alur §3–§4; lewati checklist reviewer.

Uji paham (ditanyakan mentor): "Stok barang X di lokasi Y minus — di mana Anda mulai mencari?" Jawaban benar menunjukkan paham bahwa stok = SUM(mutasi_stok), bukan angka yang disimpan.

8. Definisi "Selesai" (Definition of Done)¶

Sebuah pekerjaan disebut selesai hanya jika semua terpenuhi:

[ ] Kode sesuai Standar Penamaan & Gaya (§1–§2).
[ ] Objek DB baru punya COMMENT ON.
[ ] Ada file migrasi bernomor + berjalan di template & semua tenant uji.
[ ] Ada uji; untuk logika akuntansi/stok: rekonsiliasi/jurnal imbang lulus.
[ ] Dokumen terkait (docs/, Kamus, Dokumen 05 §9) diperbarui di PR yang sama.
[ ] Di-review & disetujui sesuai §4.

Jika satu pun belum → belum selesai. Tidak ada "nanti dirapikan" untuk penamaan, dokumentasi, atau data akuntansi. Itu cara sistem lama menjadi sulit diwariskan; kita tidak mengulanginya.