# 📋 BLUEPRINT ARSITEKTUR: INTEGRASI AUTOPURCHASE FG PROJECT KE `pembelianfgproject` (1466)

Dokumen ini merupakan cetak biru teknis (*technical blueprint*) khusus untuk fitur **Integrasi Autopurchase FG Project**, yaitu mekanisme penarikan barang dari wadah **`project_purchase_pool`** (hasil Kickoff di `master_project`) ke dalam alur transaksi penerbitan Purchase Order (PO) pada modul **`pembelianfgproject`** (Trjenis: `1466`).

---

## 1. Latar Belakang & Tujuan Arsitektur

1. **Pemisahan Peran (Separation of Concerns):**
   - Tim Estimator / PM di `master_project` hanya menentukan komposisi barang & jumlah kebutuhan teknis (tanpa menentukan supplier).
   - Tim Purchasing di `pembelianfgproject` berwenang penuh memilah supplier, menegosiasikan harga beli aktual, dan memecah pembelian ke beberapa vendor jika diperlukan.
2. **Eliminasi Pengetikan Manual (Zero Manual Input):**
   - Tim Purchasing tidak perlu mengetik ulang nama barang, kode, satuan, dan jumlah kebutuhan proyek. Cukup memilih project yang sedang aktif, lalu sistem akan memuat seluruh daftar barang kebutuhan dari `project_purchase_pool`.
3. **Pelacakan Siklus Pengadaan (Procurement Tracking & Fulfillment):**
   - Mengetahui status setiap item: apakah belum dipesan (`OPEN`), baru dipesan sebagian (`PARTIAL`), atau sudah tuntas dibuatkan PO (`CLOSED`).

---

## 2. Diagram Alur Transaksi (End-to-End Workflow)

```mermaid
flowchart TD
    A["Kickoff Project (master_project / 588)"] -->|"Insert Batch (status='OPEN')"| B[("Tabel: project_purchase_pool")]
    
    subgraph "Modul pembelianfgproject (1466) - Alur Autopurchase"
        C["User Buat Pre-PO (1466r)"] --> D["Buka Modal: 'Tarik Kebutuhan Project'"]
        B -.->|"Query item OPEN / PARTIAL"| D
        D --> E["Pilih Barang & Tentukan Qty Order"]
        E --> F["Pilih Supplier & Input Harga Beli Final"]
        F --> G["Masuk Shopping Cart (bind pool_id)"]
        G --> H["Simpan Draft Pre-PO (1466r)"]
        H --> I["Approval PO (1466)"]
    end

    I -->|"Update qty_po, qty_sisa, status"| B
    I --> J["Penerimaan Barang / GRN (1467)"]
    J --> K["Stok Masuk ke Gudang Project"]
```

---

## 3. Detail Komponen & Mekanisme Teknis

### A. Modal Selector: Tarik dari Pool PR Project (`_selectorProjectPool.php`)
Ketika tim Purchasing membuat transaksi Pre-PO (`1466r`), sistem menyediakan picker khusus untuk menarik data dari `project_purchase_pool`:
* **Filter Utama:**
  - Pilih Proyek (Dropdown Proyek dengan status aktif / kickoff).
  - Status Pool: `OPEN` atau `PARTIAL`.
* **Kolom Tabel Selector:**
  1. Nama Proyek & No. Kontrak
  2. Kode & Nama Barang FG
  3. Satuan
  4. Qty Kebutuhan Total
  5. Qty Sudah di-PO
  6. **Qty Sisa yang Belum di-PO** (`qty_sisa`)
  7. Estimasi HPP RAB
  8. *Aksi:* Tombol **"Pilih / Tambah ke PO"**

### B. Alokasi Parsial (Split Order ke Beberapa Vendor)
Jika suatu barang membutuhkan 10 Pcs:
* PO ke Supplier A: Beli 6 Pcs $\rightarrow$ `qty_po = 6`, `qty_sisa = 4`, `status = 'PARTIAL'`.
* PO ke Supplier B: Beli 4 Pcs $\rightarrow$ `qty_po = 10`, `qty_sisa = 0`, `status = 'CLOSED'`.

### C. Penyimpanan Metadata di Shopping Cart (`_TR_1466`)
Setiap baris item di dalam shopping cart (`$_SESSION['_TR_1466r']['items']`) akan mencatat referensi asal:
```php
$cartItem = array(
    "produk_id"                => $row->produk_id,
    "nama"                     => $row->produk_nama,
    "satuan"                   => $row->satuan_nama,
    "qty"                      => $qtyOrder,
    "harga"                    => $hargaBeliSupplier,
    "project_purchase_pool_id" => $row->id,          // Link ke pool
    "project_id"               => $row->project_id,  // Link ke project
    "project_nama"             => $row->project_nama,
);
```

---

## 4. Sinkronisasi Status Pool & Reversal Protection

### A. Saat Otorisasi / Pembuatan PO (`FollowUp.php:case 1` / `case 2` di `pembelianfgproject`)
Saat PO disahkan:
```php
foreach ($itemsPO as $item) {
    if (isset($item['project_purchase_pool_id']) && $item['project_purchase_pool_id'] > 0) {
        $poolID = $item['project_purchase_pool_id'];
        $qtyOrdered = (float)$item['qty'];

        $pool = $this->db->get_where("project_purchase_pool", array("id" => $poolID))->row();
        if (!empty($pool)) {
            $newQtyPo = (float)$pool->qty_po + $qtyOrdered;
            $newQtySisa = (float)$pool->qty_kebutuhan - $newQtyPo;
            $newStatus = ($newQtySisa <= 0) ? 'CLOSED' : 'PARTIAL';

            $this->db->where("id", $poolID);
            $this->db->update("project_purchase_pool", array(
                "qty_po"             => $newQtyPo,
                "qty_sisa"           => ($newQtySisa > 0 ? $newQtySisa : 0),
                "status"             => $newStatus,
                "last_updated_dtime" => date("Y-m-d H:i:s")
            ));
        }
    }
}
```

### B. Proteksi Pembatalan (PO Reject / Void)
Jika PO dibatalkan sebelum barang diterima (GRN):
- Sistem otomatis mengurangi kembali akumulasi `qty_po` dan mengembalikan `qty_sisa`.
- Status pool otomatis di-rollback dari `CLOSED` $\rightarrow$ `PARTIAL` atau `OPEN`.

---

---

## 5. Sinkronisasi HPP Balik & Audit Trail Perubahan Harga (`project_hpp_history`)

### A. Alur Pembaruan Nilai HPP Aktual
Saat Purchase Order (`1466`) disetujui (Approved) oleh Supervisor/Manager:
1. Harga beli satuan yang disepakati dengan Supplier (`harga_beli_supplier`) menjadi **HPP Aktual** untuk barang proyek tersebut.
2. Sistem secara otomatis memperbarui nilai HPP pada 2 tabel komposisi proyek terkait:
   - **`project_komposisi_workoder`** (Level Workorder / Ruangan / Fase): `hpp = $hargaBeliSupplier`, `subtotal_hpp = jml * $hargaBeliSupplier`.
   - **`project_komposisi`** (Level Master Komposisi Rekap Proyek): `hpp = $hargaBeliSupplier`, `subtotal_hpp = jml * $hargaBeliSupplier`.
3. Total Anggaran / Realisasi HPP pada header project (**`project_produk.harga_hpp_so`**) direkalkulasi secara dinamis.

### B. Pencatatan Audit Trail Transparan (`project_hpp_history`)
Setiap kali terjadi pembaruan HPP (baik dari PO 1466, revisi RAB, atau sinkronisasi balik), sistem **WAJIB** mencatat riwayat transaksi ke tabel `project_hpp_history`:

```php
// Panggil Model MdlProjectHppHistory
$this->load->model('Mdls/MdlProjectHppHistory');
$hppHistory = new MdlProjectHppHistory();

$hppHistory->recordHistory(array(
    'project_id'          => $projectId,
    'project_nama'        => $projectNama,
    'workorder_id'        => $workorderId,
    'komposisi_id'        => $komposisiId,
    'produk_id'           => $produkId,
    'produk_kode'         => $produkKode,
    'produk_nama'         => $produkNama,
    'hpp_lama'            => $hppLama,          // e.g. 0 atau HPP Estimasi RAB
    'hpp_baru'            => $hargaBeliFinal,    // e.g. Harga PO Supplier
    'sumber_perubahan'    => 'PO_PEMBELIAN_1466',
    'ref_transaksi_nomer' => $nomorPO,
    'oleh_id'             => my_id(),
    'oleh_nama'           => my_name(),
    'dtime'               => date('Y-m-d H:i:s')
));
```

### C. Manfaat Audit Trail
- **Pelacakan Variansi Harga Beli (*Purchase Price Variance / PPV*):** Mengetahui deviasi antara estimasi RAB vs realisasi PO.
- **Akuntabilitas Keuangan:** Riwayat tercatat detail (*siapa*, *kapan*, *nomor PO referensi*).
- **Integritas Laporan Laba Rugi:** Menjamin nilai HPP saat Closing (Step 5) valid dan terverifikasi.

---

## 6. Rencana Tahapan Implementasi (Phased Roadmap)

| Fase | Cakupan Pekerjaan | Target File |
| :--- | :--- | :--- |
| **Fase 1** | **UI Selector Project Pool:** Membuat modal / controller selector untuk mengambil barang dari `project_purchase_pool` | `modules/pembelianfgproject/controllers/_selectorItem.php` / `_selectorProjectPool.php` |
| **Fase 2** | **Shopping Cart Integration:** Menyimpan binding `project_purchase_pool_id` & `project_id` di sesi cart `1466r` | `modules/pembelianfgproject/controllers/_processSelectProduct.php` & `_shoppingCart.php` |
| **Fase 3** | **Sinkronisasi & Pool Consumption:** Mengupdate `qty_po`, `qty_sisa`, dan `status` saat PO `1466` disahkan | `modules/pembelianfgproject/controllers/FollowUp.php` |
| **Fase 4** | **Sync HPP Balik & Audit Trail:** Mengupdate HPP di `project_komposisi` & `project_komposisi_workoder` serta insert ke `project_hpp_history` | `modules/pembelianfgproject/controllers/FollowUp.php` |
| **Fase 5** | **Reversal Handler:** Mengembalikan alokasi sisa jika PO di-reject / void | `modules/pembelianfgproject/controllers/FollowUp.php` |
| **Fase 6** | **Uji End-to-End:** Simulasi Kickoff Project $\rightarrow$ Tarik ke PO $\rightarrow$ PO Approval $\rightarrow$ Cek Status Pool $\rightarrow$ Verifikasi Audit Trail | Script Pengujian & Verifikasi |