# Rencana Migrasi Fitur Produk Varian

## Referensi Program
- Untuk scope lintas modul (`pembelian`, `distribusi`, `penjualan`) dan rollout holding/subsidiary, lihat:
  - `w:\san_sarana_8apr\application\PLAN_MIGRASI_VARIAN_HOLDING_SUBSIDIARY.md`

## Konteks
- Source referensi: `w:\san_varian\application\modules\distribusifg`
- Target implementasi: `w:\san_sarana_8apr\application\modules\distribusi`
- Constraint: PHP 5.6, CodeIgniter 3, MariaDB 10, CentOS 7, backward compatible, aman untuk transaksi ERP.
- Batasan kerja: tidak baca/ubah file controller berawalan `__` dan file `*_OLD.php`, tidak gunakan folder `trash` sebagai referensi.

## Analisis Singkat
### Tujuan Perubahan
Membawa kemampuan produk varian di modul distribusi agar proses pilih item, keranjang, followup, posting stok, dan posting rekening tetap konsisten per varian.

### Akar Masalah
1. Konfigurasi transaksi modul `distribusi` belum memetakan `variant_id`, `variant_sku`, `variant_label`, `variant_key`.
2. Controller `distribusi` belum memiliki flow varian (`variantPicker`, `cart_key` varian, sinkron stok varian).
3. Model/helper global target belum lengkap untuk varian (`MdlLockerStockVariant`, helper cek stok varian, selector row varian).
4. Database target (`san_sarana_18feb`) belum memiliki tabel-tabel stok/accounting varian inti.

### File Terdampak (Rencana)
1. Config modul:
   - `w:\san_sarana_8apr\application\modules\distribusi\config\coTransaksiCore.php`
   - `w:\san_sarana_8apr\application\modules\distribusi\config\coTransaksiValues.php`
2. Controller modul:
   - `w:\san_sarana_8apr\application\modules\distribusi\controllers\_selectorItem.php`
   - `w:\san_sarana_8apr\application\modules\distribusi\controllers\_processSelectProduct.php`
   - `w:\san_sarana_8apr\application\modules\distribusi\controllers\_shoppingCart.php`
   - `w:\san_sarana_8apr\application\modules\distribusi\controllers\FollowUp.php`
   - `w:\san_sarana_8apr\application\modules\distribusi\controllers\Printing.php`
3. Model/helper shared:
   - `w:\san_sarana_8apr\application\helpers\Pairs\he_cek_stock_produk_locker_helper.php`
   - `w:\san_sarana_8apr\application\models\Mdls\MdlProdukVarian.php`
   - `w:\san_sarana_8apr\application\models\Mdls\MdlLockerStockVariant.php` (baru)
   - `w:\san_sarana_8apr\application\models\Mdls\MdlLockerStockMutasiVariant.php` (baru)
   - `w:\san_sarana_8apr\application\models\Mdls\MdlFifoProdukJadiVarian.php` (baru)
4. Coms global:
   - `w:\san_sarana_8apr\application\models\Coms\ComLockerStockVariant.php` (baru)
   - `w:\san_sarana_8apr\application\models\Coms\ComFifoProdukJadiVarian.php` (baru)
   - `w:\san_sarana_8apr\application\models\Coms\ComRekeningPembantuProdukVarian.php` (baru)
5. Model transaksi modul:
   - `w:\san_sarana_8apr\application\modules\distribusi\models\MdlDistribusiTransaksi.php`
6. View:
   - `w:\san_sarana_8apr\application\modules\distribusi\views\variant_picker.php` (baru)

### Dampak ke Modul Lain
1. Shared helper/model/com bersifat global, jadi berpotensi dipakai modul lain.
2. Perubahan harus dijaga agar jalur non-varian tidak berubah.
3. Posting stok/rekening/fifo varian mempengaruhi laporan persediaan, mutasi stok, dan accounting.

### Risiko Kompatibilitas
1. Jika tabel varian belum siap, transaksi bisa gagal saat postProcessor.
2. Jika key item session berubah tanpa fallback, item lama bisa hilang dari keranjang.
3. Jika mapping rekening varian tidak konsisten, jurnal persediaan bisa mismatch.
4. Jika followup/printing tidak resolve varian dengan benar, preview dan nota bisa kosong/salah.

## Rencana Implementasi Bertahap
## Fase 0 - Baseline dan Guardrail
1. Buat branch khusus migrasi varian distribusi.
2. Simpan snapshot baseline:
   - Hasil `SHOW CREATE TABLE` tabel distribusi terkait.
   - Export config modul `coTransaksiCore.php` dan `coTransaksiValues.php`.
3. Siapkan checklist uji regresi non-varian (wajib lulus sebelum go-live).

## Fase 1 - Kesiapan Database (Wajib Dulu)
Eksekusi DDL di `san_sarana_18feb` menggunakan referensi struktur dari `san_13mar`.

Tabel yang harus ada:
1. `stock_locker_variant`
2. `stock_locker_mutasi_variant`
3. `_rek_pembantu_produk_varian`
4. `_rek_pembantu_produk_varian_cache`
5. `rek_cache_persediaan_produk_varian_fifo`

Kolom produk yang harus ada:
1. `produk.has_variants` (tinyint)
2. `produk.variant_price_mode` (varchar)

Validasi pasca-DDL:
1. `SHOW TABLES LIKE 'stock_locker_variant';` (dan tabel lain di atas)
2. `SHOW COLUMNS FROM produk LIKE 'has_variants';`
3. `SHOW COLUMNS FROM produk LIKE 'variant_price_mode';`

## Fase 2 - Port Layer Shared Varian
1. Port helper `he_cek_stock_produk_locker_helper.php` agar varian-aware dengan fallback non-varian.
2. Lengkapi `MdlProdukVarian`:
   - `find_selector_row()`
   - `search_selector_rows()`
   - pertahankan `get_picker_rows()`
3. Tambah model shared varian:
   - `MdlLockerStockVariant`
   - `MdlLockerStockMutasiVariant`
   - `MdlFifoProdukJadiVarian`
4. Tambah Coms varian:
   - `ComLockerStockVariant`
   - `ComFifoProdukJadiVarian`
   - `ComRekeningPembantuProdukVarian`

Catatan: Semua class baru mengikuti style CI3 legacy dan kompatibel PHP 5.6.

## Fase 3 - Port Config Modul Distribusi
1. Mapping detail transaksi varian di:
   - `coTransaksiCore.php`
   - `coTransaksiValues.php`
2. Tambahkan route postProcessor varian sesuai konteks distribusi:
   - Locker stock varian
   - FIFO varian
   - Rekening pembantu varian
3. Pastikan mapping `variant_id` sinkron ke field `varian_id/extern_id` yang dibutuhkan com.
4. Jalur non-varian tetap aktif sebagai fallback.

## Fase 4 - Port Controller Flow Varian
1. `_selectorItem.php`
   - support `variantPicker`
   - selector varian-aware
2. `_processSelectProduct.php`
   - identity per item berbasis `cart_key`
   - reserve/release locker varian
   - dukung multi-select varian
3. `_shoppingCart.php`
   - bawa metadata varian (`variant_id`, `variant_label`, `variant_flag`, `cart_key`)
   - refresh stok varian per item
4. `FollowUp.php`
   - merge session/registry per `cart_key` varian
   - cegah collapse antar varian produk yang sama
5. `Printing.php`
   - resolver data varian untuk detail nota/preview

## Fase 5 - Hardening Model Transaksi Modul
`MdlDistribusiTransaksi.php` perlu adaptor kontrak varian (tanpa mengubah arsitektur `Mdl{Modul}Transaksi`):
1. Tambah normalisasi payload detail varian sebelum insert/update detail:
   - set default numerik/string aman
   - sanitize `variant_*` agar tidak null liar
2. Integrasi ke titik write:
   - `writeDetailMainEntries()`
   - `writeDetailEntries()`
   - `writeDetailItemsEntries()`
   - `writeDetailSubEntries_items()`
   - `writeDetailValues()`
   - `writeDetailFields()`
3. Wajib ada fallback non-varian untuk data lama.

## Fase 6 - View dan UX Pendukung
1. Tambahkan `variant_picker.php` di modul `distribusi`.
2. Pastikan tombol/proses UI hanya aktif jika identitas varian valid.
3. Pastikan tabel preview/followup menampilkan qty, uom, subtotal per baris varian dengan benar.

## Fase 7 - Uji Integrasi dan Audit
Skenario minimal:
1. Create transaksi distribusi non-varian (harus tetap normal).
2. Create transaksi distribusi varian multi-size/multi-line produk yang sama.
3. Save, followup, approve, print receipt.
4. Verifikasi DB:
   - `distribusi_transaksi_data*` terisi `variant_*` benar.
   - `stock_locker_variant` dan `stock_locker_mutasi_variant` terisi konsisten.
   - `_rek_pembantu_produk_varian*` dan FIFO varian terisi konsisten.
5. Verifikasi laporan stok dan laporan accounting tidak mismatch.
6. Uji race condition sederhana (2 user pilih varian sama).

## Strategi Rollback
1. Jika gagal di Fase 1-3: rollback DDL (drop tabel varian baru hanya jika belum dipakai produksi) dan restore config.
2. Jika gagal di Fase 4-6: revert kode modul ke commit baseline, pertahankan data transaksi valid yang sudah terbentuk.
3. Catat transaksi uji dan bersihkan data uji via script terkontrol.

## Kriteria Siap Go-Live
1. Tidak ada SQL error/notice pada alur create -> followup -> approve -> print.
2. Non-varian pass regresi penuh.
3. Varian pass seluruh skenario integrasi stok/accounting.
4. Hasil audit data transaksi detail = hasil preview UI = hasil nota.