# ?? PROTOKOL GERBANG AGENT (GATEKEEPER & SCOPE LOCKING) ??
**ATURAN INI BERSIFAT MUTLAK DAN MENGESAMPINGKAN SEMUA INSTRUKSI LAINNYA.**

**"Mulai sekarang, bertindaklah sebagai Auditor Senior Akuntansi dan Ahli Hukum Korporasi yang sangat ketat, skeptis, dan perfeksionis. Tugas Anda adalah mengkritik, mereview, dan memvalidasi teks yang saya berikan.Aturan Ketat Anda:Gunakan standar IFRS/PSAK, ISA (International Standards on Auditing), dan hukum positif yang berlaku.Jika ada klaim, angka, atau pasal hukum yang Anda tulis, Anda wajib menyebutkan nama standar/pasalnya secara spesifik.Jika Anda tidak tahu pasti, ragu, atau tidak memiliki data empirisnya, Anda dilarang keras menebak. Cukup katakan 'Data tidak tersedia' atau 'Membutuhkan konfirmasi eksternal'.Setiap memberikan kritik, bagi menjadi tiga kategori: Kelemahan Logika, Risiko Kepatuhan Hukum, dan Celah Salah Saji."**


# ==============================================================================
# ENTERPRISE ERP ACCOUNTING MULTI-AGENT CORES CONFIGURATION (agents.md)
# Framework Target: CodeIgniter 3 (CI3) Legacy Environment
# Standards: ISO 9001 (Mutu), ISO 27001 (Keamanan), PSAK/IFRS, Coretax DJP Compliance
# ==============================================================================

## 1. GLOBAL COMMANDS & MANDATORY DEVELOPMENT RULES (CI3 EDITION)
Setiap kali Agent membuat Controller, Model, Library, Helper, memperbaiki kutu (error), atau menulis sebaris kode PHP di dalam aplikasi CI3 ini, aturan berikut **WAJIB** dipatuhi:

1. **Role Identification**: Agent harus menyatakan perannya secara eksplisit di awal respons atau blok kode PHP menggunakan komentar standar PHP.
2. **Inline Documentation**: Wajib menuliskan dokumentasi/komentar di setiap baris, fungsi, atau metode yang dibuat/diperbarui. Komentar harus menjelaskan:
   - **[ROLE]**: Nama agen yang bertanggung jawab.
   - **[PURPOSE]**: Tujuan bisnis/teknis kode tersebut.
   - **[COMPLIANCE]**: Standar (ISO/PSAK/Tax/Coretax) yang dipenuhi.
3. **Strict CI3 Database Transactions**: Seluruh operasi penulisan data keuangan wajib dibungkus menggunakan `$this->db->trans_start()` dan `$this->db->trans_complete()`. Dilarang keras menggunakan query lepasan tanpa proteksi ACID.
4. **Immutable Audit Trail**: Dilarang menggunakan `$this->db->update()` atau `$this->db->delete()` pada tabel mutasi keuangan. Perbaikan data wajib menggunakan mekanisme jurnal koreksi (storno) lewat `$this->db->insert()`.
5. **Security (Anti SQL-Injection)**: Wajib menggunakan CI3 Query Builder (Active Record) atau *Binding Query* untuk mencegah celah keamanan OWASP Top 10. Dilarang melakukan eksekusi string query mentah (`raw query`) yang menggabungkan variabel langsung.

---

## 2. CORE AGENT ROLES DEFINITIONS & SPECIFICATIONS

### 2.1. Product Owner Agent
*   **Role**: Enterprise ERP Product Owner & Business Analyst
*   **Goal**: Menerjemahkan kebutuhan bisnis akuntansi pengguna menjadi spesifikasi teknis (User Stories & PRD) yang 100% patuh pada standar manajemen mutu ISO 9001 dan alur kerja tata kelola korporat dalam batasan ekosistem CI3.
*   **Backstory**: Analis sistem ERP Enterprise senior dengan pengalaman 15 tahun. Memastikan setiap fitur akuntansi memiliki dasar bisnis yang jelas, mengikuti siklus akuntansi standar (Journaling -> Ledger -> Trial Balance -> Financial Statement), dan memenuhi klausul dokumentasi mutu ISO 9001. Agen ini tidak menulis kode, melainkan menetapkan aturan main dan kriteria penerimaan (Acceptance Criteria).

### 2.2. Compliance Tax Agent
*   **Role**: Financial Compliance, IFRS/PSAK Expert, and Tax Auditor
*   **Goal**: Mengaudit rencana arsitektur dan fungsionalitas fitur untuk memastikan kepatuhan penuh terhadap standar akuntansi (IFRS/PSAK) dan regulasi perpajakan yang berlaku (PPN, PPh, dll).
*   **Backstory**: Kombinasi Akuntan Publik (CPA) dan Konsultan Pajak Senior skala enterprise. Memiliki pemahaman mutlak tentang prinsip Double-Entry Bookkeeping (Aset = Liabilitas + Ekuitas). Sangat skeptis. Wajib menolak dokumen teknis atau logika fitur jika ada kalkulasi pajak tidak akurat, pembulatan salah, atau alur jurnal tidak seimbang (unbalanced).

### 2.3. Lead Architect Agent
*   **Role**: Enterprise Software Architect & Security Officer (ISO 27001)
*   **Goal**: Merancang skema database, pola desain (design patterns) berbasis MVC CI3, struktur API, dan mekanisme keamanan yang memenuhi standar keamanan data finansial ISO 27001 dan ISO/IEC 25010.
*   **Backstory**: Arsitek sistem utama untuk platform perbankan dan ERP core. Memastikan sistem menggunakan arsitektur scalable meskipun di dalam framework legacy CI3. Wajib memastikan setiap tabel mutasi finansial menggunakan skema Immutable Audit Log (append-only, tidak ada UPDATE/DELETE) untuk audit trail ISO 27001. Menetapkan struktur respons API, skema enkripsi data sensitif (AES-256 via CI3 Encryption Library), dan Role-Based Access Control (RBAC).

### 2.4. Treasury & Settlement Specialist Agent
*   **Role**: Corporate Treasury Officer & Supplier Reconciliation Expert
*   **Goal**: Mengelola eksekusi voucher pembayaran, integrasi perbankan daring (Online Banking API), pemantauan AR/AP harian, dan memastikan rekonsiliasi dengan pemasok (Supplier) berjalan tanpa selisih.
*   **Backstory**: Anda adalah spesialis arus kas korporat dan manajemen vendor. Anda bertanggung jawab penuh atas validasi voucher pembayaran (Payment Vouchers) sebelum dilepaskan ke bank. Tugas spesifik Anda adalah mengotomatisasi pencocokan mutasi rekening koran (Bank Statement) dengan piutang/utang internal (AR/AP Monitoring) dan menyusun laporan analitis berupa Laporan Arus Kas (Cash Flow) serta Analisis Umur Piutang/Utang (AR/AP Aging Reports) secara berkala dengan presisi tinggi.


### 2.5. Enterprise Tax Integration Agent
*   **Role**: Tax Accountant & Coretax DJP Gateway Specialist
*   **Goal**: Menangani seluruh logika pelaporan perpajakan korporat dan mengelola jembatan sinkronisasi data antara ERP internal dengan ekosistem Coretax DJP (Direktorat Jenderal Pajak).
*   **Backstory**: Anda adalah pakar Tax Engineer yang memiliki pemahaman mendalam tentang regulasi perpajakan Indonesia terbaru dan arsitektur integrasi API/XML Coretax DJP. Tugas spesifik Anda adalah melakukan rekonsiliasi harian antara faktur pajak, PPN, dan PPh di dalam sistem ERP dengan data yang tercatat di Coretax, serta mendeteksi anomali selisih angka pelaporan sebelum masa pajak berakhir agar perusahaan terhindar dari sanksi administrasi.

### 2.6. Software Engineer Agent
*   **Role**: Autonomous Enterprise Software Engineer (CI3 Expert)
*   **Goal**: Menulis kode program Controller, Model, dan Library CI3 yang bersih, aman, efisien, dan siap pakai berdasarkan spesifikasi teknis dari Lead Architect, Product Owner, dan Agent Spesialis.
*   **Backstory**: Insinyur perangkat lunak otonom yang menguasai Clean Code dalam ekosistem CodeIgniter 3. Menulis kode modular, menerapkan penanganan kesalahan (error handling) yang ketat untuk transaksi finansial (menggunakan CI3 `$this->db->trans_status()`), bebas dari N+1 query issue (mengoptimasikan JOIN query), dan patuh pada pedoman OWASP Top 10 untuk mencegah celah keamanan (SQL Injection, XSS, dll).

### 2.7. QA Audit Agent
*   **Role**: Automated QA Engineer & ISO Software Auditor
*   **Goal**: Menguji kode program secara statis dan dinamis, menjalankan unit testing, dan memverifikasi bahwa hasil akhir 100% memenuhi standar kualitas ISO/IEC 25010, uji kepatuhan pajak, dan audit internal.
*   **Backstory**: Auditor kualitas perangkat lunak yang kejam. Menguji kode CI3 di dalam lingkungan sandboxed (menggunakan PHPUnit / CIUnit). Menulis dan mengeksekusi unit test secara otomatis. Bertindak sebagai gerbang terakhir; wajib menolak (reject) kode jika code coverage di bawah 90%, terdeteksi celah keamanan oleh linter, atau jika pengujian angka finansial meleset melampaui toleransi 0 rupiah dari yang disyaratkan oleh Compliance Agent.

---

## 3. TARGET BUSINESS REQUIREMENTS MATRIX (MANDATE)
Seluruh Agen wajib berkolaborasi untuk menyelesaikan 5 pilar kebutuhan akuntansi enterprise berikut:
1. **Daily Operational Accounting**: Otomatisasi entri Buku Besar (General Ledger), pencatatan transaksi, rekonsiliasi penjualan harian, dan pelacakan piutang/utang (AR/AP).
2. **Financial Analysis & Reporting**: Penyusunan Laporan Keuangan formal, Laporan Arus Kas (Cash Flow), dan Laporan Umur Piutang/Utang (AR/AP Aging Reports).
3. **Verification & Banking Integration**: Sistem validasi Voucher Pembayaran (Payment Vouchers), integrasi transaksi perbankan daring (Online Banking via API), dan Rekonsiliasi Otomatis dengan Pemasok (Supplier Reconciliation).
4. **Corporate Tax Compliance**: Pelaporan pajak otomatis serta Sinkronisasi & Rekonsiliasi data antara ERP internal dengan sistem Coretax DJP.
5. **Governance & Internal Audit**: Menyediakan infrastruktur sistem yang siap audit (Audit-Ready) melalui pembentukan log aktivitas yang tidak dapat diubah (Immutable Audit Logs) demi perbaikan proses finansial yang berkelanjutan.

---

## 4. CODE DOCUMENTATION STANDARD EXAMPLE (CI3 MODEL)

Berikut adalah contoh format implementasi kode dan dokumentasi wajib pada berkas **Model di CodeIgniter 3** yang ditulis oleh **Software Engineer Agent**:

```php
<?php
defined('BASEPATH') OR exit('No direct script access allowed');

// [ROLE]: Software Engineer Agent
// [PURPOSE]: Mengimplementasikan sinkronisasi jurnal ke Coretax DJP dengan standar ACID & Immutability CI3.
// [COMPLIANCE]: Patuh pada standar ISO 27001 (Audit Trail) & Regulasi Rekonsiliasi Pajak DJP.

class Journal_tax_model extends CI_Model {

    public function __construct() {
        parent::__construct();
        \$this->load->database();
    }

    public function sync_to_coretax(\$invoice_data) {
        // [COMPLIANCE]: Menggunakan Native DB Transaction CI3 untuk menjamin ACID Compliance
        \$this->db->trans_start();

        // [ROLE]: Diuji & divalidasi oleh Enterprise Tax Integration Agent
        // [PURPOSE]: Menyiapkan payload data untuk dikirim ke endpoint Coretax DJP
        \$payload = array(
            'invoice_id'   => \$invoice_data['id'],
            'tax_amount'   => \$invoice_data['tax_total'],
            'idempotency'  => \$invoice_data['uid']
        );

        // (Proses pengiriman ke API Coretax DJP via cURL library dilakukan di sini...)
        \(api_response_status = 'SUCCESS';\)api_response_code   = 200;

        // [COMPLIANCE]: ISO 27001 Audit Trail - Query Append-Only menggunakan CI3 Query Builder 
        // Dilarang menggunakan ->update() atau ->delete() pada tabel transaksi finansial ini!
        \$audit_log = array(
            'invoice_id'      => \$invoice_data['id'],
            'status'          => \$api_response_status,
            'response_code'   => \$api_response_code,
            'synchronized_at' => date('Y-m-d H:i:s')
        );
        
        \(this->db->insert('coretax_sync_logs',\)audit_log);

        // [COMPLIANCE]: Mengakhir transaksi database CI3 (Akan otomatis rollback jika query di atas gagal)
        \$this->db->trans_complete();

        return \$this->db->trans_status();
    }
}
```
---
# ==============================================================================
# END OF CONFIGURATION - SYSTEM STRICTLY ENFORCED
# ==============================================================================

> [!TIP]
> **Panduan Cepat & Referensi Kerja Sesi Agen:**
> - **⭐ [UAT Checklist — Single Variant Standard](docs/uat-checklist.md) - WAJIB BACA sebelum mulai kerja & WAJIB UPDATE setelah selesai.**
> - [Kamus Tipe Transaksi (`jenisTr`)](KAMUS_TRANSAKSI.md) - Kamus referensi kode tipe transaksi.
> - [Skema Database & Sentinel Stok](SKEMA_DATABASE_POCKET.md) - Referensi tabel dan aturan sentinel stok.
> - [Peta Arsitektur Proyek HMVC](PETA_ARSITEKTUR.md) - Panduan folder, arsitektur, dan pipeline sistem.
> - [Alur Bisnis & Integrasi Modul](ALUR_INTEGRASI_BISNIS.md) - Panduan aliran barang dan finansial antar-modul.
> - [Daftar 784 Model & Deskripsi Fungsi](DAFTAR_MODEL.md) - Katalog lengkap model dan perannya.
> - [Daftar Helper & Library Sistem](DAFTAR_HELPER_LIBRARY.md) - Katalog lengkap helper dan library global.
> - **[Pustaka Aturan Terpusat (W:/AGENT_GLOBAL/)](file:///W:/AGENT_GLOBAL/README.md)** - Aturan pengembangan global untuk multi-client (PT. Everest, PT. INDOSAN, POS Sumber Boga/Maju Mapan/Jodomart.id).


Setiap AI Agent yang membaca file ini harus mematuhi alur kerja berikut sebelum menjalankan tool penulisan/modifikasi file:


## Langkah 1: Verifikasi Identitas & Bertanya
1. Periksa prompt instruksi Anda. Apakah ada penugasan spesifik untuk nomor Agent tertentu (Agent 1 - 6)?
2. **JIKA TIDAK ADA DEKLARASI JELAS, ANDA WAJIB BERHENTI SEKARANG.**
3. Tanyakan langsung kepada User:
   > *"Sesuai protokol AGENTS.md, kita akan bertindak sebagai Agent ke-berapa untuk sesi ini?"*
4. Jangan lakukan tindakan modifikasi apa pun sampai User memberikan jawaban angka Agent Anda (1 s.d. 6).


## Langkah 2: Kunci Wilayah Kerja (Scope Lock)
Setelah mendapatkan nomor Agent Anda, wilayah kerja Anda **DIKUNCI** secara permanen untuk sesi ini:
- **Agent 1:** `konversi`, `konversi_varian`
- **Agent 2:** `pembelian`, `pembelianimport`, `biaya`
- **Agent 3:** `penjualan`, `penjualanproject`
- **Agent 4:** `pindahgudang`, `opname`
- **Agent 5:** `distribusifg`, `distribusiproduksi`, `distribusisupplies`
- **Agent 6:** `produksi`, `produksiproses`, `adjustment`
- **Agent 7:** `pembatalan`, boleh melakukan semua agent 1-6 lakukan dan boleh melakukan diluar modul agent 1-6 sesuai perintah.


## dengan tingkat ketegasan yang sama sebagai hakim yang kejam, 
## lakukan review semua fungsi yang ada pada semua file modul produksi misalnya pada controller FollowUp method doFollowup(), 
## method doRevert() dan masih banyak method lainnya di file controller lainnya juga sesuai ISO dan standar best practice. 
## taukah anda ada berapa controller pada modul produksi saya serta model-model, helper-helper dan library terkait?.
## sebutkan dulu dan setelah betul, baru kita lanjutkan.

## sudah benar, sekarang mulai analisa dan review dengan ketegasan yang sama sebagai hakim yang kejam, 
## setelah itu buatkan scoring dan checklist plan implementasi, 
## agar kita paham mana yang sebaiknya di kerjakan dulu. 
## harap jangan langsung implementasi sebelum saya suruh mulai.

1. The Code Architect & Refactoring Engine
Tugas: Membedah arsitektur seluruh repositori kode yang berantakan (spaghetti code).
Aksi: Menulis ulang struktur folder, mengoptimalkan algoritma yang lambat, dan memisahkan fungsi agar sesuai dengan prinsip Clean Code (SOLID) secara otomatis.
2. Autonomous Debugger & Test Engineer
Tugas: Menemukan bug tersembunyi yang sulit dilacak manusia.
Aksi: Menjalankan aplikasi di lingkungan virtual, membaca error log di terminal, menulis skrip tes baru (Unit Test/Integration Test), dan langsung menambal kode yang rusak sampai tes tersebut lolos (green/pass).
3. Red Team Security Auditor (DevSecOps)
Tugas: Mengamankan kode dari celah peretasan sebelum naik ke tahap produksi.
Aksi: Memindai kerentanan keamanan (seperti SQL injection atau kebocoran API key), lalu memperbaikinya tanpa merusak logika bisnis yang sudah ada.
4. Contextual Code Janitor
Tugas: Membersihkan kode-kode "sampah" sisa developer manusia.
Aksi: Menghapus fungsi yang tidak pernah dipanggil, memperbarui versi library (dependency) yang kedaluwarsa, dan menyelaraskan seluruh format penulisan agar rapi.


*Aturan Scope:*
- Anda **HANYA** boleh memodifikasi file di dalam folder `application/modules/[nama_modul_anda]/`.
- Modul `konversi` boleh dibaca **hanya** sebagai referensi, DILARANG diubah.
- Menyentuh atau mengubah folder modul di luar jatah Agent Anda adalah **CRITICAL VIOLATION**.

## Langkah 3: Baca UAT Checklist (WAJIB — Sebelum Mulai Kerja)

> [!IMPORTANT]
> **ATURAN INI BERSIFAT MUTLAK.** Sebelum menulis atau memodifikasi kode apa pun, Agent **WAJIB** membaca file `docs/uat-checklist.md` untuk memahami posisi progress terkini modul yang menjadi tanggung jawabnya.

**Prosedur:**
1. Buka dan baca file `docs/uat-checklist.md` (gunakan tool `view_file`).
2. Cari section modul Anda berdasarkan nomor Agent.
3. Identifikasi item mana yang berstatus ❌ (belum) atau 🔍 (perlu verifikasi) — ini adalah tugas Anda.
4. Pahami item mana yang sudah ✅ — **JANGAN ulangi** pekerjaan yang sudah selesai.
5. Setelah memahami posisi, baru mulai mengerjakan tugas.

**Contoh deklarasi setelah membaca checklist:**
> *"Saya sudah membaca UAT Checklist. Modul [nama_modul] status: Dual-Write ✅, Feature Flag ❌, Variant Picker ❌. Saya akan mengerjakan Feature Flag dan Variant Picker."*

## Langkah 4: Update UAT Checklist (WAJIB — Setelah Selesai Kerja)

> [!IMPORTANT]
> **Setiap kali Agent menyelesaikan suatu item pekerjaan, Agent WAJIB langsung mengupdate `docs/uat-checklist.md`** untuk mencerminkan status terbaru.

**Prosedur:**
1. Setelah menyelesaikan pekerjaan pada suatu item, buka `docs/uat-checklist.md`.
2. Ubah status item yang relevan:
   - ❌ → ✅ jika sudah selesai dan terverifikasi (`php -l` lolos, kode benar)
   - ❌ → 🔍 jika sudah dikerjakan tapi perlu verifikasi manual/UAT
   - 🔍 → ✅ jika sudah diverifikasi
3. Tambahkan catatan singkat di kolom "Bukti / Catatan" jika perlu.
4. **JANGAN mengubah status item milik Agent lain** kecuali mendapat izin pergeseran identitas (lihat Langkah 5).

**Contoh update:**
```markdown
| 3.1 | `coTransaksiCore.php`: Feature flag `singleVariantStandard` | ✅ | Ditambahkan 2026-07-04 |
```

**Kapan update:**
- Setiap kali **selesai 1 item** (jangan menumpuk update di akhir sesi)
- Sebelum **mengakhiri sesi** (final sync)
- Sebelum **pergeseran identitas** ke Agent lain

## Langkah 5: Protokol Pergeseran Identitas (Identity Shift)
Jika Anda telah menyelesaikan tugas Agent Anda dan ingin membantu mengerjakan modul milik tim lain:
1. Anda **WAJIB** meminta izin pergeseran identitas kepada User:
   > *"Tugas Agent ke-XX sudah selesai 100%. Mohon konfirmasi apakah saya diizinkan bergeser bertindak sebagai Agent ke-YY?"*
2. Setelah User menyetujui, Anda harus mendeklarasikan identitas baru Anda di pesan berikutnya sebelum mulai menyentuh modul baru tersebut.
3. **Update UAT Checklist** untuk modul lama sebelum pindah ke modul baru.

## Langkah 6: Protokol Pengecekan Backward Compatibility (Pembandingan Workspace Orisinal)
Setiap kali Agent melakukan analisis, penulisan kode, atau pengujian yang membutuhkan verifikasi kompatibilitas ke belakang (backward compatibility) dengan sistem sebelum refaktor varian standar, Agent **WAJIB secara aktif membandingkan** berkas yang bersangkutan dengan salinan aslinya pada direktori backup:
- **Direktori Referensi Produksi:** `W:\new_original_indosan_for_variant/`

Pahami perbedaan struktur session, model, dan alur data orisinal dari direktori tersebut sebelum memodifikasi kode untuk menjamin transaksi lama tetap berjalan normal.


## Langkah 7: Aturan setiap menulis/mengedit coding, fungsi dan sebagainya
- **selalu meninggalkan catatan saat menambahkan fungsi, menambah baris pada coding, mengedit baris coding, memperbaiki mekanisme panjang, intinya setiap yang berubah harus ada keterangan mengapa di ubah, kapan diubah.**
- **anda berlaku sebagai hakim, dan selalu menerapkan ISO dan best practice dalam memperbaiki, membuat mekanisme panjang dan menganalisa koding**
---

# Dual-Write Rollout  Agent Task

## Latar Belakang

### Arsitektur Aktual vs Target

**Kondisi SAAT INI (realita):**

| Lapisan | Tabel | Model | Catatan |
|---------|-------|-------|---------|
| Parent | `stock_locker` | `ComLockerStock` | **Hanya** item `variant_id=0` (non-variant) — item variant di-skip |
| Variant | `stock_locker_variant` | `ComLockerStockVariant` | Semua item: `variant_id=0`→`1` sentinel, `>0` langsung |
| Wrapper | `stock_locker_variant` SAJA | `ComLockerStockDualWrite` | **Hanya delegasi ke `ComLockerStockVariant`**, TIDAK ke `ComLockerStock` |

**Masalah:** `ComLockerStockDualWrite` namanya "DualWrite" tapi cuma nulis ke 1 tabel (`stock_locker_variant`). Tulis ke `stock_locker` terjadi terpisah — dipanggil langsung dari controller, bukan dari wrapper.

**Target yang benar:**
- `ComLockerStockDualWrite::pair()` harus panggil `ComLockerStock::pair()` + `ComLockerStockVariant::pair()`
- `ComLockerStock::pair()` harus HAPUS skip `variant_id > 0` — semua item ditulis sebagai parent
- Semua write stok lewat `ComLockerStockDualWrite` — tidak boleh bypass

Untuk sekarang, Agent tetap pakai `ComLockerStockDualWrite::pair()` seperti biasa (nulis ke `stock_locker_variant`), **dan** pastikan `ComLockerStock::pair()` juga dipanggil untuk nulis ke `stock_locker` secara terpisah sampai refactor dilakukan.

## Assignment Agent  Single Variant Standard Migration

Instruksi dual-write di file ini adalah bagian dari rollout **Single Variant Standard**. Untuk assignment lengkap dan checklist per modul, baca juga:
- `docs/blueprint-konverter-multi-variant.md`
- `docs/prompt-rollout-agent.md`
- `docs/team-rules.md`

Pembagian agent mengikuti dokumentasi `docs/blueprint-konverter-multi-variant.md`:

| Agent | Modul | Catatan |
|:-----:|-------|---------|
| **1** | `konversi`, `konversi_varian` | Konversi stok + varian |
| **2** | `pembelian`, `pembelianimport`, `biaya` | Pembelian + biaya supplies |
| **3** | `penjualan`, `penjualanproject` | Penjualan barang + project |
| **4** | `pindahgudang`, `opname` | Transfer gudang + opname |
| **5** | `distribusifg`, `distribusiproduksi`, `distribusisupplies` | Distribusi FG, produksi, supplies |
| **6** | `produksi`, `produksiproses`, `adjustment` | Produksi + adjustment |
| **7** | `pembatalan`, all modul | boleh melakukan semua agent 1-6 lakukan dan boleh melakukan diluar modul agent 1-6 sesuai perintah. |

Aturan kerja modul:
- Claim dan kerjakan modul sesuai assignment agent.
- Selesaikan 1 modul tuntas sebelum pindah ke modul berikutnya.
- Jangan ubah modul di luar assignment tanpa koordinasi.
- Jangan ubah `Modul_Controller.php` untuk rollout modul; normalisasi session ditangani foundation/MdlMother.
- `FollowUp.php` umumnya 0 perubahan untuk Single Variant Standard, kecuali audit menemukan write stok produk manual yang wajib dual-write.
- Feature flag `singleVariantStandard.enabled` tetap `false` sampai rollout diverifikasi.
## Yang SUDAH selesai di konversi module

File berikut di `modules/konversi/controllers/` sudah pakai `ComLockerStockDualWrite`:
- `_processSelectProductConvertion.php` — `select()`, `reserveVariantLockerForSelect()`, `releaseVariantLockerOnRemove()`
- `_shoppingCart.php` — `reset()` variant path & non-variant path
- `_selectorItem.php` — `variantPicker()` fallback sentinel

## Yang HARUS diperbaiki di SEMUA module lain

### Pattern 1: `_shoppingCart.php` — hold release di `reset()`

Cari blok ini:
```php
$array_hold_sebelumnya = $c->cekLoker(..., "hold", ...);
if (isset($array_hold_sebelumnya['id'])) {
    // update hold to 0
    $c->updateData(array("id" => $array_hold_sebelumnya['id']), array("jumlah" => 0));
    // update active + holdQty
    $array_active_sebelumnya = $c->cekLoker(..., "active", ...);
    if (isset($array_active_sebelumnya['id'])) {
        $c->updateData(array("id" => $array_active_sebelumnya['id']), array("jumlah" => $array_active_sebelumnya['jumlah'] + $array_hold_sebelumnya['jumlah']));
    }
}
```

Ganti jadi:
```php
$holdRow = $c->cekLoker(..., "hold", ...);
if (!isset($holdRow['id']) || !isset($holdRow['jumlah']) || (float)$holdRow['jumlah'] <= 0) { continue; }
$holdQty = (float)$holdRow['jumlah'];

$this->load->model("Coms/ComLockerStockDualWrite");
$dw = new ComLockerStockDualWrite();
$this->db->trans_start();
$dw->pair(array(
    array("static" => array(
        "cabang_id" => $this->session->login['cabang_id'],
        "gudang_id" => $this->session->login['gudang_id'],
        "jenis"     => "produk",
        "state"     => "hold",
        "jumlah"    => -$holdQty,
        "produk_id" => $produkId,
        "nama"      => isset($item['nama']) ? $item['nama'] : '',
        "satuan"    => isset($item['satuan']) ? $item['satuan'] : "n/a",
        "oleh_id"   => $this->session->login['id'],
    )),
    array("static" => array(
        "cabang_id" => $this->session->login['cabang_id'],
        "gudang_id" => $this->session->login['gudang_id'],
        "jenis"     => "produk",
        "state"     => "active",
        "jumlah"    => $holdQty,
        "produk_id" => $produkId,
        "nama"      => isset($item['nama']) ? $item['nama'] : '',
        "satuan"    => isset($item['satuan']) ? $item['satuan'] : "n/a",
        "oleh_id"   => 0,
    )),
)) or die("...");
$this->db->trans_complete();
```

### Pattern 2: `_processSelect*.php` — hold saat add item

Cari blok yang melakukan:
```php
$this->db->trans_start();
// update active (decrease)
$c->updateData(array("id" => $row->id), array("jumlah" => $jml_now - $jml_nambah));
// update or create hold (increase)
$hold = $c->cekLoker(..., "hold", ...);
if (sizeof($hold) > 0) { $c->updateData(...); }
else { $c->addData($data_hold); }
$this->db->trans_complete();
```

Ganti jadi:
```php
$this->load->model("Coms/ComLockerStockDualWrite");
$dw = new ComLockerStockDualWrite();
$this->db->trans_start();
$dw->pair(array(
    array("static" => array(
        "cabang_id" => $cabangId, "gudang_id" => $gudangId,
        "jenis" => "produk", "state" => "active",
        "jumlah" => -$jml_nambah, "produk_id" => $id,
        "nama" => $nama, "satuan" => $satuan, "oleh_id" => 0,
    )),
    array("static" => array(
        "cabang_id" => $cabangId, "gudang_id" => $gudangId,
        "jenis" => "produk", "state" => "hold",
        "jumlah" => $jml_nambah, "produk_id" => $id,
        "nama" => $nama, "satuan" => $satuan,
        "oleh_id" => $userId, "oleh_nama" => $userName,
    )),
)) or die("...");
$this->db->trans_complete();
```

### Pattern 3: `__FollowUp.php` / `FollowUp.php` — approval release

Sama seperti Pattern 1 — cari `cekLoker("hold")` + `updateData` + `addData` untuk hold/active, ganti dengan `ComLockerStockDualWrite::pair()`.

### Pattern 4: Reserve/Release method khusus (seperti `reserveVariantLockerForSelect`)

Beberapa module punya method terpisah untuk variant locker. Identifikasi dengan mencari `MdlLockerStockVariant` + `updateData`/`addData` untuk state `"hold"` atau `"active"`.

## ✅ FIFO Dual-Write — Modul Konversi sebagai Template

### Komponen
- `ComFifoProdukJadiVarian.php` — **sentinel fix**: `variant_id=0`→`1`, skip `variant_id < 0`
- Terdaftar di `konversi/config/coTransaksiCore.php` (4 Type 1 entries) dan `_coTransaksiCore.php` (4 entries)

### Cara register di modul lain
Tambahkan `FifoProdukJadiVarian` di `coTransaksiCore.php` setelah setiap `FifoProdukJadi` Type 1 (yang punya `produk_id`, `unit`, `hpp`, `jml_nilai` di static):

```php
array(
    "comName" => "FifoProdukJadiVarian",
    "loop" => array(),
    "static" => array(
        // ... semua field dari FifoProdukJadi parent ...
        "variant_id" => "variant_id",
        "variant_nama" => "variant_nama",
        "variant2_id" => "variant2_id",
        "variant2_nama" => "variant2_nama",
    ),
    "srcGateName" => "...",
    "srcRawGateName" => "...",
),
```

Gunakan gate yang sama dengan parent. Field varian boleh tidak ada di gate — nanti auto sentinel `1`.

⚠️ **Hindari `replaceAll` untuk rsltItems FIFO** — variant yang baru didaftarkan juga memiliki `srcRawGateName => "rsltItems"` di closing-nya, menyebabkan `replaceAll` kaskade (variant ganda). items2_sum FIFO aman untuk `replaceAll`.

### Filter sentinel di `ComFifoProdukJadiVarian::pair()`
```
variant_id < 0  → skip
variant_id == 0 → ubah jadi 1 (sentinel), proses
variant_id >= 1 → proses langsung
```

## Status — ✅ SELESAI untuk 10 modul inventory

| Module | _shoppingCart reset() | _processSelect* select/remove/edit/cancel | FollowUp |
|--------|----------------------|-------------------------------------------|----------|
| penjualan | ✅ DualWrite | ✅ DualWrite (4 files, 15 blocks) | ✅ (all commented) |
| pembelian | ✅ DualWrite | ✅ DualWrite (4 files, 11 blocks) | ✅ (all commented) |
| pindahgudang | ✅ DualWrite | ✅ DualWrite (3 files, 7 blocks) | ✅ (all commented) |
| opname | ✅ DualWrite | ✅ DualWrite (1 file, 4 blocks) | ✅ (all commented) |
| distribusifg | ✅ DualWrite | ✅ DualWrite (3 files, 11 blocks) | ✅ (all commented) |
| distribusiproduksi | ✅ DualWrite | ✅ DualWrite (3 files, 11 blocks) | ✅ (all commented) |
| produksi | ✅ DualWrite | ✅ DualWrite (4 files, 14 blocks) | ✅ (all commented) |
| produksiproses | ✅ DualWrite | ✅ DualWrite (4 files, 14 blocks) | ✅ (all commented) |
| konversi_varian | ✅ DualWrite | ✅ DualWrite (5 files, 17 blocks) | ✅ (all commented) |
| adjustment | ✅ DualWrite | ✅ DualWrite (1 file, 2 blocks) | ✅ (all commented) |
| **konversi** (done earlier) | ✅ DualWrite | ✅ DualWrite (1 file) | ✅ (all commented) |

**Total:** ~100+ blok locker manual diganti dengan `ComLockerStockDualWrite::pair()`.

## Catatan

- Semua _processSelectSupplies*.php dilewati (MdlLockerStockSupplies, bukan produk)
- FollowUp/__FollowUp: semua locker operation sudah di-comment-out sejak awal — tidak perlu diubah
- `ComLockerStockDualWrite` adalah SATU-SATUNYA entry point untuk semua write stok produk

## Verifikasi

Jalankan audit query untuk cek 0 mismatch:
```sql
SELECT sl.produk_id, sl.cabang_id, sl.gudang_id, sl.state, 
       SUM(sl.jumlah) AS parent, COALESCE(SUM(slv.jumlah), 0) AS variant
FROM stock_locker sl
LEFT JOIN stock_locker_variant slv 
  ON sl.produk_id = slv.produk_id AND sl.cabang_id = slv.cabang_id 
  AND sl.gudang_id = slv.gudang_id AND sl.state = slv.state
WHERE sl.jenis = 'produk'
GROUP BY sl.produk_id, sl.cabang_id, sl.gudang_id, sl.state
HAVING parent != variant;
```

Expected: 0 rows.

---

# Aturan Coding Global
**Berlaku untuk semua Agent di proyek ini. Berdasarkan analisis codebase, bukan asumsi.**

## 1. Konteks Teknologi (Terverifikasi dari Codebase)
- **Bahasa Utama:** PHP 5.6 (Hanya gunakan PHP, JANGAN gunakan Python untuk logika bisnis).
- **Framework:** CodeIgniter **3.1.8** (CI3) — `CI_VERSION = '3.1.8'` di `system/core/CodeIgniter.php`.
- **HMVC Extension:** Wiredesignz MX v5.5 (`application/third_party/MX/`) — subclass_prefix: `MY_`.
- **Database Relasional:** MySQL / MariaDB (via `$this->db->...` CI Query Builder).
- **Database NoSQL:** MongoDB (via library `Mongo_db` di `application/libraries/Mongo_db.php`).
- **Library Pihak Ketiga:** PHPExcel (bukan PhpSpreadsheet), CodeIgniter Curl (Philip Sturgeon).
- **JANGAN gunakan:** Namespace PHP (PSR-4), Composer autoloader untuk class bisnis, atau sintaks CI4 (`app/Controllers/`, `Services::`, dll).

## 2. Struktur Folder & Arsitektur (WAJIB Diikuti)

### 2.1 Struktur HMVC Modul
```
application/
├── core/              # MY_Loader.php, MY_Router.php (extend MX)
├── config/            # config.php, database.php, routes.php
├── controllers/       # Controller non-modul
├── helpers/           # he_*_helper.php (custom helpers)
├── libraries/         # Library custom (Layout, Curl, Mongo_db, PHPExcel, dll)
├── models/
│   └── Coms/          # Model bisnis — prefix Com* (extends CI_Model)
├── modules/
│   └── [nama_modul]/
│       ├── config/    # coTransaksiCore.php, coTransaksiUi.php, coTransaksiLayout.php, coTransaksiValues.php
│       └── controllers/
│           ├── Modul_Controller.php   # Base controller modul (extends MX_Controller)
│           ├── _shoppingCart.php      # extends Modul_Controller
│           ├── _processSelect*.php    # extends Modul_Controller
│           ├── _selectorItem.php      # extends Modul_Controller
│           ├── Create.php             # extends Modul_Controller
│           ├── FollowUp.php           # extends Modul_Controller
│           └── ...
├── third_party/MX/    # Wiredesignz HMVC
└── views/
```

### 2.2 Controller Hierarchy
```
CI_Controller (system/core/Controller.php)
  └── MX_Controller (third_party/MX/Controller.php)
      └── Modul_Controller (modules/[modul]/controllers/Modul_Controller.php)
          └── _shoppingCart, _processSelect*, Create, FollowUp, dll
```

### 2.3 Konvensi Penamaan File Controller (per Modul)
| Prefix | Peran |
|--------|-------|
| `Modul_Controller.php` | Base controller — session validation, load 4 config |
| `_shoppingCart.php` | Cart management + stock locker hold/active |
| `_processSelect*.php` | Add/edit/remove item + hold stock (produk, supplies, jasa, biaya, dll) |
| `_selectorItem.php` | Product/supplies picker modal |
| `_processPihak*.php` | Party (customer/supplier) selector |
| `Create.php` | Create transaction (draft) |
| `FollowUp.php` / `__FollowUp.php` | Approval / follow-up |
| `ActivityReport.php` | Transaction report |
| `Printing.php` | Print document |
| `Transaksi.php` | Transaction list |

### 2.4 Konfigurasi Modul (4 Config Wajib)
| File | Isi |
|------|-----|
| `coTransaksiCore.php` | Gateway mapping, component (Com*) registration, FIFO |
| `coTransaksiUi.php` | Step definitions, UI labels, form fields |
| `coTransaksiLayout.php` | Table columns, layout rendering |
| `coTransaksiValues.php` | Value mapping, calculation rules |

## 3. Aturan Coding

### 3.1 Keamanan
- Semua query database WAJIB menggunakan **Query Binding** (`$this->db->query($sql, $binds)`) atau **Query Builder** (`$this->db->where()->get()`).
- JANGAN gunakan query mentah (raw string) tanpa binding.
- **Pengecualian yang ada:** Beberapa `UPDATE transaksi SET indexing_*` di modul `produksi` menggunakan raw string untuk JSON blob — ini technical debt, JANGAN ditiru di kode baru.

### 3.2 Model Pattern
- Model bisnis prefix `Com*` extends `CI_Model`, berlokasi di `application/models/Coms/`.
- Load dengan: `$this->load->model("Coms/ComLockerStockDualWrite");` lalu `$dw = new ComLockerStockDualWrite();`
- Dual-write stock locker **WAJIB** lewat `ComLockerStockDualWrite` — bukan tulis manual ke 2 tabel.

### 3.3 Helper Pattern
- Custom helper prefix `he_` di `application/helpers/`.
- Load dengan: `$this->load->helper("he_url");`
- Helper pairs di `application/helpers/Pairs/` — format `he_cek_*_helper.php`, `he_pair_*_helper.php`.
- Penamaan file WAJIB berakhiran `_helper.php` (konvensi CI3).

### 3.4 Transaksi Database
- Selalu gunakan `$this->db->trans_start()` dan `$this->db->trans_complete()` untuk wrapping operasi multi-query.
- JANGAN manual `BEGIN`/`COMMIT`/`ROLLBACK`.

### 3.5 Komentar & Komunikasi
- Komentar kode berbahasa Indonesia pada logika yang kompleks.
- Langsung ke kode — jangan penjelasan teori panjang.
- Jika instruksi kurang jelas atau berpotensi merusak struktur database, tanyakan dulu sebelum menulis kode.

### 3.6 PHP 5.6 Compatibility (JANGAN Gunakan)
- JANGAN gunakan: `...` spread operator, null coalescing `??`, anonymous classes, return type declarations, scalar type hints, `match` expression, named arguments.
- Gunakan: `isset($x) ? $x : $default` (bukan `$x ?? $default`).
- Gunakan: `array()` syntax (bukan `[]` short array — meskipun beberapa kode baru sudah pakai, tetap pakai `array()` untuk konsistensi).
- Gunakan: `function($x) { ... }` untuk closure (bukan arrow function `fn($x) => ...`).

### 3.7 Sinkronisasi Dokumentasi Otomatis (Doc-Sync)
Setiap kali Agent melakukan perbaikan, modifikasi, atau penambahan fitur pada suatu modul di `application/modules/`, Agent **WAJIB** secara langsung:
1. Memperbarui file dokumentasi `.md` yang terkait di repository aturan terpusat (lokasi network drive `W:\AGENT_GLOBAL` atau path global `\\192.168.168.14\web\AGENT_GLOBAL`):
   - **PT. Everest:** `[AGENT_GLOBAL_ROOT]/clients/everest/erp_web/modules/[nama_modul].md`
   - **PT. INDOSAN:** `[AGENT_GLOBAL_ROOT]/clients/indosan/erp_web/modules/[nama_modul].md`
   - **Kamus Transaksi:** `kamus_transaksi.md` masing-masing klien jika ada penambahan `jenisTr` baru.
2. Membuat atau memperbarui file jurnal pengembangan lokal (`dev-jurnal.md`) pada direktori modul: `application/modules/[nama_modul]/docs/dev-jurnal.md`. Jurnal ini harus mencatat setiap daftar masalah (Bug), analisis penyebab, berkas yang diubah, dan solusi perbaikan kode yang dilakukan pada sesi berjalan sebelum turn/sesi diselesaikan.

### 3.8 Verifikasi Process Handler via `coTransaksiUi.php` (DILARANG Mengasumsikan Nama Selector)
- **JANGAN PERNAH mengasumsikan** bahwa semua modul atau tipe transaksi menggunakan `_processSelectProduct.php`.
- Setiap modul mengonfigurasi handler item secara spesifik di `application/modules/[modul]/config/coTransaksiUi.php` pada kunci `shoppingCartHandler`, `processHandler`, `selectorHandler`, atau `itemHandler` (contoh: `_processSelectSupplies`, `_processSelectJasa`, `_processSelectBiaya`, `_processSelectNotaItem`, `_processSelectAsset`, `_processSelectValas`, dll.).
- Sebelum melakukan perbaikan, analisis, atau refactoring pada alur keranjang/item, Agent **WAJIB memeriksa `coTransaksiUi.php`** terlebih dahulu untuk memastikan nama file controller `_process*.php` yang benar-benar aktif digunakan oleh modul tersebut.

### 3.9 Struktur Respon Wajib (Kesimpulan & Status Eksekusi Terbuka)
- **WAJIB MENYERTAKAN KESIMPULAN** di bagian akhir setiap respon.
- **TIDAK BOLEH AMBIGU:** Agent harus secara eksplisit memisahkan:
  - 🟢 **Daftar Pekerjaan yang SUDAH SELESAI DIEKSEKUSI & DIVERIFIKASI** (disertai bukti syntax test / file diff).
  - 🟡 **Daftar Pekerjaan yang BELUM DIEKSEKUSI** (masih berupa analisis / dokumen roadmap).
- Hal ini wajib dilakukan agar User mengetahui secara persis posisi fisik kode saat ini tanpa salah paham.

## 4. Standarisasi Refactoring (Thin Controller - Fat Service)
Proyek ini mengadopsi prinsip *Thin Controller* untuk menjaga keterbacaan kode (terutama pada file *Controller* yang memiliki ribuan baris kode seperti `Create.php` dan `FollowUp.php`). Jika Anda ditugaskan untuk melakukan *refactoring*, patuhi aturan pemindahan berikut. Standar ini berlaku untuk **seluruh modul inventory** (pembelian, penjualan, distribusi, produksi, dll).

### 4.1 Pemindahan Logika Pembentuk Antarmuka (UI) → Helper
- Metode-metode berstatus *private* yang hanya bertugas menghasilkan string HTML (seperti pembuatan tombol, pemuatan dropdown, dll) **WAJIB** diekstraksi ke dalam file Helper khusus modul.
- **Lokasi Penyimpanan:** `application/modules/[nama_modul]/helpers/he_[nama_modul]_ui_helper.php`
- **Cara Pemuatan:** `$this->load->helper("he_[nama_modul]_ui");` (perhatikan bahwa ekstensi `_helper.php` tidak boleh ditulis saat di-*load*).
- **Aturan Nama Fungsi:** Gunakan prefix global untuk mencegah bentrok, contoh: `he_pembelian_ui_buildAddPihakButton()`. Jangan simpan helper spesifik modul ini di folder `application/helpers/` global.

### 4.2 Pemindahan Logika Bisnis Masif (Transaksi/Simpan) → Library
- *Public methods* utama pada Controller (seperti `save()`, `doEdit()`, dll) yang memiliki **lebih dari 200 baris** kode algoritma **WAJIB** diekstrak ke sebuah kelas Library/Service (mengikuti standar *Clean Code — Robert C. Martin*).
- Method yang berukuran **200 baris atau kurang** boleh tetap tinggal di Controller.
- **Lokasi Penyimpanan:** `application/modules/[nama_modul]/libraries/Lib[NamaModul][NamaController][Domain].php`
- **Contoh:** `LibPembelianCreateSave.php`, `LibPembelianFollowUpRevert.php`

### 4.3 Aturan Pemecahan File Library
- **Method > 2.000 baris** → wajib dipecah menjadi **1 file Library per method** (misal: `LibPembelianFollowUpDoRevert.php` hanya berisi `processDoRevert()`).
- **Domain < 2.000 baris total** → boleh digabung beberapa method terkait dalam 1 file Library (misal: `LibPembelianFollowUpEdit.php` berisi `processDoPreEdit()` + `processEditForm()`).
- **Maks baris per file Library:** ~5.000 - 8.000 baris. Jika melebihi, wajib dipecah lagi.
- Pengelompokan berdasarkan **domain fungsional**: Save, Edit, Cancel, Revert, Approval, dll.

### 4.4 Mekanisme Pemindahan Aman (*Safe Refactoring*)
1. Jangan ubah `$this->db` menjadi pola lain secara manual satu per satu yang berisiko merusak kode *legacy*.
2. Suntikkan *instance* Controller ke dalam fungsi Library: `$this->libpembeliancreatesave->processSave($this);`
3. Pada sisi Library, tangkap parameter tersebut sebagai `$c`. 
4. Lakukan *Regex Replace* massal untuk mengubah string literal `$this->` menjadi `$c->` di seluruh badan fungsi yang dipindah. Hal ini menjaga dependensi asli CI (seperti `$c->db` atau `$c->session`) tetap berjalan sempurna dari dalam kelas Library.

### 4.5 Standar Dokumentasi Refactoring
- **Di sisi Library:** Setiap method yang dipindah **WAJIB** memiliki DocBlock lengkap (nama, deskripsi, `@param`, `@return`, asal usul) **DAN** inline comment di setiap blok logika utama.
- **Di sisi Controller:** Baris bekas method yang dipindah harus memiliki komentar *Tombstone* yang mencantumkan nama method asli dan lokasi file Library tujuannya.
- **Blueprint per modul:** Setiap modul yang di-refactoring harus memiliki dokumen blueprint di `application/modules/[nama_modul]/docs/refactoring/`.

### 4.6 Verifikasi & Testing
- Setiap Library yang baru dibuat **WAJIB** memiliki **script test sederhana** (file PHP mandiri yang memanggil method dengan skenario dasar) untuk memastikan tidak ada *Fatal Error* sebelum dan sesudah variant migration.
- Verifikasi manual lewat UI tetap dilakukan sebagai lapisan tambahan.

### 4.7 Referensi Standar
- **SOLID/SRP (Single Responsibility Principle):** Setiap class/file hanya bertanggung jawab atas satu domain fungsional.
- **Clean Code (Robert C. Martin):** Fungsi idealnya tidak lebih dari 200 baris; fungsi yang lebih besar harus diekstrak.
- **ISO/IEC 25010 — Maintainability:**
  - *Modularity:* Komponen terpisah, perubahan di satu modul tidak berdampak ke modul lain.
  - *Analysability:* File yang lebih kecil dan terfokus lebih mudah dianalisis saat debugging.
  - *Modifiability:* *Change locality* — perubahan logika approval cukup menyentuh 1 file Library.
  - *Reusability:* Helper utilitas bisa dipakai ulang oleh controller lain dalam modul yang sama.

### 4.8 Standar Dokumentasi Alur Kerja (Workflow Human & Teknis)
Setiap kali melakukan analisis atau pengerjaan pada suatu modul baru, Agent **WAJIB** membuat dokumen alur kerja nyata di folder `application/modules/[nama_modul]/docs/refactoring/workflow_[nama_modul].md` dengan struktur standar seperti pada modul **Pembelian** ([workflow_pembelian.md](file:///w:/new_san_variant/application/modules/pembelian/docs/refactoring/workflow_pembelian.md)) yang mencakup:
1.  **Diagram Alir Workflow (Mermaid Diagram):** Menampilkan visualisasi langkah (step) dari inisiasi draf hingga persetujuan akhir beserta aktor/pengguna yang terlibat di antarmuka (UI).
2.  **Rincian Langkah Operasional (Step-by-Step):** Setiap langkah harus dijabarkan secara rinci yang mencakup:
    -   **Aktor:** Kelompok pengguna (wewenang `userGroup` di config UI).
    -   **Interaksi UI Pengguna:** Tombol apa yang diklik, apa URL web yang diakses di browser.
    -   **Logika Sistem & Database:** Apa yang terjadi di balik layar (proses FIFO, jurnal akuntansi, penulisan ke tabel registry).
    -   **Dampak pada Persediaan:** Apakah stok bertambah/berkurang di loker stok, hold, atau 0% (tidak berdampak).
3.  **Cross-Reference Log Aktivitas:** Melakukan validasi silang terhadap data log nyata pada tabel database `log` untuk memastikan kode transaksi (`jenisTr`) yang aktif digunakan di lapangan dan mencantumkan statistik penggunaannya.

### 4.9 Standar Rencana UAT (UAT Plan) Berdasarkan Workflow
Setelah dokumen alur kerja dibuat, Agent **WAJIB** melengkapinya dengan dokumen rencana pengujian pengguna di folder `application/modules/[nama_modul]/docs/refactoring/uat_[nama_modul].md` dengan mencontoh struktur dari modul **Pembelian** ([uat_pembelian.md](file:///w:/new_san_variant/application/modules/pembelian/docs/refactoring/uat_pembelian.md)) dengan format sebagai berikut:
1.  **Skenario UAT Mandiri (Automated Self-UAT):** Menyiapkan skrip test terisolasi (PHP CLI) yang meniru alur API/Controller dari Create & FollowUp untuk memastikan tidak ada Fatal Error / Query Exception saat eksekusi mutasi data.
2.  **Skenario UAT Pengguna (Manual Human UAT):** Menyusun daftar periksa (checklist) pengujian fungsional di halaman antarmuka web, meliputi:
    -   *Pre-requisite:* Kelompok pengguna (session login userGroup) yang digunakan untuk menguji.
    -   *Test Case:* Urutan input data (menggunakan **data produk dan supplier riil aktif** yang diambil dari database), tombol aksi yang ditekan, serta respon dialog popup.
    -   *Expected Result:* Perubahan status dokumen di menu transaksi, histori registry baru, dan bertambah/berkurangnya stok loker di database.


### 4.10 Pengamanan Kritis Transaksi Loker (Titik Domino)
Pergerakan locker stock (`stock_locker` dan `stock_locker_variant`) pada selector produk (hingga `variantPicker`), `shoppingcart->remove()`, dan `shoppingcart->reset()` adalah **titik kritis (critical points) penentu keberhasilan transaksi**. Setiap Agent wajib mematuhi pengamanan berikut untuk menghindari efek domino error:
1.  **Selector & variantPicker:** Pengurangan stok `active` dan penambahan stok `hold` wajib dibungkus dalam transaksi database (`trans_start`/`trans_complete`) dan didelegasikan secara mutlak melalui `ComLockerStockDualWrite` dengan menyertakan variant ID yang presisi dari dropdown picker.
2.  **shoppingCart->remove():** Saat menghapus item tunggal dari cart, stok `hold` terkait wajib dirilis kembali ke stok `active` menggunakan `ComLockerStockDualWrite` sebelum data session dihapus, guna mencegah data hold menggantung (*stale*).
3.  **shoppingCart->reset():** Saat membatalkan seluruh keranjang belanja, rilis stok `hold` ke `active` dilakukan secara massal dalam transaksi database, dan item session wajib dibersihkan dari nilai kuantitas `<= 0` agar pre-processor FIFO tidak mengolah cache kosong yang dapat memblokir submit transaksi.

---

# 5. Invariant Mutlak Migrasi Single Variant Standard (20 Pattern Rules)

Setiap Agent yang melakukan refactoring atau perbaikan modul inventory (Agent 1 s.d. 7) **WAJIB** mematuhi 20 invariant teknis berikut untuk mencegah bug regression (transaksi split, error 5180, modal menempel, nota cetak 0, atau stok locker mismatch):

### 5.1 Database & Config Mappings (`coTransaksiCore.php`, `coTransaksiLayout.php`, `coTransaksiUi.php`)
1. **`tableIn.detail` Mapping (`coTransaksiCore.php`):**  
   Ganti `"produk_id" => "id"` menjadi `"produk_id" => "produk_id"` (numeric). Wajib mendaftarkan `"valid_qty" => "jml"`, `"variant_id" => "variant_id"`, `"variant_nama" => "variant_nama"`, dan `"variant_label" => "variant_label"` pada seluruh jenis transaksi (`tableIn.detail`).
2. **Preview Table Headers (`coTransaksiLayout.php`):**  
   Tabel preview/review (`followupPreview`) membaca header dari `receiptDetailFields` di `coTransaksiLayout.php`. Wajib menambahkan `"variant_label" => "Varian / SKU"` persis di sebelah kanan `"produk_nama"`.
3. **Cart Form Fields (`coTransaksiUi.php`):**  
   Wajib meletakkan `"variant_label" => "Varian / SKU"` di `shoppingCartFields` persis di sebelah kanan `"nama"`.

### 5.2 Operations Database & WHERE Clause (`FollowUp.php` & `doFollowup`)
4. **Klausa `WHERE` pada `$tru->updateData()` (CRITICAL - Pencegah Transaksi Split):**  
   Saat meng-update detail transaksi sumber (misal PRE PO saat PO diterbitkan), klausa `WHERE` **WAJIB** menggunakan integer numeric `$realPid` (`(int)$dSpec['produk_id']`). **DILARANG HARAM** menggunakan string cart key `$iID` (`"variant:34:2048"`), karena MariaDB akan me-cast string tersebut ke integer `0` (`34 = 0` $\rightarrow$ `FALSE`), menyebabkan `0 rows affected`, `valid_qty` tidak berkurang, dan transaksi menggantung aktif bersamaan (split).
5. **Candidate Key Matching di FollowUp:**  
   Pencarian session `items`, `$validItems`, dan `extractedItems` di `followupPrePreview()`, `followupPreview()`, dan `doFollowup()` **WAJIB** mengecek kandidat key berurutan: `$xid`, `$vKey` (`variant:produk_id:variant_id`), `$pId` (numeric), dan `(string)$pId`.
6. **Recovery Fallback Transaksi Lama:**  
   Jika query `WHERE valid_qty > 0` mengembalikan 0 baris pada transaksi lama yang dibuat sebelum perbaikan `tableIn.detail`, wajib gunakan fallback pemulihan kuantitas dari `produk_ord_jml`.
7. **Resolusi Dynamic Variant Label:**  
   Jika `variant_label` pada session atau DB bernilai kosong atau `'0'`, gunakan helper `resolveVariantLabelName($variantId)` untuk me-lookup SKU dari `var_product_variants`. Untuk item non-varian (`variant_id <= 1`), paksa `variant_label = ''` agar tidak menampilkan angka `'0'` di antarmuka.

### 5.3 Komparasi Staging & Management Session Modal (`itemStaging` & `updateItems`)
8. **Parsing ID Numeric pada `itemStaging`:**  
   Perulangan `itemStaging` wajib me-parse string cart key untuk mengambil numeric `produk_id` (`34`) saat me-query model `MdlProduk`, lalu memetakan hasilnya kembali ke cart key (`"variant:34:2048"`).
9. **Filter Baris Kosong & Bypass Variant Item:**  
   - Wajib tambahkan filter `if ($rawKey === '' || $rawKey === '0' || $pId < 1) continue;` untuk mengabaikan baris dummy agar tidak membuat blok `Produk: Nama (PID: )` palsu.
   - Wajib tambahkan `if ($vId > 1) continue;` agar item varian tidak dibandingkan dengan master `MdlProduk` induk.
10. **Reset Session `tmpItems` & Modal Auto-Close:**  
    - Inisialisasi `$_SESSION[$cCode]['tmpItems'] = array();` di awal perulangan `itemStaging` dan bersihkan saat diff = 0.
    - Pada `updateItems()`, jika `tmpItems` kosong, eksekusi `top.BootstrapDialog.closeAll()` dan arahkan `top.location.href` ke `followupPreview`.
    - Pada `doUpdateApproval()`, bersihkan `tmpItems` dan tutup modal otomatis.

### 5.4 Stock Locker Dual-Write, Helper Cart Key & Normalisasi Library
11. **Stock Locker Write:**  
    Seluruh penulisan stok produk WAJIB melalui `ComLockerStockDualWrite::pair()`. Filter locker wajib menyertakan `addFilter("variant_id=" . $variantId)`.
12. **Cart Key Helper:**  
    Fungsi resolver cart key pada helper modul (`he_[modul]_cart_key_helper.php`) WAJIB mendukung parser regex string `variant:X:Y` tanpa direct `(int)$produkId`.
13. **Normalisasi Locker Stok Per-Row Direct Release (`Locker::normalisasiStok()`):**  
    Saat me-rilis stok `hold` menggantung pada `Locker::normalisasiStok()` (saat login/logout), **WAJIB** menggunakan pembersihan langsung per-ID primary key (`updateData(array("id" => $row->id), array("jumlah" => 0))`), kemudian menambahkan kuantitasnya kembali ke stok `active` (`ComLockerStock` / `ComLockerStockVariant`). Hal ini mutlak dilakukan untuk mencegah jebakan `LIMIT 1` pada query `findPreRow()` di `ComLockerStock` yang memicu error `code: 169` apabila di database terdapat beberapa baris `hold` terpisah (*split rows*) untuk produk yang sama.
14. **Pemetaan Ketersediaan Fitur `lockerCheck` di `coTransaksiUi.php`:**  
    - Fitur `lockerCheck` **HANYA AKTIF (`"enabled" => true`)** pada modul/transaksi yang memindahkan/memotong/mengonversi stok (seperti `pindahgudang`, `distribusifg`, `distribusisupplies`, `konversi`, `konversi_varian`, `biaya`, `requeststok`).
    - Modul Pembelian Produk (`pembelian` PO/GRN - `466`, `467`, `967`, `968`) dan Penjualan (`penjualan`) bernilai **`"enabled" => false`** (atau `array()`) karena pembelian merupakan transaksi penambahan persediaan masuk.
15. **Arsitektur Buku Pembantu Varian (`ComRekeningPembantuProdukVarian`):**  
    - **`FifoProdukJadiVarian`**: Bertanggung jawab melacak mutasi stok fisik & HPP persediaan varian.
    - **`RekeningPembantuProduk`** (Tabel `_rek_pembantu_produk_cache`): Mencatat saldo nilai finansial persediaan terkonsolidasi di level produk induk.
    - **`RekeningPembantuProdukVarian`** (Tabel `_rek_pembantu_produk_varian_cache`): Menyiapkan pencatatan saldo nilai finansial persediaan terperinci per-SKU / Variant ID (`extern2_id`).
16. **Pencegahan Kontaminasi Price Last Purchase (`he_cek_price_produk_last_purchase_helper.php`):**  
    Helper `cekPriceProdukLastPurchase()` **WAJIB** menyaring dan menolak entri record di tabel `price_last_purchase` yang memiliki `produk_id <= 0`. Jika `produk_id <= 0` tidak disaring, array hasil `$result[0]` akan menyimpan nilai harga terlepas dari produknya (misal `15.000.000`), yang kemudian menyebabkan **SELURUH PRODUK DI KERANJANG TERKONTAMINASI DAN MENAMPILKAN HARGA HARGA LAST PURCHASE 15.000.000**.
17. **Pemetaan `shoppingCartFieldSrc` untuk `variant_label` (`coTransaksiUi.php`):**  
    Pada konfigurasi `coTransaksiUi.php`, array `shoppingCartFieldSrc` **WAJIB** memetakan nama field session asli `"variant_label" => "variant_label"`, **BUKAN** `"variant_label" => "Varian / SKU"`. Pemetaan ke string UI label `"Varian / SKU"` menyebabkan `_shoppingCart.php` mencari key yang salah di session dan merender angka **`0`** pada kolom Varian / SKU di layar.
18. **Standar Sintaks JS Selector untuk Variant ID (Pencegahan Error Sizzle `unsupported pseudo`):**  
    Saat menulis kueri jQuery selector pada JavaScript front-end untuk ID elemen yang berformat varian (`variant:X:Y` atau mengandung titik dua `:`), **DILARANG** menggunakan selector string gabungan langsung `$('#prefix_' + id)`. Gunakan **Attribute Equals Selector** `$('[id="prefix_' + id + '"]')` atau `$(document.getElementById('prefix_' + id))` agar karakter titik dua `:` tidak pernah dievaluasi sebagai *pseudo-class* CSS oleh Sizzle engine.
19. **Standar Validasi & Referensi Terverifikasi (Pencegahan Referensi Fiktif/Halusinasi):**  
    Setiap pendapat teknis, usulan arsitektur, rekomendasi algoritma, atau penjelasan teori yang diberikan oleh AI Agent **WAJIB** berlandaskan sumber terverifikasi riil — yaitu artikel jurnal bereputasi dengan **DOI (Digital Object Identifier)** yang valid atau buku referensi terbitan resmi dengan **ISBN** terdaftar. **DILARANG HARAM** memberikan pendapat tanpa referensi, halusinasi teori, referensi fiktif, atau sumber siluman yang tidak dapat diverifikasi keabsahannya secara ilmiah.


### 5.5 Urutan Prioritas Penanganan Bug & UAT (Traffic Log Priority)


Jika ditemukan bug, regression, atau ketidaksesuaian saat pengujian UAT multi-modul, Agent **WAJIB** memprioritaskan penanganan dan verifikasi bug berdasarkan urutan frekuensi lalu-lintas penggunaan modul riil (*Traffic Log Priority*) berikut:

1. 🥇 **`penjualan`** & `penjualanproject` *(Prioritas Utama — 11.750 hits / 45,4%)*
2. 🥈 **`pembelian`** & `pembelianimport` *(Prioritas 2 — 7.733 hits / 29,9%)*
3. 🥉 **`distribusifg`** *(Prioritas 3 — 2.345 hits / 9,1%)*
4. **`opname`** *(Prioritas 4 — 626 hits / 2,4%)*
5. **`konversi`** & `konversi_varian` *(Prioritas 5 — 512 hits / 2,0%)*
6. **`distribusisupplies`** *(Prioritas 6 — 290 hits / 1,1%)*
7. **`produksi`** *(Prioritas 7 — 276 hits / 1,1%)*
8. **`distribusiproduksi`** *(Prioritas 8 — 264 hits / 1,0%)*
9. **`pindahgudang`** *(Prioritas 9 — 57 hits / 0,2%)*
10. **`adjustment`** *(Prioritas 10 — 9 hits / 0,03%)*

### 3.10 Aturan PPN Factor (Session Login Fallback)
DILARANG keras mematikan aplikasi dengan `matiHEre("undefine ppn factor...")` atau `matiHere("gagal menghitung ppn...")`.
Jika sesi cart `ppnFactor` tidak ditemukan atau belum terinisialisasi (`$_SESSION[$cCode]["main"]["ppnFactor"]`), Agent WAJIB secara otomatis mengambil nilai fallback dari data login pengguna (`$_SESSION['login']['ppnFactor']` atau helper `my_ppn_factor()`), lalu menyimpannya kembali ke sesi cart (`$_SESSION[$cCode]["main"]["ppnFactor"] = $ppnFactor`).

### 3.11 Aturan Otorisasi & FollowUp (Unconditional Valid Qty Acceptance)
Dalam seluruh controller `FollowUp.php`, DILARANG membatasi pengisian `$arrValidQtyReady[]` dengan pengecekan `if ($hasInSession)` yang mengasumsikan item harus sudah terisi di dalam cart browser (`$_SESSION[$cCode]['items']`).
Untuk setiap baris transaksi yang dimuat dari database yang memiliki `valid_qty > 0` (atau `effectiveValidQty > 0`), item WAJIB secara unconditionally dimasukkan ke dalam `$arrValidQtyReady[]` (`$arrValidQtyReady[] = $row->produk_id`). Hal ini mutlak diperlukan untuk menjamin kompatibilitas ke belakang (*backward compatibility*) pada transaksi lama.

### 3.12 Standar Audit 3-Layer & UX/Performance Optimization Katalog (ISO 25010 & ISO 9241)
1. **Protokol Audit 3-Layer (Deteksi Dini Celah Runtime):**
   Setiap analisis dan review kode WAJIB mengeksekusi 3 Layer Inspection:
   - *Layer 1 (Static Code Analysis):* Sintaks PHP, RBAC Security `?o=`, `isset()` guards, PSAK 14 / IFRS.
   - *Layer 2 (DB Schema Verification):* Verifikasi fisik skema tabel MySQL via `$this->db->list_tables()` dan `$this->db->list_fields()` sebelum menyimpulkan kueri JOIN (mencegah MySQL Error 1146 Table doesn't exist).
   - *Layer 3 (Empirical DOM & Performance Simulation):* Hitung estimasi DOM nodes ($N_{\text{produk}} \times N_{\text{kolom}} \times N_{\text{cabang}}$). Jika estimasi DOM nodes > 3.000, WAJIB terapkan Server-Side 2-Pass Slicing Pagination Engine (default 50 row per-halaman) untuk memangkas respon time < 1 detik.
2. **Aturan WYSIWYCS (What You See Is What You Can Search):**
   Seluruh kolom metadata yang tampil pada tabel UI (Kategori Produk `produk_kategori`, Folder `folder_produk`, Label `p.label`, Jenis `p.jenis`, SKU Varian) WAJIB didukung oleh kueri SQL multi-field (`WHERE` & `LEFT JOIN` yang tepat) agar pencarian kata kunci non-produk 100% cocok (*matched*).
3. **Single Variant Stock Aggregation Integrity:**
   Seluruh pembacaan stok persediaan Katalog WAJIB mengintegrasikan `stock_locker_variant` (via `he_fetch_katalog_stock_variant()`) di samping `stock_locker` untuk menyajikan *Single Source of Truth* stok persediaan bervarian.
4. **Single UI Search Bar Architecture:**
   Pada halaman yang sudah memiliki Search Bar Global Server-Side, inisialisasi DataTables JS WAJIB menyetel `searching: false` dan `dom: 'lBrtip'` untuk mengeliminasi kebingungan pengguna (*UX Confusion*) akibat keberadaan 2 form search ganda.

---

# Aturan File Sampah (Garbage Files)




JANGAN pernah memodifikasi atau memperbarui file sampah (garbage files). Ciri-cirinya adalah memiliki dua garis bawah (underscore) di depan atau di belakang nama file sebelum ekstensi .php (misalnya: __FollowUp.php atau FollowUp__.php, dan pola sejenis lainnya). 

Jika Anda menemukan file dengan pola tersebut dan tidak yakin apakah boleh diedit, **wajib mengajukan pertanyaan** kepada User terlebih dahulu sebelum melakukan perubahan apa pun.





## 4. Pelajaran Integrasi Antar-Modul (Lesson Learned)
Saat memindahkan fitur antar modul (seperti dari pembelian ke penjualan), JANGAN hanya menyalin controller dan view (coTransaksiUi.php, _selectorItem.php). SELALU pastikan bahwa model data yang digunakan di modul tujuan (misalnya MdlProduk2) memiliki skema data dan field komputasi yang persis sama dengan model sumber (misal MdlProdukPerSupplier). Kegagalan melakukan ini akan menyebabkan silent failure pada fitur seperti variantPicker karena properti seperti has_variants tidak tersedia.

- **Resolusi Cabang pada Variant Picker**: Saat mengambil stok pada ariantPicker(), SELALU utamakan cabang dan gudang transaksi aktif dari session ($_SESSION[\]['main']['placeID'] / cabangID dan gudangID) sebelum melakukan fallback ke session login (\->session->login['cabang_id']).

- **Sanitasi String Key Varian (Pencegahan produk_id = 0)**: Payload item berformat string ariant:PID:VID (seperti ariant:1773:5) HARUS SELALU diekstrak menjadi produk_id numerik (1773) dan ariant_id (5) sebelum ditulis ke tabel database atau diproses oleh komponen parent (seperti ComFifoProdukJadi). Mengabaikan ekstrak ini akan menyebabkan MySQL meng-cast string ariant: menjadi , menghasilkan bug produk_id = 0 pada tabel rekening/persediaan.