# 📐 Rencana Kerja Detil & Spesifikasi Skema: 360-Degree Traceability System

Dokumen ini berisi **Spesifikasi Teknis Skema Database (Tabel, Kolom, Indeks, dan Counter)** serta rencana kerja terstruktur untuk mentransformasi sistem ERP CodeIgniter 3 HMVC menjadi **Full 360-Degree Traceable System**.

---

## User Review Required

> [!IMPORTANT]
> **Spesifikasi Database & DDL (Data Definition Language)**:
> Dokumentasi ini mendefinisikan secara rinci 3 area perubahan database:
> 1. **Tabel Audit Terpusat Baru**: `traceability_lineage_log`
> 2. **Kolom Mandatory Baru di Seluruh Tabel Transaksi Utama**: `counter_tr`, `parent_tr_id`, `parent_item_id`, `batch_number`, `source_grn_id`.
> 3. **Indeks Komposit**: Memastikan kueri penelusuran rekursif berjalan cepat (< 50ms) tanpa terjadi *full table scan*.

> [!WARNING]
> **PHP 5.6 Compatibility**:
> Semua struktur data array yang dikirim antar-komponen wajib menggunakan sintaks PHP 5.6 (menggunakan `array()`, penanganan `isset()`, tanpa *short array* `[]`, tanpa *null coalescing* `??`).

---

## 🗄️ Spesifikasi Skema Database Lengkap

### 1. Tabel Terpusat Baru: `traceability_lineage_log`
Tabel *append-only* terpusat yang merekam silsilah rantai dokumen & barang 360 derajat.

```sql
CREATE TABLE IF NOT EXISTS `traceability_lineage_log` (
  `id` BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
  `cabang_id` INT(11) NOT NULL COMMENT 'Context Scoping Cabang',
  `gudang_id` INT(11) DEFAULT NULL COMMENT 'Context Scoping Gudang',
  `jenis_tr` VARCHAR(64) NOT NULL COMMENT 'Jenis Transaksi (misal: PENJUALAN, PEMBELIAN, KONVERSI, DISTRIBUSIFG)',
  `tr_id` BIGINT(20) UNSIGNED NOT NULL COMMENT 'ID Transaksi Utama',
  `tr_no` VARCHAR(64) DEFAULT NULL COMMENT 'Nomor Dokumen (SO/DO/Faktur/GRN/PO)',
  `counter_tr` INT(11) NOT NULL COMMENT 'Nomor urut linier per cabang & jenis_tr',
  `parent_jenis_tr` VARCHAR(64) DEFAULT NULL COMMENT 'Jenis Transaksi Induk (misal: DELIVERY_ORDER)',
  `parent_tr_id` BIGINT(20) UNSIGNED DEFAULT NULL COMMENT 'ID Transaksi Induk',
  `parent_tr_no` VARCHAR(64) DEFAULT NULL COMMENT 'Nomor Dokumen Induk',
  `produk_id` INT(11) DEFAULT NULL COMMENT 'ID Produk (jika tingkat item)',
  `batch_number` VARCHAR(128) DEFAULT NULL COMMENT 'Kode Lot / Batch / Serial Number',
  `source_grn_id` BIGINT(20) UNSIGNED DEFAULT NULL COMMENT 'ID Penerimaan asal dari Supplier (Inbound Anchor)',
  `oleh_id` INT(11) NOT NULL COMMENT 'ID User pembuat / penyetuju',
  `oleh_nama` VARCHAR(128) DEFAULT NULL COMMENT 'Nama User pembuat',
  `dtime` DATETIME NOT NULL COMMENT 'Stempel waktu eksekusi',
  PRIMARY KEY (`id`),
  KEY `idx_cabang_tr` (`cabang_id`, `jenis_tr`, `tr_id`),
  KEY `idx_parent_tr` (`parent_jenis_tr`, `parent_tr_id`),
  KEY `idx_batch_number` (`batch_number`),
  KEY `idx_source_grn` (`source_grn_id`),
  KEY `idx_counter_seq` (`cabang_id`, `jenis_tr`, `counter_tr`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
```

---

### 2. Kolom Tambahan Mandatory pada Tabel Transaksi Utama

Setiap tabel transaksi utama (seperti `transaksi`, `penjualan`, `pembelian`, `penerimaan`, `distribusifg`, `konversi`) wajib memiliki 5 kolom standar berikut:

| Nama Kolom | Tipe Data | Keterangan & Fungsi |
| :--- | :--- | :--- |
| **`counter_tr`** | `INT(11) NOT NULL DEFAULT 0` | Nomor urut linier eksekusi transaksi per `cabang_id` & `jenis_tr`. |
| **`parent_tr_id`** | `BIGINT(20) UNSIGNED DEFAULT NULL` | ID transaksi induk referensi penarik. |
| **`parent_item_id`** | `BIGINT(20) UNSIGNED DEFAULT NULL` | ID baris item transaksi induk referensi. |
| **`batch_number`** | `VARCHAR(128) DEFAULT NULL` | Kode Lot / Batch / Serial Number barang. |
| **`source_grn_id`** | `BIGINT(20) UNSIGNED DEFAULT NULL` | Pointer langsung ke Penerimaan Supplier asal (*Inbound Link*). |

---

### 3. Penyesuaian Tabel Counter (`counters_number` / `counters_custom_number`)

Pemasangan indeks komposit untuk menjamin pembuatan `counter_tr` bersifat *atomic* (*row locking*) tanpa risiko bentrok:

```sql
-- Memastikan Indeks Komposit Terpasang di Tabel Counter
ALTER TABLE `counters_number` 
ADD INDEX IF NOT EXISTS `idx_counter_atomic` (`cabang_id`, `jenis_tr`, `dtime`);
```

---

## 🧱 Proposed Architectural Patterns (Reusable Core)

```
┌─────────────────────────────────────────────────────────────────────────┐
│                           71+ MODUL HMVC                                │
│ (penjualan, pembelian, penerimaan, konversi, distribusifg, pindahgudang)│
└────────────────────────────────────┬────────────────────────────────────┘
                                     │ (Menggunakan)
                                     ▼
┌─────────────────────────────────────────────────────────────────────────┐
│               REUSABLE HELPER (he_traceability_helper.php)               │
│ - he_get_counter_sequence($cabangId, $jenisTr, $dtime)                  │
│ - he_build_lineage_payload($trJenis, $trId, $parentId, $batchId, ...)    │
└────────────────────────────────────┬────────────────────────────────────┘
                                     │ (Mendeplegasikan ke)
                                     ▼
┌─────────────────────────────────────────────────────────────────────────┐
│            CENTRALIZED ENGINE (ComTraceabilityEngine.php)               │
│ - registerLineageRecord($payload)                                       │
│ - getBackwardLineage($jenisTr, $trId)                                   │
│ - getForwardLineage($jenisTr, $trId)                                    │
│ - getBatchGenealogy($batchNumber)                                       │
└─────────────────────────────────────────────────────────────────────────┘
```

---

## Proposed Changes per Component

### Component 1: Reusable Core & Helper Foundation (Gelombang 1)

#### [NEW] [he_traceability_helper.php](file:///z:/everest_13agus/application/helpers/he_traceability_helper.php)
- Helper terpusat yang menyediakan fungsi:
  - `he_get_next_counter_sequence($cabang_id, $jenis_tr, $dtime)`: Wrapper *atomic* ke `CustomCounter` untuk mengunci nomor urut linier `counter_tr`.
  - `he_build_lineage_payload(...)`: Membentuk array payload standar PHP 5.6.

#### [NEW] [ComTraceabilityEngine.php](file:///z:/everest_13agus/application/models/Coms/ComTraceabilityEngine.php)
- Model Engine Terpusat di `application/models/Coms/` yang mengelola kueri penelusuran 360 derajat dan penulisan ke tabel `traceability_lineage_log`.

#### [MODIFY] [CustomCounter.php](file:///z:/everest_13agus/application/models/CustomCounter.php)
- Menambahkan metode `generateScopedCounter($cabang_id, $jenis_tr, $dtime)` dengan mekanisme *row locking* (`FOR UPDATE`).

#### [MODIFY] [audit multi cabang.txt](file:///z:/everest_13agus/audit%20multi%20cabang.txt)
- Memperbarui dokumen audit dengan memasukkan Poin 6 mengenai kewajiban `counter_tr`.

---

### Component 2: Inbound Supply Chain Modules (Gelombang 2)
- Modul: `pembelian`, `penerimaan`, `penerimaanprojek`.
- Pengisian `source_grn_id`, `batch_number`, dan `counter_tr` saat barang diterima dari Supplier.

### Component 3: Production & Inventory Transformation Modules (Gelombang 3)
- Modul: `konversi`, `inputstok`, `pindahgudang`.
- Model: [ComManufacturIdentity.php](file:///z:/everest_13agus/application/models/Coms/ComManufacturIdentity.php) & [ComFifoBahan.php](file:///z:/everest_13agus/application/models/Coms/ComFifoBahan.php).
- Menghubungkan pemakaian bahan baku dengan batch hasil manufaktur.

### Component 4: Outbound Supply Chain & Sales Modules (Gelombang 4)
- Modul: `penjualan`, `distribusifg`, `invoicing`.
- Model: [ComFifoProdukJadi.php](file:///z:/everest_13agus/application/models/Coms/ComFifoProdukJadi.php).
- Menghubungkan penjualan ke pengeluaran DO, SO, dan batch asal.

### Component 5: Reusable GUI Traceability Explorer (Gelombang 5)
- [NEW] [Traceability.php](file:///z:/everest_13agus/application/modules/laporan/controllers/Traceability.php)
- [NEW] [traceability_explorer.php](file:///z:/everest_13agus/application/modules/laporan/views/traceability_explorer.php)

---

## Implementation Roadmap (Tahapan Gelombang)

| Gelombang | Target Modul / Komponen | Target Hasil | Estimasi Waktu |
| :--- | :--- | :--- | :--- |
| **Gelombang 1** | Reusable Core (`he_traceability_helper`, `ComTraceabilityEngine`, DDL `traceability_lineage_log`) | Tabel log & helper terpasang | 1,5 Minggu |
| **Gelombang 2** | Inbound (`pembelian`, `penerimaan`, `penerimaanprojek`) | Batch penerimaan tercatat dengan counter | 1 Minggu |
| **Gelombang 3** | Transformasi (`konversi`, `inputstok`, `pindahgudang`) | Silsilah pemakaian bahan ke produk jadi terhubung | 1,5 Minggu |
| **Gelombang 4** | Outbound (`penjualan`, `distribusifg`, `invoicing`) | Sales & Invoice terhubung penuh ke Batch & DO | 1,5 Minggu |
| **Gelombang 5** | Reusable UI Explorer (`laporan/Traceability`) | Visualisasi Graph 360 Derajat siap dipakai | 1 Minggu |

---

## Verification Plan

### Automated Tests
- Menjalankan script pengujian `scratch/test_traceability_engine.php` untuk memvalidasi performa kueri DDL `traceability_lineage_log` agar respon penelusuran rekursif < 50ms.

### Manual Verification
1. **Pengujian DDL & Indeks:** Memastikan `SHOW CREATE TABLE traceability_lineage_log` menunjukkan indeks komposit terpasang dengan benar.
2. **Pengujian Linieritas Counter:** Memastikan `counter_tr` bertambah secara presisi per cabang tanpa nomor melompat (*no gap leakage*).