# Runbook Implementasi UI Hirarki Piutang Pembelian (Reusable)

Runbook ini adalah panduan eksekusi langkah demi langkah untuk menerapkan hirarki piutang pembelian (credit note supplier) pada level tampilan (UI-only), tanpa mengubah logic transaksi/jurnal.

Kompatibilitas target:
- PHP 5.6
- CodeIgniter 3

## 1. Tujuan
Menerapkan tampilan hirarki piutang pembelian yang konsisten dan mudah dibaca, dengan struktur:
1. Piutang Pembelian (utama)
2. Kategori credit note aktif (default: 1 kartu utama)
3. Cabang/Unit (opsional)
4. Supplier/Vendor (subledger detail)

## 2. Batasan Implementasi
Wajib:
- Perubahan hanya di view/CSS/JS dan mapping data tampilan di controller.
- Perhitungan saldo tetap memakai sumber data existing.
- Posisi saldo mengikuti `detectRekDefaultPosition()` (jangan hardcode `debet-kredit` atau `kredit-debet`).
- Tema/label modul tetap `Piutang Pembelian` / `Credit Note`.

Dilarang:
- Ubah struktur database.
- Ubah posting jurnal.
- Ubah core business rule transaksi.
- Mencampur modul ini dengan `Uang Muka Supplier`.

Catatan pemisahan modul:
- `Piutang Pembelian` tetap pada rekening `1010020030` (`RekeningPembantuSupplier`).
- `Uang Muka Supplier` tetap pada rekening `1010050010` / `1010050020` (`RekeningPembantuUangMuka*`).

## 3. Input Wajib Sebelum Mulai
- Daftar akun piutang pembelian yang tampil (kode + nama).
- Mapping kategori aktif dan kode akun (minimal `1010020030`).
- Keputusan akun legacy: show/hide.
- Halaman target (controller + view).
- Acuan visual (screenshot/desain).

## 4. Output Akhir Yang Diharapkan
- Panel hirarki piutang pembelian tampil di halaman target.
- Kartu kategori utama menampilkan saldo dan jumlah supplier.
- Total gabungan kategori aktif tampil.
- Filter periode/search/export existing tetap normal.
- Akun legacy mengikuti keputusan (mis. hidden).
- Tidak ada perubahan label/tema menjadi uang muka.

## 5. Urutan Eksekusi (End-to-End)

### Step 1 - Discovery Lokasi Kode
1. Cari controller halaman piutang pembelian yang menyiapkan data.
2. Cari view yang merender panel summary + tabel detail.
3. Catat helper formatter (uang/tanggal) dan file JS filter.
4. Catat titik rawan reuse (template dipakai halaman lain).

Deliverable:
- Daftar file target (controller/view/CSS/JS).

### Step 2 - Mapping Hirarki Data Untuk UI
1. Definisikan struktur array untuk hirarki piutang pembelian di controller.
2. Tetapkan field minimal per kartu:
   - label
   - note
   - kode akun
   - saldo
   - count (supplier)
   - route_enabled
   - hide_in_ui
3. Tetapkan object totals:
   - total kategori aktif
   - total semua (opsional)
   - count agregat supplier
   - legacy_hidden

Deliverable:
- Data siap render di view tanpa mengubah query bisnis inti.

### Step 3 - Implementasi Panel UI Hirarki
1. Tambahkan blok panel hirarki di view (di atas tabel).
2. Render kartu per kategori aktif (default minimal 1 kartu: `1010020030`).
3. Hide kartu legacy jika `hide_in_ui=true`.
4. Render badge total dan catatan mode aktif.
5. Pastikan link kartu tetap menuju detail halaman yang benar.

Deliverable:
- Panel hirarki tampil stabil di desktop/mobile.

### Step 4 - Sinkronisasi Filter Dan Search
1. Pastikan filter periode tetap muncul pada mode hirarki.
2. Pastikan search keyword tetap berfungsi.
3. Pastikan tombol reset dan search submit tetap berfungsi.
4. Pastikan export/print tetap aktif sesuai role.

Deliverable:
- Interaksi user tidak berubah (hanya styling/penempatan visual).

### Step 5 - Fine-Tuning Visual
1. Samakan warna panel dengan acuan desain tema piutang pembelian.
2. Samakan tipografi nilai saldo (lebih dominan dari label).
3. Rapikan spacing panel, filter, dan tabel.
4. Samakan style header tabel bila dibutuhkan.
5. Verifikasi readability kontras warna.

Deliverable:
- Hasil visual mendekati desain acuan.

### Step 6 - Quality Check
1. Jalankan syntax check file PHP yang diubah.
2. Uji desktop (Chrome/Edge).
3. Uji mobile/tablet viewport.
4. Uji minimal 2 role user (operasional + holding).
5. Cek tidak ada regresi halaman lain yang memakai view/partial sama.

Deliverable:
- Bukti lulus validasi teknis dan fungsional.

### Step 7 - Dokumentasi Dan Handover
1. Catat daftar file yang diubah.
2. Catat keputusan bisnis (mis. legacy hidden).
3. Catat pemisahan modul dari uang muka supplier.
4. Simpan screenshot before/after.
5. Catat known limitation.
6. Lampirkan checklist status final.

Deliverable:
- Paket handover implementasi siap audit.

## 6. Template Catatan Per Eksekusi
- Aplikasi:
- Modul/Halaman:
- Scope UI-only:
- Kategori aktif:
- Kategori legacy:
- File diubah:
- Hasil syntax check:
- Hasil test fungsi:
- Hasil test visual:
- Risiko tersisa:
- Next action:

## 7. Quick Rollback Plan
1. Revert file view yang diubah.
2. Revert mapping panel di controller.
3. Jalankan ulang syntax check.
4. Verifikasi halaman kembali ke baseline.

## 8. Referensi Pendamping
- `CHECKLIST_UI_HIRARKI_PIUTANG_PEMBELIAN.md`
- `CHECKLIST_UI_HIRARKI_PIUTANG.md`
- `RUNBOOK_UI_HIRARKI_UANG_MUKA_SUPPLIER.md`
- `UAT_QUICKCHECK_UI_HIRARKI_KEUANGAN.md`

## 9. Eksekusi UAT Cepat (Wajib Sebelum Handover)
1. Isi identitas uji pada `UAT_QUICKCHECK_UI_HIRARKI_KEUANGAN.md`.
2. Jalankan verifikasi visual + interaksi + cross-role.
3. Simpan screenshot before/after dan URL bukti filter/search.
4. Catat status akhir uji dan risiko tersisa.