# 📄 BLUEPRINT: Implementasi Modul "Clean Invoice" (Amandemen Transaksi)

## 1. Latar Belakang & Tujuan
**Konteks Bisnis:** Dalam transaksi B2B di Indonesia, konsumen seringkali menolak dokumen *Credit Note / Nota Retur* jika terjadi perubahan harga atau pembatalan item pada saat penagihan. Konsumen mensyaratkan **"Clean Invoice"** (Faktur Baru yang nominalnya sudah disesuaikan, tanpa coretan/jejak revisi).
**Masalah Sistem:** Dokumen Invoice berada di ujung fase (Fase 5). Membatalkan (Void) Invoice berarti harus meruntuhkan 4 fase sebelumnya (Surat Jalan, Packing, Picking, DO), yang mana tidak mungkin dilakukan karena barang fisik sudah terkirim.
**Tujuan Solusi:** Memberikan *Clean Invoice* kepada konsumen secara instan, tanpa meruntuhkan fase sebelumnya, namun tetap 100% mematuhi standar *Audit Trail* (ISO 9001) dan aman dari teguran Dirjen Pajak (DJP).

---

## 2. Arsitektur Solusi Terpilih: "In-Place Amandemen dengan Delta Adjustment"
Alih-alih melakukan *Void & Re-issue* (yang merusak fase sebelumnya), sistem akan menggunakan pendekatan **Adendum / Amandemen Langsung (In-Place Update)** yang dibungkus dengan sistem Jurnal Selisih (*Delta Adjustment*).

### Konsep Utama:
1. **Preservasi Nomor:** Nomor Invoice asli (contoh: `INV.1.171.81`) dipertahankan.
2. **Delta Calculation:** Sistem menghitung selisih (qty/harga) dari Invoice versi 1 ke versi 2.
3. **Adjustment Journal:** Sistem mengeksekusi Jurnal Balik (Reversal) *hanya* sebesar nilai selisihnya, bukan membatalkan keseluruhan transaksi.
4. **Audit Snapshot:** Versi lama dari Invoice wajib dibungkus (serialize) dan disimpan permanen di tabel log sebelum proses modifikasi dilakukan.

---

## 3. Alur Kerja (Workflow)

```mermaid
graph TD
    A[User buka Invoice .81] --> B{Tombol Amandemen Diklik}
    B -->|Cek Otorisasi| C{Apakah Punya Akses Supervisor?}
    C -->|Tidak| D[Tolak Akses]
    C -->|Ya| E{Cek Status e-Faktur DJP}
    
    E -->|Sudah Approved DJP| F[Tolak Amandemen! Wajib pakai Nota Retur / FP Pengganti]
    E -->|Belum Upload / Draf| G[Buka Form Edit Amandemen]
    
    G --> H[User ubah Qty / Harga item]
    H --> I[Simpan Amandemen]
    
    I --> J[1. Snapshot Data Lama -> transaksi_data_registry]
    I --> K[2. Hitung Selisih/Delta Harga & Qty]
    I --> L[3. Eksekusi Jurnal Penyesuaian Akuntansi]
    I --> M[4. Eksekusi Modul Gudang: Masukkan Stok Batal]
    I --> N[5. Overwrite baris transaksi Invoice .81]
    
    N --> O((Selesai: Print Clean Invoice))
```

---

## 4. Rincian Teknis & Database

### A. Tabel Utama (`transaksi` & `transaksi_items`)
Sistem mengizinkan eksekusi `UPDATE` (Bukan DELETE atau INSERT baru) pada baris ID transaksi yang bersangkutan. 
* Total Nilai Transaksi (`total_rp`, `tagihan_total`) di-update sesuai perhitungan baru.
* Qty barang di `transaksi_items` di-update sesuai perhitungan baru.

### B. Tabel Audit (`transaksi_data_registry`)
Ini adalah "nyawa" dari sistem keamanan ISO Anda.
Sebelum `UPDATE` pada poin A dieksekusi, sistem wajib melakukan *Query SELECT* seluruh detail Invoice versi 1, mengubahnya menjadi format JSON/Base64, lalu melakukan `INSERT` ke tabel ini dengan kode pengenal:
* `transaksi_id` = ID Invoice yang diamandemen
* `registry_patch` = `amandemen_v1` (atau versi revisi)
* `main` = Data JSON lengkap sebelum diedit.

### C. Pembuatan Jurnal Penyesuaian (Akuntansi)
Jika total invoice turun dari Rp 35 Juta menjadi Rp 30 Juta (Selisih 5 Juta). Sistem **tidak** me-revert 35 Juta lalu menjurnal ulang 30 Juta. 
Sistem memanggil `MdlRevertJurnal` atau `MdlCashFlowBuilder` dengan tipe instruksi khusus: **Jurnal Penyesuaian (Credit Note Internal)** senilai Rp 5 Juta (Mengurangi Piutang Rp 5 Jt, dan Mengurangi Pendapatan Rp 5 Jt).

### D. Penyesuaian Gudang (Logistik)
Jika perubahan melibatkan penurunan Kuantitas Fisik (misal 2 PC batal):
Sistem memanggil modul Penerimaan Retur / *ComLockerStockDualWrite* secara otomatis tanpa intervensi user, untuk menambahkan 2 PC ke kartu stok gudang asal.

---

## 5. Mitigasi Risiko & Keamanan (Fraud Prevention)

Penerapan *Clean Invoice* membuka celah manipulasi tagihan, sehingga harus digembok dengan ketat:

1. **Proteksi Otorisasi (Gembok 1)**
   Fungsi ini harus dibuat sebagai *Sub-Modul* terpisah (misal: `application/modules/amandemen_invoice`). Modul ini hanya bisa diakses oleh *Role/Group* level Supervisor atau Manager Keuangan.
2. **Proteksi Pajak (Gembok 2)**
   Sistem meletakkan validasi (Early Validation Pattern) di awal *controller*.
   ```php
   if ($invoice['efaktur'] == 1 || $invoice['efaktur_status'] == 'APPROVED_DJP') {
       die("Gagal: Faktur Pajak sudah disetujui DJP. Amandemen Clean Invoice dilarang secara hukum. Silakan gunakan alur Retur Pajak/Faktur Pengganti.");
   }
   ```
3. **Proteksi Repetisi (Gembok 3)**
   Beri batasan bahwa satu invoice maksimal hanya boleh diamandemen 1 atau 2 kali, untuk menghindari perombakan data yang tidak terkendali oleh internal.
4. **Laporan Audit Khusus (Laporan Anti-Fraud)**
   Developer wajib menyediakan satu menu "Laporan Invoice Amandemen" untuk Direktur/Owner, guna memantau riwayat semua dokumen yang di-*overwrite*, beserta tanggal dan *User ID* pelakunya.

---

## 6. Tahapan Pengembangan (Roadmap)

Tahapan eksekusi jika *Blueprint* ini disetujui:

* [ ] **Tahap 1: Pembuatan Controller Amandemen.** Membangun antarmuka (*View*) khusus yang memungkinkan Supervisor memanggil dokumen Invoice yang *locked*, dan membukanya untuk di-edit parsial.
* [ ] **Tahap 2: Logika Snapshot Registry.** Membuat *helper* / fungsi di Model yang sanggup merangkum struktur transaksi kompleks menjadi JSON dan menge-save-nya ke `transaksi_data_registry`.
* [ ] **Tahap 3: Logika Jurnal Selisih (Delta).** Membangun algoritma untuk menghitung selisih harga versi lama vs versi baru, dan mengirimkan jurnalnya ke tabel *accounting*.
* [ ] **Tahap 4: Logika Stok Retur (Delta).** Membangun perintah ke modul gudang untuk memasukkan kembali stok yang batal di tengah jalan.
* [ ] **Tahap 5: Testing & Validasi DJP.** Uji coba menyeluruh memastikan sistem menolak Invoice yang berstatus *"Sukses e-Faktur"*.