# Panduan Baku Refaktor Migrasi JSON Data Registry (Acuan Antar Modul)

Dokumen ini adalah acuan standar dan *cheat sheet* resmi untuk melakukan refaktor migrasi dari metode **Blob Registry legacy** (`transaksi_data_registry`) ke **JSON Data Registry** (`transaksi_data_json`) pada seluruh modul aplikasi (misalnya: `penjualan`, `pembelianservice`, `gudang`, `pembayaran`, `penerimaan`, dll).

---

## 1. Arsitektur Data & Tabel Database

- **Tabel Detail Registry Legacy**: `transaksi_data_registry` (`dataRegistry`) $\rightarrow$ Menggunakan format Blob (`serialize` / `base64_encode`).
- **Tabel Baru JSON Data Registry**: `transaksi_data_json` (`dataJson`) $\rightarrow$ Menggunakan format JSON (`json_encode` / `json_decode`).
- **Tabel Header Registry (Tetap)**: `transaksi_registry` (`registry`) $\rightarrow$ Pembacaan melalui `lookupBaseRegistries()` atau `lookupRegistries()` tetap membaca tabel header ini dan **tidak diubah** ke JSON.

---

## 2. Pemetaan Method Model (`MdlTransaksi.php`)

Gunakan fungsi bayangan (*shadow methods*) khusus format JSON berikut saat melakukan refaktor pada *controller*:

| Kategori Operasi | Legacy Method | Shadow JSON Method | Tabel Target | Format Penyimpanan |
|---|---|---|---|---|
| **Write (Simpan Baru)** | `writeDataRegistries($id, $data)` | `writeDataRegistriesJson($id, $data)` | `transaksi_data_json` | `json_encode($val)` |
| **Update (Perbarui)** | `updateDataRegistry($where, $data)` | `updateDataRegistryJson($where, $data)` | `transaksi_data_json` | `json_encode($val)` |
| **Read by Master ID** | `lookupDataRegistriesByMasterID($id)` | `lookupDataRegistriesJsonByMasterID($id)` | `transaksi_data_json` | `json_decode($val, true)` |
| **Read dengan Filter** | `lookupDataRegistries()` | `lookupDataRegistriesJson()` | `transaksi_data_json` | `json_decode($val, true)` |
| **Read Joined Main** | `lookupDataRegistries_joined()` | `lookupDataRegistriesJson_joined()` | `transaksi` + `transaksi_data_json` | `json_decode($val, true)` |
| **Read Base Data** | `lookupBaseDataRegistries($ids)` | `lookupBaseDataRegistriesJson($ids)` | `transaksi_data_json` | `json_decode($val, true)` |
| **Read Main+Slave** | `lookupTransaksiDataRegistries($id)` | `lookupTransaksiDataRegistriesJson($id)` | `transaksi` + `transaksi_data_json` | `json_decode($val, true)` |

---

## 3. Aturan Penguraian Data (Decoding Rule)

1. **Penguraian Kolom Registri JSON**:
   Wajib menggunakan **`json_decode($val, true)`** dengan argumen kedua `true` agar menghasilkan *array* asosiatif multi-dimensi.
2. **Fungsi yang Digantikan**:
   - `blobDecode($val)` $\rightarrow$ `json_decode($val, true)`
   - `unserialize(base64_decode($val))` $\rightarrow$ `json_decode($val, true)`
3. **Pengecualian Atribut Non-Registri**:
   Kolom utama di tabel `transaksi` seperti `counters` atau `ids_his` tetap diurai dengan `blobDecode()` karena bukan merupakan bagian dari tabel `transaksi_data_json`.

---

## 4. Panduan Langkah Demi Langkah Refaktor Modul Lain

### Langkah 1: Refaktor Fungsi Penulisan & Pembaruan (Write & Update)
Cari di controller:
- Ubah `$tr->writeDataRegistries(...)` $\rightarrow$ `$tr->writeDataRegistriesJson(...)`
- Ubah `$tr->updateDataRegistry(...)` $\rightarrow$ `$tr->updateDataRegistryJson(...)`

### Langkah 2: Refaktor Fungsi Pembacaan Data (Read Operations)
Cari pemanggilan query registri:
- Ubah `$tr->lookupDataRegistriesByMasterID($id)` $\rightarrow$ `$tr->lookupDataRegistriesJsonByMasterID($id)`
- Ubah `$tr->lookupDataRegistries()` $\rightarrow$ `$tr->lookupDataRegistriesJson()`
- Ubah `$tr->lookupDataRegistries_joined()` $\rightarrow$ `$tr->lookupDataRegistriesJson_joined()`
- Ubah `$tr->lookupBaseDataRegistries($ids)` $\rightarrow$ `$tr->lookupBaseDataRegistriesJson($ids)`
- Ubah `$tr->getFields()["dataRegistry"]` $\rightarrow$ `$tr->getFields()["dataJson"]`

### Langkah 3: Refaktor Penguraian Variabel Registri (Parsing)
- Ubah `unserialize(base64_decode($row->$param))` $\rightarrow$ `json_decode($row->$param, true)`
- Ubah `blobDecode($row->$param)` $\rightarrow$ `json_decode($row->$param, true)`

---

## 5. Contoh Komparasi Kode (Sebelum vs Sesudah)

### Contoh A: Pembacaan Registri Berdasarkan Master ID (`Printing.php`, `_processSelectNotaItem.php`)

**SEBELUM (Legacy Blob):**
```php
$tmpReg = $tr->lookupDataRegistriesByMasterID($trID)->result();
$regFields = $tr->getFields()["dataRegistry"];

if (sizeof($tmpReg) > 0) {
    foreach ($tmpReg as $row) {
        foreach ($regFields as $param) {
            if (isset($row->$param)) {
                $masterTableInParams = unserialize(base64_decode($row->$param));
            }
        }
    }
}
```

**SESUDAH (JSON Registry):**
```php
$tmpReg = $tr->lookupDataRegistriesJsonByMasterID($trID)->result();
$mongoFields = $tr->getFields()["dataJson"];

if (sizeof($tmpReg) > 0) {
    foreach ($tmpReg as $row) {
        foreach ($mongoFields as $param) {
            if (isset($row->$param)) {
                $masterTableInParams = json_decode($row->$param, true);
            }
        }
    }
}
```

---

### Contoh B: Penulisan Registri Transaksi Baru (`Create.php`, `FollowUp.php`)

**SEBELUM (Legacy Blob):**
```php
$doWriteReg = $tr->writeDataRegistries($insertID, $baseRegistries);
```

**SESUDAH (JSON Registry):**
```php
$doWriteReg = $tr->writeDataRegistriesJson($insertID, $baseRegistries);
```

---

### Contoh C: Pembaruan Registri (`Create.php`)

**SEBELUM (Legacy Blob):**
```php
$doWriteReg = $tr->updateDataRegistry($where_registry, $baseRegistries);
```

**SESUDAH (JSON Registry):**
```php
$doWriteReg = $tr->updateDataRegistryJson($where_registry, $baseRegistries);
```