# STANDAR OPERASIONAL PROSEDUR (SOP): INVESTIGASI & DRILL-DOWN KETERPUTUSAN RANTAI MODUL
## Universal Cross-Module Transaction Pipeline & Interactive Drill-Down Runbook
### Lingkungan Teknis: CodeIgniter 3.1.8 HMVC, PHP 5.6, MariaDB 10, Everest ERP

> [!IMPORTANT]
> Dokumen ini adalah panduan operasional khusus (**Specialized On-Demand Runbook**) yang wajib dipelajari dan dijalankan oleh AI Agent ketika menangani masalah **keterputusan relasi data antar-modul transaksi** (seperti: data tercatat di modul hulu namun tidak muncul di modul hilir, hilangnya antrean pembayaran/pajak/komisi, atau inkonsistensi selektor transaksi).
> 
> Dokumen ini melengkapi [SOP_PERBAIKAN_MODUL_TRANSAKSI.md](file:///w:/GLOBAL_AGENT/SOP_PERBAIKAN_MODUL_TRANSAKSI.md) dan aturan mutlak pada [AGENTS.md](file:///w:/everest_25okt/AGENTS.md).

---

## 1. Kriteria Pemicu Pemanggilan Dokumen (Trigger Conditions)

Agen **WAJIB** meload dan menerapkan runbook ini apabila menemukan salah satu kondisi berikut:
1. **Data Hulu Ada, Hilir Hilang:** Dokumen transaksi berhasil diterbitkan di modul asal (misal `biaya project`, `pembelian`, `invoicing`, `penjualan`) dan nilainya tercatat di tabel riwayat/registry, namun **tidak muncul sama sekali di antarmuka modul hilir** (seperti `pph 21 A/P payment`, `settlement piutang`, `payment hutang vendor`, `surat jalan`).
2. **Nilai Hilir Bernilai Nol / Tidak Sinkron:** Dokumen hilir berhasil ditarik, tetapi nilai tagihan, DPP, potongan pajak, atau sisa hutang bernilai `0`.
3. **Selektor Dokumen Kosong (*Empty Modal Selector*):** Tombol pilih nota / pilih tagihan pada modul hilir tidak menampilkan daftar transaksi yang seharusnya belum lunas.
4. **Instruksi Pengguna:** Pengguna menginstruksikan investigasi atau perbaikan alur hubungan antar-dua modul transaksi (alur Produsen $\rightarrow$ Konsumen).

---

## 2. Pola Arsitektur Universal: Rantai Produsen–Konsumen (Producer–Consumer Pipeline)

Di Everest ERP, integrasi antar-modul tidak menggunakan tabel relasional statis langsung, melainkan melalui **Integration Bus Tables** (terutama `transaksi_payment_source`, `jurnal`, dan `rekening_koran`).

```
┌─────────────────────────────────────────────────────────────────────────────┐
│ MODUL HULU (PRODUCER)                                                       │
│ 1. Keranjang Sesi (_shoppingCart.php)       ──> Menyusun Gate Array         │
│ 2. Konfigurasi Modul (coTransaksiCore.php)  ──> Mendaftarkan Komponen       │
│ 3. Write-Path (Create.php / FollowUp.php)   ──> Eksekusi Komponen           │
└──────────────────────────────────────┬──────────────────────────────────────┘
                                       │ Menulis ke Bus Data
                                       ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ INTEGRATION BUS TABLE (transaksi_payment_source / jurnal / locker)          │
│ Baris data per peruntukan: target_jenis, label, tagihan, sisa, extern_id    │
└──────────────────────────────────────┬──────────────────────────────────────┘
                                       │ Dibaca oleh Modul Hilir
                                       ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ MODUL HILIR (CONSUMER)                                                      │
│ 1. Antrean Undone List (Transaksi::selectPaymentSrc) ──> Kueri SQL Join     │
│ 2. Selektor Manual (_selectorItem / coTransaksiUi.php)──> Model Selektor    │
└─────────────────────────────────────────────────────────────────────────────┘
```

Setiap keterputusan data selalu terjadi pada salah satu dari **4 Titik Kegagalan Universal (The 4 Failure Points)**.

---

## 3. Fase 1: Checklist Investigasi Mandiri 4 Layer (Mandatory Code-Recon)

Sebelum mengajukan pertanyaan kepada Developer atau mengubah kode, Agen **WAJIB** melakukan pemindaian menyeluruh pada 4 lapisan berikut:

### Layer 1: Audit Pembentukan Gate Sesi (`_shoppingCart.php` Hulu)
Periksa bagaimana data rincian disusun di dalam sesi sebelum transaksi disimpan:
* **Identifikasi Nama Gate Sumber:** Periksa berkas `coTransaksiCore.php` pada transaksi hulu untuk menemukan nama array gate yang dibutuhkan (misal: `items`, `items2_sum`, `items5_sum`, `rsltItems`).
* **Deteksi Varian Entitas (Group vs Individu):**
  * Apakah logika pengisian gate hanya berlaku untuk entitas group (misal via fungsi pembaca anggota seperti `getMembersBySpk()`)?
  * Apakah ada proteksi/fallback jika pihak pelaksana adalah **perseorangan/non-group** (`empty($members)`)?
* **Kelengkapan Atribut Fallback:** Jika terdapat fallback entitas individu, periksa apakah seluruh atribut finansial yang dibutuhkan hilir ikut dihitung (misal: `employee_id`, `employee_nama`, `nilai_dpp_pph`, `pph21_nilai_detail`, `pph23_nilai`, `nilai_kas_cn_detail`).
* **Validasi Kondisi Penyaring (*Filter Condition*):** Periksa apakah ada kondisi bypass seperti `optionFreelancerID == $_SESSION[$cCode]['main']['internal_mode']` yang berpotensi mematikan pembentukan gate jika modenya tidak cocok.

### Layer 2: Audit Eksekusi Penulisan Database (`Create.php` / `FollowUp.php` Hulu)
Periksa alur eksekusi saat tombol simpan ditekan:
* **Pemeriksaan Komponen di `coTransaksiCore.php`:**
  * Pastikan komponen bus data terdaftar di blok `components` atau `postProcessor` (misal: `PaymentSourceDetail` dengan `srcGateName = "items5_sum"`).
* **Pemeriksaan Kondisi Eksekusi di Controller:**
  * Di `Create.php` atau `FollowUp.php`, cari loop pemanggilan komponen:
    ```php
    if (isset($_SESSION[$cCode][$srcGateName]) && (sizeof($_SESSION[$cCode][$srcGateName]) > 0)) {
        // Eksekusi ComPaymentSourceDetail / ComJurnal
    }
    ```
  * **Critical Check:** Jika pada Layer 1 array gate bernilai kosong (`count = 0`), blok eksekusi ini akan **dilewati tanpa error** (*silent failure*). Header transaksi tetap tersimpan dengan sukses, namun baris relasi di `transaksi_payment_source` tidak pernah terbit.

### Layer 3: Audit Kriteria Ingesti Antrean Hilir (`Transaksi::selectPaymentSrc` Hilir)
Periksa kueri yang digunakan modul hilir untuk menampilkan daftar antrean yang belum diproses (*undoneList*):
* **Pemeriksaan Target Jenis:** Pastikan `transaksi_payment_source.target_jenis` diisi tepat sesuai kode transaksi hilir (misal `.1483` untuk PPh 21, `.115` untuk PPh 23, `.4447` untuk Vendor A/P).
* **Pemeriksaan Filter Cabang:** Periksa apakah kueri membatasi `transaksi_payment_source.cabang_id = login.cabang_id`. Jika transaksi dibuat di cabang yang berbeda (misal Pusat `-1` vs Cabang), pastikan aturan visibilitas multi-cabang terpenuhi.
* **Pemeriksaan Threshold Sisa:** Periksa klausul batas sisa hutang/kewajiban (misal `sisa >= 5` atau `sisa > 0`).
* **Pemeriksaan Integritas Dokumen Induk (Join Table):**
  * Periksa apakah kueri melakukan `INNER JOIN transaksi ON transaksi_payment_source.transaksi_id = transaksi.id`.
  * Pastikan dokumen induk berstatus sah (`transaksi.status = '1'` dan `transaksi.trash = '0'`). Jika transaksi hulu masih berstatus draf/menunggu approval (`status != '1'`), data tidak akan muncul di hilir.

### Layer 4: Audit Model Selektor Antarmuka (`coTransaksiUi.php` Hilir)
Periksa konfigurasi modal pencarian manual (*search picker modal*):
* **Kesesuaian Model Selektor (`selectorModel`):**
  * Periksa apakah `selectorModel` mengarah ke tabel fisik yang benar.
  * *Contoh Anomali Sering Terjadi:* Menetapkan `selectorModel => "MdlNota"` (yang membaca tabel `transaksi`) dengan filter `label = 'hutang pph 21'`, padahal kolom `label` tersebut berada di tabel `transaksi_payment_source`.
* **Kesesuaian Parameter Field:** Pastikan `selectorParamFields` memetakan kolom ID referensi (`transaksi_id` vs `id`) secara tepat agar tidak tertukar saat dipilih ke keranjang belanja hilir.

---

## 4. Fase 2: Protokol Wajib "Interactive Grill-Me" (Drill-Down Gate)

> [!CAUTION]
> **DILARANG KERAS MENGUBAH KODE ATAU MEMANIPULASI DATABASE SEBELUM FASE INI DISELESAIKAN.**
> Agen tidak boleh membuat asumsi sepihak mengenai aturan perpajakan, pemecahan nama vendor, atau penanganan data masa lalu.

Setelah menyelesaikan investigasi 4 layer di atas, Agen **WAJIB berhenti** dan menyajikan laporan temuan serta mengajukan **3 Pertanyaan Kunci Pengunci (*The 3 Drill-Down Questions*)** kepada Developer:

### Format Laporan Hasil Recon Mandiri (Fact Sheet):
```markdown
### 📋 Hasil Investigasi 4-Layer Rantai Transaksi
- **Modul Hulu (Produsen):** [Kode & Nama Modul Hulu] -> Nota: [Nomor Nota]
- **Modul Hilir (Konsumen):** [Kode & Nama Modul Hilir]
- **Temuan Layer 1 (Gate Sesi):** [Jelaskan apakah array gate terisi atau kosong, dan alasannya]
- **Temuan Layer 2 (Write-Path Bus):** [Jelaskan apakah komponen bus dieksekusi atau terlewat]
- **Temuan Layer 3 (Kueri Hilir):** [Jelaskan kecocokan kueri di selectPaymentSrc dan tabel database]
- **Temuan Layer 4 (Model Selektor):** [Jelaskan kesesuaian selectorModel di coTransaksiUi]
```

### 3 Pertanyaan Wajib Pengunci (The 3 Mandatory Inquiries):

1. **Pertanyaan 1: Regulasi & Perlakuan Logika Bisnis (Business Rule Confirmation)**
   * *"Untuk kasus anomali entitas yang ditemukan (misal: pelaksana perseorangan/non-group vs group mandor), bagaimana alur pembukuan yang sah menurut SOP perusahaan? Apakah kewajiban finansial (misal PPh 21) wajib otomatis diterbitkan atas nama pihak utama (`pihakID`), atau harus ada input rincian manual oleh petugas kasir?"*
2. **Pertanyaan 2: Kebijakan Penanganan Data Historis (Legacy Data Remediation)**
   * *"Untuk nota-nota yang sudah terlanjur terbit di masa lalu tanpa baris di `transaksi_payment_source` (seperti nota yang diperiksa saat ini): Apakah kita perlu membuatkan skrip koreksi mandiri (*one-time data patch script*) untuk meng-insert baris yang hilang ke database agar antreannya segera muncul, atau perbaikan kode hanya ditujukan untuk transaksi baru ke depan?"*
3. **Pertanyaan 3: Penyelarasan Jalur Antarmuka Hilir (Selector vs Queue Ingestion)**
   * *"Pada modul hilir, apakah proses transaksi wajib menggunakan antrean otomatis (`selectPaymentSrc`), atau selektor modal manual (`coTransaksiUi.php` -> `_selectorItem`) juga harus disinkronkan ke model tabel yang tepat (`MdlPaymentSource`)?"*

---

## 5. Fase 3: Protokol Eksekusi & Remediasi Terarah

Setelah Developer memberikan jawaban dan instruksi atas sesi *Grill-Me*, Agen mengeksekusi perbaikan dengan mematuhi batasan berikut:

### 1. Remediasi Jalur Tulis Hulu (*Write-Path Hardening*)
* Terapkan *Early Validation & Self-Healing Pattern* pada `_shoppingCart.php` dan `Create.php`:
  * Jika array gate kosong akibat entitas non-group, pastikan blok fallback otomatis menginisiasi baris entitas dengan nilai finansial yang lengkap.
  * Cegah nilai nominal `pph21_nilai_detail` atau `sisa` tertinggal `0` jika nilai header utama di form kasir lebih dari `0`.
* Pastikan kompatibilitas penuh dengan **PHP 5.6** (`isset($x) ? $x : array()`, dilarang operator `??` atau short array `[]`).
* Jangan ada komentar placeholder (`// ... existing code ...`). Tuliskan fungsi secara utuh sesuai aturan [AGENTS.md](file:///w:/everest_25okt/AGENTS.md).

### 2. Remediasi Jalur Baca Hilir (*Read-Path Alignment*)
* Selaraskan kueri pada controller hilir (`Transaksi::selectPaymentSrc`) agar tidak menggunakan penggabungan string mentah (*Zero Raw SQL Concatenation*).
* Pastikan parameter binding digunakan pada seluruh klausa filter cabang, target jenis, dan batas sisa.

### 3. Pembuatan Skrip Koreksi Data Historis (Jika Diminta oleh Developer)
Jika Developer menginstruksikan perbaikan pada data lama yang cacat relasi:
* Buat skrip mandiri pada direktori aman (misal scratch script atau CLI controller).
* Skrip wajib memverifikasi dokumen induk terlebih dahulu (`status = 1`, `trash = 0`).
* Eksekusi insert ke `transaksi_payment_source` wajib menyalin `id_master`, `transaksi_id`, nomor nota, `cabang_id`, dan nominal yang persis sama dengan yang tercatat di registry transaksi induk.
* Bungkus seluruh operasi perbaikan ke dalam transaksi database atomik:
  ```php
  $this->db->trans_start();
  // Operasi insert baris transaksi_payment_source yang hilang
  $this->db->trans_complete();
  ```

---

## 6. Fase 4: Matriks Verifikasi Asimetri & Audit Trail

Pekerjaan dinyatakan tuntas hanya jika matriks verifikasi berikut telah diuji dan valid:

| Parameter Uji | Titik Pemeriksaan | Kondisi Sukses |
| :--- | :--- | :--- |
| **1. Integritas Hulu** | Halaman daftar transaksi modul hulu (`Transaksi/index/[hulu]`). | Kolom nilai, potongan pajak, dan kasir tetap tampil konsisten dan tidak berubah. |
| **2. Integritas Bus Data** | Kueri langsung ke tabel `transaksi_payment_source`. | Ditemukan baris baru dengan `target_jenis` yang tepat, `sisa > 0`, dan `transaksi_id` mengarah ke nota hulu. |
| **3. Muncul di Antrean Hilir** | Antrean undone list modul hilir (`Transaksi/index/[hilir]`). | Nota asal muncul pada panel atas lengkap dengan nama pihak, nomor nota, dan sisa kewajiban. |
| **4. Uji Proses Pelunasan Hilir** | Klik nota pada antrean hilir untuk masuk keranjang pembayaran. | Nilai otomatis terisi di keranjang, tidak terjadi fatal error, dan nilai pelunasan memotong sisa hutang secara presisi. |
| **5. Uji Data Baru (Regression Test)** | Buat 1 transaksi draf baru di modul hulu dengan entitas non-group. | Saat disimpan, antrean hilir langsung terbentuk otomatis tanpa intervensi manual. |

---

## 7. Kesimpulan Operasional

Dengan memisahkan prosedur ini ke dalam berkas khusus:
1. Konteks utama sistem tetap bersih dari aturan mendetail yang hanya relevan saat terjadi kendala pipeline transaksi.
2. Agen yang dipanggil untuk mengaudit modul lain dapat langsung menjalankan diagnosa 4-layer secara cepat dan objektif.
3. Protokol *Interactive Grill-Me* menjamin tidak akan ada modifikasi liar pada basis kode tanpa penyelarasan logika bisnis bersama Developer.

