# Runbook Implementasi UI Hirarki Piutang (PSAK 71, Strict Existing COA)

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

Kompatibilitas target:
- PHP 5.6
- CodeIgniter 3

## Status Eksekusi Saat Ini (Update 2026-04-16)
- Status implementasi: `DONE` (coding selesai, UAT manual lulus).
- Tahap selesai:
- Mapping strict existing COA + status `active/legacy/planned` di controller.
- Kalkulasi totals `active/all/usaha/non_usaha/dimension_count/legacy_hidden`.
- Normalisasi saldo berbasis `detectRekDefaultPosition`.
- Render UI kartu per section (`Piutang Usaha` dan `Piutang Non-Usaha`).
- Badge total: `Total Piutang Aktif`, `Piutang Usaha`, `Piutang Non-Usaha`, `Dimensi Aktif`, `Total Piutang Semua` (kondisional).
- UAT manual lulus berdasarkan evidence:
- Desktop panel hirarki + tabel detail.
- Search keyword aktif (`q=indo`) dan hasil tabel konsisten.
- Tampilan mobile tetap usable.
- Syntax check lulus:
- `php -l application/controllers/Ledger.php`
- `php -l application/views/ledger.php`
- File yang sudah diubah:
- `application/controllers/Ledger.php`
- `application/views/ledger.php`
- Tahap tersisa:
- Tidak ada blocker kritikal.
- Siap handover.


## 1. Tujuan
Menerapkan tampilan hirarki piutang yang konsisten dengan best practice PSAK 71 (ECL/CKPN) dan struktur COA existing, dengan prinsip:
1. Hanya memakai akun yang sudah ada di sistem (`Strict Existing COA`).
2. Tidak membuat akun/jurnal baru pada fase UI-only.
3. Memisahkan tampilan antara `Piutang Usaha` dan `Piutang Non-Usaha`.
4. Menyiapkan placeholder `CKPN` sebagai `planned/inactive` bila akun belum siap dipakai.

## 2. Prinsip Strict Existing COA
Wajib:
- Ambil daftar akun dari master COA existing (`acc_coa` + alias aktif).
- Gunakan kode/nama akun existing apa adanya.
- Jika akun best practice belum tersedia di COA aktif, tampilkan sebagai `planned/inactive` (opsional), tanpa posting dan tanpa manipulasi saldo.

Dilarang:
- Menambah akun baru di database.
- Mengubah mapping jurnal atau aturan posting piutang.
- Mengubah logic approval/validasi transaksi existing.

## 3. Batasan Implementasi
Wajib:
- Perubahan dibatasi pada `view`, CSS, JS, dan mapping data tampilan di controller.
- Perhitungan saldo tetap memakai sumber data existing.

Dilarang:
- Mengubah struktur database.
- Mengubah posting jurnal.
- Mengubah core business rule transaksi.

## 4. Input Wajib Sebelum Mulai
Siapkan data berikut sebelum coding:
- Daftar akun piutang existing (kode + nama) dari master COA aktif.
- Keputusan status akun per item: `active`, `legacy`, atau `planned/inactive`.
- Halaman target (controller + view) untuk mode hirarki.
- Acuan visual panel hirarki yang akan dipakai.

## 5. Baseline Mapping COA Piutang (Final Draft `san_15apr`)

### 5.1 Piutang Usaha (Candidate Active)
- `1010020010` - Piutang Usaha Lokal
- `1010020080` - Piutang Usaha Project
- `1010020050` - Piutang Usaha Jasa
- `piutang valas` - Piutang Usaha Valas

### 5.2 Piutang Non-Usaha (Candidate Active)
- `piutang lain` - Piutang Lain-Lain
- `1010060010` - Piutang Cabang
- `1010060030` - Piutang Ke Pusat
- `1010060040` - Piutang Biaya Cabang
- `1010060020` - Piutang Aktiva Tetap Cabang

### 5.3 Legacy / Planned
- `1010020090` - Piutang Usaha Marketplace (`legacy`, default `hide`).
- `CKPN / Cadangan Kerugian Penurunan Nilai` (`planned`, menunggu akun + route final).
- `Piutang Retensi` (`planned`, jika route aktif belum final).
- `Piutang Pajak Restitusi` (`planned`, tetap di domain perpajakan sampai route final siap).

### 5.4 Out of Scope Modul
- `1010020030` (Piutang Pembelian / Credit Note Supplier) tetap pada modul `Piutang Pembelian`, tidak digabung ke panel ini.

## 6. Output Akhir Yang Diharapkan
- Panel hirarki piutang tampil pada halaman target.
- Kartu per section utama (`usaha` dan `non_usaha`) menampilkan saldo dan jumlah dimensi aktif.
- Badge total aktif, subtotal per section, dan dimensi aktif tampil.
- Filter periode/search/export existing tetap normal.
- Akun `legacy`/`planned` mengikuti kebijakan tampil yang disepakati.

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

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

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

### Step 2 - Validasi Master COA Existing
1. Cocokkan draft akun piutang dengan master COA aktif.
2. Tandai item yang benar-benar aktif dan dipakai transaksi.
3. Tandai item yang belum ada/legacy untuk mode `planned` atau `hide`.

Deliverable:
- Mapping final akun piutang strict existing per section.

### Step 3 - Mapping Hirarki Data Untuk UI
1. Definisikan struktur array hirarki piutang di controller.
2. Tetapkan field minimal per kartu:
- `label`
- `note`
- `route_rel`
- `route_rekening`
- `section` (`usaha` / `non_usaha`)
- `group`
- `status`
- `count_label`
- `route_enabled`
- `hide_in_ui`
- `saldo`
- `count`
3. Tetapkan object totals:
- total akun aktif
- total semua akun
- subtotal per section (`usaha`, `non_usaha`)
- count agregat dimensi aktif
- indikator `legacy_hidden`

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

### Step 4 - Implementasi Panel UI Hirarki Piutang
1. Tambahkan blok panel hirarki di atas tabel.
2. Render kartu berdasarkan section:
- Piutang Usaha
- Piutang Non-Usaha
3. Render item akun sesuai mapping strict existing.
4. Hide item `legacy/planned` sesuai kebijakan.
5. Pastikan link kartu menuju detail existing yang valid.

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

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

Deliverable:
- Interaksi user tidak berubah (hanya tampilan/hirarki).

### Step 6 - Fine-Tuning Visual
1. Samakan warna panel dengan acuan desain.
2. Samakan tipografi nilai saldo (lebih dominan dari label).
3. Rapikan spacing panel, filter, dan tabel.
4. Verifikasi readability kontras warna.

Deliverable:
- Hasil visual konsisten dan mudah dibaca.

### Step 7 - 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 pada halaman lain bertemplate sama.

Deliverable:
- Bukti lulus validasi teknis dan fungsional.

### Step 8 - Dokumentasi Dan Handover
1. Catat daftar file yang diubah.
2. Catat keputusan status akun (`active/legacy/planned`).
3. Simpan screenshot before/after.
4. Catat known limitation.
5. Lampirkan checklist status final.

Deliverable:
- Paket handover implementasi siap audit.

## 8. Template Catatan Per Eksekusi
- Aplikasi:
- Modul/Halaman:
- Scope UI-only:
- Section akun aktif:
- Akun legacy/planned:
- Mapping COA final dipakai:
- File diubah:
- Hasil syntax check:
- Hasil test fungsi:
- Hasil test visual:
- Risiko tersisa:
- Next action:

## 9. Quick Rollback Plan
Jika hasil UI tidak sesuai:
1. Revert file view yang diubah.
2. Revert mapping panel di controller.
3. Jalankan ulang syntax check.
4. Verifikasi halaman kembali ke baseline.

Catatan:
- Lakukan rollback per file agar mudah ditelusuri.
- Hindari rollback massal tanpa review perubahan.

## 10. Referensi Pendamping
Gunakan bersama:
- `CHECKLIST_UI_HIRARKI_PIUTANG_PSAK71.md`
- `UAT_QUICKCHECK_UI_HIRARKI_KEUANGAN.md`

## 11. Eksekusi UAT Cepat (Wajib Sebelum Handover)
Setelah coding selesai, jalankan quickcheck ini:
1. Isi identitas uji pada `UAT_QUICKCHECK_UI_HIRARKI_KEUANGAN.md`.
2. Jalankan blok `UAT Visual Ringkas`.
3. Jalankan blok `UAT Interaksi Ringkas`.
4. Jalankan blok `UAT Cross-Role Ringkas`.
5. Simpan evidence screenshot dan ringkasan status (`LULUS` / `LULUS DENGAN CATATAN` / `TUNDA`).

Target waktu:
- 10-20 menit per modul untuk validasi baseline.