# 🛡️ PANDUAN DAN BLUEPRINT MODUL STOK OPNAME (AGENTS_OPNAME) 🛡️

Dokumen ini berisi rangkuman arsitektur, histori perbaikan performa, dan panduan teknis khusus modul **Stok Opname** (transaksi tipe `1119` untuk Gudang Good / PUSAT DC, dan `2229` untuk Gudang Project). Dokumen ini wajib dibaca dan dipatuhi oleh setiap AI Agent berikutnya yang melanjutkan pengembangan modul ini.

---

## 1. STRUKTUR BERKAS MODUL OPNAME
*   **Controllers:**
    *   `application/modules/opname/controllers/Opname.php` - Alur utama, inisiasi sesi draf opname, input fisik, eksekusi, serta unggah berkas excel.
    *   `application/modules/opname/controllers/FollowUp.php` - Alur pratinjau persetujuan (*approval preview*) dan otorisasi tingkat 1/2.
*   **Models:**
    *   `application/models/Mdls/MdlDashboardOpname.php` - Status sesi aktif opname (`status=1`, `confirm_id=0`).
    *   `application/models/Mdls/MdlDashboardOpnameData.php` - Log item detail opname (`dashboard_opname_data`).
*   **Views:**
    *   `application/modules/opname/views/` - Khususnya file `transaksi.php` yang digunakan untuk merender tabel e-form persetujuan.
*   **Libraries & Helpers Terkait:**
    *   `application/libraries/Excel.php` - Library PHPExcel wrapper untuk manipulasi XLS.
    *   `application/helpers/he_format_helper.php` - Helper formatter visual e-form (`formatField`).

---

## 2. PENYELESAIAN MASALAH & OPTIMASI (Selesai Diterapkan)

### A. Optimasi Performa & Kecepatan Rendering (Mencegah Error 503)
*   **Masalah:** Saat memuat modal *approval request* dengan data yang masif (2200+ item), Apache memicu HTTP 503 "Service Unavailable" (Timeout FastCGI 60 detik) karena CPU overhead saat merender ribuan elemen form.
*   **Solusi:**
    1.  **Eager Loading Library:** Memindahkan instansiasi objek `FieldCalculator` keluar dari perulangan baris produk di `FollowUp::followupPreview()`.
    2.  **Static Caching Formatter:** Menerapkan variabel `static` pada fungsi pembantu formatting di `he_format_helper.php` (`formatField()`, `formatField_he_format()`, dan `formatField_he_format_json()`). Hal ini mencegah pemuatan konfigurasi `heTransaksi_ui` dan library `MataUang` sebanyak 22.000+ kali secara redundan (sekarang dimuat hanya **1 kali saja** di pemanggilan pertama per request).

### B. Akurasi Dashboard Monitoring (Best Practice)
*   **Masalah:** Progress baris "PUSAT (DC)" di dashboard monitoring menampilkan `69 / 80` yang membingungkan karena penyebutnya (`80`) adalah seluruh kategori di database. Padahal, operator memang hanya menargetkan 69 kategori pada sesi tersebut (progress harusnya `69 / 69` atau status "ok" saat selesai).
*   **Solusi:**
    *   Mengubah perhitungan `$totalCats` di `viewOpnameAktive()` pada [Opname.php](file:///w:/everest_20jul/application/modules/opname/controllers/Opname.php) agar mengambil data join ke tabel `dashboard_opname_data`. Penyebut kemajuan kini dinamis mengikuti jumlah kategori target pada sesi berjalan.

### C. Kecepatan Eksekusi Unggah Excel
*   **Masalah:** Unggah template Excel berisi ribuan data stok opname memakan waktu berputar (I/O disk berulang) hingga menit dan sering gagal.
*   **Solusi:**
    *   Membungkus alur looping update query di dalam transaksi database tunggal (`$this->db->trans_start()` dan `$this->db->trans_complete()`) pada `Opname::executeOpname()`. Kecepatan meningkat 90%+ (dari menit menjadi 1-2 detik).

### D. Perbaikan Unduhan Excel Rusak/Korup
*   **Masalah:** Mengunduh berkas Excel gagal dan filenya rusak saat dibuka karena CentOS PHP-FPM memblokir folder temporary default OS `/tmp` (masalah `open_basedir` & write permissions).
*   **Solusi:**
    *   Mengalihkan target folder pembuatan file temp PHPExcel di [Excel.php](file:///w:/everest_20jul/application/libraries/Excel.php) dari `sys_get_temp_dir()` ke folder internal proyek yang memiliki hak akses penuh: `FCPATH . 'uploads/'`.
    *   Menambahkan perintah `ob_clean()` dan `flush()` tepat sebelum pengiriman header download pada method `writer()` untuk mencegah kebocoran buffer output PHP yang merusak format biner file XLS.

### E. Penataan Visual Antarmuka (UI/UX)
*   **Penyelarasan Posisi:** Memindahkan pilihan Cabang & Gudang ke posisi teratas modal dialog e-form stok opname.
*   **Collapsed Merek:** Komponen pilihan Merek diposisikan di bawahnya dengan status tersembunyi default (`display: none;`).
*   **jQuery Auto-Expand:** Menambahkan event handler JQuery `.slideDown(300)` pada fungsi callback select gudang `onGudangSelect()`. Area Merek otomatis meluncur terbuka begitu gudang selesai dipilih.

---

## 3. INSTRUKSI KRITIS UNTUK AI AGENT BERIKUTNYA

1.  **PHP 5.6 Compatibility (Wajib):**
    *   DILARANG keras menggunakan syntax PHP modern seperti Null Coalescing Operator (`??`), Short Array Syntax (`[]`), Arrow Functions (`fn()`), atau spread operator (`...`).
    *   Gunakan `isset($x) ? $x : $default` dan struktur `array()`.
2.  **Zero Placeholders:**
    *   DILARANG menyembunyikan atau memotong kode yang sudah ada dengan komentar `// ...` atau `/* existing code */`. Seluruh fungsi yang diubah wajib dituliskan utuh dari bracket `{` hingga `}`.
3.  **Protokol Keamanan File Upload:**
    *   Jika melakukan penambahan/modifikasi fitur unggahan berkas, pastikan untuk selalu memverifikasi tipe biner MIME (MIME-Type asli) dari berkas yang diunggah dan lakukan pengacakan nama berkas (*randomize filename*) demi keamanan server (ISO 27001).
4.  **Transaction Wrapper:**
    *   Gunakan wrapping query multi-tabel menggunakan transaksi database bawaan CodeIgniter 3 (`$this->db->trans_start()` / `$this->db->trans_complete()`). Jangan menggunakan raw manual transaction control (`BEGIN`/`COMMIT`/`ROLLBACK`).