Chapter 4 — Development Conventions (v2 — Final)

Status: 🔒 Mengikat · Rumah: 1_BMP_Blueprint Pasangan: Data Model v1.5 (skema) · Blueprint Ch.3 (arsitektur) · UI Reference (pola)

4.0 Prinsip

1. Konvensi dipaksakan tooling, bukan ingatan — compiler, Credo, Dialyzer, CI. Yang tak bisa dicek otomatis, ditulis sebagai doctest.
2. Zero custom libraries — logika bisnis hidup di Ash domain; stack tunduk hierarki dependency Chapter 3 §10.
3. Dokumentasi = test — setiap @doc aksi publik wajib punya doctest; doc yang tidak berjalan adalah doc yang berbohong.
4. Satu aturan, satu rumah — pola UI di UI Reference; skema di Data Model; arsitektur di Blueprint. Komentar kode merujuk dokumen, tidak menduplikasi.
5. Keamanan tiga lapis, tiga rumah (v2) — Cloak (at-rest) + Ash.Policy.Authorizer (aksi) + konfigurasi workspace (visibilitas UI). Hide UI ≠ security.
6. Ledger immutabel = source of truth (v2) — derived state (bins, closing) selalu rebuildable; tidak ada write langsung.

4.1 Coding Standard & Naming

4.2 Struktur Folder per-Domain (diisi v2)

lib/bmp/<domain>/            # satu folder per bounded context
  resources/  actions/  policies/  events/  reports/
lib/bmp_web/components/      # komponen bersama (kontrak compile-time)
lib/bmp_web/<domain>/        # LiveView per modul — TIPIS, tanpa logika bisnis
priv/repo/migrations/        # migrasi Ash + bump schema_version
priv/static/fonts/           # Inter .woff2 (bundle lokal)
priv/print_templates/        # template XML Tincture per dokumen
priv/print_templates/fiscal/ # template fiskal Bahasa Indonesia (§4.13)
agent/                       # crate Rust sync-agent — DI LUAR app Ash

Aturan:

1. Folder domain = satu-satunya rumah logika bisnis; bmp_web hanya presentasi.
2. Lintas domain = public actions + events, tidak pernah import resource domain lain langsung.
3. agent/ tidak boleh memanggil aksi Ash; mutasi replikasi aman di level constraint (Invarian #6).

4.3 Generator (mix task)

1. mix bmp.gen.resource Domain Name --archival --cloak=f1,f2 --ledger
2. mix bmp.gen.report Domain Name · mix bmp.gen.event Domain Name
3. Output generator: UUID pk, timestamps, stub policy, stub doctest, migrasi dengan bump schema_version. Generator adalah penjaga konvensi pertama.

4.4 Testing Strategy & CI/CD

Debug: LiveDebugger (dev-only) + Phoenix.LiveView.Debug (production, read-only).

4.5 Migration Strategy & Versioning

1. Migrasi hanya via Ash; tanpa SQL manual di production.
2. Setiap migrasi menaikkan schema_version (kontrak sync-agent); agent menolak koneksi bila versi node tidak cocok.
3. Urutan upgrade: server kantor dulu, baru laptop — sync berhenti sementara, tidak corrupt.
4. Non-destruktif untuk tabel finansial: tambah kolom nullable dulu; "hapus" = AshArchival, tidak pernah DROP data (retensi 10 tahun).
5. Tanpa DDL runtime: dimensi akuntansi custom = kolom terdefinisi kode per instalasi, terversioning (menolak "unlimited" ERPNext).
6. Business rule kritikal sebagai CHECK constraint SQLite (qty >= 0, amount > 0) — last line of defense replikasi (Invarian #6).
7. Pragma wajib per node: journal_mode=WAL; busy_timeout=5000 (Addendum Chapter 3).
8. Versioning app = SemVer; changelog ditulis sebagai dokumentasi.

4.6 Release

1. Single binary (Burrito); font, ikon (Lucide SVG), dan library pure-BEAM (tincture, eqrcode, exceed, nimble_csv) ter-bundle — nol CDN, nol binary eksternal.

4.7 Extension SDK

1. Permukaan publik = hanya public actions + events per domain. Modul komunitas (Chapter 8) menumpang lewat situ, tidak pernah write langsung ke resource core.
2. Boundary dipaksakan di CI: Dialyzer + Credo custom check (SDK compliance).

4.8 Documentation Standard

1. @moduledoc setiap resource memuat: mesin apa, rujukan silang (Data Model §x, UI Reference §y), invarian.
2. Log keputusan per chapter (pola v9 §9): siapa/kapan/kenapa.
3. Penanda status konsisten dengan Peta Menu & Data Model: 🔒 terkunci · 👁️ hide · ❌ buang.

4.9 Bahasa & Lokalisasi (baru v2)

1. Satu bahasa untuk sistem: English. Kode, identifier, komentar, string UI, serta istilah teknis & proper noun (Ash, Phoenix, Oban, Tincture, Sales Order, Delivery Note, Work Order, Batch, Submit, Settings, Background Job, Error Log, dll.) tidak diterjemahkan. Ash tetap Ash, bukan "Abu".
2. Tanpa lapisan i18n/Gettext. Satu istilah, satu arti, di semua tempat: developer membaca Bmp.Sales.SalesOrder, user melihat "Sales Order", dokumen menulis "Sales Order".
3. Bahasa Indonesia hanya untuk prosa naratif — dokumen alasan (BMP-Kenapa.md), pesan bantuan panjang, komunikasi internal — dengan terminologi tetap English.
4. Pengecualian karena undang-undang: output fiskal untuk otoritas wajib Bahasa Indonesia — lihat §4.13.
5. Rationale: terjemahan menghilangkan distingsi (English punya Brown & Chocolate; Indonesia hanya "coklat"), dan tanpa glossary terjemahan mesin melahirkan "Kopi" untuk Copy — menu warung, bukan editor.

4.10 Uang, Presisi & Waktu (baru v2)

1. Uang via AshMoney; tampilan & total dokumen = Rupiah bulat (tanpa desimal); rate satuan internal s.d. 4 desimal; selisih pembulatan → akun Round Off.
2. conversion_factor = 9 desimal (konversi UOM).
3. Waktu disimpan UTC; posting_date (date) + posting_time (time); UI render Asia/Jakarta; tidak ada timezone per-user untuk tanggal fiskal.

4.11 ID, Numbering Series & Event Payload (baru v2)

1. UUID pk di semua tabel; UUIDv7 untuk tabel ledger/transaksi (time-ordered, lokalitas index SQLite).
2. Numbering series terdefinisi kode per instalasi (tanpa DDL runtime): SO-SHOPEE-2026-W32, BLG-2026-001, dll. Dokumen cancel menyimpan nomornya (tidak dipakai ulang).
3. Payload event membawa ID + fakta immutabel minimal; konsumen yang butuh data lengkap membaca via public action (tanpa salinan basi di payload).

4.12 Error, Logging & Async Jobs (baru v2)

1. Taksonomi error: validation (inline) · domain (toast actionable) · infra (System Console + Sentry).
2. Telemetry event bernama bmp.<domain>.<entity>.<action>.
3. Log sanitizer: field ter-Cloak (margin/COGS, payroll, bank, resep, PII) tidak pernah muncul di log/telemetry/Sentry.
4. Async jobs (Oban/Broadway/AshOban sesuai Ch.3 §2): semua job idempoten; job membawa ID dan membaca data terkini saat run; scheduled job terdaftar di satu manifest dan tampil di System Console.

4.13 Laporan Fiskal & Template Output Bahasa Indonesia (baru v2)

Aturan:

1. Output fiskal = laporan wajib Bahasa Indonesia menurut UU KUP Pasal 28 ayat (2) & lampiran SPT Badan: Laporan Posisi Keuangan (Neraca), Laporan Laba Rugi, Laporan Arus Kas, Neraca Saldo, Buku Besar, Bukti Potong PPh. Faktur Pajak mengikuti format standar DJP (BMP hanya memasok data).
2. Semua output fiskal dirender dari template Tincture di priv/print_templates/fiscal/*.xml — terversioning, tanpa eksekusi kode; perubahan template = perubahan dokumen (wajib changelog).
3. Seluruh string template diambil hanya dari Glosarium Fiskal (bawah). Tidak ada string Indonesia hard-coded di kode; CI mengeceknya (§4.4).
4. CoA account_name wajib diisi Bahasa Indonesia ("Beban Marketplace Fee"); account_number = kode angka. Nama internal/kode tetap English.
5. Angka: Rupiah penuh, bulat, pemisah ribuan titik; kepala memuat "(Dalam Rupiah penuh, kecuali dinyatakan lain)".
6. Export xlsx lampiran SPT (via exceed) memakai header kolom yang sama persis dengan template print — satu glosarium, dua wujud.
7. CI: smoke-render semua template fiskal per build; gagal bila placeholder tak terisi atau string di luar glosarium.

Kepala & kaki bersama (semua template):

{NAMA_PERUSAHAAN}
{ALAMAT_LENGKAP}
NPWP : {NPWP}
──────────────────────────────────────────────
{JUDUL_LAPORAN}   ← uppercase, dari glosarium
{PERIODE}         ← "Per 31 Desember 2026" / "Untuk Tahun yang Berakhir 31 Desember 2026"
(Dalam Rupiah penuh, kecuali dinyatakan lain)

Kaki: Dicetak dari BMP : {tanggal} {pencetak} · Halaman {n} dari {N} · blok tanda tangan: Disusun oleh, (______) {Nama – Finance} · Mengetahui, (______) {Nama – Owner}

Template 1 — LAPORAN POSISI KEUANGAN (NERACA) (invarian: TOTAL ASET = TOTAL LIABILITAS DAN EKUITAS)

ASET
ASET LANCAR
  Kas dan Setara Kas                          {n}
  Piutang Usaha                               {n}
  Persediaan                                  {n}
  Pajak Dibayar di Muka                       {n}
TOTAL ASET LANCAR                             {n}
ASET TIDAK LANCAR
  Aset Tetap                                  {n}
  Akumulasi Penyusutan                       ({n})
TOTAL ASET TIDAK LANCAR                       {n}
TOTAL ASET                                    {n}

LIABILITAS DAN EKUITAS
LIABILITAS JANGKA PENDEK
  Utang Usaha                                 {n}
  Utang Pajak                                 {n}
  Pendapatan Diterima di Muka                 {n}
TOTAL LIABILITAS JANGKA PENDEK                {n}
LIABILITAS JANGKA PANJANG                     {n}
TOTAL LIABILITAS                              {n}
EKUITAS
  Modal Disetor                               {n}
  Laba Ditahan                                {n}
  Laba (Rugi) Berjalan                        {n}
TOTAL EKUITAS                                 {n}
TOTAL LIABILITAS DAN EKUITAS                  {n}

Template 2 — LAPORAN LABA RUGI DAN PENGHASILAN KOMPREHENSIF LAIN

PENDAPATAN USAHA                              {n}
BEBAN POKOK PENJUALAN                        ({n})
LABA KOTOR                                    {n}
BEBAN OPERASIONAL
  Beban Marketplace Fee                       {n}
  Beban Komisi Reseller                       {n}
  Beban Diskon Penjualan                      {n}
  Beban Promosi                               {n}
  Beban Gaji dan Kesejahteraan                {n}
  Beban Penyusutan                            {n}
  Beban Umum dan Administrasi                 {n}
TOTAL BEBAN OPERASIONAL                      ({n})
LABA OPERASIONAL                              {n}
PENDAPATAN (BEBAN) LAIN-LAIN                  {n}
LABA SEBELUM PAJAK                            {n}
BEBAN PAJAK PENGHASILAN                      ({n})
LABA BERSIH                                   {n}

Template 3 — LAPORAN ARUS KAS (metode tidak langsung) (invarian: KAS AKHIR = saldo akun Bank+Cash di Neraca)

ARUS KAS DARI AKTIVITAS OPERASI
  Laba Bersih                                 {n}
  Penyesuaian: Beban Penyusutan               {n}
  Perubahan Piutang Usaha                    ({n}/{n})
  Perubahan Persediaan                       ({n}/{n})
  Perubahan Utang Usaha & Pajak               {n}
KAS BERSIH DARI OPERASI                       {n}
ARUS KAS DARI AKTIVITAS INVESTASI
  Perolehan Aset Tetap                       ({n})
KAS BERSIH DARI INVESTASI                    ({n})
ARUS KAS DARI AKTIVITAS PENDANAAN
  Setoran Modal                               {n}
KAS BERSIH DARI PENDANAAN                     {n}
KENAIKAN (PENURUNAN) BERSIH KAS               {n}
KAS DAN SETARA KAS AWAL PERIODE               {n}
KAS DAN SETARA KAS AKHIR PERIODE              {n}

Template 4 — NERACA SALDO

Template 5 — BUKU BESAR (satu akun per blok)

Kepala blok: {KODE} — {NAMA AKUN}

Template 6 — BUKTI POTONG PPh 23 (mengikuti struktur e-Bupot; sumber: tax_withholding_entries + purchase_invoices)

Glosarium Fiskal — sumber string tunggal (§4.13-G)

Changelog v2 (vs docx v1)

• 4.0 +2 prinsip (keamanan 3 lapis; ledger immutabel).
• 4.1 baris Bahasa → dirujuk ke §4.9 (keputusan satu bahasa).
• 4.2 diisi (sebelumnya kosong).
• 4.4 +3 lapis test (sync idempotensi, smoke-render fiskal, invarian Neraca).
• 4.9–4.12 baru: Bahasa & Lokalisasi · Uang/Presisi/Waktu · ID/Series/Event · Error/Logging/Async.
• 4.13 baru: laporan fiskal Bahasa Indonesia + 6 template + Glosarium Fiskal (wajib UU KUP Pasal 28 ayat 2).