# Runbook Template Universal UI Hirarki Keuangan (Reusable Antar Aplikasi)

Dokumen ini adalah template universal untuk implementasi UI hirarki keuangan lintas aplikasi, dengan pendekatan:
- UI-only
- Strict existing COA
- Kompatibel untuk stack lama (mis. PHP 5.6 + CodeIgniter 3)

## Cara Pakai Cepat
1. Duplikat file ini menjadi `RUNBOOK_UI_HIRARKI_<MODUL>_<APP>.md`.
2. Isi seluruh placeholder `{{...}}`.
3. Sesuaikan mapping akun active/legacy/planned dengan COA aplikasi target.
4. Jalankan implementasi mengikuti urutan step.
5. Sinkronkan dengan checklist universal.

## Placeholder Wajib
- `{{APP_NAME}}`: nama aplikasi target
- `{{MODULE_NAME}}`: nama modul (kas/piutang/persediaan/hutang/pajak/dll)
- `{{TARGET_URL}}`: URL halaman target
- `{{TARGET_CONTROLLER}}`: file controller target
- `{{TARGET_VIEW}}`: file view target
- `{{COA_GROUP_NAME}}`: nama grup akun yang dipetakan
- `{{PIC_IMPL}}`: PIC implementasi
- `{{DATE_PLAN}}`: tanggal perencanaan

## 1. Tujuan
Menerapkan UI hirarki untuk `{{MODULE_NAME}}` pada aplikasi `{{APP_NAME}}` secara aman, terukur, dan dapat diaudit, tanpa mengubah posting jurnal atau struktur data inti.

## 2. Prinsip Universal
Wajib:
- Gunakan akun existing dari COA aktif.
- Pisahkan status akun: `active`, `legacy`, `planned`.
- Pertahankan perilaku filter/search/export existing.
- Pastikan perubahan fokus pada presentasi data (UI-only).

Dilarang:
- Menambah akun baru pada fase UI-only.
- Mengubah logic posting jurnal.
- Mengubah business rule transaksi.
- Mengubah skema database.

## 3. Scope Implementasi
Dalam scope:
- Mapping data hirarki di controller.
- Render panel hirarki di view.
- Styling ringan dan script interaksi kecil (toggle/filter UI).
- Perhitungan summary dari data existing.

Di luar scope:
- Engine akuntansi.
- Approval flow.
- Migrasi data.

## 4. Input Wajib Sebelum Coding
- Daftar COA existing untuk `{{COA_GROUP_NAME}}`.
- Daftar alias akun aktif.
- Daftar endpoint detail yang valid.
- Contoh data uji (saldo > 0, saldo = 0, multi-dimensi).
- Acuan visual panel yang disepakati.

## 5. Template Mapping COA

### 5.1 Tabel Mapping Akun
Isi tabel berikut untuk aplikasi target:

| Kode/Nama Akun | Label UI | Route Rel | Route Rekening | Status | Section | Hide Default | Catatan |
|---|---|---|---|---|---|---|---|
| `{{ACC_1}}` | `{{LABEL_1}}` | `{{REL_1}}` | `{{ROUTE_1}}` | `active` | `{{SECTION_1}}` | `false` | `{{NOTE_1}}` |
| `{{ACC_2}}` | `{{LABEL_2}}` | `{{REL_2}}` | `{{ROUTE_2}}` | `active` | `{{SECTION_2}}` | `false` | `{{NOTE_2}}` |
| `{{ACC_3}}` | `{{LABEL_3}}` | `{{REL_3}}` | `{{ROUTE_3}}` | `legacy/planned` | `{{SECTION_3}}` | `true` | `{{NOTE_3}}` |

### 5.2 Definisi Status
- `active`: tampil default, dapat diklik (jika route tersedia).
- `legacy`: boleh dihitung, default hide dari panel utama.
- `planned`: default hide, route disabled.

## 6. Kontrak Data UI (Template)
Minimal field yang disediakan per kartu:
- `label`
- `note`
- `summary_rel`
- `query_candidates`
- `status`
- `section` (opsional sesuai modul)
- `route_enabled`
- `count_label`
- `hide_in_ui`
- `saldo`
- `count`

Template total summary:
- `active`
- `all`
- `section totals` (opsional sesuai modul)
- `dimension_count` / `item_count` / `entity_count`
- `legacy_hidden`

## 7. Kontrak Tampilan UI (Template)
- Panel muncul di atas tabel detail.
- Kartu active ditampilkan default.
- Kartu legacy/planned mengikuti kebijakan hide/show.
- Badge summary minimal:
- Total aktif
- Total semua (opsional jika tidak hide)
- Dimensi aktif
- Subtotal per section (opsional)
- Catatan mode aktif tampil jelas.

## 8. Urutan Eksekusi Universal

### Step 1 - Discovery
1. Identifikasi file controller, view, helper terkait.
2. Identifikasi query string yang dipakai halaman.
3. Identifikasi dependencies tabel/filter existing.

Deliverable:
- Daftar file target dan resiko regresi.

### Step 2 - Finalisasi Mapping COA
1. Validasi akun active vs existing COA.
2. Tandai akun legacy/planned.
3. Putuskan aturan hide/show.

Deliverable:
- Mapping final yang disepakati user bisnis.

### Step 3 - Implementasi Controller
1. Bentuk array hierarchy links.
2. Bentuk totals summary.
3. Jaga compatibility key lama bila diperlukan.

Deliverable:
- Data siap render tanpa ubah bisnis inti.

### Step 4 - Implementasi View
1. Render panel, kartu, badge.
2. Terapkan status badge active/planned.
3. Jaga interaksi filter/search/export tetap normal.

Deliverable:
- UI hirarki tampil stabil desktop/mobile.

### Step 5 - Quality Check
1. Syntax check file berubah.
2. Uji desktop + mobile.
3. Uji minimal 2 role.
4. Verifikasi tidak ada regresi lintas halaman.

Deliverable:
- Bukti lulus validasi teknis/fungsional.

### Step 6 - Dokumentasi & Handover
1. Finalisasi checklist.
2. Simpan screenshot evidence.
3. Tulis risiko tersisa.
4. Tetapkan status akhir (`LULUS`/`LULUS DENGAN CATATAN`/`TUNDA`).

Deliverable:
- Paket handover siap audit.

## 9. Quality Gate Universal
- Lulus syntax check (`php -l` atau setara stack target).
- Tidak ada error runtime/console kritikal.
- Filter/search/export tetap normal.
- Layout desktop/mobile usable.
- Query string state tidak rusak.

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

## 11. Template Catatan Implementasi
- Aplikasi: `{{APP_NAME}}`
- Modul: `{{MODULE_NAME}}`
- URL: `{{TARGET_URL}}`
- Scope: UI-only strict existing COA
- File diubah:
- Mapping active:
- Mapping legacy/planned:
- Hasil syntax check:
- Hasil UAT:
- Risiko tersisa:
- Next action:

## 12. Referensi
Gunakan bersama:
- `CHECKLIST_TEMPLATE_UNIVERSAL_UI_HIRARKI_KEUANGAN.md`
- `UAT_QUICKCHECK_UI_HIRARKI_KEUANGAN.md`