# Rencana Perbaikan Kinerja Katalog Produk

## Metadata
- Dokumen: `KATALOG_PERFORMANCE_PLAN.md`
- Dibuat: 2026-05-28
- Endpoint fokus: `Katalog/viewProduk` (mode `KatalogGudang`)
- Tujuan utama: semua data tetap tampil lengkap, tetapi waktu load lebih ringan

## Prinsip Wajib
1. Informasi produk tetap lengkap per cabang dan per gudang.
2. Tidak menambah jumlah klik user untuk melihat data utama.
3. Aturan bisnis wajib tetap sama:
   - tampil jika saldo > 0
   - jika saldo = 0, tampil hanya jika ada mutasi tahun berjalan
4. Setiap perubahan wajib punya bukti ukur sebelum dan sesudah.

## Metode 1: Quick Win (target 1 hari kerja)
Fokus: perbaikan cepat, risiko rendah, tanpa ubah perilaku UI utama.

| ID | Langkah | Detail Teknis | Estimasi | Status | Bukti |
|---|---|---|---|---|---|
| QW-01 | Baseline profiling | Catat durasi per blok: query produk, harga, stok, hold, images, fifo, pairing, render | 1-2 jam | IN_PROGRESS | Instrumentasi aktif di `viewProduk` |
| QW-02 | Aktifkan filter bisnis final | Terapkan filter hasil sesuai rule saldo/mutasi (tanpa mengubah tampilan kolom) | 1-2 jam | TODO | Diff + sample hasil |
| QW-03 | Batasi query turunan ke kandidat produk | Query harga/stok/hold/images/fifo hanya untuk `produk_id` kandidat hasil QW-02 | 2-3 jam | TODO | Query count before/after |
| QW-04 | Bersihkan beban non-esensial | Matikan output debug di alur katalog, rapikan blok filter duplikat | 1 jam | TODO | Diff |
| QW-05 | Verifikasi parity data | Bandingkan output lama vs baru pada sampel cabang/kategori/query | 1 jam | TODO | Checklist verifikasi |
| QW-06 | Uji performa cepat | Uji 3 skenario: `q kosong`, `q terisi`, `kat filter`; catat p50/p95 | 1 jam | TODO | Laporan metrik |

### Kriteria Sukses Quick Win
- p95 endpoint turun minimal 30%.
- Jumlah row hasil akhir tidak melanggar rule bisnis.
- Tidak ada perubahan struktur data yang diterima view.

## Metode 2: Sistemik (target 1-2 sprint)
Fokus: perbaikan arsitektur agar performa stabil jangka panjang.

| ID | Langkah | Detail Teknis | Estimasi | Status | Bukti |
|---|---|---|---|---|---|
| SYS-01 | Pisahkan service katalog | Buat service khusus agregasi katalog agar controller tipis dan terukur | 1-2 hari | TODO | PR link |
| SYS-02 | Read model stok teragregasi | Bangun tabel/cache agregat per `cabang-gudang-produk` (active/hold/total) | 2-3 hari | TODO | DDL + job |
| SYS-03 | Pipeline refresh terjadwal | Update agregat via cron/incremental refresh dengan fallback rebuild | 1-2 hari | TODO | Job log |
| SYS-04 | Query kontrak tunggal untuk view | Satu jalur query terstandar untuk produk + harga + stok + hold + image pointer | 1-2 hari | TODO | EXPLAIN + benchmark |
| SYS-05 | Hardening indeks DB | Index komposit sesuai filter/join aktual query katalog | 1 hari | TODO | DDL + hasil EXPLAIN |
| SYS-06 | Guardrail observability | Tambah metrik otomatis (durasi, row count, memory) + threshold alert | 1 hari | TODO | Dashboard/log |
| SYS-07 | Rollout bertahap | Feature flag `katalog_v2`, A/B internal, cutover bertahap | 1 hari | TODO | Catatan rollout |

### Kriteria Sukses Sistemik
- p95 endpoint turun minimal 60% dari baseline awal.
- Waktu render browser stabil untuk dataset besar.
- Hasil data konsisten dengan rule bisnis.
- Perubahan aman melalui feature flag dan rollback plan.

## Trace Board (Master)
Gunakan tabel ini sebagai sumber kebenaran progres.

| Task ID | Metode | Owner | Start | End | Status | Dependency | Output | Catatan |
|---|---|---|---|---|---|---|---|---|
| QW-01 | Quick Win | Codex + Tim Dev | 2026-05-28 | - | IN_PROGRESS | - | Baseline report | Instrumentasi per blok sudah dipasang |
| QW-02 | Quick Win | TBD | - | - | TODO | QW-01 | Rule filter aktif |  |
| QW-03 | Quick Win | TBD | - | - | TODO | QW-02 | Query narrowing |  |
| QW-04 | Quick Win | TBD | - | - | TODO | QW-01 | Cleanup debug/filter |  |
| QW-05 | Quick Win | TBD | - | - | TODO | QW-02,QW-03 | Data parity report |  |
| QW-06 | Quick Win | TBD | - | - | TODO | QW-03 | Perf retest |  |
| SYS-01 | Sistemik | TBD | - | - | TODO | QW-06 | Service layer |  |
| SYS-02 | Sistemik | TBD | - | - | TODO | SYS-01 | Aggregate model |  |
| SYS-03 | Sistemik | TBD | - | - | TODO | SYS-02 | Refresh pipeline |  |
| SYS-04 | Sistemik | TBD | - | - | TODO | SYS-02 | Unified query |  |
| SYS-05 | Sistemik | TBD | - | - | TODO | SYS-04 | Index tuning |  |
| SYS-06 | Sistemik | TBD | - | - | TODO | SYS-04 | Observability |  |
| SYS-07 | Sistemik | TBD | - | - | TODO | SYS-05,SYS-06 | Gradual rollout |  |

Status yang dipakai: `TODO`, `IN_PROGRESS`, `BLOCKED`, `DONE`.

## Template Log Harian
Isi setiap hari untuk jejak kerja dan audit.

| Tanggal | Task ID | Aktivitas | Hasil | Kendala | Next Step | PIC |
|---|---|---|---|---|---|---|
| 2026-05-28 | QW-01 | Pasang marker profiling per blok di `Katalog/viewProduk` | Hook profiling siap dipakai dengan parameter `profile_katalog=1`; log JSON `KATALOG_PROFILE` aktif | Belum ada sampel metrik runtime dari environment user | Jalankan 3 skenario uji dan kumpulkan p50/p95 | Codex |

## Definition of Done
1. Semua task pada metode yang dipilih berstatus `DONE`.
2. Bukti ukur sebelum/sesudah tersedia.
3. Tidak ada regresi fungsi pada data katalog.
4. Catatan rollout dan rollback terisi.