BMP

Business Management Platform

Project Blueprint & Design Documentation

Dokumen Gabungan — v2.3

Table of Contents

Introduction 11

Peta Keseluruhan & Status 11

Dua “Architecture” yang Berbeda Level 12

Urutan Pengerjaan 12

Latar Belakang — Analisis 12 ERP Open Source 12

Chapter 1: Design Foundation 14

1.1 Theme 14

1.2 Color System 15

1.3 Typography 16

1.4 Iconography 17

1.5 Shadow & Elevation System (baru) 18

1.6 Spacing, Radius & Grid (baru) 19

1.7 Contoh Penerapan 21

1.8 Tiga Prinsip Meta Visual 22

Chapter 2: Interaction Structure 23

2.1 Landing Page & Layout 23

2.1.1 Rail Sidebar (atas → bawah) 24

2.1.2 Header (page-head 44px) 24

2.1.3 Isi Landing (My Attention) 24

2.1.4 Perilaku Icon Sync (5 State) 25

2.2 List / Table View 26

2.2.1 Prinsip Pengorganisasian 26

2.2.2 Elemen List 26

2.3 Navigation & Information Structure 27

2.3.1 Hierarki Halaman (3 Tingkat) 28

2.3.2 Peta Gestur → Efek 28

2.3.3 Pembagian Peran Penanda 28

2.3.4 Struktur Flyout 28

2.3.5 Pola Sidebar (Final: Flat + Trigger Klik) 29

2.3.6 Keselamatan Gestur 29

2.3.7 Global Navigation vs Local Navigation 29

2.3.8 Lima Hal Spesifik Navigasi ERP/BMP 30

2.4 Form & Detail View 31

2.4.1 Prinsip Pengorganisasian 31

2.4.2 Conditional Field vs Progressive Disclosure 33

2.5 Search & Command Palette 33

2.5.1 Dua Mode Pemicu 33

2.5.2 Hasil Pencarian 33

2.5.3 Empty State & Halaman Alat 33

2.6 Notification & Approval Workflow 34

2.6.1 Feed "My Attention" 34

2.6.2 Pola Fork-Join Checker Lintas Divisi 35

2.7 Personalization & Account Model 35

2.7.1 Model Akun, bukan Persona Gabungan 36

2.7.2 Admin vs Business Home 36

2.8 Consistency Patterns 37

2.9 Responsive & Usage Context 38

2.10 Konvensi Bahasa UI Sistem 39

2.11 Tangga Intensitas Overlay (5 Level) 39

2.12 Kamus 12 Aturan BMP (dari Studi Kasus ERPNext v16) 40

2.13 Pola Keyboard, Touch & A11y 40

2.13.1 Peta Keyboard Global 40

2.13.2 Touch, Focus & Guard 41

2.14 Studi Kasus: Anti-Pattern ERPNext v16 41

Temuan #1 — Search Modal Gelap 41

Temuan #2 — Load More di List Bisnis 41

Temuan #3 — Sidebar Campur Domain 41

Temuan #4 — Launcher Menyamakan Kategori 41

Temuan #5 — Breadcrumb Tidak Konsisten 41

Temuan #6 — Slot Primary untuk Navigasi 41

Temuan #7 — Halaman Alat Kosong Mati 41

Temuan #8 — Ornamen Konsumer di List 42

Temuan #9 — Label Navigasi Truncate 42

Temuan #10 — Flag Teknis di List Bisnis 42

Temuan #11 — Suffix Company 42

Temuan #12 — Dropdown Campur Jenis 42

Catatan Implementasi Teknis Chapter 2 42

Log Keputusan Final (dari 3 Konflik Hasil Penggabungan) 43

Chapter 3: Architecture 44

3.0 Architecture Invariants 44

3.1 Fondasi: Phoenix — Ash — Event-driven 45

3.2 Async & Data Processing 45

3.3 Architecture Mapping untuk UI/UX System 45

3.4 Performance Budget & Caching Strategy 46

3.5 Cloak & Pemisahan Tanggung Jawab IT 47

3.6 Data Layer — Full SQLite 47

3.6.1 Search Engine: FTS5 (Full-Text Search 5) 47

3.6.2 Pagination: Offset/Limit Optimization 48

3.7 Audit, Retensi & Kepatuhan (final) 48

3.8 Ledger Khusus 48

3.9 Cache & State 48

3.10 Real-time Event Architecture untuk UI 49

3.11 Observability, I18n, Storage 49

3.12 Asset Pipeline & Offline Bundle 50

3.13 Testing & Static Analysis 50

3.14 Deployment Profiles 51

Peran node di Profile 2 51

3.15 Hierarki Pemilihan Dependency (kebijakan resmi) 52

Addendum: Mekanisme Sync-Agent — Penjelasan Detail 53

1. Gambaran Besar 53

2. Komponen Utama 53

2.1 Session Manager 53

2.2 Flush Scheduler 53

2.3 Transport Layer 53

2.4 Apply Engine 54

2.5 State Manager 54

2.6 Telemetry Publisher 54

3. Alur Lengkap: Laptop ke Server Kantor 54

Fase 1 — Capture 54

Fase 2 — Flush 54

Fase 3 — Transport 54

Fase 4 — Apply di Server 54

Fase 5 — Konfirmasi & State Update 55

Fase 6 — Sync Balik (Server → Laptop) 55

4. Conflict Resolution 55

5. Failure Mode & Recovery 55

6. Catatan Penting Operasional 55

Penguatan (v2.0) — konteks offline-first UI: 56

Anchor ID — Deteksi Konflik Non-LWW (v2.0): 56

Chapter 4: Data Model & Table Specifications 57

4.1. Master Data 57

4.1.1 companies 57

4.1.2 accounts (Chart of Accounts) 58

4.1.3 cost_centers 58

4.1.4 fiscal_years 59

4.1.5 accounting_periods 59

4.1.6 items (Master Produk) 60

4.1.7 item_groups 60

4.1.8 customers 61

4.1.9 customer_groups 61

4.1.10 suppliers 61

4.1.11 supplier_groups 62

4.1.12 warehouses 62

4.1.13 uoms (Unit of Measure) 63

4.1.14 uom_conversions 63

4.1.15 price_lists 63

4.1.16 item_prices 63

4.1.17 sales_persons 64

4.1.18 numbering_series ➕ v1.6 (BARU) 64

4.1.19 departments ➕ v1.7 (BARU) 64

4.2 Inventory & Stock 65

4.2.1 batches 65

4.2.2 stock_entries 65

4.2.3 stock_entry_items 66

4.2.4 stock_ledger_entries (SLE) — Immutable 66

4.2.5 bins (Agregasi Stok) 67

4.2.6 stock_reservations ➕ v1.6 (BARU) 67

4.3 Purchase 68

4.3.1 purchase_orders 68

4.3.2 purchase_order_items 68

4.3.3 purchase_receipts 69

4.3.4 purchase_receipt_items 69

4.3.5 purchase_invoices 69

4.3.6 purchase_invoice_items 70

4.3.7 material_requests 70

4.3.8 landed_cost_vouchers 70

4.3.9 landed_cost_voucher_items 71

4.4 Manufacturing 71

4.4.1 boms (Bill of Materials) 71

4.4.2 bom_items 72

4.4.3 operations 72

4.4.4 work_orders 72

4.4.5 work_order_operations 73

4.4.6 production_plans 73

4.4.7 production_plan_items 73

4.5 Sales 74

4.5.1 Core Sales Tables 74

4.5.1.1 sales_orders 74

4.5.1.2 sales_order_items 75

4.5.1.3 delivery_notes 75

4.5.1.4 delivery_note_items 75

4.5.1.5 sales_invoices 76

4.5.1.6 sales_invoice_items 76

4.5.2 Fee Components & Configuration 77

5.2.1 customer_fee_components (Master Jenis Biaya) 77

5.2.2 customer_fee_configs (Konfigurasi Biaya per Customer) 77

4.5.3 Fee Snapshots 78

4.5.3.1 sales_order_fees 78

4.6 Accounting 78

4.6.1 Core Accounting 78

4.6.1.1 journal_entries 78

4.6.1.2 journal_entry_items 79

4.6.1.3 gl_entries (General Ledger) — Immutable 79

4.6.1.4 payment_ledger_entries 79

4.6.1.5 payment_terms_templates — TABEL BARU (Hide) 80

4.6.1.6 payment_schedules — TABEL BARU (Hide) 80

4.6.2 Payment & Banking 80

4.6.2.1 modes_of_payment — TABEL BARU 80

4.6.2.2 payment_entries 80

4.6.2.3 payment_entry_deductions — TABEL BARU 81

4.6.2.3a payment_entry_references — BARU 81

4.6.2.4 banks — TABEL BARU (Hide) 82

6.2.5 bank_accounts — TABEL BARU (Hide) 82

4.6.2.6 bank_transactions — TABEL BARU (Hide) 82

4.6.3 Tax & Withholding 83

4.6.3.1 taxes_templates (Sales & Purchase) 83

4.6.3.2 tax_template_items 83

4.6.3.3 tax_withholding_categories 83

4.6.3.4 tax_withholding_entries — TABEL BARU 83

4.6.4 Budget & Period 84

4.6.4.1 budgets — TABEL BARU (Hide) 84

6.4.2 budget_items — TABEL BARU (Hide) 84

6.4.3 monthly_distributions — TABEL BARU (Hide) 84

4.7 Quality 85

4.7.1 quality_inspections 85

4.7.2 quality_templates 85

4.7.3 non_conformances 85

4.8 Asset 86

4.8.1 asset_categories 86

4.8.2 assets 86

4.8.3 asset_depreciation_schedules 87

4.8.4 asset_movements 87

4.8.5 asset_repairs 87

4.8.6 asset_maintenances 88

4.8.7 asset_maintenance_logs 88

4.9 HR (Minimalis) 89

4.9.1 employees 89

4.9.2 attendances 89

4.9.3 leave_types 90

4.9.4 leave_allocations 90

4.9.5 leave_applications 90

4.9.6 salary_structures 90

4.9.7 payroll_entries 91

4.9.8 salary_slips 91

4.10 System & Framework 92

4.10.1 users 92

4.10.2 permissions 92

4.10.3 access_logs 92

4.10.4 modules ➕ v1.6 (BARU) 93

4.10.5 workspaces ➕ v1.6 (BARU) 93

4.10.6 settings ➕ v1.6 (BARU) 93

4.10.7 schema_metadata ➕ v1.6 (BARU) 94

4.10.8 roles ➕ v1.7 (BARU) 94

4.10.9 user_roles ➕ v1.7 (BARU) 94

4.11 Relasi Antar Tabel (Tree Structure) 95

4.12 Cloak Registry (Keamanan Tiga Lapis) 97

4.12.1 Grup Cloak 97

4.12.2 Aturan Penegakan (Konvensi Implementasi) 97

4.13 Catatan Implementasi 98

Changelog v1.7 (vs v1.6) 99

Penambahan Tabel Baru 99

Perubahan Tipe Data / Refactor Struktural 100

Catatan 100

Changelog v1.6 (vs v1.5) 101

Penambahan Tabel Baru 101

Penambahan Kolom Baru 101

Perubahan Tipe Data 101

Perubahan Konvensi 101

Penambahan Akun Beban 101

Penghapusan 101

Chapter 5: Development Conventions 102

Catatan Merge (K + O + Q) 102

5.0 Development Invariants 103

5.1 Bahasa & Naming Convention 103

5.1.1 Elixir & Ash Naming 104

5.1.2 UI Component Naming (LiveView / HEEx) 104

5.1.3 File Naming 104

5.2 Project Structure & Folder Convention 105

5.3 Domain Ownership 106

5.4 Resource Convention 107

5.5 Action Convention 107

5.5.1 Generic CRUD 107

5.6 Public Action vs Internal Implementation 108

5.7 Event Convention 108

5.7.1 Event Payload 108

5.8 Anchor ID 108

5.9 State Machine Convention 109

5.10 Database Convention 109

5.11 UUID Convention 109

5.12 Money & Numeric Precision 109

5.13 Tree Data Convention 110

5.14 Archive vs Delete 110

5.15 Async Job Convention 110

5.16 Reactor Convention 110

5.17 Sync-Agent Boundary 110

5.18 Logging & Sensitive Data 110

5.19 LiveView Convention 111

5.20 UI State vs Application Data 111

5.21 Query Convention 111

5.22 Performance Convention 112

5.23 Testing Strategy 112

5.24 Testing Libraries 113

5.25 Property-Based Testing 113

5.26 Mocking Convention 113

5.27 Static Analysis 114

5.28 Documentation Convention 114

5.29 Error Convention 115

5.30 Transaction Convention 115

5.31 Migration Convention 115

5.32 SQLite Operational Convention 115

5.33 Import Convention 116

5.34 Numbering Convention 116

5.35 Release & Versioning 116

5.35.1 Semantic Versioning 116

5.35.2 Changelog Convention 116

5.35.3 Release Packaging & Asset Fingerprinting 116

5.36 Git Convention 117

5.37 CI Pipeline 117

5.38 Definition of Done 117

5.39 Anti-Patterns 118

5.40 Development Decision Hierarchy 118

5.41 Dependency Rule 118

5.42 Laporan Fiskal & Template Output Bahasa Indonesia 119

5.43 Final Principle 122

Introduction

Dokumen ini adalah blueprint proyek BMP (Business Management Platform) secara utuh — menggabungkan seluruh keputusan desain dan arsitektur yang telah disepakati ke dalam satu struktur dokumentasi resmi, menggantikan catatan sesi yang sebelumnya tersebar di beberapa file terpisah.

Peta Keseluruhan & Status

Seluruh cakupan proyek dipetakan ke dalam empat kelompok besar berikut, masing-masing dengan status pengerjaan saat dokumen ini disusun:

Dua “Architecture” yang Berbeda Level

Penting dipisahkan agar tidak rancu: “System UI/UX” (Chapter 6) dan “Architecture” (Chapter 3) sama-sama menyentuh topik Module/Permission/Role/Workspace, tapi dari sudut pandang berbeda.

Urutan Pengerjaan

Urutan bab dalam dokumen ini disusun berdasarkan ketergantungan — apa yang harus mapan dulu sebelum yang lain bisa dibangun konsisten di atasnya, bukan sekadar urutan sembarang:

1. Design Foundation — token visual (warna, tipografi, ikonografi) yang jadi dasar semua komponen bersama; ditunda akan berarti banyak yang harus diubah retroaktif.
2. Interaction Structure — pola perilaku layar (layout, navigasi, list, form, report, workflow) yang dibangun di atas Design Foundation.
3. Architecture — pondasi teknis (Phoenix, Ash, event-driven, sync-agent, deployment) sebelum konvensi kode ditulis.
4. Data_Model_&_Table_Specifications — skema database lengkap untuk implementasi
   Ash Framework
5. Development Conventions — bergantung pada keputusan Architecture di atas.
6. System UI/UX — formalisasi Module/Permission/Role/Workspace/Settings sebagai spesifikasi resmi, karena modul-modul di bawah akan mengacu ke sini.
7. Report & Workflow — struktur lintas modul yang dipakai oleh seluruh Modul ERP.
8. Modul ERP Core — memakai seluruh fondasi di atas.
9. Modul Optional/Community — paling akhir, dapat didorong ke kontributor komunitas.

Latar Belakang — Analisis 12 ERP Open Source

Sebelum menyusun prinsip desain BMP, dilakukan analisis terhadap 12 aplikasi ERP open source sebagai pembanding: ERPNext, Dolibarr, Apache OFBiz, metasfresh, iDempiere, Tryton, OpenPetra, Axelor, inoERP, LedgerSMB, BlueSeer, dan WebERP.

Kesimpulan utama: hampir semua ERP tersebut membangun UI dengan mengikuti struktur backend (skema database, metadata resource), bukan mengikuti alur kerja/pengalaman user. Pola kesalahan yang berulang:

• UI mengikuti skema tabel — form/menu di-generate dari struktur data (DocType di ERPNext, AD_Window di iDempiere/metasfresh), bukan disusun dari alur keputusan user.
• Navigasi mengikuti hierarki teknis — tree menu dalam (iDempiere, Apache OFBiz) mencerminkan struktur modul database, bukan frekuensi pemakaian nyata.
• Dashboard dekoratif, bukan actionable — angka ditampilkan tanpa mengarahkan tindakan, kecuali metasfresh yang mendekati filosofi task-oriented landing page.
• Tidak ada konsistensi lintas layar — pada WebERP dan LedgerSMB khususnya, tiap halaman terasa dibuat oleh developer berbeda karena tidak ada komponen/pola bersama yang dipaksakan.
• Satu layout untuk semua peran — staf akuntansi dan staf produksi/gudang melihat kerangka UI identik, padahal kebutuhan visual & interaksi mereka sangat berbeda.

Prinsip inti yang menjadi fondasi seluruh dokumen ini:

UI yang nyaman selalu menjawab “apa yang sedang ingin dicapai user saat ini” — bukan “bagaimana data ini disimpan di backend”.

BMP (Business Management Platform) secara sadar dirancang untuk UMKM yang sedang berkembang menuju skala menengah — bukan enterprise. Konsekuensinya: default harus cukup sederhana untuk dipakai tanpa training/konsultan, approval bertingkat bersifat opsional (bukan default wajib), dan satu orang boleh memegang lebih dari satu akun fungsi sesuai kebutuhan bisnis kecil yang masih hemat sumber daya.

Chapter 1: Design Foundation

Bab ini mendefinisikan fondasi visual, tipografi, filosofi ukur, dan prinsip meta yang menjadi landasan mutlak bagi seluruh antarmuka BMP. Setiap komponen UI yang dibangun di Chapter 2 (Interaction Structure) dan Chapter 6 (System UI/UX) harus mematuhi token dan batasan yang ditetapkan di sini — makin lama ditunda, makin banyak yang harus diubah retroaktif.

Status: 🔒 Final / Mengikat (v2.0) Dasar: Spec Navigasi & Landing (Mockup Final v9) · UI Reference Prinsip v1 Tujuan: Menyatukan bahasa visual, mencegah anti-pattern konsumer, dan mengunci dimensi spasial antarmuka.

Changelog v2.0:

• [REVISI] 1.2 Color System: accent bergeser dari teal (#0D9488) ke hijau (#16A34A) setelah eksplorasi mockup v2.0–v2.2, jadi identitas visual resmi BMP. Palet netral disegarkan ke skala hangat (mendekati Tailwind “stone”) — bukan lagi greige v9 yang lama.
• [BARU] 1.5 Shadow & Elevation System: fondasi untuk Tangga Intensitas Overlay di Chapter 2.11.
• [BARU] 1.6 Spacing, Radius & Grid: memformalkan filosofi “chrome fix, kanvas fluid” dan mengunci seluruh dimensi spasial dari Spec v9.
• [BARU] 1.8 Tiga Prinsip Meta Visual: landasan filosofis penolakan pola UX konsumer, dari UI Reference v1.

1.1 Theme

Tema visual BMP adalah Operational Minimalist. Arah visualnya profesional tapi tidak mengintimidasi — berbeda dari kesan “software korporat kaku” ala ERP enterprise yang membuat pemilik UMKM merasa perlu training dulu sebelum berani memakainya. Berbeda juga dari aplikasi konsumer yang memprioritaskan engagement dan infinite scrolling — BMP dirancang memaksimalkan Konteks Operasional dan Kejelasan Data.

• Kesan: Bersih, profesional, tidak berisik, berorientasi tugas (task-oriented).
• Aturan Emas: Tidak ada ornamen dekoratif yang tidak mendukung pengambilan keputusan bisnis.
• Sudut membulat sedang (radius ≈ 6–8px) — tidak tajam-kotak seperti software akuntansi lawas, tidak juga terlalu bulat ala aplikasi konsumen.
• Latar netral hangat, bukan abu-abu dingin murni — memberi kesan lebih ramah untuk dipakai berjam-jam.
• Ditulis sebagai design token (CSS custom properties), bukan nilai hex hardcode — supaya white-label (rebranding warna oleh UMKM lain di versi open source) tinggal mengganti token, tanpa menulis ulang komponen.

1.2 Color System

Token warna bersifat semantik (berdasarkan fungsi), bukan sekadar warna brand. Satu token = satu makna, berlaku konsisten di seluruh komponen. Aksen dijaga sangat langka supaya fokus pengguna tetap di data operasional.

Token navigasi (turunan dari surface-1, dipakai khusus di rail & area non-kanvas):

Aturan Warna:

1. Hijau (--color-accent) sangat langka — hanya untuk logo, pager aktif, focus ring, dan CTA absolut. Tidak boleh dipakai untuk teks biasa atau latar kartu; penggunaannya dibatasi supaya mata pengguna langsung tertarik saat warna ini muncul.
2. Diferensiasi elemen (mis. tombol hover, collapse toggle) dilakukan lewat perbedaan tone (kecerahan) pada permukaan yang sama, bukan dengan memperkenalkan hue baru.
3. Warna status (amber/merah/hijau) hanya untuk badge status, angka KPI, dan indikator overdue — bukan dekorasi umum.

1.3 Typography

Dua kebutuhan khusus aplikasi bertipe ERP/BMP yang sering diabaikan desain UI generik:

• Angka harus rata (tabular numerals, font-variant-numeric: tabular-nums) — supaya kolom nominal/kuantitas di tabel sejajar rapi antar baris, lurus vertikal sempurna.
• Terbaca jelas di ukuran kecil — karena banyak tabel padat (list view, form multi-kolom).

Font terpilih: Inter — open source, mendukung tabular numerals bawaan, teruji untuk UI aplikasi data-berat. Karena aplikasi berjalan offline/LAN-only, font wajib di-bundle lokal (.woff2 di priv/static/fonts/), tidak boleh bergantung pada Google Fonts CDN.

Label & header tabel: wajib UPPERCASE, ukuran kecil (10–11px), warna muted — membedakan secara instan “label sistem” dari “data inputan user”.

Berat font dibatasi 3: Regular (400) untuk body, Medium (500) untuk judul/emphasis, Semibold (600) khusus text-2xl (angka KPI besar butuh bobot lebih tegas) — mencegah developer bebas memakai Bold/Black secara tidak konsisten.

1.4 Iconography

Satu sumber ikon untuk seluruh aplikasi, bukan campuran beberapa icon set.

• SVG inline dibungkus komponen bersama <.icon name="check" /> di Phoenix — bukan icon font berbasis CDN, karena aplikasi offline.
• Satu icon set (Lucide atau Heroicons — open source, gaya konsisten, bisa di-bundle lokal tanpa CDN), gaya outlined (stroke), bukan filled.
• Dua ukuran tetap: 16px (inline dengan teks kecil/tombol) dan 20px (aksi utama/navigasi).
• Stroke width konsisten 1.5–2px agar semua ikon senada secara visual.
• Aturan truncation: ikon tidak pernah dipotong. Ruang sempit → kecilkan ukuran ikon atau bungkus teks ke baris kedua — jangan pakai ellipsis (…) pada label navigasi (Aturan BMP #9, Chapter 2.12).

— widget: "design_foundation_styleguide"
Lembar acuan visual: swatch warna, contoh type scale dengan tabular numerals, dan sampel ikon dua ukuran.

1.5 Shadow & Elevation System (baru)

Elevation di BMP bukan dekorasi — ia mengkomunikasikan kedalaman interaksi dan intensitas interupsi. Sistem ini menjadi fondasi Tangga Intensitas Overlay di Chapter 2.11.

Aturan Elevation:

1. Elevation naik = interupsi naik. Level 4 hanya untuk modal keputusan destruktif/bloking — jangan pakai untuk flyout atau dropdown.
2. Backdrop gelap hanya menyertai level 4. Level 1–3 tidak menggunakan backdrop gelap — elevation cukup mengkomunikasikan kedalaman.
3. Semua shadow pakai rgba(0,0,0,...) — tidak ada shadow berwarna.

1.6 Spacing, Radius & Grid (baru)

BMP mengikuti filosofi “chrome fix, kanvas fluid”, terinspirasi efisiensi ruang kerja profesional: semua ketebalan bingkai (chrome — sidebar, header, baris, tombol) berukuran tetap; yang cair (fluid) hanya sisa ruang kanvas.

Aturan mutlak:

• Nol rasio proporsional di desktop — tidak ada komponen diskalakan terhadap inci layar (mis. width: 20vw).
• Layar 14” vs 19”: tidak ada elemen yang membesar secara fisik. Layar lebih besar cuma menampung lebih banyak kolom/baris data di kanvas fluid. Ukuran fisik hanya berubah lewat OS Scaling (DPI).

Tabel Dimensi Kunci (terkunci — terikat Spec v9, tidak boleh diubah tanpa revisi Blueprint):

Radius

Spacing Scale

Aturan Grid: tidak ada 12-column grid yang ketat — layout BMP berbasis panel dan zona (rail, head, kanvas), bukan grid kolom.

Density & Personalisasi: dua tingkat kepadatan didukung tanpa merusak tata letak — Comfortable (44px), baris/input lebih renggang, cocok layar sentuh atau keterbacaan santai; Compact (36px), baris lebih rapat, cocok power-user yang butuh lebih banyak baris data per layar. Pilihan density, status rail (expanded/collapsed), dan pin landing page disimpan di level user session (bukan global).

1.7 Contoh Penerapan

Dua contoh berikut menunjukkan token di atas diterapkan pada tampilan halaman web yang mendekati bentuk final (bukan wireframe kotak-kotak).

Contoh 1 — Home Dashboard

— widget: "bmp_home_high_fidelity"
Halaman Home dengan sidebar ikon, search bar, feed My Attention, dan 3 KPI card dengan tabular numerals.

Contoh 2 — List View

— widget: "bmp_list_view_high_fidelity"
Tabel Sales Order dengan tab saved-view, badge status berwarna, dan kolom nilai rata kanan tabular numerals.

1.8 Tiga Prinsip Meta Visual

Tiga prinsip ini menjadi batu uji setiap keputusan visual di BMP — menjelaskan mengapa token dan komponen di atas dirancang begitu, dan wajib dipegang tim UI/UX & Developer saat merancang komponen baru. BMP secara sadar menolak pola interaksi aplikasi konsumer (media sosial, e-commerce B2C) yang dirancang untuk retensi adiktif.

1. Proporsionalitas Interupsi — intensitas overlay (Chapter 1.5, 2.11) harus sebanding dengan pentingnya peristiwa. Jangan pernah pakai modal gelap (level 4/5) untuk hasil pencarian (level 2) atau form cepat. Implikasi: Shadow level 4 hanya untuk modal. Search anchored level 2 tanpa gelap. Tombol danger hanya untuk aksi destruktif.
2. Konteks Operasional — data bisnis adalah data operasional, bukan konten konsumsi. User butuh total konteks, posisi data, dan batasan waktu — bukan infinite feed. Pager tradisional lebih dihargai daripada Load More untuk data master/transaksi (detail di 2.2). Implikasi: Typography dioptimalkan untuk ukuran kecil dan tabular numerals. Spacing cukup rapat untuk kepadatan data. Chrome fix agar konteks tidak bergeser.
3. Kemurnian Konteks (Bounded UI) — setiap elemen UI mencerminkan satu kepemilikan arsitektural. Jangan campur konsep Platform, Master Data, dan Policy/Settings di satu permukaan yang sama. Implikasi: Rail sidebar murni milik domain (Strict UI Ownership). Settings punya hub tersendiri (6.4). Zona settings di rail hanya terlihat role admin.

Chapter 2: Interaction Structure

Status: 🔒 Final / Mengikat (v2.0)

Dasar: Spec Navigasi & Landing (Mockup Final v9) · UI Reference v1 · Temuan UX (Studi Kasus ERPNext v16) · mockup visual (draf C)

Tujuan: Mengunci perilaku spasial, hierarki navigasi 3 tingkat, dan mencegah anti-pattern interupsi yang merusak flow operasional.

Bagian ini mendefinisikan bagaimana tiap jenis layar disusun secara konsisten di seluruh modul BMP — mengikuti prinsip inti: alur kerja user, bukan struktur backend. Semua pola di bawah dibangun di atas token visual Chapter 1.

Catatan penggabungan (editorial, baca sebelum lanjut): dokumen ini menggabungkan tiga draf — K (paling lengkap: 2.1–2.14 + studi kasus penuh), Q (revisi "final/mengikat" yang lebih ringkas, 2.1–2.8), dan C (draf visual dengan 18 referensi mockup/widget bergambar, disematkan langsung di bagian terkait). Isinya sebagian besar identik lintas ketiganya; struktur K dipakai sebagai kerangka utama karena paling lengkap dan paling dekat dengan apa yang sudah "terkunci" di Blueprint master. Tiga konflik sempat ditemukan (footer, trigger flyout, jumlah level tangga overlay) — ketiganya sudah diputuskan final oleh user dan diterapkan langsung di badan dokumen ini; log keputusannya ada di penutup dokumen.

2.1 Landing Page & Layout

Masalah pada ERP pembanding: landing page berupa "app launcher" (grid ikon besar) menyisakan ruang kosong besar saat modul sedikit; semua ikon modul diberi bobot visual sama padahal frekuensi pemakaian berbeda jauh; tidak menjawab "apa yang perlu dikerjakan hari ini"; kolom mengikuti urutan tabel database, bukan keputusan bisnis.

Prinsip pengorganisasian (C):

• Search bar di posisi paling atas — menggantikan kebutuhan mencari ikon modul.
• Satu feed "My Attention" menggabungkan task + notifikasi + alert, diurutkan berdasarkan urgensi — bukan dipisah ke banyak sumber. Item actionable dipisahkan visual dari info-only.
• KPI dipersempit jadi yang relevan dengan peran user, bukan digelar merata.
• Module launcher (grid ikon besar) dihapus jika sudah ada sidebar — menghindari duplikasi sistem navigasi.
• Ukuran & posisi panel mengikuti urgensi, bukan grid simetris seragam.

Arsitektur halaman BMP (Zona):

Tanpa footer di halaman manapun (final — lihat log keputusan di penutup dokumen). Status sinkronisasi data (relevan karena BMP local-first dengan sync-agent) tidak hilang fungsinya — dipindah jadi icon sync di header kanan (5 state + popover detail, lihat §2.1.4), sementara identitas aplikasi ("Powered by Phoenix · Ash") sudah punya tempat di baris akun bawah rail (§2.1.1 poin 7). Tanpa greeting. Tanpa launcher grid. Rail + flyout + Ctrl+K menutup long tail navigasi. Tanpa title-block di content — identitas halaman hanya ada di breadcrumb; mengulang judul (H1) di kanvas adalah redundansi visual.

2.1.1 Rail Sidebar (atas → bawah)

2.1.2 Header (page-head 44px)

• Kiri: breadcrumb hierarkis; "Home" = ikon saja; semua level dapat diklik; kedalaman maksimum 3 level.
• Kanan: [home] + [icon sync — lihat perilaku 5-state di §2.1.4].
• Avatar = dropdown berkelompok: header (nama + email) → grup Preferences (My Profile, Preferences) → grup Session (Log Out, warna danger).

2.1.3 Isi Landing (My Attention)

Landing page menjawab "apa yang perlu dikerjakan hari ini", bukan "di mana letak modulnya".

• Search bar paling atas.
• KPI strip 4 kartu: label uppercase 11px muted; nilai 24px tabular; semantik warna angka (amber = perlu perhatian, merah = overdue, gelap = netral).
• Tabel antrean: header uppercase abu solid; angka rata kanan tabular; badge status semantik; aksi baris (View/Process) hover-reveal.
• Pager tradisional: "1-20 of 230" + lingkaran bernomor (aktif = accent) + Next + pemilih ukuran halaman. Bukan Load More.

📎 hasil konsolidasi landing page (feed My Attention, KPI ringkas, dokumen terakhir), dibanding versi awal yang terlalu ramai.

2.1.4 Perilaku Icon Sync (5 State)

Icon sync di header kanan bukan sekadar tombol refresh generik — ini satu-satunya sinyal di UI bahwa BMP bersifat local-first (data bisa "beda" sesaat antar laptop sebelum tersinkron), jadi harus membawa informasi state yang nyata, bukan cuma on/off.

Offline dan Konflik sengaja dipisah, tidak digabung jadi satu warna merah yang sama — keduanya beda secara fundamental: offline artinya "tidak apa-apa, nanti otomatis lanjut begitu koneksi kembali"; konflik artinya "ada yang perlu manusia putuskan sekarang". Kalau disamakan, user tidak bisa membedakan mana yang harus segera ditindaklanjuti.

Interaksi klik: membuka popover kecil anchored di bawah icon — pola yang sama persis dengan dropdown avatar/search (Level 2 di tangga overlay §2.11, tanpa backdrop gelap), bukan cuma memicu animasi tanpa isi. Isi popover:

• Waktu sync terakhir.
• Kalau ada yang pending: "3 dokumen menunggu sync".
• Kalau ada konflik: daftar ringkas + tombol "Tinjau" yang mengarah ke halaman resolusi konflik.
• Tombol "Sync sekarang" manual di bagian bawah.

Popover ini adalah satu-satunya jalan masuk dari UI ke mekanisme anchor_id (deteksi konflik non-LWW, Chapter 3 §Sync-Agent Addendum). Tanpa jalan masuk ini, fitur deteksi-konflik di backend ada tapi tidak kepakai secara praktis oleh user — sync icon jadi jembatan yang menghubungkan arsitektur sync ke lapisan interaksi.

2.2 List / Table View

Masalah pada ERP pembanding: kolom mengikuti urutan tabel database; status hanya teks polos tanpa sinyal visual; filter tersembunyi di panel terpisah; bulk action sulit ditemukan; "Load More" merusak spatial memory; ornamen konsumer (like/komentar) menambah noise; flag teknis bocor ke list bisnis.

2.2.1 Prinsip Pengorganisasian

• Status sebagai sinyal visual (warna/badge), ditaruh paling kiri setelah checkbox.
• Kolom default dibatasi (±5) yang dipakai untuk keputusan cepat; kolom lain di balik "kelola kolom".
• Saved view sebagai tab di atas tabel ("Assigned to Me", "Pending Approval", "Overdue") menggantikan filter form tersembunyi.
• Baris yang menyimpang dari normal (overdue, ditolak) diberi penekanan visual.
• Action bar kontekstual muncul otomatis saat baris dipilih.
• Row density dapat diatur (comfortable 44px / compact 36px), persist per user.
• Pager tradisional wajib — "1-20 of N" + lingkaran bernomor + Next. Load More / infinite scroll hanya untuk Timeline, Activity Log, Notification Log, Audit Trail.

2.2.2 Elemen List

📎 List view Sales Order versi high-fidelity, dapat dipakai ulang sebagai referensi visual bagian ini.

2.3 Navigation & Information Structure

Koreksi konsep penting: navigasi bukan flowchart (satu jalur linear). Model yang tepat adalah peta kedalaman dengan panah dua arah di tiap level, ditambah jalur pintas (search) yang dapat melompati level tengah.

📎 diagram lima level kedalaman navigasi (Home → Workspace → List → Detail → Sub-record) dengan panah dua arah dan jalur pintas via search.

2.3.1 Hierarki Halaman (3 Tingkat)

Halaman utilitas (My Profile, Preferences) diperlakukan seperti landing: di luar workspace, tanpa baris aktif.

2.3.2 Peta Gestur → Efek

2.3.3 Pembagian Peran Penanda

• Rail (baris aktif) = "di wilayah mana saya" — rail konstan di semua halaman (peta stabil; spatial memory); hanya highlight yang bergerak.
• Breadcrumb = "path lengkap saya, dan bagaimana mundur" — digenerate dari pohon navigasi yang sama dengan sidebar (satu source of truth).
• Flyout = "ke mana saya bisa pergi di modul ini".

2.3.4 Struktur Flyout

• Item pertama = Overview (= Workspace; jalur bagi mode collapsed dan jalur alternatif mode expanded).

• Grup ber-header legend divider: label 10px uppercase duduk di atas garis tipis yang menembusnya — terbaca pemisah, bukan item menu.

  • Grup modul bisnis: Transactions / Masters / Reports (kosakata konsisten dengan dokumen modul).
  • Grup System & Utility: Access / Communication / System.

• Tanpa policy di flyout bisnis — policy hidup di Administration (Settings Hub).

• Panel: min-width 224px, radius 8px, shadow level 2, overlay tanpa layout shift, max-height calc(100vh − 16px) + scroll internal.

Aturan produksi flyout: click-to-pin, tutup pada klik-luar/Esc; hanya satu flyout terbuka (membuka satu = lain menutup otomatis); clamp viewport (flyout yang melewati batas bawah bergeser naik otomatis).

2.3.5 Pola Sidebar (Final: Flat + Trigger Klik)

(Prinsip "sidebar flat" berasal dari draf C, tidak ada di K/Q.) Tree bersarang (expand/collapse permanen) tidak dipakai karena mencerminkan struktur database, bukan frekuensi pemakaian. Sidebar flat (1 level) adalah baseline — ini sudah otomatis konsisten dengan struktur rail K/Q yang memang flat sejak awal.

Keputusan final: trigger flyout tetap KLIK (chevron), bukan hover. Alasan utama bukan cuma keamanan gestur (2.3.6), tapi BMP eksplisit mendukung mode Tablet touch-first untuk staf gudang/kasir (§2.9) — hover tidak eksis di touchscreen, jadi trigger hover akan berperilaku beda per device dan melanggar konsistensi (§2.8). Usulan hover dari draf C ditolak; bagian flat-sidebar-nya diserap karena memang sudah sejalan dengan rail yang ada.

📎 ilustrasi dari draf C: perbandingan sidebar flat dengan flyout munculan saat hover. Konsep flat-nya dipakai; trigger hover-nya ditolak (lihat catatan final di atas).

2.3.6 Keselamatan Gestur

• Chevron tidak pernah menavigasi → menjelajah menu selalu aman; guard form-belum-disimpan hanya muncul pada gestur navigasi eksplisit (label, item flyout, logo) — normal seperti klik link mana pun. Membuka menu tidak boleh menjadi "hukuman untuk niat yang tidak bersalah".
• Chevron: visual 14px, hit area ≥28×28px, hover + tooltip sendiri ("Sub-menu"), focusable terpisah; Enter pada baris = navigasi.

2.3.7 Global Navigation vs Local Navigation

📎 kombinasi rak ikon (global nav) identik di semua halaman dengan breadcrumb + tab (local nav) yang berubah sesuai konteks.

2.3.8 Lima Hal Spesifik Navigasi ERP/BMP

• Hierarki data bisnis ≠ hierarki navigasi aplikasi — Chart of Accounts, BOM, dsb. hanya boleh muncul sebagai widget di satu layar spesifik, tidak pernah jadi navigasi utama.
• Document Trail — rantai dokumen (Quotation → Sales Order → Delivery Note → Invoice → Payment) sebagai pola navigasi khas ERP.
• Context Switcher (Company/Branch/Fiscal Year) — sumbu global nav kedua, mengubah scope seluruh data yang terlihat.
• Status dokumen menentukan navigasi yang valid — tombol/opsi aksi berubah mengikuti status (Draft vs Submitted).
• Reports/Analytics butuh pintu masuk sendiri, lintas modul, tidak dikubur di tree tiap modul.

📎 rantai dokumen dengan status kini disorot.

📎 Settings Hub sebagai jalur discovery config/master data, dikelompokkan per kategori fungsional.

📎 satu halaman penuh menggabungkan global nav, local nav, status-aware action bar, dan document trail sekaligus.

2.4 Form & Detail View

Masalah pada ERP pembanding: field diurutkan sesuai skema tabel; tabel item/baris sulit dinavigasi keyboard; validasi baru muncul setelah submit; field read-only tidak dibedakan visual.

2.4.1 Prinsip Pengorganisasian

• Urutan field mengikuti urutan keputusan, dikelompokkan berdasarkan pertanyaan: Who → What → When/How — bukan tabel asal data.
• Progressive disclosure — field inti selalu terlihat, field jarang dipakai di balik "Advanced Details" yang dapat di-expand.
• Validasi inline, muncul tepat di sebelah field saat itu juga.
• Field read-only diberi gaya visual berbeda tegas (latar abu-abu).
• Action bar sticky & status-aware.
• Tabel item dirancang untuk kecepatan: tambah baris tanpa reload, tab-to-next-cell, total otomatis update.

📎 Form Sales Order tersusun Who→What→When/How dengan validasi inline dan field read-only bertanda visual.

📎 Advanced Details terbuka, termasuk contoh conditional field metode pembayaran.

2.4.2 Conditional Field vs Progressive Disclosure

Aturan desain conditional field: jangan bikin layout "lompat" kasar; validasi harus ikut kondisi aktif (field tersembunyi tidak boleh dianggap wajib); data lama tidak boleh hilang diam-diam saat kondisi berubah; jangan berantai lebih dari 2 tingkat.

2.5 Search & Command Palette

Masalah pada ERP pembanding: search tercecer per-modul; hasil tidak dikelompokkan; tidak ada "command" (search hanya bisa navigasi); kotak kosong tidak menawarkan apa-apa; klik search membuka modal tengah gelap (level 5) padahal ekspektasi user level 2.

2.5.1 Dua Mode Pemicu

Mesin pencarian yang sama melayani kedua pemicu — perbedaan hanya posisi dan konteks pemanggilan.

2.5.2 Hasil Pencarian

• Dikelompokkan berdasarkan jenis: Action → Document → Report → Setting.
• Toleran typo & bisa cari lewat kode/nomor dokumen.
• Prefix untuk mempersempit cepat (# report, > action).
• Sajikan status di tiap hasil (badge warna).
• Kotak kosong menampilkan Recent Activity & Quick Actions sebelum user mengetik.

2.5.3 Empty State & Halaman Alat

• Tidak ada halaman "kosong mati" — setiap halaman alat (tools, report) harus membuka dalam keadaan berguna (data default, item terakhir, atau pilihan terpandu).
• Empty state wajib memuat CTA aksi berikutnya (mis. "Belum ada invoice bulan ini. [Buat Sales Invoice]").

📎 command palette dengan hasil terkelompok: Action, Document (dengan badge status), dan Report.

2.6 Notification & Approval Workflow

Masalah pada ERP pembanding: sebagian besar tidak punya sistem notifikasi terpadu; notifikasi terpecah ke banyak sumber; harus buka dokumen penuh untuk approve hal sederhana; tidak ada progres approval bertingkat yang terlihat; approval yang didiamkan lama diperlakukan sama seperti yang baru masuk.

Terminologi resmi alur approval BMP: Submitter → Checker (paralel, lintas divisi) → Approver (final).

2.6.1 Feed "My Attention"

Satu feed terpadu menggabungkan task + notifikasi + alert, diurutkan berdasarkan urgensi — bukan dipisah ke banyak sumber. Item actionable (butuh tindakan user) dipisahkan visual dari info-only.

📎 feed notifikasi terpadu (actionable vs info-only) dan contoh progres approval bertingkat linear (stepper 2 tingkat).

2.6.2 Pola Fork-Join Checker Lintas Divisi

Untuk kasus seperti Purchase Order yang membutuhkan verifikasi dari lebih dari satu divisi (contoh: Manager Production & Manager Accounting) sebelum sampai ke Approver akhir (Direktur/GM), alur tidak lagi linear melainkan fork-join:

• Kedua Checker diverifikasi secara paralel, tidak saling menunggu urutan.
• Jika salah satu Checker tidak setuju, alur berhenti total saat itu juga — tidak diteruskan ke Approver sama sekali.
• Hasil penolakan bersifat laporan tercatat (siapa menolak, alasannya) kepada Submitter — bukan alur revisi otomatis yang membuka kembali dokumen yang sama.
• Pengajuan ulang diperlakukan sebagai dokumen/pengajuan baru, bukan reopen dokumen lama — menjaga jejak audit tetap bersih.

Catatan implementasi: pola ini secara alami dipetakan ke Reactor (fan-out/fan-in dengan compensation saat salah satu step gagal) — dibahas lebih lanjut di Chapter 3 Architecture.

📎 diagram fork-join: Purchasing submit → dua Checker paralel (Manager Production, Manager Accounting) → Approver terkunci sampai kedua Checker selesai.

2.7 Personalization & Account Model

Tiga lapisan yang dipisah tegas:

• Permission — apa yang boleh dilihat/dilakukan, diatur admin.
• Role Default — dari yang boleh diakses, mana yang relevan ditampilkan duluan untuk fungsi tertentu (template per fungsi).
• Personal Customization — penyesuaian individu di atas default.

📎 role default per fungsi (Sales/Warehouse/Finance) sebagai template admin, dengan contoh override personal dan opsi reset ke default.

2.7.1 Model Akun, bukan Persona Gabungan

Keputusan desain BMP: satu orang dapat memiliki lebih dari satu akun terpisah (contoh: budi.kasir dan budi.pemilik), bukan satu akun dengan banyak peran digabung otomatis. Personalisasi dan permission melekat ke akun, bukan ke individu fisiknya.

• Segregation of duties (SoD) — penting khususnya di Finance/Accounting, memastikan ada jeda pemeriksaan sadar saat berpindah dari peran pengambil keputusan ke peran eksekusi, meski dilakukan orang yang sama.
• Untuk UMKM yang berkembang, struktur akun (mis. Manager, Treasury) sudah bisa disiapkan sejak awal meski masih dipegang 1 orang — begitu ada staf baru, admin tinggal buat kredensial baru tanpa desain ulang sistem.
• Perpindahan antar akun dipermudah lewat pola Account Switcher (bukan logout-login penuh setiap kali).

📎 daftar akun tersimpan sesinya, badge notifikasi per akun tanpa menggabungkan datanya.

2.7.2 Admin vs Business Home

Akun IT/Sysadmin murni (tanpa keterlibatan transaksi bisnis) mendapat home berupa System Console (status job, backup, permintaan akses user) yang berbeda kategori sepenuhnya dari home operasional bisnis — bukan sekadar varian KPI dari template yang sama.

📎 perbandingan Home akun bisnis (Sales) dengan Home akun IT Admin (System Console), dua kategori informasi berbeda total.

2.8 Consistency Patterns

Kamus perilaku — satu pola untuk satu situasi, dipakai persis sama di seluruh aplikasi, dipaksakan lewat komponen bersama (bukan sekadar dokumentasi yang harus diingat manual).

Cara menjaga konsistensi secara teknis: shared Phoenix function components (<.modal>, <.toast>, <.button variant="...">, <.empty_state>) dengan attr/slot untuk kontrak yang dicek saat compile; katalog visual komponen (PhoenixStorybook); test khusus untuk komponen bersama karena dampak perubahannya luas.

📎 lembar acuan pola interaksi: hierarki tombol, toast, modal konfirmasi destruktif, empty state, loading skeleton.

2.9 Responsive & Usage Context

Untuk konteks kantor lokal (LAN, offline), isu klasik field usage (sinyal putus-putus, offline sync) tidak relevan. Yang tetap relevan: kemungkinan ada titik pemakaian fisik berbeda dalam satu lokasi — bukan device berbeda karena di luar kantor, tapi konteks fisik berbeda dalam satu gedung/toko.

• Jangan membangun satu layout "responsive universal" — rancang 2–3 mode spesifik untuk peran yang memang membutuhkan:

  • Desktop dense — staf akuntansi (tabel padat, keyboard-first).
  • Tablet touch-first — staf gudang/kasir (target sentuh besar, swipe).
  • Kiosk/display — area produksi/gudang (read-only, auto-refresh, font besar, tanpa interaksi).

• Karena berjalan lewat LAN via browser, tidak perlu aplikasi native terpisah — cukup breakpoint CSS untuk mode touch.

📎 perbandingan prioritas informasi: tabel padat untuk Desktop staf akuntansi vs target sentuh besar untuk Tablet staf gudang.

2.10 Konvensi Bahasa UI Sistem

Catatan kecil: C menyebut baris terakhir sebagai "Settings" saja, K menyebut "Settings Hub" — dipakai "Settings Hub" karena konsisten dengan istilah yang sama di 2.3.4 dan 2.3.8.

2.11 Tangga Intensitas Overlay (5 Level)

Elevation di Chapter 1 adalah apa (shadow). Tangga di sini adalah kapan (aturan pemakaian). Intensitas overlay harus proporsional dengan pentingnya peristiwa. Versi final ini memakai 5 level — selaras dengan Chapter 1 §1.5 (Shadow & Elevation) yang sudah lebih dulu dikunci dengan 5 level shadow mengikuti tangga overlay ini persis; Toast/snackbar masuk ke Level 3, dan Fullscreen jadi pola situasional tanpa nomor level tersendiri (bukan level ke-6).

Fullscreen (print preview, data import wizard) tetap ada sebagai pola situasional — dipakai untuk pergantian mode sungguhan, tapi tidak diberi nomor level tersendiri karena bukan soal "seberapa mengganggu", melainkan mode kerja yang sepenuhnya berbeda.

Aturan:

• Posisi overlay selalu mengikuti titik perhatian pemicu (anchor point).
• Penggelapan (backdrop) mengikuti modalitas, bukan fungsi.
• Search anchored tanpa gelap bukan estetika spasial — itu manajemen budget interupsi user.

2.12 Kamus 12 Aturan BMP (dari Studi Kasus ERPNext v16)

2.13 Pola Keyboard, Touch & A11y

2.13.1 Peta Keyboard Global

2.13.2 Touch, Focus & Guard

2.14 Studi Kasus: Anti-Pattern ERPNext v16

Bab penutup Chapter 2 — justifikasi empiris untuk seluruh keputusan di atas. Format: Temuan → Diagnosis → Koreksi.

Temuan #1 — Search Modal Gelap

Diagnosis: klik search di level 2 (eksplorasi) tetapi ditampilkan dengan level 5 (modal gelap). Memutus kontinuitas spasial, menyembunyikan konteks, meninggalkan attention residue.

Koreksi: Aturan #1 — search anchored, tanpa gelap.

Temuan #2 — Load More di List Bisnis

Diagnosis: infinite scroll cocok untuk konsumsi konten (social media), merusak spatial memory dan total konteks pada data operasional.

Koreksi: Aturan #2 — pager tradisional wajib.

Temuan #3 — Sidebar Campur Domain

Diagnosis: User dan Email Account (domain System) masuk ke sidebar Organization — melanggar Single Ownership, menciptakan beban kognitif ganda.

Koreksi: Aturan #3 — Strict UI Ownership.

Temuan #4 — Launcher Menyamakan Kategori

Diagnosis: Framework (Platform), Organization (Master), dan Settings (Policy) ditampilkan sebagai ikon setara — meruntuhkan taksonomi.

Koreksi: Aturan #4 — Settings Hub tunggal, platform invisible.

Temuan #5 — Breadcrumb Tidak Konsisten

Diagnosis: Breadcrumb di-generate dari route page, bukan dari pohon workspace sidebar — dua sumber kebenaran yang bertentangan.

Koreksi: Aturan #5 — satu source of truth untuk IA.

Temuan #6 — Slot Primary untuk Navigasi

Diagnosis: Tombol hitam "Set User Permissions" adalah tautan ke halaman lain, bukan aksi create — mengkhianati muscle memory.

Koreksi: Aturan #6 — slot primary = aksi dominan.

Temuan #7 — Halaman Alat Kosong Mati

Diagnosis: Permission Manager terbuka dengan dua input kosong + kalimat perintah — tidak mengajar atau menawarkan langkah pertama.

Koreksi: Aturan #7 — setiap halaman membuka berguna.

Temuan #8 — Ornamen Konsumer di List

Diagnosis: Like, komentar, dan hati di list User — noise di konteks bisnis; semantik "suka" menyesatkan.

Koreksi: Aturan #8 — tanpa pola sosial di list operasional.

Temuan #9 — Label Navigasi Truncate

Diagnosis: "Manufactur...", "Subcontrac..." — navigasi adalah tempat terakhir yang boleh mengorbankan keterbacaan.

Koreksi: Aturan #9 — tidak pernah truncate.

Temuan #10 — Flag Teknis di List Bisnis

Diagnosis: Kolom "Is Group" di Department — user berpikir "induk/anak", bukan "flag group".

Koreksi: Aturan #10 — konsep bisnis, bukan mekanisme.

Temuan #11 — Suffix Company

Diagnosis: "Accounts − PSGA" — metadata menempel ke identitas, membuat list bising.

Koreksi: Aturan #11 — badge/kolom terpisah.

Temuan #12 — Dropdown Campur Jenis

Diagnosis: Satu menu berisi navigasi, preferensi, sesi, dan aksi sistem tanpa pengelompokan.

Koreksi: Aturan #12 — dikelompokkan per jenis, role-gated.

Catatan Implementasi Teknis Chapter 2

• Navigasi dan layout diimplementasikan sebagai Phoenix Layout bersama (layouts/app.html.heex) dengan slot untuk :rail, :head, dan inner content.
• State navigasi (rail expanded/collapsed, flyout terbuka, baris aktif) dikelola di LiveView mount atau session cookie (untuk persist per user).
• Breadcrumb generate dari satu struktur data pohon (Elixir map/list) yang juga meng-drive sidebar rail — tidak boleh ada dua sumber.
• Dirty-form guard menggunakan JavaScript beforeunload dan LiveView hook untuk mendeteksi perubahan form sebelum navigasi.

Log Keputusan Final (dari 3 Konflik Hasil Penggabungan)

• 1. Footer (2.1) — DIHAPUS. K dan Q sebelumnya mencantumkan zona "Footer" 28px, bertentangan dengan spec v9 yang terkunci ("tidak ada footer di halaman manapun"). Diputuskan: footer dihapus total, tanpa kehilangan fungsi — status sync (paling krusial karena BMP local-first) pindah ke icon sync 5-state di header (§2.1.4); "Powered by Phoenix · Ash" sudah punya tempat di baris akun bawah rail; live clock dihilangkan (bukan info kritis); nomor versi pindah ke halaman Settings/About.
  2. Trigger flyout (2.3.5) — KLIK, bukan hover. Draf C mengusulkan sidebar flat + flyout hover; keputusan final tetap klik chevron (sesuai v9), karena BMP mendukung mode Tablet touch-first untuk staf gudang/kasir (§2.9) dan hover tidak eksis di touchscreen. Prinsip "sidebar flat" dari C tetap dipakai karena sudah sejalan dengan struktur rail yang ada.

4. Tangga overlay (2.11) — 5 level, bukan 6. Versi K (6 level) sempat dipakai di draf sebelumnya, tapi ternyata tidak selaras dengan Chapter 1 §1.5 (Shadow & Elevation) yang sudah lebih dulu terkunci dengan 5 level shadow mengikuti tangga overlay ini. Diputuskan pindah ke versi Q (5 level): Toast masuk ke Level 3, Fullscreen jadi pola situasional tanpa nomor level.
5. Dimensi rail & header — dikonfirmasi ulang oleh user berdasarkan mockup HTML yang sudah berjalan: rail sidebar 210px expanded / 48px collapsed (bukan 224px seperti draf awal), page-head 44px (bukan 48px). Sudah diterapkan ke seluruh tabel/spec di dokumen ini.

Selain empat hal di atas, isi ketiga draf pada dasarnya identik — perbedaan Q terutama gaya penulisan yang lebih ringkas tanpa kehilangan substansi, dan C menambahkan 18 referensi visual yang sekarang disematkan langsung di tiap bagian terkait.

Chapter 3: Architecture

Status: 🔒 Final / Mengikat (v2.0)

Perubahan v2.0: menambahkan 6 sub-bab baru (Architecture Mapping untuk UI/UX, Performance Budget & Caching, Cloak & Pemisahan Tanggung Jawab IT, FTS5/Pagination sebagai sub-bab Data Layer, Real-time Event Architecture, Asset Pipeline & Offline Bundle) + klarifikasi ETS vs Persisted State + penguatan Addendum Sync-Agent untuk konteks offline-first UI. Seluruh sub-bab lama dipertahankan, hanya diberi nomor baru.

3.0 Architecture Invariants

Prinsip yang mengikat seluruh keputusan di bawah — bukan sekadar filosofi tersirat, tapi aturan yang tidak boleh dilanggar modul manapun.

4. Business logic tidak pernah bergantung pada topologi deployment (Standalone → Office Local-First).
5. Domain logic hidup di Ash Resource/Action, bukan di Phoenix controller.
6. Baca lintas domain lewat public action; efek samping lintas domain lewat event.
7. Transaksi lintas domain yang butuh kepastian “semua-atau-tidak” memakai Reactor.
8. Replikasi (sync-agent) tidak pernah memanggil Ash action.
9. Mutasi hasil replikasi harus aman di level constraint database (CHECK, UNIQUE) — ini last line of defense, bukan pengganti validasi Ash.
10. Data ledger transaksional bersifat append-only (insert-only, tidak pernah UPDATE/DELETE).
11. Derived state (mis. stok saat ini) tidak pernah jadi source of truth — selalu rebuildable dari data ledger.
12. Data finansial/audit tidak pernah dihapus otomatis.
13. Sync infrastructure (sync-agent) berada di luar domain model Ash — infrastructure layer, bukan business/service layer BMP.
14. Setiap event/transaksi yang punya dokumen penyerta di dunia nyata (invoice supplier, nomor produksi, surat jalan, dst.) wajib punya anchor_id — hash pendek dari (entity_type + nomor dokumen penyerta + tanggal event). Konflik sync dideteksi lewat UNIQUE(anchor_id), bukan last-write-wins (detail di Addendum Sync-Agent).

3.1 Fondasi: Phoenix — Ash — Event-driven

DDD sebagai struktur makro (satu Ash.Domain = satu bounded context), tiap domain punya Model + Domain Logic sendiri, tetapi View tetap mengikuti Design System terpusat — bukan MVC penuh yang berdiri sendiri per domain. Folder structure per-domain (lib/bmp/sales/), bukan per-layer teknis.

3.2 Async & Data Processing

3.3 Architecture Mapping untuk UI/UX System

Chapter 3 sebelumnya berbicara ke pembaca backend saja. Tapi keputusan UI/UX di Chapter 1, 2, dan 6 punya implikasi arsitektural yang perlu eksplisit didokumentasikan — supaya developer tahu mengapa komponen tertentu dipilih, bukan cuma apa.

3.4 Performance Budget & Caching Strategy

UI/UX responsif (chrome fix, search cepat, list tanpa jeda) butuh janji performa dari architecture.

Caching Hierarchy: - L1 — ETS (in-memory, per node): master data, menu tree, user session — volatile, cepat - L2 — SQLite query cache (Ash built-in): query berulang - L3 — Disk / Sync-Agent: data historis besar

Larangan: - Tidak ada N+1 query di list view (dicek via test) - Tidak ada full table scan untuk filter/search (harus pakai index) - Tidak ada query tanpa LIMIT untuk dropdown/flyout (maks 100 item)

3.5 Cloak & Pemisahan Tanggung Jawab IT

Compliance & keputusan bisnis kritis dari Peta Menu Rev3: field rahasia (resep/twist_notes, margin, payroll, rekening bank) harus terlindung dari staf IT meski mereka administrator sistem.

• Data-at-rest: field sensitif dienkripsi via AshCloak (lihat Data Model §12 Cloak Registry) — bukan disembunyikan lewat Ash Policy role-exclusion, karena itu cuma menahan akses lewat aplikasi, tidak menahan akses lewat file database mentah.
• Akses server: dipisah di level organisasi, bukan kode — 2 staf IT Support masing-masing cuma pegang 1 perangkat (Fortigate atau Mikrotik), tidak ada akses Server App/database. Cuma Manager IT yang pegang akses itu.
• Implikasi arsitektur: kunci enkripsi Cloak tidak boleh tersimpan di tempat yang bisa dijangkau staf IT biasa — idealnya dikelola terpisah oleh Manager IT atau di environment variable server yang aksesnya sama-sama dibatasi.

3.6 Data Layer — Full SQLite

• RDBMS: SQLite saja (AshSqlite.DataLayer) — satu data layer resmi Ash untuk seluruh profil deployment, dari Standalone hingga Office + Mobile Laptop. PostgreSQL, MariaDB, dan YugabyteDB tidak lagi jadi bagian dari stack — kompleksitas dual data layer dan cluster Postgres dihapus karena topologi yang dipilih (SQLite per node + sync-agent) tidak membutuhkannya.
• Ash native multitenancy (strategy :attribute atau :context) tetap jadi jawaban single/multi-tenant tanpa package tambahan — kompatibel penuh dengan SQLite per-tenant.
• AshDoubleEntry — ledger Accounting BMP Core. AshMoney — tipe uang presisi, hindari floating-point error.
• AshStateMachine — jawaban resmi untuk konsep Workflow (umum).
• AshPaperTrail — riwayat perubahan field, fondasi audit trail immutable.

Karena hanya satu data layer, tidak ada lagi kebutuhan “test matrix lintas database” — menyederhanakan CI dan menghilangkan kelas bug “jalan di SQLite, gagal di Postgres” (atau sebaliknya) yang sebelumnya jadi risiko di desain dual-layer.

3.6.1 Search Engine: FTS5 (Full-Text Search 5)

SQLite FTS5 dipakai untuk search dokumen/nomor — bagian dari implementasi Search Ctrl+K di §3 (Architecture Mapping UI/UX) di atas. Index FTS5 dibangun di atas kolom yang sering dicari (nomor dokumen, nama item/customer), disinkronkan via trigger SQLite saat insert/update.

3.6.2 Pagination: Offset/Limit Optimization

Konfirmasi arah yang sudah diputuskan di §3: pagination pakai offset/limit + count aggregate, bukan cursor-based — konsisten dengan Aturan BMP #2 (Chapter 2.12, Pager Tradisional). Optimisasi: index pada kolom sort default (biasanya posting_date DESC atau created_at DESC) supaya OFFSET besar tidak jadi full-scan.

3.7 Audit, Retensi & Kepatuhan (final)

AshArchival + AshPaperTrail, dengan empat aturan wajib:

1. Tidak ada purge otomatis untuk Resource finansial/audit (PO, Invoice, Journal Entry, Approval/Checker-Approver record). Archive bersifat permanen — tidak ada job terjadwal yang menghapus data ini bahkan setelah retention period (10 tahun untuk pajak Indonesia) terlewati. Storage murah, kehilangan bukti hukum mahal.
2. Aksi archive itu sendiri wajib tercatat AshPaperTrail — setiap “penghapusan” (arsip) harus punya jejak siapa/kapan/kenapa, sebagai meta-audit atas aksi audit-nya sendiri.
3. Document Trail dan tab Archived wajib menampilkan record yang diarsipkan secara utuh — query di kedua tempat ini harus eksplisit menyertakan data ter-archive (include_archived?: true), tidak boleh ikut tersaring oleh filter default AshArchival.
4. Archive adalah state transition (ACTIVE → ARCHIVED), bukan deletion secara konsep maupun implementasi — baris tetap ada secara fisik di database, hanya ditandai archived_at. Mental model ini yang membuat aturan 1–3 di atas konsisten.

Lapis keamanan lain (tidak berubah): AshAuthentication (model akun terpisah) → Ash.Policy.Authorizer (otorisasi) → AshCloak (enkripsi field sensitif) → AshRateLimiter (endpoint publik).

3.8 Ledger Khusus

TigerBeetle (via TigerBeetlex) — bukan pengganti RDBMS BMP Core, hanya untuk POS & E-commerce standalone. Scope sempit: cuma Account/Transfer (ledger kas) — katalog/sesi/cart tetap SQLite. Terhubung ke BMP Core lewat batch sync harian (Oban scheduled job, konfigurable), longgar — bukan transaksi real-time lintas sistem.

3.9 Cache & State

Dengan topologi disederhanakan menjadi SQLite-per-node, kebutuhan shared cache/pub-sub lintas node (Redix) tidak lagi relevan — tiap node (server kantor maupun laptop) berjalan sebagai instance mandiri.

Mnesia dan Redix tidak masuk stack — keduanya menjawab kebutuhan cluster/multi-node yang sudah tidak ada di topologi ini.

Klarifikasi (v2.0) — ETS vs Persisted State: ETS tidak persisten saat server restart, padahal state UI per user (rail collapsed, density, landing pin) perlu bertahan. Maka:

• ETS — cache data aplikasi (master data, query result, menu tree): volatile, cepat.
• SQLite user_settings — state UI persisten (density, rail, saved views): survive restart.
• Browser localStorage (opsional) — state UI pure client (sidebar width manual, zoom level).
• ❌ Mnesia — tidak dipakai (kompleksitas tidak sebanding).
• ❌ Redix/Redis — tidak dipakai (menambah dependency infrastruktur).

3.10 Real-time Event Architecture untuk UI

Menjelaskan bagaimana event backend sampai ke UI (My Attention, notifikasi approval, status dokumen berubah).

Phoenix PubSub Topics: - user:{user_id}:notifications — approval masuk, task assigned - company:{company_id}:document_updates — dokumen yang sedang dibuka user lain berubah status - company:{company_id}:kpi_refresh — trigger refresh KPI strip

Event-to-UI Mapping:

Backpressure: user offline (mobile laptop) → event di-queue di Oban → saat online, di-flush batch (maks 50 event/burst) → UI tampilkan “N notifikasi baru”, bukan toast individual per event.

3.11 Observability, I18n, Storage

• :telemetry + OpentelemetryAsh — Phoenix/Ecto/Oban/Ash semua sudah emit event telemetry bawaan; cukup untuk System Console tanpa tool eksternal seperti Grafana. sync-agent juga mempublish metrik ke :telemetry (lihat Addendum).
• Sentry-elixir — error tracking, free tier longgar dan bisa self-hosted.
• Gettext — internasionalisasi, disiapkan sejak awal karena rencana open source lintas negara.
• Waffle — file/attachment disimpan di disk lokal per node (tidak ada kebutuhan object storage cloud pada topologi ini).

3.12 Asset Pipeline & Offline Bundle

Menjelaskan bagaimana font & ikon (disebut Chapter 1) di-build dan di-deploy sebagai bundle offline.

• Bundling: Font Inter di-subset (Latin + Latin Extended) via fonttools pyftsubset, jadi .woff2; ikon Lucide tree-shaking (cuma yang dipakai) jadi SVG sprite; CSS Tailwind JIT dengan purge berdasar komponen Phoenix.
• Build output: semua di priv/static/assets/; nol request eksternal (tanpa Google Fonts/CDN ikon/analytics); service worker opsional v1, wajib v2.
• Versioning: asset fingerprinting via mix phx.digest; Cache-Control: immutable untuk asset hashed, must-revalidate untuk index.html.

3.13 Testing & Static Analysis

• Doctest (dokumentasi = test), Bypass (mock HTTP eksternal), Mox (mock kontrak internal), StreamData (property-based), Oban.Testing, Ash.Generator (data seed).
• CI single data layer: SQLite — tidak ada lagi test matrix lintas database.
• mix format, Credo (+ custom SDK compliance check), Dialyzer/Dialyxir (wajib di boundary SDK).
• LiveDebugger (dev-only) dan Phoenix.LiveView.Debug (aman untuk production, read-only) untuk debugging.

3.14 Deployment Profiles

Dua profil, disederhanakan dari desain sebelumnya setelah PostgreSQL/cloud dihapus dari scope.

Peran node di Profile 2

Ini koreksi penting dari desain sebelumnya: bukan semua komputer perlu instalasi penuh + sync-agent. Hanya laptop yang benar-benar berpindah lokasi (dan karenanya butuh kemampuan offline) yang menjalankan SQLite lokal dan sync-agent. PC kantor yang selalu berada di LAN cukup jadi client biasa ke server kantor — persis seperti aplikasi web internal pada umumnya, tanpa kompleksitas sync sama sekali.

Detail lengkap mekanisme sync-agent (komponen, alur, protokol, failure mode, keamanan) dibahas di Addendum.

3.15 Hierarki Pemilihan Dependency (kebijakan resmi)

Tier 1 Ash/Phoenix → Tier 2 Elixir umum → Tier 3 Erlang/OTP langsung. Di mana pun Ash punya ekstensi resmi (Ash*), itu selalu dipilih di atas library generik non-Ash. Non-Ash hanya dipakai untuk hal di luar cakupan Ash (Phoenix itu sendiri, LiveState, Swoosh, Waffle, sync-agent) — semuanya tetap murni ekosistem Erlang/Elixir/Rust resmi tanpa dependency berat di luar itu.

Rincian Library Tier 2 (Elixir Umum) yang Dikunci untuk BMP:

1. PDF Engine: tincture (pure Elixir). Menghasilkan PDF berkualitas tipografi tinggi (PDF/A untuk arsip, AES-256 untuk slip gaji) tanpa binary eksternal seperti wkhtmltopdf atau Chrome headless. Template PDF disimpan sebagai data XML, bukan HTML.
2. QR Code: eqrcode (pure Elixir, zero dependencies). Dipakai untuk men-generate QR code Batch ID pada label traceability CPKB (Modul Manufacturing & Sales). Output SVG-nya langsung di-embed ke dalam template tincture.
3. XLSX Export: exceed (pure Elixir, stream-oriented). Dipakai untuk mengekspor laporan berskala besar (misal: GL drill-down ribuan baris di Accounting, atau Sales Analytics tahunan) langsung ke format Excel .xlsx tanpa menyebabkan memory blow-up.
4. CSV Import/Export: nimble_csv (pure Elixir). Dipakai sebagai jalur utama ingest data massal, seperti import rekap CSV harian dari marketplace (Sales) dan import statement bank (Accounting).
5. Image Processing: DITOLAK. Kebutuhan manipulasi foto produk (resize, crop) dilayani di client-side (browser) atau tidak diperlukan sama sekali. Library populer seperti image (yang membungkus NIF libvips dari bahasa C) ditolak agar stack BMP tetap 100% pure BEAM tanpa risiko segmentation fault atau keharusan mengompilasi binary C di server produksi.
6. Email (Swoosh): DITUNDA. Sesuai keputusan arsitektur, pengiriman dokumen (Invoice/DN) di Fase 1 dilakukan manual (Save PDF → Gmail/WA). Integrasi SMTP otomatis ditunda ke Fase 2.

Addendum: Mekanisme Sync-Agent — Penjelasan Detail

1. Gambaran Besar

Sync-agent adalah proses Rust kecil yang berjalan di server kantor dan di tiap laptop mobile (bukan di PC kantor — lihat bagian 9). Tugasnya satu: memastikan perubahan data di SQLite laptop dan SQLite server kantor selalu sinkron, tanpa Ash app perlu tahu apa pun.

2. Komponen Utama

Diagram 1 — Komponen Sync-Agent

2.1 Session Manager

Bertanggung jawab atas capture perubahan dari SQLite: membuat SQLite Session via rusqlite (feature session), attach ke tabel-tabel yang perlu disinkronkan, merekam setiap INSERT/UPDATE/DELETE yang dilakukan Ash app, dan menghasilkan changeset (blob biner) saat flush dipanggil. Session Manager tidak mengintervensi Ash app sama sekali — Ash menulis ke SQLite seperti biasa, Session Extension merekam efeknya di belakang layar.

2.2 Flush Scheduler

Bertanggung jawab memutuskan kapan changeset diambil dan dikirim. Model koneksi: begitu laptop pertama kali terhubung ke server kantor, seluruh perubahan tertunda langsung di-flush dan disinkronkan penuh (initial full sync). Setelah itu, koneksi TCP+TLS dijaga tetap terbuka (persistent) — setiap ada perubahan baru, flush dipicu segera (event-driven), bukan menunggu timer. Timer berkala (5–10 detik) tetap dipertahankan sebagai heartbeat/fallback (menjaga koneksi hidup dan menangkap perubahan yang mungkin terlewat), bukan sebagai mekanisme utama.

• Initial connect → flush semua perubahan tertunda (full sync)
• Perubahan baru setelah connect → flush langsung (event-driven), koneksi tetap terbuka
• Timer heartbeat (5–10 detik) — fallback, menjaga koneksi & menangkap perubahan yang lolos
• Manual trigger via System Console (opsional)

2.3 Transport Layer

Bertanggung jawab mengirim dan menerima changeset antar node.

• Koneksi TCP + TLS (rustls) — wajib, termasuk untuk LAN kantor, karena data yang lewat adalah data finansial.
• Autentikasi: pre-shared key per instalasi, dikonfigurasi saat setup awal.
• Laptop selalu menginisiasi koneksi ke server kantor — bukan sebaliknya.
• Format: length-prefixed binary frame — [4 bytes: panjang payload][N bytes: changeset blob]
• Handle retry, backoff eksponensial, dan koneksi putus.

2.4 Apply Engine

Bertanggung jawab menerapkan changeset yang diterima ke SQLite lokal: memanggil sqlite3changeset_apply() via rusqlite, menjalankan conflict handler per baris per tabel, dan mengirim ACK ke pengirim setelah berhasil.

2.5 State Manager

Bertanggung jawab menyimpan status sync — high_water_mark (offset changeset terakhir yang berhasil di-ACK, berfungsi sebagai sync cursor), schema_version (versi schema SQLite saat ini), last_synced_at, dan peer_status (reachable/unreachable). Disimpan di file lokal kecil terpisah (bukan di SQLite utama) agar tidak tercampur dengan data bisnis.

2.6 Telemetry Publisher

Mempublikasikan metrik ke Elixir lewat named pipe/Unix socket — event :telemetry (sync.changeset.sent, sync.changeset.applied, sync.conflict.resolved, sync.lag_seconds) yang dikonsumsi System Console BMP untuk menampilkan status sync per node.

3. Alur Lengkap: Laptop ke Server Kantor

Diagram 2 — Alur Lengkap Sync (Laptop → Server → Laptop)

Fase 1 — Capture

Ash app (exqlite) menulis ke SQLite (WAL mode) seperti biasa — INSERT/UPDATE/DELETE apa pun. Session Manager (rusqlite + session feature) merekam semua perubahan secara otomatis di belakang layar.

Fase 2 — Flush

Dipicu oleh perubahan baru (event-driven, koneksi persistent), timer heartbeat, peer baru terdeteksi, atau manual trigger. Session Manager memanggil sqlite3session_changeset() dan menghasilkan changeset blob biner.

Fase 3 — Transport

Transport Layer di laptop mengecek peer reachable, membuka (atau memakai) koneksi TCP+TLS ke server kantor, mengirim schema_version untuk verifikasi, mengirim changeset dalam frame length-prefixed, lalu menunggu ACK.

Fase 4 — Apply di Server

Server menerima frame, memverifikasi schema_version (tidak cocok → tolak koneksi, kirim error), lalu meneruskan ke Apply Engine yang memanggil sqlite3changeset_apply() dengan conflict handler:

• Ledger transaksional — UNIQUE conflict (ref_doc + sku) → OMIT (skip, bukan error).
• Master/state — version incoming > lokal → REPLACE; version sama/lebih lama → OMIT atau flag manual review.

Berhasil → kirim ACK. Gagal → kirim NACK + alasan.

Fase 5 — Konfirmasi & State Update

Laptop menerima ACK → update high_water_mark, update last_synced_at, publish telemetry (sync.changeset.sent + applied). Menerima NACK → log error, retry dengan backoff eksponensial, publish telemetry sync.conflict.manual bila perlu.

Fase 6 — Sync Balik (Server → Laptop)

Setelah ACK terkirim, server melakukan hal yang sama: flush session server (perubahan dari user kantor), kirim changeset ke laptop, laptop apply lalu kirim ACK balik. Ini yang membuat sync dua arah berjalan dalam satu koneksi persistent yang sama — bukan dua koneksi terpisah.

4. Conflict Resolution

Diagram 3 — Conflict Resolution per Jenis Tabel

5. Failure Mode & Recovery

Diagram 4 — Failure Mode & Recovery

• Crash sebelum kirim: changeset sudah dibuat tapi sync-agent crash sebelum terkirim → restart, baca high_water_mark, session baru dibuat ulang, perubahan yang sama terekam lagi, kirim ulang — conflict handler OMIT menangani duplikat. Data aman.
• Crash setelah kirim, sebelum ACK: server sudah apply, tapi sync-agent laptop crash sebelum terima ACK → restart dengan high_water_mark belum ter-update → kirim ulang changeset yang sama → server terima duplikat, conflict handler OMIT — tidak ada kerusakan data.
• Laptop offline lama: session terus merekam perubahan lokal selama offline. Begitu laptop kembali ke LAN kantor dan sync-agent mendeteksi peer reachable, semua perubahan tertunda di-flush dan dikirim (dalam beberapa batch bila changeset besar); server apply semua batch, lalu kirim balik changeset perubahan kantor selama laptop offline. Kedua node kembali sinkron.

6. Catatan Penting Operasional

WAL Mode wajib — semua SQLite yang terlibat harus dikonfigurasi:

PRAGMA journal_mode=WAL; PRAGMA busy_timeout=5000; Tanpa ini, Ash app dan sync-agent bisa saling block saat menulis bersamaan.

CHECK Constraint wajib — karena apply changeset bypass Ash action, business rule kritikal harus ada di level SQLite, bukan hanya di validasi Ash: CHECK (qty >= 0) CHECK (amount > 0)

Schema Version wajib — setiap migrasi Ash harus menaikkan schema_version di metadata database. Sync-agent membaca ini sebelum menerima koneksi apa pun, dan menolak sync jika versi laptop dan server tidak cocok (urutan upgrade: server kantor dulu, baru laptop — selama laptop belum di-upgrade, sync berhenti sementara, bukan corrupt).

Penguatan (v2.0) — konteks offline-first UI:

• Sync scope: master data wajib full; transaksi hanya periode aktif; report tidak di-sync, dihitung ulang saat online.
• Conflict resolution: berbasis anchor_id (bukan last-write-wins) — tabrakan anchor_id di-flag sebagai Sync Conflict untuk direview manual, tidak ditolak otomatis dan tidak ditimpa diam-diam; master data tetap manual merge.
• UI state sync: rail collapsed, density, saved views — sync via JSON ringan, terpisah dari mekanisme data bisnis.
• Offline indicator: dot koneksi di header (sudah ada di mockup) — harus terhubung ke status sync-agent sungguhan, bukan dekorasi statis.

Anchor ID — Deteksi Konflik Non-LWW (v2.0):

Menggantikan last-write-wins untuk seluruh tabel event/transaksional (bukan cuma draft) — setiap event yang di dunia nyata punya dokumen penyerta (invoice supplier, nomor produksi, surat jalan, dsb.) wajib mencatat identitas itu lewat 1 kolom tambahan.

Formula: anchor_id = short_hash(entity_type + nomor_dokumen_penyerta + tanggal_event). Contoh: barang masuk dari invoice INV-88214 tanggal 12 Agu 2026 → short_hash("goods_receipt|INV-88214|2026-08-12"); produksi batch PRD-0451 tanggal 15 Agu 2026 → short_hash("production|PRD-0451|2026-08-15").

Ditegakkan lewat UNIQUE(anchor_id) per tabel (Invariant #11) — dua laptop offline yang mencatat kejadian bisnis yang sama akan menghasilkan anchor_id identik, sehingga tabrakan kelihatan saat sync (bukan salah satu diam-diam kalah lewat timestamp).

Penanganan tabrakan: di-flag sebagai Sync Conflict untuk direview manual (Manager/Admin terkait) — tidak ditolak otomatis dan tidak ditimpa diam-diam, konsisten dengan prinsip “yang pengecualian dibuat terlihat” (BMP Reason).

Cakupan: seluruh tabel event/transaksional yang punya dokumen penyerta di dunia nyata — bukan cuma goods receipt dan production yang jadi contoh; setiap resource baru wajib dicek apakah dia kandidat anchor_id saat didesain.

Chapter 4: Data Model & Table Specifications

Bab ini menjawab pertanyaan "apa" — skema database lengkap untuk implementasi
Ash Framework. Rasional di balik tiap keputusan besar (kenapa Customer = channel,
kenapa stok tidak boleh negatif, kenapa IT tidak bisa baca field rahasia, dst) ada
di dokumen pendamping BMP Reason*. Konvensi penulisan kode yang mengikuti
skema ini ada di Chapter 5 (Development Conventions).*

Status: 🔒 Final / Mengikat
Dasar: Chapter 3 (Architecture) · BMP Reason · Data Model v1.6
Tujuan: Blueprint tunggal untuk implementasi database dan resource Ash Framework
Versi: 1.7 (Upgrade dari v1.6 — menuntaskan 2 refactor struktural dari Cross-Check v1.5 yang sempat terlewat)

Changelog v1.7 (vs v1.6):

1. ➕ Tabel baru departments (§1.19) — master departemen (Finance & Accounting, HR & GA, Production, Sales, Marketing, Technical Support, IT Support, Quality), menggantikan string bebas.

2. 🔧 employees.department (string) → employees.department_id (UUID → departments).

3. ➕ Tabel baru roles (§10.8) dan user_roles (§10.9, junction many-to-many) — menggantikan users.roles (JSONB).

4. 🔧 permissions.role (string bebas) → permissions.role_id (UUID → roles).

5. 🔧 users — kolom roles (JSONB) dihapus, digantikan relasi lewat user_roles.

4.1. Master Data

4.1.1 companies

4.1.2 accounts (Chart of Accounts)

Akun Beban Wajib untuk Komponen Fee:

4.1.3 cost_centers

Catatan: Cost Center hide dari UI untuk user operasional. Hanya Owner/Finance yang melihatnya.

4.1.4 fiscal_years

4.1.5 accounting_periods

Catatan: Accounting Period hide dari UI sampai ada kebutuhan tutup buku formal.

4.1.6 items (Master Produk)

4.1.7 item_groups

4.1.8 customers

Catatan: Customer di BMP = Channel Marketplace (Shopee, Tokopedia, TikTok Shop). Setiap Customer/channel memiliki 1 Sales Person penanggung jawab (lihat 1.17 sales_persons).

4.1.9 customer_groups

4.1.10 suppliers

4.1.11 supplier_groups

4.1.12 warehouses

Warehouse Zoning BMP:

• FG Store (Finished Goods layak jual)
• RM Store (Raw Material)
• Packaging Store
• Quarantine (menunggu QC)
• Maturing Zone (Bulk maturing)
• Mixing Area (Area produksi)
• Rejected (Barang reject)
• Scrap (Barang rusak)

4.1.13 uoms (Unit of Measure)

4.1.14 uom_conversions

4.1.15 price_lists

Catatan Penting: BMP hanya menggunakan 1 Price List ("Harga Dasar — IDR"). Semua variasi harga (diskon, markup) ditangani oleh Fee Components (lihat bagian 5.2).

4.1.16 item_prices

4.1.17 sales_persons

Catatan: sales_persons = pandangan "fungsi Sales" atas karyawan; identitas tunggal tetap di employees. 1 Customer/channel → 1 sales_person_id; sales_orders.sales_person_id menyimpan snapshot PIC saat transaksi (histori kontribusi tahan rotasi).

4.1.18 numbering_series ➕ v1.6 (BARU)

Catatan: Numbering series terdefinisi kode per instalasi (§4.11). Tidak ada DDL runtime. Dokumen cancel menyimpan nomornya (tidak dipakai ulang).

4.1.19 departments ➕ v1.7 (BARU)

Catatan: Master departemen — formalisasi dari org chart (8 departemen: Finance & Accounting, HR & GA, Production, Sales, Marketing, Technical Support, IT Support, Quality). Semua departemen melapor langsung ke Direktur (§ org chart), jadi tidak butuh parent_id/tree.

4.2 Inventory & Stock

4.2.1 batches

4.2.2 stock_entries

4.2.3 stock_entry_items

4.2.4 stock_ledger_entries (SLE) — Immutable

4.2.5 bins (Agregasi Stok)

MATERIALIZED VIEW (v1.5): bins adalah derived state — diisi ulang dari stock_ledger_entries + order terbuka; bukan source of truth dan tidak menerima write langsung. actual_qty = SUM(qty_change) per item+warehouse; valuation_rate = rate SLE terakhir; projected_qty = actual + incoming terbuka − outgoing terbuka; reserved_qty = reservasi aktif. Rebuildable kapan pun via aksi Repost / job Oban (konsisten Architecture Invariant #8: derived state selalu rebuildable dari ledger).

4.2.6 stock_reservations ➕ v1.6 (BARU)

Catatan: Tabel untuk reservasi stok aktif. Dihitung dalam projected_qty bins.

4.3 Purchase

4.3.1 purchase_orders

4.3.2 purchase_order_items

4.3.3 purchase_receipts

4.3.4 purchase_receipt_items

4.3.5 purchase_invoices

4.3.6 purchase_invoice_items

4.3.7 material_requests

4.3.8 landed_cost_vouchers

4.3.9 landed_cost_voucher_items

4.4 Manufacturing

4.4.1 boms (Bill of Materials)

4.4.2 bom_items

4.4.3 operations

4.4.4 work_orders

4.4.5 work_order_operations

4.4.6 production_plans

4.4.7 production_plan_items

4.5 Sales

4.5.1 Core Sales Tables

4.5.1.1 sales_orders

Catatan Dedup Key:

• Untuk mencegah double import CSV, digunakan kombinasi unik: (customer_id, item_id, posting_date).
• Sales Person tidak masuk dedup key (channel yang sama tetap 1 baris rekap per hari meski PIC-nya berganti); sales_person_id cuma mencatat siapa yang bertanggung jawab saat itu, dipakai untuk laporan kontribusi per staf.
• v1.6: Kolom dedup_hash menyimpan hash SHA-256 dari kombinasi dedup key untuk pencarian cepat dan validasi unik di database.

4.5.1.2 sales_order_items

4.5.1.3 delivery_notes

4.5.1.4 delivery_note_items

4.5.1.5 sales_invoices

4.5.1.6 sales_invoice_items

4.5.2 Fee Components & Configuration

Filosofi Desain:

BMP menggunakan 1 Price List ("Harga Dasar — IDR"). Semua variasi harga (diskon, markup) ditangani oleh Fee Components.

5.2.1 customer_fee_components (Master Jenis Biaya)

Catatan: Tabel ini adalah master data yang mendefinisikan jenis biaya. Tidak memiliki relasi langsung ke customers karena satu jenis biaya bisa digunakan oleh banyak customer (reusable).

5.2.2 customer_fee_configs (Konfigurasi Biaya per Customer)

Catatan: Tabel ini adalah pivot table yang menghubungkan Customer dengan Komponen Biaya dan menentukan nilai biaya yang berlaku untuk customer tersebut. Relasi langsung ke customers ada di sini.

4.5.3 Fee Snapshots

Catatan: sales_order_fees adalah tabel snapshot yang menyimpan biaya aktual pada saat Sales Order dibuat. Ini menjaga histori tetap akurat meskipun ada perubahan fee di masa depan (prinsip immutability akuntansi).

4.5.3.1 sales_order_fees

4.6 Accounting

4.6.1 Core Accounting

4.6.1.1 journal_entries

4.6.1.2 journal_entry_items

4.6.1.3 gl_entries (General Ledger) — Immutable

4.6.1.4 payment_ledger_entries

4.6.1.5 payment_terms_templates — TABEL BARU (Hide)

4.6.1.6 payment_schedules — TABEL BARU (Hide)

4.6.2 Payment & Banking

4.6.2.1 modes_of_payment — TABEL BARU

4.6.2.2 payment_entries

4.6.2.3 payment_entry_deductions — TABEL BARU

Catatan: Pengganti JSONB deductions untuk memudahkan agregasi laporan.

4.6.2.3a payment_entry_references — BARU

(payment_entry_deductions §6.2.3 tetap — kini satu-satunya rumah deduksi.)

4.6.2.4 banks — TABEL BARU (Hide)

6.2.5 bank_accounts — TABEL BARU (Hide)

4.6.2.6 bank_transactions — TABEL BARU (Hide)

4.6.3 Tax & Withholding

4.6.3.1 taxes_templates (Sales & Purchase)

4.6.3.2 tax_template_items

4.6.3.3 tax_withholding_categories

4.6.3.4 tax_withholding_entries — TABEL BARU

4.6.4 Budget & Period

4.6.4.1 budgets — TABEL BARU (Hide)

6.4.2 budget_items — TABEL BARU (Hide)

6.4.3 monthly_distributions — TABEL BARU (Hide)

4.7 Quality

4.7.1 quality_inspections

4.7.2 quality_templates

4.7.3 non_conformances

4.8 Asset

4.8.1 asset_categories

4.8.2 assets

4.8.3 asset_depreciation_schedules

4.8.4 asset_movements

4.8.5 asset_repairs

4.8.6 asset_maintenances

4.8.7 asset_maintenance_logs

4.9 HR (Minimalis)

4.9.1 employees

4.9.2 attendances

4.9.3 leave_types

4.9.4 leave_allocations