# 🏛️ SYSTEM BLUEPRINT: DUAL-TRACK WATERFALL TAX LEDGER ARCHITECTURE
## Universal Commercial Receivables & Tax Harmonization Engine for Multi-Tier ERP Systems
### Standard Operasional & Logika Otak AI (Universal AI-Ready Brain Document)

> [!IMPORTANT]
> **PANDUAN OPERASIONAL AI (AI AGENT DIRECTIVE):**  
> Dokumen ini adalah cetak biru arsitektur mandiri (*self-contained blueprint*) yang berfungsi sebagai **"otak sistem"** bagi AI Agent (Antigravity, ChatGPT, Claude, atau LLM lainnya) maupun Software Architect.
> 
> Saat menangani modul **Penjualan (Sales Order)**, **Distribusi / Surat Jalan (Fulfillment)**, **Invoicing / Piutang (A/R)**, **Kasir (Cashier/Banking)**, dan **Pajak (Tax / e-Faktur)** di perusahaan mana pun, AI **DILARANG MENGUBAH KODE ATAU MERANCANG SISTEM** sebelum membaca dan mematuhi seluruh aksioma, protokol *Interactive Grill-Me*, dan algoritma *waterfall* di dalam berkas ini.

---

## 1. PENDAHULUAN & LATAR BELAKANG MASALAH

Pada banyak sistem ERP konvensional, integrasi antara nilai komersial penjualan dan kewajiban perpajakan sering mengalami kegagalan sistemik (*systemic failure*), terutama saat transaksi melibatkan **Uang Muka (Down Payment)**, **Pembayaran Bertahap (Termin/Installment)**, atau **Pengiriman Parsial (Split Delivery)**.

### Pola Kesalahan Fatal yang Sering Terjadi:
1. **Asumsi Buta "Include Pajak":** Sistem secara keliru menganggap setiap angka penerimaan kas atau sisa tagihan pasti sudah termasuk pajak, lalu membaginya secara paksa dengan `1 + tarif` (misal membagi `1.11`). Hal ini menggerus nilai DPP yang sebenarnya murni dan menghasilkan angka desimal ganjil.
2. **"Make-Up Logic" di View Controller:** Lapisan tampilan (*view*) dipaksa bertindak sebagai mesin hitung darurat yang mereka-reka (*reverse engineer*) potongan uang muka secara instan, bukan membaca saldo hakiki dari basis data (*Single Source of Truth*).
3. **Kekacauan Pengiriman Parsial:** Sistem tidak tahu uang muka memotong surat jalan yang mana ketika pesanan dikirim bertahap dalam beberapa kali pengiriman.
4. **Kebutaan terhadap Pembatalan Faktur (*Tax Rejection Blindness*):** Sistem komersial menganggap uang muka masih memotong pajak, padahal faktur pajak uang mukanya telah dibatalkan (*reject*) oleh petugas pajak di DJP.

Arsitektur **Dual-Track Waterfall Tax Ledger** dirancang untuk menyelesaikan seluruh masalah di atas secara tuntas, matematis, dan terstandarisasi.

---

## 2. TIGA AKSIOMA DASAR SISTEM (THE 3 INVARIANT AXIOMS)

Setiap implementasi kode wajib tunduk pada 3 aksioma mutlak berikut:

### ⚡ Aksioma 1: Pemisahan Saldo Hakiki (Dual-Track Separation)
* Nilai transaksi dasar penjualan barang/jasa adalah **DPP (Dasar Pengenaan Pajak)**, yaitu hak komersial bersih perusahaan atas penyerahan barang/jasa.
* Nilai **PPN (Pajak Pertambahan Nilai)** adalah titipan penerimaan negara yang perhitungannya mengikat pada DPP, bukan angka bruto yang dibagi-bagi secara arbitrer di hilir.
* Sistem **WAJIB** memelihara dua saldo independen yang berjalan berpasangan: **Track DPP** dan **Track PPN**. Dilarang mencampurnya menjadi satu nilai skalar tunggal pada tabel integrasi *bus data*.

### ⚡ Aksioma 2: Integritas Jalur Baca Pasif (Passive Read-Path Integrity)
* Lapisan presentasi (*View* / *viewResume Controller*) **HANYA BOLEH MEMBACA** status saldo riil yang sudah sah tersimpan di basis data (*Single Source of Truth*).
* Dilarang keras melakukan manipulasi aritmatika pemotongan uang muka atau pembagian tarif pajak di dalam *view controller*. Jika data di layar salah, yang diperbaiki adalah *write-path* saat approval transaksi, bukan menambal rumus di *view*.

### ⚡ Aksioma 3: Dua Tahap Siklus Pajak (Two-Tier Tax Lifecycle)
* **Tier 1 - Tahap Komitmen (Saat Sales Order Terbit):**  
  Sistem membentuk *Tax Commitment Schedule* (pagasi komitmen pajak yang belum terutang secara hukum). Nomor faktur fisik belum diterbitkan ke kantor pajak (DJP) karena penyerahan fisik dan pembayaran belum terjadi.
* **Tier 2 - Tahap Realisasi Fiskal (Saat Kas Masuk atau Barang Dikirim):**  
  Faktur Pajak resmi (e-Faktur) baru terbit sah secara hukum saat ada pemicu (*trigger*):
  * Kas masuk mendahului penyerahan &rarr; Terbit Faktur Pajak Uang Muka.
  * Barang diserahkan &rarr; Terbit Faktur Pajak Penyerahan / Pelunasan.

---

## 3. PROTOKOL WAJIB: INTERACTIVE "GRILL-ME" (BUSINESS POLICY DISCOVERY)

Sebelum menulis kode atau konfigurasi modul, AI Agent / Software Architect **WAJIB mewawancarai (*GRILL-ME*)** pemilik sistem atau analis bisnis menggunakan 4 pertanyaan kunci berikut guna menentukan profil kebijakan perusahaan:

```
┌─────────────────────────────────────────────────────────────────────────────┐
│               INTERACTIVE "GRILL-ME" DECISION MATRIX                        │
├─────────────────────────────────────────────────────────────────────────────┤
│ Q1: Tax Timing Policy    ──> [A] Kaku (Strict)   vs [B] Fleksibel (Deferred)│
│ Q2: Cashier Enforcement  ──> [A] Terkunci Otomatis vs [B] Sakelar Manual    │
│ Q3: Journal Policy       ──> [A] Komitmen Bersih vs [B] Cadangan PPN        │
│ Q4: Tax Rejection Action ──> [A] Auto-Rollback   vs [B] Strict Audit Lock   │
└─────────────────────────────────────────────────────────────────────────────┘
```

### ❓ Pertanyaan 1: Kebijakan Waktu Pengakuan Pajak (*Tax Timing Policy*)
> *"Bagaimana kebijakan perpajakan perusahaan Anda saat menerima uang muka / cicilan?"*

* **Profil A [Mode Kaku / Strict Pay-as-you-go]:**  
  Setiap kas masuk (Uang Muka / Termin), PPN **wajib dipungut dan dilaporkan saat itu juga** di masa pajak berjalan (sesuai Pasal 13 ayat 1a UU PPN).  
  *Konsekuensi:* Terbit Faktur Pajak Uang Muka resmi (`EF-UM`). Faktur pelunasan akhir hanya menagih sisa PPN penyerahan.
* **Profil B [Mode Fleksibel / Tax Deferred to Final Settlement]:**  
  Uang muka diperlakukan sebagai **setoran pokok murni (DPP)**. Pajak ditangguhkan, dan seluruh kewajiban PPN baru ditagihkan serta dilaporkan secara penuh pada saat penyerahan barang / faktur pelunasan akhir.  
  *Konsekuensi:* Saat DP masuk tidak ada faktur pajak terbit. Faktur pelunasan menagih sisa pokok **ditambah seluruh PPN kontrak**.
* **Profil C [Mode WAPU / Bendaharawan Pemerintah / BUMN]:**  
  Pelanggan memungut PPN sendiri. Kasir hanya menagih DPP murni; PPN dialihkan ke piutang SPM/WAPU.

### ❓ Pertanyaan 2: Kontrol Validasi Form Kasir (*Cashier Input Enforcement*)
> *"Apakah kasir dikunci oleh sistem atau diberi keleluasaan menentukan perlakuan pajak?"*

* **Opsi A [Locked Automation]:** Kasir tidak memilih. Sistem otomatis menghitung pajak berdasarkan master data pelanggan dan katalog barang.
* **Opsi B [Operator Toggle Selection]:** Kasir memiliki tombol pilihan di form:  
  `[ ] Uang Muka Sudah Termasuk Pajak (Include)`  
  `[ ] Uang Muka Pokok Murni Tanpa Pajak (Exclude)`  
  `[ ] Uang Muka Non-BKP / Bebas Pajak`

### ❓ Pertanyaan 3: Perlakuan Jurnal Akuntansi atas Pajak Ditangguhkan (*Journal Ledger Policy*)
> *"Jika uang muka diterima tanpa pajak (Profil B), bagaimana pencatatan akuntansinya?"*

* **Metode A [Komitmen Bersih / Net Liability]:**  
  `[Debet] Kas` vs `[Kredit] Uang Muka Konsumen` sebesar uang masuk. Seluruh PPN baru dicatat saat faktur penyerahan terbit.
* **Metode B [Cadangan PPN Ditangguhkan / Accrued Tax Exposure]:**  
  `[Debet] Kas` (Rp 2,5 jt) + `[Debet] Piutang PPN Ditangguhkan` (Rp 275 rb) vs `[Kredit] Uang Muka` (Rp 2,5 jt) + `[Kredit] Hutang PPN Belum Ada Faktur` (Rp 275 rb).

### ❓ Pertanyaan 4: Penanganan Pembatalan Faktur DP (*Tax Reversal Protocol*)
> *"Jika faktur pajak uang muka dibatalkan oleh DJP, apa tindakan sistem terhadap tagihan kasir?"*

* **Opsi A [Auto-Rollback to Deferred Tax]:** PPN uang muka yang batal otomatis ditambahkan kembali menjadi piutang pada tagihan pelunasan akhir.
* **Opsi B [Strict Audit Lock]:** Sistem mengunci proses pelunasan komersial sampai tim pajak menerbitkan faktur pengganti yang sah.

---

## 4. STRUKTUR ARSITEKTUR DUAL-TRACK LEDGER

```
┌─────────────────────────────────────────────────────────────────────────────┐
│ TRACK 1: COMMERCIAL DPP LEDGER (Hak Pendapatan Barang & Jasa)               │
├─────────────────────────────────────────────────────────────────────────────┤
│ Nilai Kontrak DPP (SO)               : DPP_TOTAL                            │
│ Alokasi Uang Muka Pokok (DPP)        : - DPP_DP                             │
│ ─────────────────────────────────────────────────────────────────────────── │
│ SISA HAK TAGIH POKOK PENYERAHAN      : = DPP_SISA                           │
│ Alokasi Penyerahan Parsial / Akhir   : - DPP_DELIVERED                      │
│ SALDO AKHIR DPP                      : = 0.00 (LUNAS)                       │
└─────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│ TRACK 2: FISCAL PPN LEDGER (Kewajiban Pelaporan SPT e-Faktur DJP)           │
├─────────────────────────────────────────────────────────────────────────────┤
│ Pagu Kewajiban PPN (Tarif x DPP_TOTAL): PPN_TOTAL                           │
│ Realisasi Faktur Pajak Uang Muka      : - PPN_DP_REALIZED                   │
│ ─────────────────────────────────────────────────────────────────────────── │
│ SISA KEWAJIBAN PPN TERUTANG          : = PPN_SISA                           │
│ Realisasi Faktur Pajak Pelunasan     : - PPN_FINAL_REALIZED                 │
│ SALDO AKHIR PPN                      : = 0.00 (TERLAPOR PENUH)              │
└─────────────────────────────────────────────────────────────────────────────┘
```

---

## 5. ALGORITMA PENYERAPAN AIR TERJUN (WATERFALL DRAWDOWN)

Ketika Uang Muka (DP) diterima, sistem mencatatnya sebagai **Kantong Saldo DP (*DP Bucket*)**. Penyerapan saldo DP terhadap surat jalan / invoice penyerahan mengikuti algoritma air terjun berikut:

```
Inisialisasi:
    Saldo_DP_Tersedia = Nilai_DP_Diterima;

Untuk Setiap Penyerahan Barang (Surat Jalan ke-i):
    Nilai_Penyerahan_i = Subtotal_DPP_Barang_i;
    
    JIKA Saldo_DP_Tersedia >= Nilai_Penyerahan_i MAKA:
        DP_Diserap_i       = Nilai_Penyerahan_i;
        Saldo_DP_Tersedia  = Saldo_DP_Tersedia - Nilai_Penyerahan_i;
        Tagihan_Netto_i    = 0.00;
        Keterangan_i       = "Lunas Penuh tertutup Uang Muka";
        
    SELAIN ITU (Saldo_DP_Tersedia < Nilai_Penyerahan_i):
        DP_Diserap_i       = Saldo_DP_Tersedia;
        Tagihan_Netto_i    = Nilai_Penyerahan_i - Saldo_DP_Tersedia;
        Saldo_DP_Tersedia  = 0.00;
        Keterangan_i       = "Faktur Pelunasan Bersih (Netto Tagihan)";
```

*Keunggulan:* Berapapun kali barang dipecah kirim (*split shipment*), sistem tidak pernah mengalami salah hitung atau saldo gantung.

---

## 6. SIMULASI KANONIKAL KASUS RIIL (GROUND TRUTH VERIFICATION)

Berikut adalah studi kasus standar industri untuk menguji validitas sistem:

### Data Kontrak & Transaksi:
* **Nilai Dasar Penjualan (DPP Murni):** **Rp 4.100.000**
  * Bracket Mounting 4x8 : 4 unit x @Rp 150.000 = Rp 600.000
  * Bracket Hoda 0.5-1.5 : 4 unit x @Rp 100.000 = Rp 400.000
  * Jasa Pasang 1.5 PK   : 6 unit x @Rp 400.000 = Rp 2.400.000
  * Jasa Pasang 1 PK     : 2 unit x @Rp 350.000 = Rp 700.000
* **Tarif Pajak PPN:** 11% &rarr; **Total PPN Kontrak:** $11\% \times 4.100.000 = \mathbf{Rp\ 451.000}$
* **Total Hakiki Nilai Kontrak (DPP + PPN):** $4.100.000 + 451.000 = \mathbf{Rp\ 4.551.000}$
* **Uang Muka Diterima Kasir:** **Rp 2.500.000** *(Dikonfirmasi: Murni Pokok tanpa pajak / Exclude PPN)*.

---

### Perhitungan Hari Pelunasan (Settlement Day Calculation)

Karena total hakiki kontrak adalah **Rp 4.551.000** dan konsumen baru menyetor pokok **Rp 2.500.000**, maka total uang kas yang **WAJIB DIBAYAR KONSUMEN HARI INI** adalah:

$$\text{Tagihan Pelunasan Hari Ini} = Rp\ 4.551.000 - Rp\ 2.500.000 = \mathbf{Rp\ 2.051.000}$$

### Dekomposisi 3 Unsur Tagihan Rp 2.051.000:
1. **Sisa Pokok Penyerahan (Sisa DPP):**  
   $$4.100.000 - 2.500.000 = \mathbf{Rp\ 1.600.000}$$
2. **PPN atas Sisa Penyerahan Barang/Jasa (11% x Sisa DPP):**  
   $$11\% \times 1.600.000 = \mathbf{Rp\ 176.000}$$
3. **PPN atas Uang Muka yang Tertunggak (11% x DP Pokok):**  
   $$11\% \times 2.500.000 = \mathbf{Rp\ 275.000}$$

$$\mathbf{Total\ Pelunasan} = 1.600.000 + 176.000 + 275.000 = \mathbf{Rp\ 2.051.000}$$

---

### ⚠️ Pembongkaran Kesalahan Fatal Sistem Lama:
* **Yang Dilakukan Sistem Lama:**  
  Sistem lama menganggap angka sisa Rp 1.600.000 adalah angka *include PPN*, lalu membaginya dengan `1.11`:  
  $\text{DPP Palsu} = \frac{1.600.000}{1,11} = \mathbf{Rp\ 1.441.441,44}$  
  $\text{PPN Palsu} = 1.600.000 - 1.441.441,44 = \mathbf{Rp\ 158.558,56}$  
  Dan harga satuan barang di tabel fisik dipaksa dibagi 1.11 (@135.135, @90.090, @360.360, @315.315), sehingga perkalian baris menjadi rusak visual ($4 \times 135.135 \neq 600.000$).
* **Koreksi Dual-Track Waterfall:**  
  Angka Rp 1.600.000 adalah **Sisa DPP murni**. Tidak boleh dibagi 1.11! Harga satuan barang tetap utuh sesuai harga jual aslinya (@150.000, @100.000, @400.000, @350.000).

---

## 7. STRUKTUR DATA INTEGRATION BUS (`transaksi_payment_source`)

Untuk mendukung arsitektur ini, tabel perantara integrasi (*integration bus table*) wajib memiliki kolom *dual-track* definitif:

```sql
ALTER TABLE transaksi_payment_source 
ADD COLUMN dpp_tagihan       DECIMAL(15,2) NOT NULL DEFAULT 0.00 COMMENT 'DPP Hak Komersial Asal',
ADD COLUMN ppn_tagihan       DECIMAL(15,2) NOT NULL DEFAULT 0.00 COMMENT 'PPN Terutang Asal',
ADD COLUMN dpp_terbayar      DECIMAL(15,2) NOT NULL DEFAULT 0.00 COMMENT 'DPP yang Sudah Teralokasi',
ADD COLUMN ppn_terbayar      DECIMAL(15,2) NOT NULL DEFAULT 0.00 COMMENT 'PPN yang Sudah Difakturkan/Dibayar',
ADD COLUMN dpp_sisa          DECIMAL(15,2) NOT NULL DEFAULT 0.00 COMMENT 'Sisa Saldo DPP Belum Lunas',
ADD COLUMN ppn_sisa          DECIMAL(15,2) NOT NULL DEFAULT 0.00 COMMENT 'Sisa Saldo PPN Belum Terbit/Lunas',
ADD COLUMN tax_inclusivity   ENUM('INCLUDE', 'EXCLUDE', 'NON_TAX') NOT NULL DEFAULT 'INCLUDE',
ADD COLUMN tax_timing_mode   ENUM('STRICT', 'DEFERRED', 'WAPU') NOT NULL DEFAULT 'STRICT';
```

---

## 8. ATURAN PENULISAN KODE UNTUK AI AGENT (AI CODING DIRECTIVES)

Setiap AI Agent yang membuat atau memperbarui kode modul transaksi wajib mematuhi panduan ini:

1. **Dilarang Rumus Pembagian 1.11 Statis:**  
   Dilarang menulis `$dpp = $nilai / 1.11;` secara serampangan. Pembagian tarif hanya sah jika data transaksi memiliki atribut terverifikasi `tax_inclusivity == 'INCLUDE'`. Jika `tax_inclusivity == 'EXCLUDE'`, nilai tersebut adalah DPP itu sendiri.
2. **Atomic Write-Path:**  
   Setiap eksekusi transaksi di `Create.php` atau `FollowUp.php` wajib memutakhirkan saldo `dpp_sisa` dan `ppn_sisa` secara berpasangan dalam satu transaksi database atomik (`$this->db->trans_start()` / `$this->db->trans_complete()`).
3. **Passive Read-Path di View:**  
   Fungsi `viewResume()` pada controller mana pun dilarang menghitung ulang pemotongan uang muka di memori PHP. View hanya bertugas merender kolom `dpp_sisa`, `ppn_sisa`, dan `sisa` yang diambil langsung dari basis data.
4. **Preservasi Tabel Rincian Barang:**  
   Kolom harga satuan (`Price`) di tabel barang wajib menampilkan harga satuan DPP asli tanpa didiskon oleh rumus pembagian PPN, agar perkalian visual $\text{Qty} \times \text{Price} = \text{Sub-Amount}$ selalu valid dan terpercaya.
5. **Tax Void / Reversal Awareness:**  
   Sistem wajib mendeteksi status dokumen penolakan pajak (`110rrj` / status reject). Jika faktur uang muka berstatus batal, sistem wajib memperingatkan kasir bahwa PPN uang muka tersebut belum sah terdaftar di DJP.

---

## 9. KESIMPULAN ARSITEKTUR

Dengan menerapkan **Dual-Track Waterfall Tax Ledger**:
1. Seluruh cabang perusahaan dan jenis bisnis (kaku maupun fleksibel) dapat terakomodasi melalui parameterisasi *Interactive Grill-Me*.
2. Integritas data terjamin sejak hulu (SO) hingga hilir (e-Faktur & Kasir) tanpa ada logika tambal-sulam di lapisan antarmuka.
3. Kepatuhan terhadap kaidah perpajakan DJP dan standar akuntansi PSAK 72 terpenuhi 100%.

