# Sintesis 05 - Modul Konversi Stok dan Multi-Variant

**Subjudul:** Consolidasi 12 dokumen blueprint, checklist, dan verifikasi untuk modul `konversi` / `konversi_varian` pada ERP CI3 HMVC (PHP 5.6), CodeIgniter 3, Standar ISO/IEC 25010, dan acuan SAP LO-VC / SAP Movement Types 561-562-701-702.

**Ruang lingkup sintesis:** 12 file sumber pada folder `W:\_md_result\file_md_san` yang mencakup blueprint konversi stok, blueprint konversi varian, blueprint konverter multi-variant, blueprint upgrade support varian, blueprint UAT fix selector/shopping cart varian, checklist upgrade varian, 15 skenario verifikasi gate, workflow modul konversi, panduan reviu kode SAP variant conversion, blueprint sementara (temp), UAT checklist, dan blueprint varian supplies serta produksi BOM.

**Status dokumen:** Sintesis analitis. Tidak ada patch kode yang dieksekusi oleh dokumen ini.

---

## 2. Ringkasan Eksekutif

Modul konversi stok di lingkungan ERP ini mengalami revisi arsitektural besar dalam rentang beberapa bulan, yang tercermin dari 12 dokumen sumber. Ada tiga lapisan fokus yang saling terkait:

1. **Lapisan model transaksi dasar (lama, masih berlaku).** `blueprint_konversi_stok.md` menegaskan bahwa ERP memakai model base terpusat `MdlTransaksi` (header) dan `MdlTransaksiData` (detail), dengan larangan keras menulis query insert/update manual. Konversi stok dibentuk sebagai pola double-entry: satu baris qty minus untuk produk asal, satu baris qty plus untuk varian tujuan, dengan `kode_transaksi`/`jenis_transaksi` bernilai `KONVERSI_STOK` dan status `PENDING` lalu `APPROVED`.

2. **Lapisan upgrade varian (baseline non-varian ke varian-aware).** `blueprint-upgrade-modul-konversi-support-varian.md` mengidentifikasi empat mode konversi M1-M4 (Varian ke Varian, Non-Varian ke Varian, Varian ke Non-Varian, Non-Varian ke Non-Varian native), kontrak session `items_source`/`items_target` plus gate legacy `items`/`items2`/`items2_sum`, aturan strict qty balance dan HPP balance, serta pemilihan komponen posting berbasis `item_type` (`FifoProdukJadi`/`LockerStock`/`LockerStockMutasi` untuk non-varian vs `FifoProdukJadiVarian`/`LockerStockVariant`/`LockerStockMutasiVariant` untuk varian).

3. **Lapisan konsolidasi multi-variant (single standard variant).** Dua blueprint konverter multi-variant menetapkan arah akhir "setiap produk adalah varian" dengan sentinel `variant_id = -1`, session key seragam `variant:{produk_id}:{variant_id}`, dan penghapusan dual pipeline `rsltItems` + `rsltItems2` menjadi satu jalur.

Pemeriksaan mendetail terhadap dokumen verifikasi (`15-skenario-verifikasi-konversi-items-gate.md`) memperlihatkan dua hal penting yang harus-buyar dalam sintesis ini. Pertama, mutual exclusion antar lima kelas komponen sudah terbukti, tetapi ada pre-existing bug nama field (`qty` vs `jml`, `name` vs `nama`) yang membuat seluruh komponen LockerStock pada gate `items` menjadi NO-OP dengan `jumlah = 0`. Kedua, dua edge case (S13 dan S14) masih berstatus data loss.

Checklist status menunjukkan implementasi baru hanya 7 item berstatus `Selesai`, 1 `Sedang`, 2 `Blocked`, dan sisanya `Belum`. Artinya blueprint sudah matang di desain tetapi implementasi engine posting, validator, audit, dan UAT belum dijalankan.

---

## 3. Definisi dan Peran Modul Konversi

### 3.1 Definisi

Modul konversi adalah fitur ERP untuk memindahkan atau mengubah komposisi stok dari satu produk atau varian ke produk atau varian lain, tanpa mengubah nilai total aset. Bedakan konversi dari mutasi biasa: mutasi hanya memindahkan jumlah dalam satu SKU, sedangkan konversi selalu memiliki dua sisi, yaitu pengurangan source dan penambahan target yang harus seimbang secara kuantitas dan nilai.

### 3.2 Peran dalam Sistem

| Aspek | Peran Modul Konversi | Bukti Sumber |
|---|---|---|
| Alur transaksi | 2 step: `request` lalu `approve` | `WORKFLOW_MODUL_KONVERSI.md` section 3 |
| Jenis transaksi | `1334` (pusat), `334` (cabang) | `WORKFLOW_MODUL_KONVERSI.md` section 2, `UAT_Checklist.md` bagian Test Environment |
| Target dokumen pusat | Step 1 menghasilkan `1334r` state `pending approval`; step 2 dari `1334r` menghasilkan `1334` state `sent` | `WORKFLOW_MODUL_KONVERSI.md` section 3.1 |
| Target dokumen cabang | Step 1 menghasilkan `334r` state `pending approval`; step 2 dari `334r` menghasilkan `334` state `sent` | `WORKFLOW_MODUL_KONVERSI.md` section 3.2 |
| Mode M1-M4 | Menentukan pasangan komponen posting dan aturan validator | `blueprint-upgrade-modul-konversi-support-varian.md` section 13 |
| Model base ERP | `MdlTransaksi` header, `MdlTransaksiData` detail double-entry | `blueprint_konversi_stok.md` section 2 |
| Standar acuan | ISO/IEC 25010, SAP LO-VC, ISO 9001:2015, ISO 27001:2022, ISO 28000:2007, ISO 8000 | `blueprint-konverter-multi-variant.md` section 2 |

### 3.3 Modul Turunan: `konversi_varian`

Blueprint terpisah Timberculkan modul `konversi_varian` dengan dua jenis transaksi sendiri:

- `jenisTr` `881`: Konversi Varian Produk, misalnya warna Merah XL menjadi Hitam L.
- `jenisTr` `7881`: Konversi Varian Supplies (bahan penolong).

Modul ini memakai pola dual-write lock dengan kelas `ComLockerStockDualWrite` dan `ComLockerStockSuppliesDualWrite`, serta jurnal `ComJurnal` yang mencatat Persediaan Varian Target (D) versus Persediaan Varian Sumber (K). Struktur controllernya memuat sub-controller `_processSelectProductConvertion.php`, `_processSelectSuppliesConvertion.php`, dan `_shoppingCart.php`.

### 3.4 Pemisahan yang Harus Dijaga

Ada dua batas yang wajib tidak dicampur:

- Batas modul: `konversi` menangani alur konversi umum dengan jenis transaksi `1334`/`334`, sedangkan `konversi_varian` menangani konversi antarvarian dan supplies dengan jenis transaksi `881`/`7881`.
- Batas workspace: `blueprint-konverter-multi-variant.md`-Acuan workspace `w:/san_staging/application/modules/konversi`, sedangkan `blueprint_konversi_varian.md` dan `_tmp_blueprint.md`-Acuan workspace `c:/xampp/htdocs/new_san_variant` dan `w:/new_san_variant`. Ketiga ini bukan workspace yang sama, sehingga instruksi harus dibaca relatif terhadap workspace asal masing-masing dokumen.

---

## 4. Aturan Konversi Stok dan Satuan

### 4.1 Aturan Integrasi Model Base

Dari `blueprint_konversi_stok.md`:

1. DILARANG menulis query insert/update manual ke database; seluruh penyimpanan wajib lewat model base.
2. Header diisi melalui `$this->load->model('MdlTransaksi');` dan detail melalui `$this->load->model('MdlTransaksiData');`.
3. `kode_transaksi` atau `jenis_transaksi` bernilai `KONVERSI_STOK`.
4. `status` bernilai `PENDING` saat request dan `APPROVED` saat approval.
5. Pola double-entry per item keranjang:
   - Baris minus: `id_produk` = ID produk non-varian asal, `qty` = nilai minus, contoh `-50.0000`.
   - Baris plus: `id_produk` = ID varian produk tujuan, `qty` = nilai plus, contoh `50.0000`.
6. Kedua baris membawa `hpp` yang sama, dan `id_transaksi` dari header.

### 4.2 Aturan Bisnis Legacy (Business Controls)

| Kode | Aturan | Dampak Implementasi |
|---|---|---|
| `[SoD-01]` | `approved_by` tidak boleh sama dengan `requested_by` atau `created_by` | Validasi di tingkat Controller saat tombol Approve ditekan |
| `[INV-01]` | Larangan negative stock: sebelum approval, cek sisa stok riil produk non-varian tidak boleh lebih kecil dari kuantitas yang dikurangi | Memanggil fungsi pengecekan stok dari Model Persediaan Base |
| `[L-04]` | Semua nilai kuantitas wajib dilemparkan sebagai string angka presisi untuk mendukung `DECIMAL`; dilarang operasi matematik `float` PHP 5.6 | Menghindari pembulatan tidak akurat |

### 4.3 Contoh Implementasi Controller dari Sumber

`blueprint_konversi_stok.md` memberikan class `Stock_conversion extends MX_Controller` dengan method `save_request()`:

- Baris 71 pada markdown: load dua model base dalam satu baris.
- Baris 83-88: array `$data_header` berisi `jenis_transaksi`, `id_gudang`, `status`, `created_by`.
- Baris 91: `$this->MdlTransaksi->insert_data($data_header)`.
- Baris 98-104: `$detail_minus` dengan `qty` = `(string)($item['qty_convert'] * -1)` dan `hpp` = `$item['hpp']`.
- Baris 107-113: `$detail_plus` dengan `id_produk` = `$item['variant_product_id_tujuan']` dan `qty` = `(string)$item['qty_convert']`.
- Baris 117: redirect ke `stock_conversion/list_request`.

### 4.4 Reviu Kode dan Logika Bisnis dari Panduan SAP

`sap_variant_conversion_rules.md` menambahkan lapisan validasi yang berbeda fokus, yaitu switching mode produk dari non-varian ke variant configuration dengan model kode induk `S-ADS` dan kode varian `S-ADS-[Warna]-[Ukuran]`.

| Rule | Logika | Konsekuensi |
|---|---|---|
| Rule 3.1 | Modifikasi status produk dari Non-Variant ke Variant pada kode induk hanya boleh jika saldo stok fisik gudang bernilai 0 | Mencegah inventory misalignment dan tumpang tindih kalkulasi HPP/Moving Average Price |
| Rule 3.2 | Proses switching diblokir jika kode induk masih terikat dokumen aktif: Purchase Order belum Goods Receipt, Sales Order belum Delivery atau Invoiced, Stock Opname belum posting | Open document integrity |
| Rule 3.3 | Nilai total aset tidak boleh berubah: `Qty Old x Standard Price Old = sum(Qty Variant_i x Standard Price Variant_i)` | Akun Inventory Adjustment dikreditkan kembali dengan nilai sama persis |

Tiga fase transaksi yang diwajibkan secara atomik pada isolation level Serializable:

1. Fase 1 Pengosongan: mengurangi stok `S-ADS` dari 100 pcs menjadi 0 pcs, padanan Movement Type `562` atau `702`.
2. Fase 2 Auto-Generation SKU: format `[Parent_SKU]-[Color_Code]-[Size_Code]` dengan fungsi sanitasi string untuk mencegah karakter ilegal.
3. Fase 3 Pengisian Kembali: memasukkan stok riil hasil opname fisik ke SKU baru, padanan Movement Type `561` atau `701`.

Instruksi review kode yang harus dijalankan AI Agent:

1. Cari fungsi yang mengubah status produk menjadi Varian tanpa mengecek `where stock_qty = 0`; tandai sebagai Critical Bug.
2. Cari error handling; jika gagal di Fase 3, sistem harus melakukan database rollback sehingga stok induk tidak hilang.
3. Cari modul hak akses; fungsi switching dibatasi untuk role `Inventory_Manager` atau `Data_Governance`.

Data wajib log untuk audit ISO 27001:2022 adalah `User_ID`, `Timestamp`, `Old_Stock_Qty`, `New_Stock_Per_Variant`, `Movement_Type_Used`, dan `Financial_Journal_ID`.

### 4.5 Aturan Satuan dan Rasio

`blueprint-upgrade-modul-konversi-support-varian.md` section 14.1 menambah aturan satuan yang belum ada di dokumen lain:

1. Jika source dan target berbeda satuan, sistem wajib menyimpan `jml_per_satuan`.
2. `jml_per_satuan` harus lebih besar dari 0.
3. Jika hasil konversi menghasilkan pecahan, boleh hanya jika satuan produk mengizinkan decimal qty; jika tidak ada konfigurasi satuan decimal, default ditolak.
4. Tidak boleh ada pembulatan diam-diam pada qty stok.

Flag terkait: `allow_decimal_qty` (default ikut konfigurasi satuan produk) dan `allow_unit_ratio_conversion` (default `true`, wajib validasi rasio).

Catatan: checklist item `F1-07` "Tambah handling satuan dan `jml_per_satuan`" berstatus `Belum` di file `_shoppingCart.php`, sehingga aturan satuan di atas masih berupa desain.

### 4.6 Aturan HPP dan Nilai

Section 14.2 dokumen upgrade varian:

1. Total nilai source wajib sama dengan total nilai target.
2. Formula minimal: `sum(source_qty * source_hpp) == sum(target_qty * hpp_injector)`.
3. `hpp_injector` target harus berasal dari nilai source atau aturan costing yang jelas.
4. Manual override HPP hanya boleh jika `allow_manual_hpp_override = true` dan tercatat di audit.

Flag terkait: `allow_manual_hpp_override` default `false`.

Kontrol turunan dari standar variant_cutover: `FVC-01/FVC-02/FVC-03` berstatus ADOPTED, yaitu nilai inventory sebelum dan sesudah harus sama dan HPP target berasal dari source atau override berapproval. Kontrol `FVC-04/L-04` ADOPTED melarang FLOAT untuk qty, harga, HPP, dan total nilai.

### 4.7 Review Kode: Temuan Konkret dari Verifikasi Gate

`15-skenario-verifikasi-konversi-items-gate.md` menemukan pre-existing bug nama field pada konfigurasi items gate. Session `items` hanya punya field `jml` dan `nama`, bukan `qty` dan `name`.

| Config | Tertulis di Config | Resolves ke | Seharusnya |
|---|---|---|---|
| LockerStock jumlah | `-qty` | 0 | `-jml` |
| LockerStock nama | `name` | 0 | `nama` |
| LockerStockMutasi qty_debet | `-qty` | 0 | `-jml` |
| PreFifo produk_qty | `qty` | 0 | `jml` |
| PreFifo extern_nama | `name` | 0 | `nama` |

Lokasi baris konfigurasi yang disebut: `coTransaksiCore.php` lines 174, 205, 586, 613, 640.

Dasar perhitungan yang dipakai sumber: `makeValue("-qty", $row, $row, 0)` melakukan `multiExplode` dengan `preg_split('/(\+|\-|\*|\/|\(|\))/', "-qty")` menghasilkan `["", "qty"]`, `sizeof = 2 > 1` sehingga masuk calculation path, `val = "qty"`, `isset($sourceHitung["qty"]) = false`, `$static = 0`, `str_replace("qty", 0, "-qty") = "-0"`, `calculate("-0") = 0`.

Akibat: semua komponen postProcessor LockerStock adalah NO-OP dengan jumlah 0. Eksekusi locker sebenarnya terjadi di shopping cart melalui `reserveLockerForSelect` dan `reserveVariantLockerForSelect`, bukan di postProcessor.

Temuan kedua: `ComLockerStockMutasi.variantMutationCom` tidak pernah di-instantiate pada baris 18 di-set null dan baris 314-316 mengecek null, sehingga sebelum patch ini variant items di outParamsVarian tidak pernah dieksekusi. Dampak: mutasi varian hilang. Fix: penambahan komponen `ComLockerStockMutasiVariant` terpisah.

---

## 5. Arsitektur Konverter Multi-Variant

### 5.1 Prinsip Dasar

Prinsip yang berulang di dua dokumen blueprint konverter multi-variant:

> Setiap produk adalah varian. Produk tanpa varian eksplisit otomatis memiliki satu varian default dengan `variant_id = -1`.

Sentinel globals yang-specified:

```php
define('VARIANT_DEFAULT_ID', -1);
define('VARIANT_DEFAULT_LABEL', 'Default');

function resolveVariantId($produkId, $variantId = 0)
{
    if ((int)$variantId > 0) {
        return (int)$variantId;
    }
    return VARIANT_DEFAULT_ID; // -1
}
```

### 5.2 Baseline Masalah

`blueprint-konverter-multi-variant.md` mendiagnosis lima masalah struktural:

1. Dual session key. Non-varian memakai key `"1743"` (produk_id), varian memakai `"variant:1743:15"`. Akibatnya `buildVariantKeyCandidate()` pada `FollowUp.php:219` harus menebak format key.
2. Ghost key harus dibersihkan. `FollowUp.php:281-284` menghapus paksa key dengan kondisi `$isVariantSibling && $vid < 1 && strpos($ck, "variant:") !== 0`.
3. Dual processing pipeline. `rsltItems` untuk non-varian dengan gate `tableIn_detail_rsltItems`, dan `rsltItems2` untuk varian dengan gate `tableIn_detail_rsltItems2`. Logika berulang di `FollowUp.php:1448-1523`.
4. Dual stock table. `stock_locker` untuk non-varian, `stock_locker_variant` untuk varian dengan dua filter `produk_id` dan `variant_id`.
5. Dual HPP injector. `afterPreProcessorInjector` untuk `rsltItems` dan `afterPreProcessorInjector2` untuk `rsltItems2`.

### 5.3 Arsitektur Target pada `san_staging`

| Layer | Sebelum | Sesudah |
|---|---|---|
| Session key non-varian | `"1743"` | `"variant:1743:-1"` |
| Session key varian | `"variant:1743:15"` | tetap |
| Pipeline | `rsltItems` + `rsltItems2` | hanya `rsltItems2` |
| Detail gate | `tableIn_detail_rsltItems` + `tableIn_detail_rsltItems2` | hanya `tableIn_detail_rsltItems2` |
| HPP injector | `afterPreProcessorInjector` + `afterPreProcessorInjector2` | hanya `afterPreProcessorInjector2` |
| Stock table | `stock_locker` + `stock_locker_variant` | hanya `stock_locker_variant` |
| Mutasi | `stock_locker_mutasi` + `stock_locker_mutasi_variant` | hanya `stock_locker_mutasi_variant` |
| Komponen config | `FifoProdukJadi` + `FifoProdukJadiVarian` | hanya `FifoProdukJadiVarian` |

View database penjagat yang dirancang:

```sql
CREATE VIEW stock_unified AS
SELECT produk_id, variant_id, cabang_id, gudang_id, state, jumlah
FROM stock_locker_variant
UNION ALL
SELECT produk_id, -1 AS variant_id, cabang_id, gudang_id, state, jumlah
FROM stock_locker
WHERE produk_id NOT IN (SELECT DISTINCT produk_id FROM stock_locker_variant);
```

Akses stok terpadu lewat helper `getUnifiedStock($produkId, $variantId, $cabangId, $gudangId)` yang memuat model `Mdls/MdlLockerStockVariant` dan menambahkan filter `produk_id`, `variant_id`, `cabang_id`, `gudang_id`, dan `state = 'active'`.

### 5.4 Arsitektur Alternatif pada `new_san_variant`

`_tmp_blueprint.md` menganutkan arah berbeda yang penting untuk synthesizer, yaitu dual-write permanen dengan satu pipeline:

| Layer | Komponen |
|---|---|
| Posting gate | `rsltItems` saja, menangani `variant_id` di session |
| FIFO value | `FifoProdukJadi` + `FifoProdukJadiVarian` (dual-write) |
| Locker stok | `LockerStock` + `LockerStockVariant` (dual-write) |
| Mutasi stok | `LockerStockMutasi` + `LockerStockMutasiVariant` (dual-write) |

Status akhir tabel: `stock_locker`, `stock_locker_variant`, `stock_locker_mutasi`, dan `stock_locker_mutasi_variant` semuanya tetap aktif. Tidak ada fase cleanup.

Konsekuensi arsitektural yang ditegaskan sumber:

- Normalisasi session otomatis di `MdlMother::__construct()`, memindai session dengan prefiks `_TR_` yang punya `items`, lalu memanggil `normalizeSessionKeys()`. Konsekuensinya nol perubahan di `Modul_Controller.php`, nol method baru, dan sifat idempoten.
- Atomicity wajib: setiap transaksi posting menulis ke enam komponen sekaligus dan harus dibungkus `trans_start()` / `trans_complete()` di semua 19 modul. Tanpa transaksi, partial write dikategorikan sebagai P0 bug.
- Reconciliation otomatis via cron harian dengan query `HAVING total_locker != total_variant` yang menggabungkan `stock_locker` dan `stock_locker_variant` per `produk_id`.
- Cakupan 19 modul inventory dengan pembagian 6 agent: konversi dan konversi_varian, pembelian, penjualan, pindahgudang dan opname, distribusi, produksi.

### 5.5 Feature Flag dan Rollback

Flag pada `blueprint-konverter-multi-variant.md`:

```php
"singleVariantStandard" => array(
    "enabled" => false,
    "defaultVariantId" => -1,
    "forceKeyNormalization" => true,
),
```

Rollback plan:

| Skenario | Tindakan |
|---|---|
| Session error setelah normalizer | Matikan `normalizeSessionKeys()` via feature flag |
| Stok tidak balance | Matikan view `stock_unified`, aktifkan kembali query `stock_locker` |
| Key format bentrok | Aktifkan `buildVariantKeyCandidate()` sebagai fallback |
| Approval gagal | Kembalikan `afterPreProcessorInjector` dan `rsltItems` |

Estimasi penghapusan dari blueprint: sekitar 763 baris, rinciannya `normalizeSessionDetailGatesByItems()` ~146 baris, `buildVariantKeyCandidate()` ~18, `applyCounterRowsToExistingGate()` ~53, `isVariantTrapEnabled()` ~14, `logVariantTrap()` ~16, `writeVariantTrapFile()` ~16, separuh `_processSelectProductConvertion.php` ~400, separuh `coTransaksiCore.php` ~100.

Estimasi total program: sekitar 100+ file berubah dalam 8-12 minggu pada versi `san_staging`, atau 4-6 minggu dengan 6 agent paralel pada versi `new_san_variant`.

---

## 6. Upgrade Modul Konversi untuk Mendukung Produk Varian

### 6.1 Baseline Masalah Teknis

Lima root cause yang diidentifikasi pada `blueprint-upgrade-modul-konversi-support-varian.md`:

1. Kontrak UI masih non-varian. Flow `1334` memakai selector source `MdlProduk2` dan target pairing `MdlProduk2` tanpa kontrak varian pada `coTransaksiUi.php:39` dan `coTransaksiUi.php:232`. Validator `shoppingCartValidatorsPairedItem` membandingkan source `items` versus target `items2_sum` pada `coTransaksiUi.php:275` tanpa level varian per parent.
2. Processor target belum memuat stok varian. `resultSelect()` menerima `id2` sebagai `produk_id` target biasa pada `_processSelectProductConvertion.php:824` dan `:844`. Belum ada loader `MdlProdukVarian` dan belum ada query `stock_locker_variant`.
3. Cart edit target generik. `recordPairedItem()` dan `recordPairedItemSatuan()` menulis `items2_sum` generik per baris pada `_shoppingCart.php:2918` dan `:3117`. Tidak ada guard eksplisit total qty varian lebih kecil dari atau sama dengan qty parent.
4. Core posting masih non-varian. Komponen target masih memakai `FifoProdukJadi`, `LockerStock`, `LockerStockMutasi` pada `coTransaksiCore.php:590`, `:616`, `:637`. Belum ada `variant_id` sebagai identity posting.
5. Dampak bisnis: risiko salah posting ke produk parent, risiko qty mismatch, risiko audit trail parent-variant tidak traceable.

### 6.2 Opsi Implementasi

| Opsi | Inti | Kelebihan | Konsekuensi |
|---|---|---|---|
| Opsi A (Recommended) | Satu flow dengan mode resolver native plus feature flag | User tetap di modul `konversi`, backward compatible, blast radius terkendali | Perlu logic bercabang di beberapa file legacy |
| Opsi B | Split flow per mode, masing-masing punya selector, validator, core config | Lebih mudah dibaca, risiko salah branch kecil | Maintenance lebih berat, perubahan rule global disalin ke banyak flow |

Catatan keputusan eksplisit: delegasi proses varian ke modul `variant_cutover` tidak dipakai dalam blueprint upgrade. Modul `variant_cutover` hanya menjadi referensi pola implementasi. Ini berbeda dengan `blueprint_konversi_varian.md` yang justru menempatkan `variant_id_asal` dan `variant_id_tujuan` di dalam modul `konversi_varian` sendiri.

### 6.3 Kontrak Session Target

| Gate | Isi | Field Minimal |
|---|---|---|
| `items_source` | Sumber stok yang dikurangi | `item_type`, `produk_id`, `variant_id`, `parent_produk_id`, `jml`, `current_stok`, `hpp` |
| `items_target` | Tujuan stok yang ditambah | `item_type`, `produk_id`, `variant_id`, `parent_produk_id`, `jml`, `hpp_injector` |
| `items` | Gate legacy source, dipertahankan agar flow lama tidak rusak | Mempertahankan struktur existing |
| `items2` | Detail target dan detail varian per parent | `items2[parent_produk_id][variant_id] = {variant_id, sku, current_stok, jml, ...}` |
| `items2_sum` | Gate agregat posting target | Wajib membawa `variant_id` untuk item varian, kosong/null untuk non-varian |
| `conversion_mode` | Disimpan di session atau main value | Nilai valid `M1`, `M2`, `M3`, `M4` |

Nilai `item_type` berisi `produk` atau `variant`. Resolusi mode memakai kombinasi `source_is_variant` dan `target_is_variant` masing-masing bernilai `{0|1}`.

### 6.4 Kontrak Validasi

Tujuh rule global:

1. `sum(items_source.*.jml) == sum(items_target.*.jml)`.
2. `jml` setiap baris harus lebih besar dari 0.
3. Source dan target yang identik harus ditolak.
4. Source stock wajib cukup: source `produk` dicek ke `stock_locker`, source `variant` dicek ke `stock_locker_variant`.
5. Target stock tidak dipakai sebagai batas penambahan, kecuali target juga menjadi source pada baris lain dalam transaksi yang sama.
6. `variant_id` wajib valid dan sesuai `parent_produk_id` untuk semua item bertipe `variant`.
7. Jika gagal, blokir tombol approve dengan pesan spesifik per source atau target.

### 6.5 Kontrak Posting Berbasis `item_type`

| Sisi | Tipe | Komponen |
|---|---|---|
| Source | `produk` | `LockerStock`, `LockerStockMutasi` |
| Source | `variant` | `LockerStockVariant`, `LockerStockMutasiVariant` |
| Target | `produk` | `FifoProdukJadi`, `LockerStock`, `LockerStockMutasi` |
| Target | `variant` | `FifoProdukJadiVarian`, `LockerStockVariant`, `LockerStockMutasiVariant` |

`variant_id` wajib ikut di gate atau table mapping hanya untuk item bertipe `variant`. Bila engine config tidak dapat bercabang dalam satu gate, harus dibuat gate terpisah: `items_source_produk`, `items_source_variant`, `items_target_produk`, `items_target_variant`.

### 6.6 Matriks Mode Konversi Detail

**M1 Varian ke Varian.** Source dari `stock_locker_variant`, target ke `stock_locker_variant`. Jika lintas parent varian, default ditolak dan hanya boleh jika flag `allow_cross_parent_variant = true`. Pengurangan dan penambahan sama-sama memakai komponen varian-aware.

**M2 Non-Varian ke Varian.** Source dari `stock_locker`, target ke `stock_locker_variant`. Wajib ada distribusi varian dan total distribusi harus sama dengan qty source. Pengurangan tetap lewat komponen native, penambahan memakai komponen varian-aware.

**M3 Varian ke Non-Varian.** Source dari `stock_locker_variant`, target ke `stock_locker`. Total qty source varian harus sama dengan qty target non-varian. Pengurangan varian-aware, penambahan native.

**M4 Non-Varian ke Non-Varian.** Tetap flow native existing, tidak boleh regress saat `variant_mode` aktif untuk mode lain, dan tidak ada field varian wajib pada mode ini.

### 6.7 Flag Konfigurasi

| Flag | Default | Fungsi |
|---|---|---|
| `variant_mode_enabled` | global/per-flow | Mengaktifkan mode varian |
| `allow_cross_parent_variant` | `false` | Izin konversi lintas parent varian |
| `strict_qty_balance` | `true` | Qty source harus sama dengan qty target |
| `enforce_sod` | `true` | Requestor tidak boleh menjadi approver |
| `fallback_to_native_on_nonvariant` | `true` | Non-varian kembali ke jalur native |
| `reject_self_conversion` | `true` | Tolak source dan target identik |
| `validate_variant_parent_map` | `true` | Validasi `variant_id` terhadap parent |
| `allow_decimal_qty` | ikut konfigurasi satuan produk | Izin qty desimal |
| `allow_manual_hpp_override` | `false` | Izin override HPP manual |
| `allow_unit_ratio_conversion` | `true`, wajib validasi rasio | Konversi antar satuan |

### 6.8 Data Integrity Guardrails

1. Seluruh eksekusi followup tetap dalam satu DB transaction per approval.
2. Tidak boleh ada SQL string manual untuk query varian; gunakan Query Builder atau binding.
3. Blokir approve bila total source dan target kurang atau lebih, ada qty negatif, stok source tidak cukup, atau `variant_id` tidak sesuai parent.
4. Simpan relasi parent-variant dan `conversion_mode` di transaksi detail untuk audit.
5. Jangan pakai `current_stok` target sebagai batas penambahan stok; batas stok hanya berlaku pada item yang dikurangi.

### 6.9 Rencana Fase

| Fase | Isi | Status menurut checklist |
|---|---|---|
| Fase 0 | Baseline dan toggle, feature flag default nonaktif, resolver mode | 2 dari 6 selesai |
| Fase 1 | Readiness data, loader varian, session contract | 5 dari 7 selesai, 1 sedang, 1 belum |
| Fase 2 | UI, cart, hold, alokasi varian | 0 dari 9 selesai |
| Fase 3 | Validator approve dan guard integritas | 0 dari 11 selesai |
| Fase 4 | Posting engine dan core mapping | 0 dari 8 selesai |
| Fase 5 | Audit, error logging, compliance evidence | 0 dari 8 selesai |
| Fase 6 | UAT mode dan release gate | 0 dari 14 selesai |

Aturan kerja yang ditegaskan checklist: jangan masuk Fase 4 sebelum Fase 0-3 selesai; semua patch wajib kompatibel PHP 5.6; query baru wajib Query Builder atau binding; tidak boleh mengubah flow native non-varian tanpa UAT M4.

### 6.10 Referensi Pola Varian-Aware

Tujuh titik referensi dari modul `variant_cutover` yang disebutkan di akhir blueprint upgrade:

1. `variant_cutover/config/coTransaksiUi.php:452` untuk `recordItemColumnVarian`.
2. `variant_cutover/controllers/_processSelectProductConvertion.php:1156` untuk `loadVarianProduk`.
3. `variant_cutover/controllers/_processSelectProductConvertion.php:1172` untuk `getVariantCurrentStock`.
4. `variant_cutover/controllers/_shoppingCart.php:3373` untuk `recordItemColumnVarian`.
5. `variant_cutover/config/coTransaksiCore.php:651` untuk `FifoProdukJadiVarian`.
6. `variant_cutover/config/coTransaksiCore.php:678` untuk `LockerStockVariant`.
7. `variant_cutover/config/coTransaksiCore.php:700` untuk `LockerStockMutasiVariant`.

---

## 7. Fix Konversi: Selector dan Shopping Cart Varian

### 7.1 Tujuh Gap UAT yang Jadi Ruang Kerja

`blueprint-uat-fix-konversi-selector-shoppingcart-varian.md` merumuskan tujuh fokus UAT:

1. Pembeda jelas produk varian versus non-varian di selector.
2. Klik produk non-varian langsung masuk shopping cart.
3. Klik produk varian membuka modal pilih varian, lalu klik varian baru masuk shopping cart.
4. Shopping cart konsisten untuk source dan target varian maupun non-varian.
5. Varian dan master setara di session `items`.
6. Varian dan master setara di session `items2`.
7. Dropdown target di shopping cart `items2` bisa pilih varian maupun non-varian.

### 7.2 Baseline Masalah dengan Bukti Baris

| No | Temuan | Bukti |
|---|---|---|
| 3.1 | Flag `variant_mode_enabled` masih `false` untuk `1334` dan `334` | `coTransaksiUi.php:15` dan `coTransaksiUi.php:1155` |
| 3.2 | `selectorViewedFields` belum memuat `has_variants` | `coTransaksiUi.php:78` dan `coTransaksiUi.php:1215`; badge render belum ada di `_selectorItem.php:323`, pembanding `variant_cutover/_selectorItem.php:332` |
| 3.3 | Belum ada `variantPicker` di modul `konversi` | `views/_selector.php:44` dan `:81`; `_selectorItem` tidak punya endpoint `variantPicker` |
| 3.4 | Enum `item_type` tidak sinkron | Resolver mode di `Modul_Controller.php:109` membaca `variant`, sedangkan gate mengisi `varian` di `_processSelectProductConvertion.php:32` dan `:54` |
| 3.5 | Dropdown paired target masih product-only | `coTransaksiUi.php:234` dan `_shoppingCart.php:1902` memakai `MdlProduk2` saja |
| 3.6 | Struktur session bercampur shadow-state | `items_source` dan `items_target` hasil rebuild, sedangkan flow cart membaca `items` |
| 3.7 | Flow remove/edit masih identity produk parent | `_processSelectProductConvertion.php:874` dan `:891` memakai `$_GET['id']` dan `MdlLockerStock` by produk |
| 3.8 | Kontrak render source versus warning target belum tegas | `views/shoppingCart.php:517`; session bukti UAT menunjukkan `items` dan `items_source` terisi namun `items_target` kosong |
| 3.9 | State messaging belum dipisah | Pesan `SILAHKAN PILIH ITEM HASIL KONVERSI...` dan `you have not chosen any item yet` dapat muncul berurutan |
| 3.10 | Perbedaan layer shopping cart versus sub-postProcessor | Step `request` `1334r`/`334r` komponen `LockerStockVariant` belum terdaftar; guard awal sudah diterapkan agar `ComLockerStock` hanya memproses row non-varian `variant_id = 0` |

### 7.3 Kontrak Identitas Item

Identity kanonik yang disepakati:

1. Key row source non-varian di `items` tetap native, yaitu key numerik `id` master produk tanpa perubahan.
2. Key row source varian di `items` memakai format `variant:{id_master}:{id_varian}`.
3. `id_master` sama dengan `produk_id` atau parent product, `id_varian` lebih besar dari 0 untuk varian.
4. `item_type` diturunkan dari pola key: key `variant:*:*` menghasilkan `variant`, key numerik native menghasilkan `produk`.

Aturan khusus dua varian dari master yang sama: wajib tersimpan sebagai dua row terpisah dengan kunci `variant:1743:501` dan `variant:1743:502`. Larangan eksplisit menggabungkan dua varian berbeda ke satu row source hanya karena `produk_id` sama.

Sepuluh field kontrak item minimal: `session_key`, `item_type`, `produk_id`, `variant_id`, `parent_produk_id`, `nama`, `kode` atau `produk_kode`, `satuan`, `jml`, dan `hpp` atau `harga`.

Aturan sinkron session:

1. `items` adalah single source of truth untuk source rows, tanpa `items_source` maupun `items_target`.
2. `items2` adalah detail distribusi target per row source dengan bentuk `items2[source_session_key][target_session_key]`.
3. `items2_sum` adalah agregat target per row source untuk validasi lama, tetapi wajib menyimpan `session_key`, `item_type`, `produk_id`, `variant_id`.
4. View shopping cart membaca `items` apa adanya dari session; bila ada normalisasi atau rebuild, hasilnya wajib ditulis kembali ke `$_SESSION[$cCode]['items']` sebelum render, embodying prinsip view equals session.

### 7.4 Kontrak Routing PostProcessor per Row

1. Routing postProcessor wajib berbasis row `variant_id`, tidak boleh per-transaksi global.
2. Source `items`: `variant_id = 0` memakai `LockerStock` dan `LockerStockMutasi`; `variant_id > 0` memakai `LockerStockVariant` dan `LockerStockMutasiVariant`.
3. Target `items2_sum`: `variant_id = 0` memakai `FifoAverage/FifoProdukJadi` plus `LockerStock` plus `LockerStockMutasi`; `variant_id > 0` memakai `FifoProdukJadiVarian` plus `LockerStockVariant` plus `LockerStockMutasiVariant`.
4. Guard minimum: `ComLockerStock` skip row varian, `ComLockerStockVariant` skip row non-varian dengan `variant_id < 1`, dan payload legacy dengan `cart_key = variant:{pid}:{vid}` dianggap varian walau `variant_id` belum terisi.
5. Catatan step: `request` tidak otomatis menambah stok target; eksekusi stok target utama tetap terjadi saat `approve`.

### 7.5 Mutual Exclusion yang Terbukti

Lima kelas komponen dengan kondisi skip:

| Class | File:line | Skip condition | Dampak |
|---|---|---|---|
| `ComLockerStock` | `ComLockerStock.php:118-122` | `varian_id > 0` | NV only |
| `ComLockerStockMutasi` | `ComLockerStockMutasi.php:126-153` | `variantID > 0` dipush ke outParamsVarian, no-op | NV only |
| `ComLockerStockVariant` | `ComLockerStockVariant.php:60-62` | `variant_id < 1` | V only |
| `ComLockerStockMutasiVariant` | `ComLockerStockMutasiVariant.php:26-28` | `variant_id < 1` | V only |

Kesimpulan sumber: setiap item diproses oleh tepat satu set komponen, tidak ada double processing.

Detail tambahan yang ditemukan saat trace:

- `ComLockerStock` pada baris 59 membaca `variant_id`, pada baris 66-77 melakukan cek `cart_key`, pada baris 118 memutuskan skip.
- `ComLockerStock` pada baris 56 memiliki elseif untuk string dengan awalan `variant:`, pada baris 57 melakukan `(int)str_replace("variant:", "", ...)`, pada baris 114 menetapkan `static['varian_id']`, pada baris 118 skip.
- `PreFifoProdukJadi` pass-through key untuk varian adalah `variant_id^2`. Contoh `881^2 = 776161` dan `882^2 = 777924`, sehingga unik.

### 7.6 Kontrak Render Source-First

Enam aturan wajib:

1. Jika `items` berisi minimal satu row, tabel source wajib tetap tampil.
2. Warning target atau `paired item warning` tidak boleh menggantikan atau menutupi tabel source.
3. Empty state wajib dipisah: empty source menampilkan pesan belum pilih item source, sedangkan source ada target kosong menampilkan warning pairing target per row atau section target.
4. Styling warning target hanya di section target, bukan global cart container.
5. `pairedItemNoTarget` tidak boleh memicu fallback cart kosong total.
6. Selector JS dan DOM untuk key varian harus aman dari karakter `:`.

### 7.7 Indikator Kemajuan yang Sudah Diterapkan

Blueprint mencatat guard awal yang sudah diterapkan: `ComLockerStock` hanya memproses row non-varian dengan `variant_id = 0`, dan row varian dengan `variant_id > 0` atau `cart_key` format `variant:{pid}:{vid}` diabaikan di jalur parent locker.-hard-filter shadow row source invalid dengan `produk_id = 0` atau `nama = 0` saat `followupPrePreview` dan `followupPreview` juga sudah menjadi bagian rencana file.

### 7.8 Rencana Perubahan File

Sepuluh file yang direncanakan, dengan fokus masing-masing:

1. `config/coTransaksiUi.php`: aktifkan `variant_mode_enabled` untuk `1334` dan `334`, tambah `has_variants` di `selectorViewedFields`, siapkan config dropdown target union.
2. `controllers/_selectorItem.php`: tambah helper `build_variant_picker_url`, `selector_supports_variant_picker`, `variantPicker`, override `socketURL` untuk item `has_variants = 1`, badge visual varian atau non-varian.
3. `views/_selector.php`: dukung `dialog_size` untuk modal varian, pastikan click non-varian tetap direct-add.
4. `views/variant_picker.php`: file baru, adopsi pola requeststok.
5. `controllers/_processSelectProductConvertion.php`: normalisasi `item_type`, tambah parser dan generator key varian `variant:{pid}:{vid}` pada select dan remove.
6. `controllers/_shoppingCart.php`: hilangkan dependency `items_source/items_target`, pastikan renderer memakai `items` apa adanya, generator `selItems` union produk dan varian.
7. `views/shoppingCart.php`: render dropdown target berbasis identity, enforce source-first render, pisahkan pesan empty source dan empty target.
8. `controllers/Transaksi.php`: validasi paired item berbasis `session_key` dan `item_type`, validasi tabrakan row saat parent sama tetapi `variant_id` berbeda.
9. `application/models/Coms/ComLockerStock.php`: guard row varian agar tidak menulis ke `stock_locker` parent, deteksi varian dari `variant_id`, `varian_id`, dan fallback `cart_key`.
10. `controllers/FollowUp.php`: router atau filter row-level sebelum `pair()`, hard-filter shadow row saat `followupPrePreview` dan `followupPreview`.

Empat fase eksekusi: Fase A selector marker dan variantPicker modal; Fase B session contract canonical dan normalizer enum `item_type`; Fase C shopping cart dropdown union dan writer `items2`/`items2_sum`; Fase D validator hardening, UAT matrix, dan evidence. Tambahan guard eksekusi: perbaikan source-first render dijalankan sebelum optimasi UX target lain.

### 7.9 Parameter Pembuktian Empat Belas

Empat belas parameter pembuktian yang disediakan sumber, diringkas:

| ID | Parameter |
|---|---|
| P-00 | Source visibility guard, tabel source tetap tampil walau target kosong |
| P-01 | Selector marker, pembeda varian dan non-varian |
| P-02 | Click behavior non-varian, langsung masuk `items` tanpa modal |
| P-03 | Click behavior varian, modal terbuka, key `variant:{id_master}:{id_varian}` |
| P-04 | Session equality, field kanonik sama untuk `items` dan `items2_sum` |
| P-05 | `items2` equality, edit atau remove tidak menimpa row identity lain |
| P-06 | Dropdown target equality, opsi produk dan varian dalam satu source row |
| P-07 | Validator integrity, total qty seimbang dan mapping parent valid |
| P-08 | No regression M4, skenario non-varian ke non-varian tetap lolos |
| P-09 | State messaging split, pesan tidak tumpang tindih |
| P-10 | Same master multi-variant source, dua row terpisah |
| P-11 | Session lifecycle integrity, create, pair, edit, remove |
| P-12 | PostProcessor routing integrity, tidak ada write silang |
| P-13 | No shadow row in followup preview, row invalid tidak tampil |

---

## 8. Skenario Verifikasi

Tabel 15 skenario dari `15-skenario-verifikasi-konversi-items-gate.md`, tipe Static Code Analysis atau Code Trace, tanggal 2026-06-07, scope perubahan tiga komponen varian di `items` gate postProcessor.

| ID | Skenario | Data Kunci | Expected | Status |
|---|---|---|---|---|
| S1 | NV source ke NV target, single item | `id:1743, jml:10, variant_id:0` | Mutually exclusive, `tableIn_detail.jml = 10`, locker tetap hold 10 dari shopping cart | Lulus |
| S2 | V source ke V target, single item | `variant_id:881, cart_key:variant:1743:881` | `FifoAverageConvertion` skip, `FifoProdukJadi` pass-through key `881^2 = 776161`, komponen varian diproses | Lulus |
| S3 | NV source ke V target | `variant_id:0` | Items gate tidak peduli target type, sama dengan S1 | Lulus |
| S4 | V source ke NV target | `variant_id:881` | Items gate tidak peduli target type, sama dengan S2 | Lulus |
| S5 | NV ke NV, multi item beda produk | `id:1743 jml:10`, `id:1744 jml:5` | Setiap item diproses independen | Lulus |
| S6 | V ke V, dua variant produk sama | `variant_id:881` dan `882` | Pass-through key `776161` dan `777924` unik | Lulus |
| S7 | V ke V, beda produk beda variant | `id:1743 vid:881`, `id:1745 vid:883` | Kunci unik via `variant_id^2` | Lulus |
| S8 | V ke V, satu item multi qty | `variant_id:881, jml:100` | Sama dengan S2 | Lulus |
| S9 | NV plus V source ke V target | `variant_id:0` dan `881` | Tabel enam komponen: NV PROSES pada [0][1][2], V PROSES pada [3][4][5], tidak ada overlap | Lulus |
| S10 | NV plus V source ke NV target | `id:1743 vid:881, id:1745 vid:882` | Sama dengan S9 untuk items gate | Lulus |
| S11 | V1 plus V2 source ke V target | `id:1743 vid:881`, `id:1745 vid:882` | Sama dengan S6 | Lulus |
| S12 | Multiple NV plus Multiple V ke mixed target | Gabungan S9 dan S6 | Campuran OK | Lulus |
| S13 | `cart_key = variant:X:Y` dengan `variant_id = 0` | `variant_id:0, cart_key:variant:1743:881` | ComLockerStock skip via cart_key detection, komponen varian juga skip karena `variant_id < 1` | Data loss |
| S14 | `variant_id` string `variant:X:Y` | `variant_id:variant:1743:881` | NV skip karena parse 881, komponen varian skip karena cast int 0 | Data loss |
| S15 | Reset cart campuran NV dan V | NV `hold=10 active=90` di `stock_locker`, V `hold=5 active=45` di `stock_locker_variant` | `MdlLockerStock::cekLoker(hold)` update hold 0 dan active bertambah 10; `MdlLockerStockVariant::cekLoker(hold)` update hold 0 dan active bertambah 5 | Lulus, sudah diverifikasi di fix `_shoppingCart.php:2301-2409` |

Arsitektur pipeline yang menjadi konteks 15 skenario:

```
items gate (session $_SESSION[cCode]['items'])
  |- preProcessor[0]: FifoAverageConvertion -> inject HPP ke items gate
  |- preProcessor[1]: FifoProdukJadi -> rsltItems gate
  |- fillValues_he_value_builder -> tableIn_detail, tableIn_detail2, dll
  |- CounterNumber -> inject counter fields ke items
  |- postProcessor "1334" items gate -> 6 komponen
  |   [0] LockerStock (hold, -qty)          -> NV only
  |   [1] LockerStock (moved, +qty)         -> NV only
  |   [2] LockerStockMutasi                -> NV only
  |   [3] LockerStockVariant (hold, -qty)  -> V only, baru
  |   [4] LockerStockVariant (moved, +qty) -> V only, baru
  |   [5] LockerStockMutasiVariant         -> V only, baru
  `- Write DB (tableIn_detail jml langsung)

rsltItems gate
  |- RekeningPembantuProduk (NV)
  `- RekeningPembantuProdukVarian (V)

items2_sum gate (target)
  |- LockerStockVariant (active, +jml)
  `- LockerStockMutasiVariant
```

Tiga komponen baru yang ditambahkan pada gate `postProcessor["1334"]["detail"]`:

| No | Komponen | Tabel | Fungsi |
|---|---|---|---|
| 1 | `LockerStockVariant (hold, -qty)` | `stock_locker_variant` | Release hold source variant |
| 2 | `LockerStockVariant (moved, +qty)` | `stock_locker_variant` | Tulis moved source variant |
| 3 | `LockerStockMutasiVariant (qty_debet=-qty)` | `stock_locker_mutasi_variant` | Mutasi source variant |

Perubahan oleh patch yang tercatat: source variant items sekarang punya `LockerStockVariant` dan `LockerStockMutasiVariant` yang sebelumnya hanya NV; mutual exclusion lima Com classes terverifikasi; `PreFifoProdukJadi` pass-through variant fields ke `rsltItems`; `RekeningPembantuProdukVarian` menerima input; namun qty tetap 0 karena pre-existing field name mismatch yang sama dengan NV.

Penilaian risiko S13 dan S14: jarang terjadi karena `_shoppingCart.php` pada baris 55 selalu set `variant_id` sebagai integer `(int)$tmp[2]`.

---

## 9. Checklist dan UAT Konversi

### 9.1 Status Item Checklist Upgrade

Ringkasan berdasarkan `checklist-upgrade-modul-konversi-support-varian.md`. Definisi status: `Belum` belum dikerjakan, `Sedang` sedang dikerjakan, `Selesai` sudah dipatch dan diverifikasi, `Blocked` butuh keputusan atau temuan teknis.

| ID | Item | Status | Catatan Evidence |
|---|---|---|---|
| F0-01 | Trace flow existing `1334` dan `334` dari UI sampai followup | Belum | |
| F0-02 | Verifikasi komponen varian tersedia di modul `konversi` | Blocked | Belum ada `FifoProdukJadiVarian`, `LockerStockVariant`, `LockerStockMutasiVariant` di modul `konversi` |
| F0-03 | Verifikasi `coTransaksiValues.php` bisa membawa `item_type`, `produk_id`, `variant_id` | Blocked | Mapping `item_type` belum ada, perlu penambahan gate baru |
| F0-04 | Tambah flag `variant_mode_enabled` default nonaktif | Selesai | `config/coTransaksiUi.php` |
| F0-05 | Tambah resolver `conversion_mode` tanpa mengubah posting | Selesai | `controllers/Modul_Controller.php` |
| F0-06 | Pastikan M4 tetap memakai behavior native | Belum | |
| F1-01 | Loader produk varian via `MdlProdukVarian` | Sedang | Helper `loadVarianProduk()` sudah ada, belum diarahkan ke `MdlProdukVarian` |
| F1-02 | Query stok varian dari `stock_locker_variant` | Selesai | Helper `getVariantCurrentStock()` sudah filter `variant_id`, `state`, `cabang_id`, `gudang_id` |
| F1-03 | Validasi mapping `variant_id` ke `parent_produk_id` | Selesai | Helper `isVariantBelongsToProduk()` |
| F1-04 | Bentuk session `items_source` dan `items_target` | Selesai | Gate di selector plus `rebuildConversionGates()` di `_shoppingCart.php` |
| F1-05 | Pertahankan session legacy `items`, `items2`, `items2_sum` | Belum | |
| F1-06 | Tambah field minimal `item_type`, `produk_id`, `variant_id`, `parent_produk_id`, `jml`, `hpp` | Selesai | Field sudah diisi pada gate source dan target |
| F1-07 | Tambah handling satuan dan `jml_per_satuan` | Belum | |
| F2-01 | UI/parameter pilih source type dan target type | Belum | |
| F2-02 | Kolom source `item_type`, `current_stok`, `distribute`, `sisa_distribute` | Belum | |
| F2-03 | Kolom target `item_type`, `sku`, `header_varian`, `current_stok`, `jml` | Belum | |
| F2-04 | Handler alokasi varian `recordItemColumnVarian` | Belum | |
| F2-05 | Rebuild `items_source`, `items_target`, `items2_sum` setiap edit | Belum | |
| F2-06 | Source hold untuk `produk` di `stock_locker` | Belum | |
| F2-07 | Source hold untuk `variant` di `stock_locker_variant` | Belum | |
| F2-08 | Release hold saat remove item dari cart | Belum | |
| F2-09 | Release hold saat cancel, rollback, timeout | Belum | |
| F3-01 | Validasi `total_qty_source == total_qty_target` | Belum | |
| F3-02 | Validasi total nilai source = total nilai target | Belum | |
| F3-03 | Validasi source stock real-time sesuai `item_type` | Belum | |
| F3-04 | Validasi qty setiap baris lebih dari 0 | Belum | |
| F3-05 | Tolak self-conversion | Belum | |
| F3-06 | Validasi `variant_id` sesuai parent | Belum | |
| F3-07 | Validasi satu transaksi hanya satu gudang | Belum | |
| F3-08 | Validasi SoD `requestor != approver` | Belum | |
| F3-09 | Validasi `requestor != rollback_user` | Belum | |
| F3-10 | Tambah status `DRAFT`, `IN_PROGRESS`, `COMPLETED`, `FAILED`, `ROLLED_BACK` | Belum | |
| F3-11 | Tambah timeout proses default 30 menit | Belum | |
| F4-01 | Pisahkan gate source/target berbasis `item_type` | Belum | |
| F4-02 | Source `produk` pakai `LockerStock` dan `LockerStockMutasi` | Belum | |
| F4-03 | Source `variant` pakai komponen varian | Belum | |
| F4-04 | Target `produk` pakai `FifoProdukJadi`, `LockerStock`, `LockerStockMutasi` | Belum | |
| F4-05 | Target `variant` pakai komponen varian | Belum | |
| F4-06 | `tableIn detail/detail2/detail2_sum` membawa `item_type`, `produk_id`, `variant_id` | Belum | |
| F4-07 | Followup dalam satu DB transaction | Belum | |
| F4-08 | Simulasi gagal di tengah dan rollback penuh | Belum | |
| F5-01 | Audit mencatat mode, item, qty, HPP, user, timestamp | Belum | |
| F5-02 | Audit immutable dari aplikasi | Belum | |
| F5-03 | Retensi audit minimal 5 tahun | Belum | |
| F5-04 | Error log mencatat `transaksi_id`, mode, fase, file, line, timestamp, stack trace | Belum | |
| F5-05 | Change management evidence | Belum | |
| F5-06 | Risk register konversi | Belum | |
| F5-07 | Rekonsiliasi inventory adjustment account | Belum | |
| F5-08 | CAPA log dan incident response evidence | Belum | |
| F6-01 | UAT M1 Varian ke Varian happy path | Belum | |
| F6-02 | UAT M2 Non-Varian ke Varian happy path | Belum | |
| F6-03 | UAT M3 Varian ke Non-Varian happy path | Belum | |
| F6-04 | UAT M4 Non-Varian ke Non-Varian tidak regress | Belum | |
| F6-05 | UAT insufficient stock diblokir | Belum | |
| F6-06 | UAT over-allocation diblokir | Belum | |
| F6-07 | UAT under-allocation diblokir | Belum | |
| F6-08 | UAT financial mismatch diblokir | Belum | |
| F6-09 | UAT wrong variant-parent mapping diblokir | Belum | |
| F6-10 | UAT self-conversion diblokir | Belum | |
| F6-11 | UAT rollback saat gagal di tengah | Belum | |
| F6-12 | UAT concurrency 2 user tidak double movement | Belum | |
| F6-13 | UAT performa approve 50 detail kurang dari 10 detik | Belum | |
| F6-14 | UAT responsif PC 1024x768 dan tablet 800x1280 | Belum | |

Ringkasan kuantitatif: total item 59, dengan 7 `Selesai`, 1 `Sedang`, 2 `Blocked`, 49 `Belum`.

### 9.2 Larangan Teknis

Sepuluh larangan dengan status seragam `Belum diverifikasi`:

| ID | Larangan |
|---|---|
| L-01 | Dilarang hard delete transaksi atau audit konversi |
| L-02 | Dilarang update atau insert stok manual tanpa transaksi operasional |
| L-03 | Dilarang commit per fase |
| L-04 | Dilarang memakai FLOAT untuk qty, harga, HPP, dan total nilai |
| L-05 | Dilarang approve source dan target identik |
| L-06 | Dilarang bypass mapping `variant_id` ke `parent_produk_id` |
| L-07 | Dilarang konversi tanpa audit trail |
| L-08 | Dilarang membiarkan hold source menggantung |
| L-09 | Dilarang request dan approve oleh user yang sama pada transaksi yang sama |
| L-10 | Dilarang menebak alokasi varian otomatis tanpa rule config tertulis |

### 9.3 Evidence Minimum

Sepuluh file evidence di `docs/evidence/konversi/`, seluruhnya berstatus `Belum`:

`fs-02_m1_m2_m3_m4_qty_balance_<tanggal>.md`, `fvc-01_hpp_balance_<tanggal>.md`, `rl-03_atomic_rollback_<tanggal>.md`, `pst-06_hold_release_<tanggal>.md`, `sod-01_request_approve_separation_<tanggal>.md`, `cmp-01_audit_immutable_<tanggal>.md`, `pe-01_performance_50_detail_<tanggal>.md`, `mt-02_error_logging_recovery_<tanggal>.md`, `lc-01_risk_register_<tanggal>.md`, `lc-03_inventory_adjustment_reconciliation_<tanggal>.md`.

### 9.4 KPI Performa Adopted

| KPI | Target |
|---|---|
| Load daftar source/target varian | kurang dari 3 detik |
| Approve konversi 50 detail | kurang dari 10 detik |
| Rollback konversi | kurang dari 5 detik |
| Memory proses PHP-FPM | maksimal 256 MB |
| Selisih stok akibat konversi | 0 kejadian per bulan |
| SoD violation | 0 kejadian per bulan |
| Konversi tanpa audit trail | 0 kejadian per bulan |
| Rollback rate | maksimal 5 persen dari total konversi |

Catatan: tabel kesesuaian pada section 15 blueprint upgrade menyebut target load varian kurang dari 2 detik, sedangkan tabel KPI adopted pada section 16.3 menyebut kurang dari 3 detik. Ini adalah kontradiksi numerik yang harus diputuskan.

### 9.5 UAT Checklist Manual

`UAT_Checklist.md` memuat UAT manual terhadap web `\\192.168.5.14\web\san_staging` dengan modul `konversi` dan jenis transaksi `1334` dan `334`. Seluruh kotak centang masih kosong, sehingga belum ada bukti eksekusi.

Struktur cakupan:

| TC | Judul | Cakupan |
|---|---|---|
| TC-1 | Flow Non-Varian, regression M4 existing | Create `1334` 6 langkah, create `334`, follow-up 4 langkah, reject |
| TC-2 | Flow Varian, new feature | Create `1334` varian 9 langkah, save 10 pemeriksaan DB, follow-up 3 langkah, reject 3 langkah |
| TC-3 | Edge Cases | Balance validation, mixed varian dan non-varian, back navigation |
| TC-4 | Data Integrity | DB check non-varian 4 baris, DB check varian 3 baris |

Ringkasan area yang harus diisi tester: Non-Varian Regression, Varian Flow, Edge Cases, Data Integrity, masing-masing dengan pilihan Pass atau Fail, disertai baris kosong untuk Tester dan Date.

Tabel dan kolom yang diperiksa pada TC-2.2 dan TC-4:

| Tabel | Check |
|---|---|
| `transaksi_data` | `produk_jenis = 'produk_source'` dan `produk_jenis = 'produk_target'` |
| `fifo_produk_jadi` | FIFO source release non-varian dan FIFO target parent |
| `fifo_produk_jadi_varian` | FIFO varian terisi per `variant_id` |
| `stock_locker` | Locker source hold release dan locker target parent active |
| `stock_locker_variant` | Entries sesuai `variant_id` dengan state active, dan mutasi varian tercatat |

Pola pada check M4 non-varian: `transaksi_data` dengan `produk_jenis = 'produk_source'` harus punya `variant_id` bernilai 0 atau null; `stock_locker` dan `fifo_produk_jadi` tidak boleh berisi data varian.

### 9.6 Release Checklist Konversi

Lima belas item release gate dari section 16.2, ditolak jika salah satu belum lulus:

1. M1 Varian ke Varian lulus happy path, rollback, insufficient stock.
2. M2 Non-Varian ke Varian lulus qty balance dan HPP balance.
3. M3 Varian ke Non-Varian lulus qty balance dan HPP balance.
4. M4 Non-Varian ke Non-Varian tidak regress dari flow native existing.
5. Source stock real-time dibaca dari `stock_locker` atau `stock_locker_variant` sesuai `item_type`.
6. Source hold atau lock dibuat dan release saat remove, cancel, rollback, timeout.
7. `conversion_mode`, `item_type`, `produk_id`, `variant_id`, qty, HPP, user request, user approve, dan timestamp server tercatat di audit.
8. Audit log tidak bisa diedit atau dihapus dari aplikasi.
9. `requestor != approver` dan `requestor != rollback_user`.
10. Total qty source sama dengan total qty target.
11. Total nilai source sama dengan total nilai target.
12. Tidak ada penggunaan FLOAT untuk qty, nilai, atau HPP.
13. Semua query baru memakai Query Builder atau binding.
14. Error logging mencatat fase gagal dan `transaksi_id`.
15. Evidence UAT dan compliance tersimpan di path standar.

Acceptance criteria per mode M1 sampai M4, minimal tujuh: happy path, insufficient stock diblokir, over-allocation diblokir, under-allocation diblokir, rollback saat simulasi gagal di tengah, concurrency dua user tidak menimbulkan double movement, jurnal dan stok akhir balance.

---

## 10. Temuan Lintas-Dokumen dan Kontradiksi

### 10.1 Kontradiksi Arsitektur Pipeline

| Aspek | `blueprint-konverter-multi-variant.md` | `_tmp_blueprint.md` |
|---|---|---|
| Pipeline | Hanya `rsltItems2`, hapus `rsltItems` | Hanya `rsltItems`, tidak butuh `rsltItems2` |
| `stock_locker` | Dihapus, data dimigrasi ke `stock_locker_variant` dengan `variant_id = -1` | Tetap aktif untuk laporan agregat dan 36 modul |
| Fase cleanup | Ada, Fase 4 hapus `stock_locker` dan `stock_locker_mutasi` | Tidak ada fase cleanup, dual-write permanen |
| Letak normalizer | `Modul_Controller::__construct()` | `MdlMother::__construct()` otomatis untuk session `_TR_*` |
| Cakupan | Modul `konversi` saja, lalu rollout bertahap | 19 modul inventory dengan 6 agent paralel |
| Estimasi | 8 sampai 12 minggu, 100+ file | 4 sampai 6 minggu |

Kedua dokumen memakai prinsip dan sentinel yang sama, tetapi pilihan pipeline, tabel, dan tempat normalizer saling bertentangan. Sumber tidak menjelaskan mana yang menggantikan mana, sehinggastatus dokumen tidak dapat dipastikan tanpa klaransi.

### 10.2 Kontradiksi Format Session Key

Tiga pola key coexist dalam sumber:

1. Non-varian tetap key numerik native dan varian memakai `variant:{id_master}:{id_varian}`, dipakai oleh `WORKFLOW_MODUL_KONVERSI.md` section 5 dan blueprint UAT fix section 5.2.
2. Semua item memakai `variant:{pid}:{vid}` dengan non-varian menjadi `variant:1743:-1`, dipakai oleh kedua blueprint konverter multi-variant.
3. Supplies memakai `supplies:{supplies_id}:{variant_id}` dengan fallback `variant_id = 1` untuk non-varian, dipakai oleh blueprint varian supplies.

Ketiganya belum disatukan. Selain itu normalizer multi-variant mengubah key numerik menjadi `variant:pid:-1`, sedangkan aturan source-first dari blueprint UAT fix melarang key non-varian berubah.

### 10.3 Kontradiksi Sentinel Varian Default

Nilai sentinel tidak konsisten: `variant_id = -1` dipakai sebagai varian default implisit pada kedua blueprint konverter, `variant_id = 0` dipakai sebagai penanda non-varian pada blueprint upgrade dan UAT fix, dan `variant_id = 1` dipakai sebagai fallback non-varian untuk supplies. Tiga nilai untuk satu konsep yang sama.

### 10.4 Kontradiksi Enum `item_type`

Resolver mode di `Modul_Controller.php:109` membaca nilai `variant`, sedangkan gate builder mengisi `varian` di `_processSelectProductConvertion.php:32` dan `:54`. Dampaknya `conversion_mode` berpotensi jatuh ke M4 meskipun baris item varian. Blueprint UAT fix mewajibkan penyamaan enum ke `variant` dengan normalizer untuk kompatibilitas input `varian`.

### 10.5 Kontradiksi Sumber vs Target Stok sebagai Batas

Blueprint upgrade section 6.2 rule 5 dan section 9 poin 5 menegaskan target stock tidak dipakai sebagai batas penambahan. Namun tempelan yang lebih lama masih mendeskripsikan approach yang lebih longgar. Sumber tidak menandai mana yang menggantikan, kecuali blueprint UAT fix yang menegaskan ulang dengan prinsip soft lock hanya untuk source.

### 10.6 Kontradiksi Numerik KPI

Section 15 tabel kesesuaian menyebut `load varian <2 detik`, sedangkan section 16.3 KPI adopted menyebut `Load daftar source/target varian < 3 detik`. Section 15 juga menyebut approve 50 baris `<10 detik` yang konsisten dengan 16.3.

### 10.7 Kontradiksi Workspace

Tiga workspace berbeda disebut pada dokumen yang sama: `w:/san_staging/application/modules/konversi`, `w:/new_san_variant`, dan `c:/xampp/htdocs/new_san_variant`. Selain itu environment UAT adalah `\\192.168.5.14\web\san_staging`. Setiap instruksi harusQualified terhadap workspace asal.

### 10.8 Kontradiksi Delegasi ke `variant_cutover`

Blueprint upgrade menyatakan delegasi ke `variant_cutover` dihapus dari rekomendasi, dan `variant_cutover` hanya referensi pola. Namun `blueprint_konversi_varian.md` justru membangun modul `konversi_varian` dengan dual-write lock dan jurnal sendiri, dan `_tmp_blueprint.md` memasukkan `konversi_varian` sebagai bagian dari rollout 19 modul. Posisi modul ini belum final.

### 10.9 Ketidakjelasan_Rule Zero Stock

`sap_variant_conversion_rules.md` mewajibkan saldo stok fisik nol sebelum switching non-varian ke varian. Tidak ada satu pun dari blueprint upgrade, checklist, maupun 15 skenario yang memuat validasi zero stock ini. Checklist validator hanya memuat total qty, total nilai, real-time stock, qty positif, self-conversion, parent map, satu gudang, SoD, dan rollback user. Ini gap cakupan yang nyata.

### 10.10 Data Loss pada S13 dan S14

Dua skenario pada dokumen verifikasi berstatus data loss. Sumber menandainya pre-existing dan jarang terjadi karena `_shoppingCart.php` baris 55 selalu set integer, tetapi tidak ada item checklist maupun UAT case yang menutup kedua skenario tersebut.

### 10.11 Dampak Komponen NO-OP

Seluruh komponen LockerStock pada `items` gate postProcessor adalah NO-OP karena field name mismatch pada `coTransaksiCore.php` baris 174, 205, 586, 613, 640. Konsekuensinya, arsitektur konverter multi-variant yang mengandalkan `postProcessor` untuk mutasi stok akan gagal menulis. Locker hanya terupdate di shopping cart saat select dan reset. Tidak ada checklist item yang menutup perbaikan ini; F0-02 dan F0-03 masih `Blocked`.

### 10.12 Estimasi Tidak Konsisten

Estimasi 8 sampai 12 minggu dan sekitar 763 baris dihapus pada versi `san_staging`, sedangkan 4 sampai 6 minggu dengan 6 agent pada versi `new_san_variant` yang justru tidak menghapus kode. Perbedaan ini konsekuensi langsung dari kontradiksi arsitektur pada 10.1.

### 10.13 Stok Varian Supplies Belum Terdbc

`blueprint-varians-supplies-dan-produksi-bom.md` merancang sentinel `variant_id = 1` untuk supplies non-varian dan tabel `stock_locker_supplies_variant` untuk opname. Belum ada blueprint konversi yang mengintegrasikan aturan ini ke gate `konversi` untuk jenis transaksi `881` dan `7881` secara eksplisit di luar `konversi_varian`.

### 10.14 BOM Produksi Belum Terhubung ke Konversi

Skema `produksi_bom` dan `produksi_bom_detail` dengan pattern Inherit-or-Override dan resolution order dua langkah (`variant_id` spesifik lebih dulu, lalu `variant_id = 0` global) dirancang untuk produksi, bukan konversi._relation antara komposisi BOM dan hasil konversi tidak dispesifikasikan di sumber.

---

## 11. Lampiran: Daftar File Sumber

| Nama File | Ukuran | Topik H1 | Peran dalam sintesis |
|---|---|---|---|
| `blueprint_konversi_stok.md` | 5.692 byte, 121 baris | AGENTIC BLUEPRINT: MODUL KONVERSI STOK (CI3 HMVC - INTEGRASI MODEL BASE ERP) | Sumber aturan model base `MdlTransaksi`/`MdlTransaksiData`, pola double-entry `KONVERSI_STOK`, dan business controls SoD-01, INV-01, L-04. Dasar section 3 dan 4.1 sampai 4.3 |
| `blueprint_konversi_varian.md` | 5.435 byte, 110 baris | BLUEPRINT CETAK BIRU MODUL: KONVERSI VARIAN PRODUK & SUPPLIES | Sumber jenisTr `881` dan `7881`, dual-write locker `ComLockerStockDualWrite` dan `ComLockerStockSuppliesDualWrite`, jurnal `ComJurnal`, dan struktur controller `konversi_varian`. Dasar section 3.3 |
| `blueprint-konverter-multi-variant.md` | 18.793 byte, 530 baris | BLUEPRINT: KONVERTER MULTI-VARIANT - SINGLE STANDARD VARIANT ARCHITECTURE | Sumber arsitektur target single standard variant pada `san_staging`, sentinel `-1`, session key seragam, view `stock_unified`, estimasi 763 baris dihapus, rollback plan, dan T1-T5. Dasar section 5.3 dan 5.5 |
| `blueprint-upgrade-modul-konversi-support-varian.md` | 31.264 byte, 683 baris | BLUEPRINT UPGRADE MODUL `konversi` MENJADI SUPPORT PRODUK VARIAN | Sumber utama empat mode M1-M4, kontrak session, kontrak validasi dan posting, flag, guardrails, aturan satuan dan HPP, matriks kesesuaian ISO 25010, KPI, release checklist, dan 10 item larangan. Dasar section 6 dan 9.4 sampai 9.6 |
| `blueprint-uat-fix-konversi-selector-shoppingcart-varian.md` | 22.936 byte, 457 baris | BLUEPRINT UAT FIX `konversi`: Selector + ShoppingCart Support Varian | Sumber tujuh gap UAT dengan bukti baris, kontrak identity item, kontrak render source-first, kontrak routing postProcessor per row, 10 rencana perubahan file, dan 14 parameter pembuktian. Dasar section 7 |
| `checklist-upgrade-modul-konversi-support-varian.md` | 11.931 byte, 216 baris | CHECKLIST PLAN UPGRADE MODUL `konversi` SUPPORT PRODUK VARIAN | Sumber status implementasi 59 item checklist per fase 0 sampai 6, 10 larangan teknis, dan 10 evidence minimum. Dasar section 9.1 sampai 9.3 |
| `15-skenario-verifikasi-konversi-items-gate.md` | 13.441 byte, 329 baris | Verifikasi 15 Skenario - PostProcessor Items Gate (Konversi Varian) | Sumber 15 skenario trace lengkap, mutual exclusion lima Com classes dengan file:line, pre-existing bug nama field `qty`/`jml` dan `name`/`nama`, serta temuan `variantMutationCom` null. Dasar section 4.7, 7.5, dan 8 |
| `WORKFLOW_MODUL_KONVERSI.md` | 3.246 byte, 111 baris | WORKFLOW MODUL KONVERSI | Sumber workflow 2 step dengan target dokumen `1334r`/`1334`/`334r`/`334`, kontrak session cart, pola identity item, flow selector ke shopping cart, pairing target, dan aturan UI. Dasar section 3.2 dan 7.6 |
| `sap_variant_conversion_rules.md` | 5.292 byte, 71 baris | PANDUAN REVIU KODE & LOGIKA BISNIS: KONVERSI STOK VARIAN (ERP STANDARD) | Sumber rule zero stock, open document integrity, financial balancing, tiga fase transaksi dengan Movement Type 561/562/701/702, dan tiga instruksi review kode AI Agent. Dasar section 4.4 |
| `_tmp_blueprint.md` | 12.864 byte, 326 baris | BLUEPRINT: KONVERTER MULTI-VARIANT - SINGLE STANDARD VARIANT ARCHITECTURE | Sumber alternatif dual-write permanen pada `new_san_variant` dengan satu pipeline `rsltItems`, normalizer di `MdlMother::__construct()`, atomicity enam komponen, reconciliation cron, dan rollout 19 modul dengan 6 agent. Dasar section 5.4 dan 10.1 |
| `UAT_Checklist.md` | 6.023 byte, 139 baris | UAT Checklist - Modul Konversi Varian Produk | Sumber UAT manual terhadap `\\192.168.5.14\web\san_staging` dengan TC-1 sampai TC-4, tabel `transaksi_data`, `fifo_produk_jadi`, `fifo_produk_jadi_varian`, `stock_locker`, dan `stock_locker_variant`. Dasar section 9.5 |
| `blueprint-varians-supplies-dan-produksi-bom.md` | 6.594 byte, 121 baris | Blueprint & Design Arsitektur: Penyetaraan Varian Supplies & Produksi Bervarian (Multi-Variant BOM) | Sumber session key `supplies:{id}:{variant_id}` dengan fallback `variant_id = 1`, pattern Inherit-or-Override untuk BOM, skema `produksi_bom` dan `produksi_bom_detail`, serta resolution order dua langkah. Dasar section 10.13 dan 10.14 |

Jumlah file sumber yang dibaca: 12 dari 12. Tidak ada file yang dilewati.

---

## Catatan Penutup Syntheses

Belum ada satu pun dari 59 item checklist berstatusROLLOUT lengkap; 7 `Selesai`, 1 `Sedang`, 2 `Blocked`, 49 `Belum`. Semua 15 skenario verifikasi pada gate `items` berstatus Lulus kecuali S13 dan S14 yang berstatus data loss. Checklist UAT manual seluruhnya belum diisi centang. Artefak wajib berikutnya: memperbaiki field name mismatch pada `coTransaksiCore.php`, menyelesaikan `Blocked` F0-02 dan F0-03,oustsheet menambah validasi zero stock dari panduan SAP ke validator approve, dan memutuskan kontradiksi arsitektur pipeline dan sentinel antara `san_staging` dan `new_san_variant`.
