# Implementation Plan Integrasi Varian di Estimates

## Tujuan
Menerapkan dukungan varian produk pada form item Estimates secara bertahap, aman, dan tetap kompatibel dengan alur existing (produk non-varian tetap berjalan tanpa perubahan perilaku utama).

## Ruang Lingkup
- Modul utama:
  - `app/Controllers/Estimates.php`
  - `app/Views/estimates/item_modal_form.php`
  - `app/Models/Estimate_items_model.php`
  - `app/Models/Invoice_items_model.php` (suggestion lookup)
- Referensi skema varian:
  - `documentation/add_tabel_varian.md`

## Aturan Bisnis Final
1. Produk tanpa varian: proses tetap seperti saat ini.
2. Produk dengan varian aktif: user wajib memilih varian saat tambah item estimate.
3. Harga selalu mengikuti produk induk (parent). Varian tidak memiliki harga terpisah di estimates.
4. Data varian tersimpan sebagai snapshot di transaksi agar histori tidak berubah walau master varian berubah.

## Status Implementasi (Update: 23 April 2026)
- [x] Tahap 0 - Baseline dan Kontrak Data
- [x] Tahap 1 - Perubahan Skema Data Transaksi
- [x] Tahap 2 - Endpoint Lookup Varian
- [x] Tahap 3 - Integrasi UI di Modal Item Estimate
- [x] Tahap 4 - Validasi dan Simpan di Backend
- [x] Tahap 5 - Tampilan di List Estimate, Preview, dan PDF
- [x] Tahap 6 - Pencarian SKU Varian
- [~] Tahap 7 - QA, UAT, dan Rollout (checklist sudah tersedia, UAT penuh menunggu eksekusi tim)

## Ringkasan Realisasi
- Skema `rise_estimate_items` untuk varian sudah disiapkan via migration/manual SQL:
  - `variant_id`
  - `variant_sku`
  - `variant_label`
  - `variant_snapshot`
- Backend Estimates sudah mendukung:
  - lookup varian by `item_id`
  - validasi item-variant
  - simpan snapshot varian per transaksi
  - mode bulk tambah varian + merge jika varian sama pada estimate yang sama
- Frontend modal item Estimates sudah mendukung:
  - mode single varian (edit)
  - mode bulk varian (add)
  - validasi qty varian > 0
  - quick focus input qty varian (single click, tanpa double click)
- Tampilan varian sudah muncul di:
  - tabel item estimate
  - preview estimate
  - PDF estimate
- Pencarian item sudah bisa menemukan produk dari SKU varian.
- Key bahasa varian sudah ditempatkan di `custom_lang` (ID/EN), bukan `default_lang`.
- Dokumen checklist QA/UAT tersedia di:
  - `documentation/estimates-varian-qa-checklist.md`

## Tahapan Implementasi

## Tahap 0 - Baseline dan Kontrak Data
### Status
Selesai.

### Fokus
- Menetapkan kontrak request/response endpoint varian.
- Menetapkan rule validasi final (server-side sebagai sumber kebenaran).

### Output
- Dokumen kontrak payload dan respons.
- Daftar validasi wajib.

### DoD
- Disepakati bahwa produk ber-varian aktif wajib pilih varian.
- Tidak ada ambiguitas field antara item induk vs varian.

---

## Tahap 1 - Perubahan Skema Data Transaksi
### Status
Selesai.

### Fokus
Menambahkan kolom varian pada `rise_estimate_items` (nullable untuk backward compatibility).

### Kolom yang disarankan
1. `variant_id` (INT, NULL)
2. `variant_sku` (VARCHAR, NULL)
3. `variant_label` (VARCHAR, NULL)
4. `variant_snapshot` (TEXT/JSON, NULL, opsional)

### Output
- Migration SQL terstruktur.
- Script rollback sederhana.

### DoD
- Item lama (non-varian) tetap bisa dibaca/simpan normal.
- Tidak ada error pada list existing estimates.

---

## Tahap 2 - Endpoint Lookup Varian
### Status
Selesai.

### Fokus
- Menyediakan endpoint daftar varian by `item_id`.
- Menyediakan endpoint detail varian by `variant_id`.

### Output
- Endpoint respons konsisten untuk UI modal.
- Penanda `has_variants` dan `variant_count` di flow suggestion.

### DoD
- Dapat membedakan: tanpa varian, varian aktif, varian nonaktif.
- Error message valid jika kombinasi item-variant tidak cocok.

---

## Tahap 3 - Integrasi UI di Modal Item Estimate
### Status
Selesai.

### Fokus
Menambahkan field varian pada modal item secara kondisional.

### Perilaku
1. Pilih produk.
2. Jika produk punya varian aktif, tampil dropdown varian (required).
3. Jika tidak punya varian, field varian disembunyikan.
4. Harga tetap dari induk meskipun varian dipilih.
5. Pada mode tambah item, varian dapat diinput multi-qty via mini tabel agar beberapa varian bisa ditambahkan sekaligus.

### Output
- UX modal stabil untuk dua mode (varian / non-varian).

### DoD
- Submit di client-side gagal jika produk ber-varian tetapi varian belum dipilih (mode edit) atau belum ada qty varian > 0 (mode tambah).
- Produk non-varian tetap bisa submit seperti sebelumnya.

---

## Tahap 4 - Validasi dan Simpan di Backend
### Status
Selesai.

### Fokus
Validasi kuat di `save_item()`:
- `variant_id` wajib jika item punya varian aktif.
- `variant_id` harus milik `item_id`.
- varian harus aktif.

### Output
- Penyimpanan `item_id` + data snapshot varian ke `estimate_items`.

### DoD
- Request manual (bypass frontend) tetap tervalidasi.
- Data transaksi konsisten dan tidak bisa mismatch item-variant.

---

## Tahap 5 - Tampilan di List Estimate, Preview, dan PDF
### Status
Selesai.

### Fokus
Menampilkan informasi varian pada hasil transaksi.

### Output
- Badge/label varian di baris item.
- Informasi varian muncul di preview dan PDF.

### DoD
- Dokumen estimate tetap jelas saat master varian berubah.
- User dapat mengidentifikasi varian yang dipilih dari output dokumen.

---

## Tahap 6 - Pencarian SKU Varian (Enhancement)
### Status
Selesai.

### Fokus
Memungkinkan pencarian produk berdasarkan SKU varian.

### Output
- Suggestion bisa menemukan item melalui SKU varian.

### DoD
- Hasil pencarian relevan dan tidak menghasilkan duplikasi membingungkan.

---

## Tahap 7 - QA, UAT, dan Rollout
### Status
Parsial.

### Fokus
Menjamin kualitas sebelum release.

### Test Matrix Minimum
1. Produk tanpa varian.
2. Produk dengan 1 varian.
3. Produk dengan banyak varian.
4. Varian nonaktif.
5. Edit item estimate lama (sebelum fitur varian).
6. Copy alur ke modul turunan (jika ada).

### Output
- Checklist UAT.
- Rollback plan.

### DoD
- Tidak ada regresi pada alur estimate existing.
- User acceptance untuk skenario utama terpenuhi.

## Catatan Implementasi
- Semua key bahasa baru harus ditaruh di `custom_lang` (sesuai standar tim), bukan `default_lang`.
- Komit perubahan dilakukan per tahap agar mudah tracking dan rollback.