# Blueprint Baseline Modul `variant_cutover` (Holding)

## 1. Tujuan

Dokumen ini adalah baseline teknis dan bisnis untuk modul `application/modules/variant_cutover/*` pada workspace `san_staging`, sebagai dasar:

1. Stabilitas operasional modul cutover varian di holding.
2. Acuan porting ke ERP subsidiary yang beda versi.
3. Acuan gap analysis terhadap standar kualitas internal.

Dokumen acuan utama yang wajib dipakai bersama blueprint ini:

- `application/modules/variant_cutover/STANDAR_MODUL_VARIANT_CUTOVER_ISO25010.md`
- `application/modules/variant_cutover/sap_variant_conversion_rules.md`

## 2. Ruang Lingkup

### In Scope

1. Struktur konfigurasi transaksi 2 flow utama:
   - `881` (cabang)
   - `7881` (pusat)
2. Alur request, validasi, followup, dan rollback.
3. Integritas data session gate (`items`, `items2`, `items2_sum`) ke tabel transaksi.
4. Pemetaan kepatuhan terhadap standar ISO25010 internal.

### Out of Scope

1. Eksekusi perubahan kode di subsidiary.
2. Penyamaan skema database subsidiary (baru dikerjakan di fase porting).

## 3. Baseline Arsitektur Modul Saat Ini

### 3.1 Modul dan Konfigurasi Kunci

1. Konfigurasi UI flow berada di `coTransaksiUi.php`:
   - Flow `881` didefinisikan di `coTransaksiUi.php:5`.
   - Flow `7881` didefinisikan di `coTransaksiUi.php:375`.
   - Keduanya memakai `selectorProcessor => _processSelectProductConvertion/select` (`coTransaksiUi.php:80`, `coTransaksiUi.php:449`).
   - Keduanya memakai `editHandlerMethod2 => recordItemColumnVarian` (`coTransaksiUi.php:82`, `coTransaksiUi.php:452`).
2. Komponen core (pre/post/component) berada di `coTransaksiCore.php`.
3. Struktur layout receipt berada di `coTransaksiLayout.php`.
4. Modul controller inti:
   - `Create.php`
   - `Transaksi.php`
   - `FollowUp.php`
   - `_processSelectProductConvertion.php`
   - `_shoppingCart.php`
   - `Modul_Controller.php`

### 3.2 Model Eksekusi Konfigurasi

Model modul bersifat config-driven:

1. `coTransaksiUi` menentukan step, role, selector, dan UI gate.
2. `coTransaksiCore` menentukan:
   - `preProcessor`
   - `components`
   - `postProcessor`
   - mapping `tableIn*` ke tabel transaksi.
3. Session gate `$_SESSION[_TR_<jenisTr>]` dipakai sebagai sumber data lintas controller.

## 4. Alur Bisnis-Teknis End-to-End

### 4.1 Step Request (Create)

1. Entry transaksi ditulis saat create/save step awal di `Create.php`.
2. Untuk flow `7881`/`881`, status awal konversi di-set `DRAFT` via `setConversionStatus()`:
   - `Create.php:2044-2045`
   - helper di `Modul_Controller.php:90-104`

### 4.2 Pemilihan Produk Sumber dan Locker Hold

1. Pemilihan source product masuk lewat `_processSelectProductConvertion::select()`:
   - `_processSelectProductConvertion.php:27`
2. Locker check aktif via config:
   - `coTransaksiUi.php:49`
   - `coTransaksiUi.php:418`
3. Saat qty berubah, sistem menggeser `stock_locker` active <-> hold dengan transaksi DB lokal:
   - `_processSelectProductConvertion.php:187`
   - `_processSelectProductConvertion.php:228`
4. Data varian dimuat dan stok varian diambil dari `stock_locker_variant`:
   - `_processSelectProductConvertion.php:1156`
   - `_processSelectProductConvertion.php:1172`
   - `_processSelectProductConvertion.php:1181`

### 4.3 Alokasi Varian di Shopping Cart

1. Alokasi qty varian dilakukan di `recordItemColumnVarian()`:
   - `_shoppingCart.php:3373`
2. Guard utama:
   - total qty varian tidak boleh melebihi qty parent (`_shoppingCart.php:3416`).
3. Nilai `distribute` dan `sisa_distribute` parent direkalkulasi:
   - `_shoppingCart.php:3430-3437`
4. Gate `items2_sum` direbuild dari hasil alokasi:
   - `_shoppingCart.php:3441-3511`

### 4.4 Validasi Sebelum Tombol Hijau (Approve)

Semua validasi dilakukan di `Transaksi::validate()`:

1. Balance qty source vs target (khusus `7881`):
   - `Transaksi.php:663` (guard flow)
2. Open document validation (`7881` dan `881`):
   - `Transaksi.php:704-707`
   - query detail dokumen terbuka ada di blok `Transaksi.php:718+`
3. Parent stock zero validation (`7881` dan `881`):
   - `Transaksi.php:804-806`
   - override via `override_stok_parent`:
     - `Transaksi.php:834`
     - `Transaksi.php:859`
4. Status konversi ditampilkan pada history row:
   - `Transaksi.php:1528`
   - source status dari `transaksi_values` via `getConversionStatus()`.

### 4.5 Followup Eksekusi

1. Followup utama dijalankan di `FollowUp::doFollowup()`:
   - `FollowUp.php:4374`
2. Saat mulai, status diubah ke `IN_PROGRESS`:
   - `FollowUp.php:4429`
3. Konkurensi dijaga lewat mark-for-update:
   - `FollowUp.php:4422-4423` (`setCekPrevalue/getCekPrevalue`)
4. Eksekusi transaksi DB dibungkus:
   - `FollowUp.php:4729` (`trans_start`)
   - `FollowUp.php:9345` (`trans_complete`)
5. Saat sukses, status jadi `COMPLETED`:
   - `FollowUp.php:9569`
   - `FollowUp.php:9589`

### 4.6 Revert / Rollback

1. Revert 1 step:
   - `FollowUp::doRevert()` di `FollowUp.php:9601`
2. Revert all:
   - `FollowUp::doRevertAll()` di `FollowUp.php:15106`
3. Status diubah ke `ROLLED_BACK`:
   - `FollowUp.php:9612`
   - `FollowUp.php:15117`
4. Kedua flow memakai transaksi DB:
   - `FollowUp.php:9661` + `FollowUp.php:15033`
   - `FollowUp.php:15203` + `FollowUp.php:16550`

## 5. Pemetaan Komponen Stok dan Accounting

Pada `coTransaksiCore.php`, flow `7881/881` sudah memetakan komponen varian-aware:

1. `FifoProdukJadiVarian`:
   - `coTransaksiCore.php:651`
   - `coTransaksiCore.php:936`
   - `coTransaksiCore.php:1337`
2. `LockerStockVariant`:
   - `coTransaksiCore.php:678`
   - `coTransaksiCore.php:1363`
3. `LockerStockMutasiVariant`:
   - `coTransaksiCore.php:700`
   - `coTransaksiCore.php:1386`
4. Field `valid_qty` untuk gate detail target:
   - `coTransaksiCore.php:297`
   - `coTransaksiCore.php:309`
   - `coTransaksiCore.php:1046`
   - `coTransaksiCore.php:1058`

Makna bisnis:

1. Source product dikurangi dari locker source.
2. Target varian ditambah ke locker varian.
3. Mutasi stok dan nilai (hpp/hpp injector) diposting melalui komponen accounting.

## 6. Matriks Kepatuhan Terhadap STANDAR ISO25010 (Baseline Saat Ini)

Referensi standar:

- `STANDAR_MODUL_VARIANT_CUTOVER_ISO25010.md`:
  - `FS-02` di line `49`
  - `RL-03` di line `60`
  - `SoD-01` di line `144`
  - `CMP-01` di line `157`
  - `PST-01` di line `178`
  - `FVC-01` di line `194`
  - `ODC-01/ODC-02` di line `207/208`
  - `TPC-01/TPC-05` di line `222/226`
  - `COR-01/COR-05` di line `239/243`

| Kontrol | Baseline Saat Ini | Status |
|---|---|---|
| FS-02 (Q parent = sum Q varian) | Sudah ada guard di `Transaksi::validate()` (`Transaksi.php:663`) | Partial |
| RL-03 + TPC-01 (atomic tx) | `Create`/`FollowUp`/`Revert` memakai `trans_start` + `trans_complete` | Partial |
| PST-01 (parent stock zero) | Sudah ada blok validasi parent stock + pesan blokir | Partial |
| ODC-01/ODC-02 (open docs) | Sudah ada blok validasi open documents | Partial |
| TPC-05 (rollback penuh) | Ada flow `doRevert` dan `doRevertAll` | Partial |
| TPC-06 (status DRAFT..ROLLED_BACK) | Status sudah disimpan/ditampilkan | Partial |
| SoD-01 (inisiasi != approval) | Flow `881` beda role (`o_gudang` vs `o_gudang_spv`), flow `7881` masih sama-sama `c_gudang` | Gap |
| CMP-01 (audit immutable) | Ada activity log, tetapi status konversi disimpan dengan `REPLACE` ke `transaksi_values` (overwrite) | Gap |
| COR-05 (rollback formal + alasan + approval) | Revert tersedia, tetapi baseline belum mewajibkan alasan rollback + anti self-rollback di level gate ini | Gap |
| COR-01 (freeze transaksi) | Belum ditemukan freeze gate eksplisit di flow ini | Gap |
| FVC-01 (konsistensi nilai aset) | Komponen accounting/hpp sudah ada, tetapi belum ada guard eksplisit rekonsiliasi nilai sebelum commit | Partial |

## 7. Root Cause dan Risiko Teknis Utama (Untuk Porting)

1. Ketergantungan tinggi pada session gate (`items/items2/items2_sum`) lintas controller.
2. Konfigurasi besar dan kompleks pada `coTransaksiCore.php` + `coTransaksiValues.php`, dengan potensi drift antar file.
3. Beberapa query kritikal masih string-concatenation (belum query binding), termasuk blok validasi open docs di `Transaksi.php:718+`.
4. Status `FAILED` tersedia di enum (`Modul_Controller.php:92`) tetapi tidak terlihat di-set saat error path.
5. Flow `7881` belum memenuhi SoD ketat karena step 1 dan step 2 memakai group sama (`coTransaksiUi.php:385` dan `coTransaksiUi.php:395`).
6. `recordItemColumnVarian()` masih memiliki titik rawan maintainability pada rebuild payload `items2_sum` dan pemakaian variabel dinamis di blok map field (`_shoppingCart.php:3498`).

## 8. Opsi Solusi Blueprint untuk Tahap Porting Subsidiary

### Opsi A (Recommended): Compatibility Adapter Layer

1. Pertahankan blueprint logic holding sebagai canonical behavior.
2. Di subsidiary, buat adapter untuk:
   - mapping tabel/kolom
   - mapping komponen comName
   - mapping role/group approval
3. Tambahkan validation harness agar rule PST/ODC/TPC tetap identik.

Keuntungan:

1. Perubahan inti lebih kecil.
2. Drift antar versi lebih terkendali.

### Opsi B: Full Fork Module ke Subsidiary

1. Copy modul penuh, lalu refactor sesuai struktur subsidiary.

Risiko:

1. Maintenance cost tinggi.
2. Drift cepat antara holding vs subsidiary.

### Opsi C: Ekstrak Engine Cutover Menjadi Shared Service Internal

1. Pisahkan engine validasi + eksekusi stock/accounting dari UI controller.
2. Holding dan subsidiary memanggil engine yang sama dengan adapter tipis.

Risiko:

1. Effort awal lebih besar.
2. Butuh disiplin versioning.

## 9. Rencana Fase Berikutnya (Saat Workspace Subsidiary Sudah Tersedia)

1. Buat matrix perbandingan struktur:
   - controller chain
   - config keys (`coTransaksiUi/Core/Layout/Values`)
   - tabel stok/accounting
2. Tentukan mapping adapter:
   - role/group mapping
   - table/field mapping
   - component mapping (`Fifo*`, `Locker*`, `Jurnal*`, `Rekening*`)
3. Jalankan dry-run test pada 4 skenario minimum:
   - success path
   - open docs blocked
   - parent stock non-zero blocked
   - rollback path

## 10. Skenario Verifikasi Baseline (Manual Logic Test)

1. `Balance check`:
   - Parent qty 100, total varian 100 -> lolos.
   - Parent qty 100, total varian 99/101 -> diblokir.
2. `Open document`:
   - Produk parent masih punya dokumen valid_qty > 0 -> diblokir.
3. `Parent stock zero`:
   - Stok parent > 0, tanpa override -> diblokir.
   - Stok parent > 0, dengan override -> lolos gate ini (tetap cek gate lain).
4. `Followup status`:
   - Create -> DRAFT
   - Followup start -> IN_PROGRESS
   - Followup success -> COMPLETED
   - Revert -> ROLLED_BACK
5. `Concurrency`:
   - Jalankan followup paralel pada transaksi sama, pastikan transaksi kedua tertahan oleh lock/check.
6. `Rollback`:
   - Simulasikan gagal di tengah postProcessor, pastikan rollback dan tidak meninggalkan stok setengah pindah.

## 11. Kesimpulan Baseline

1. Modul `variant_cutover` sudah memiliki fondasi flow konversi, gate validasi utama, dan transaksional DB di proses kritikal.
2. Untuk kepatuhan penuh terhadap standar ISO25010 internal, gap terbesar saat ini ada di:
   - SoD flow `7881`
   - audit trail immutable
   - prosedur rollback formal
   - freeze transaksi
   - status FAILED path
3. Blueprint ini siap dipakai sebagai baseline sebelum masuk tahap mapping ke workspace subsidiary.