# BLUEPRINT CETAK BIRU MODUL: PENJUALAN
**Modul:** `penjualan`  
**Workspace:** `new_san_variant`  
**Standard:** Single Variant Standard & Dual-Write Rollout  
**Tanggal Analisis:** 2026-07-29  

---

## 1. IDENTITAS MODUL

- **Nama Modul:** `penjualan`
- **Pola Kompleksitas:** **Transaksi Kompleks** (Melibatkan Multi-Variant Product Picker, Integration CRM order bridge, Multi-Step Sales Approval, Dual-Write Stock Locker Hold/Release, Diskon Bertingkat, PPN Factor, & Retur Penjualan).
- **Jenis Transaksi (`jenisTr`):**
  - `582` : Penjualan Reguler / Sales Order (Faktur Penjualan)
  - `749` : Piutang Penjualan / Pelunasan Piutang
  - `982` : Retur Penjualan (Sales Return with Stock Restoration)
  - `1982`: Retur Penjualan Non-Stok
  - `382` : Penjualan POS / Direct Cash Sales
  - `1582`: Penjualan Indent / Booking Order
  - `584` : Penjualan Paket / Assembling Sales
  - `1784`: Penjualan Komposit

---

## 2. DAFTAR FUNGSI & LOGIKA BISNIS (REVERSE ENGINEERING)

### 2.1 Base Controller & Configuration

#### [Modul_Controller.php](file:///c:/xampp/htdocs/new_san_variant/application/modules/penjualan/controllers/Modul_Controller.php)
- **Fungsi `__construct()`**:
  - *Input (POST/GET/URI)*: `URI segment(4)` sebagai `$this->jenisTr`, `URI segment(1)` sebagai `$this->modul`.
  - *Validasi*: Session login `validateUserSession($this->session->login['id'])`.
  - *Config Loaded*: `coTransaksiUi`, `coTransaksiCore`, `coTransaksiLayout`, `coTransaksiValues`.
  - *Helper Loaded*: `he_access_right`, `he_session_replacer`, `he_url`.
  - *State & DB Schema Mapping*: `$this->mongoTableList` (`transaksi`, `transaksi_values`, `transaksi_data`, `transaksi_data_values`, `transaksi_sign`, `transaksi_extstep`, `transaksi_registry`).

---

### 2.2 Entry Transaksi (Draft / Create & CRM Bridge)

#### [Create.php](file:///c:/xampp/htdocs/new_san_variant/application/modules/penjualan/controllers/Create.php)
- **Fungsi `index()`**:
  - *Input*: `GET/POST` parameters (filter customer, sales ID, jenisTr).
  - *Validasi*: Inisialisasi session cart `_TR_[jenisTr]`.
  - *Query*: MdlCustomer, MdlProduk, MdlCabang.
  - *Output*: View `transaksi_modul.php` / UI Step 1 (Pencarian & Pemilihan Customer/Produk).
- **Fungsi `preview()`**:
  - *Input*: Data session cart `_TR_[jenisTr]`.
  - *Validasi*: Pengecekan kelengkapan data customer (`pihakID`), item cart tidak kosong, limit kredit customer (`MdlCustomer`).
  - *Query*: MdlMongoMother / MdlTransaksi untuk kalkulasi HPP & Jurnal Piutang/Penjualan/Stok.
  - *Output*: View `template/transaksi_extern.html` / UI Step 2 (Ringkasan Faktur Penjualan).
- **Fungsi `save()`**:
  - *Input*: `POST` form payload (catatan, alamat pengiriman, diskon total, pajak PPN, cara bayar).
  - *Validasi*: Form rules `pihakID` wajib, `item` minimal 1.
  - *Query Database*:
    - `transaksi` (Insert header faktur penjualan).
    - `transaksi_data` (Insert detail item penjualan + variant_id & variant_nama).
    - `transaksi_values` (Insert total nilai penjualan, DPP, PPN, HPP).
    - `transaksi_registry` (Insert step registrasi sales).
  - *Output*: Redirect ke `FollowUp` atau JSON status.
- **Fungsi Integrasi CRM (`previewCrm()`, `previewCrmVariantPicker()`, `savePreviewCrmVariant()`, `doRejectCrm()`)**:
  - *Input*: Payload JSON CRM Bridge CLI.
  - *Logic*: Menerima order dari platform CRM external, memetakan produk CRM ke `produk_id` & `variant_id` lokal, menyimpan audit trail di `preview_crm_variant_audit`.

---

### 2.3 Executing & FollowUp Approval

#### [FollowUp.php](file:///c:/xampp/htdocs/new_san_variant/application/modules/penjualan/controllers/FollowUp.php)
- **Fungsi `index()`**:
  - *Input*: Filter datatable (status step approval, tanggal, cabang).
  - *Query*: `transaksi` where `jenisTr` in (`582`, `982`, `382`, dll) AND status step pending.
  - *Output*: View list transaksi pending approval.
- **Fungsi `followupPrePreview()` & `followupPreview()`**:
  - *Input*: `GET/POST` ID transaksi penjualan.
  - *Query*: Fetch detail `transaksi_data` + verifikasi customer membership & limit kredit.
  - *Output*: View modal/halaman approval supervisor.
- **Fungsi `doFollowup()`** *(Core Execution Sales)*:
  - *Input*: `POST` ID transaksi penjualan + keputusan approval.
  - *Validasi*: User access level (`he_access_right`), lock transaksi.
  - *Query & Model Executed*:
    1. **Status Update**: Update `transaksi` state menjadi `completed`.
    2. **Jurnal Otomatis**: Panggil `ComJurnal` untuk mencatat Jurnal Piutang (D), Penjualan (K), HPP (D), dan Persediaan (K).
    3. **Stock Release (Dual-Write)**: Panggil `ComLockerStockDualWrite::pair()` untuk mengubah state stok dari `hold` menjadi `-hold` & `-active` (penjualan) atau `+active` (retur penjualan), dengan aturan sentinel (`variant_id=0` -> `1`).
    4. **Registry Update**: Update `transaksi_registry`.
  - *Output*: JSON status success + option cetak faktur.
- **Fungsi `doRevert()` & `doCancelPacking()`**:
  - *Input*: `POST` ID transaksi.
  - *Logic*: Membatalkan transaksi penjualan dan melepaskan hold stok via `ComLockerStockDualWrite`.

---

### 2.4 Cart Engine & Multi-Variant Product Picker

#### [_shoppingCart.php](file:///c:/xampp/htdocs/new_san_variant/application/modules/penjualan/controllers/_shoppingCart.php)
- **Fungsi `viewCart()`**: Render tabel item keranjang penjualan.
- **Fungsi `reset()`**:
  - *Logic Dual-Write Stock*: Melepaskan hold locker stok yang dikunci sementara saat memilih barang, menggunakan `ComLockerStockDualWrite::pair()` untuk sinkronisasi `stock_locker` dan `stock_locker_variant`.
- **Fungsi `recordFieldElement()`, `recordItemColumn()`, `autoAdjustRoundingAjax()`**: Real-time update AJAX untuk harga, diskon, dan pembulatan.

#### [_selectorItem.php](file:///c:/xampp/htdocs/new_san_variant/application/modules/penjualan/controllers/_selectorItem.php) & [views/variant_picker.php](file:///c:/xampp/htdocs/new_san_variant/application/modules/penjualan/views/variant_picker.php)
- **Fungsi `variantPicker()`**: Modal picker khusus untuk memilih varian produk (ukuran, warna, grade) secara presisi dengan mengecek stok locker varian real-time (`stock_locker_variant`).
- **Fungsi `selectItem()`**: Memasukkan produk + varian terpilih ke dalam keranjang `_TR_[jenisTr]`.

#### [_processSelectProduct.php](file:///c:/xampp/htdocs/new_san_variant/application/modules/penjualan/controllers/_processSelectProduct.php)
- **Fungsi `select()`, `multiSelect()`, `remove()`, `updateValues()`**:
  - *Logic*: Pengisian item barang reguler ke cart.
  - *Stock Locker*: Memanggil `ComLockerStockDualWrite::pair()` untuk mengunci stok `hold` pada varian terpilih.

---

### 2.5 Reporting, CRM & Detail Views

#### [TransaksiCrm.php](file:///c:/xampp/htdocs/new_san_variant/application/modules/penjualan/controllers/TransaksiCrm.php)
- **Fungsi `viewOrderCrm()`, `checkCustomerRegisterStatus()`, `saveCustomerToPihakLain()`**: Mengelola verifikasi dan pendaftaran otomatis data pelanggan baru yang datang dari saluran CRM.

#### [ViewDetails.php](file:///c:/xampp/htdocs/new_san_variant/application/modules/penjualan/controllers/ViewDetails.php)
- **Fungsi `nomer()`, `item_report()`**:
  - *Multi-Variant Fix*: Menggunakan unique row key indexing (`{produk_id}_{variant_id}`) untuk memunculkan rincian varian produk tanpa konflik key.

#### [Printing.php](file:///c:/xampp/htdocs/new_san_variant/application/modules/penjualan/controllers/Printing.php)
- **Fungsi `viewReceipt()`, `viewProformaReceipt()`, `viewSmallReceipt()`**: Generasi dokumen Faktur Penjualan, Surat Jalan, dan Struk POS.

---

## 3. IDENTIFIKASI PERBEDAAN DENGAN MOCKUP GLOBAL

| No | Komponen / Fitur Unik | Deskripsi & Perbedaannya dengan Mockup Standar |
|:--:|:----------------------|:------------------------------------------------|
| 1 | **Multi-Variant Product Picker (`_selectorItem/variantPicker`)** | UI Modal khusus yang memuat matriks varian (ukuran x warna) dan mengecek ketersediaan stok real-time per varian di `stock_locker_variant`. |
| 2 | **CRM Order Bridge Integration (`TransaksiCrm.php` & `Create::previewCrm`)** | Fitur impor & pemetaan order otomatis dari aplikasi CRM eksternal dengan pencocokan pelanggan dan audit trail pemetaan varian (`preview_crm_variant_audit`). |
| 3 | **Limit Kredit & Approval Group Customer** | Validasi limit kredit pelanggan secara dinamis pada `FollowUp.php` sebelum faktur dapat disetujui. |
| 4 | **Diskon Bertingkat & Auto Rounding Ajax (`_shoppingCart`)** | Perhitungan diskon kompleks (diskon 1 + diskon 2 + diskon nominal) serta penyesuaian pembulatan harga otomatis. |
| 5 | **Dual-Write Stock Locker Sales (`ComLockerStockDualWrite`)** | Mengunci stok barang & varian pada state `hold` saat dimasukkan ke cart dan melepaskannya (`-active`) secara sinkron saat faktur disetujui. |

---

## 4. ARSITEKTUR KODE BARU (THE BLUEPRINT)

### 4.1 Struktur Controller & Service Layer Baru

```
application/modules/penjualan/
├── config/
│   ├── coTransaksiCore.php
│   ├── coTransaksiUi.php
│   ├── coTransaksiLayout.php
│   └── coTransaksiValues.php
├── controllers/
│   ├── Modul_Controller.php       # Base controller
│   ├── Create.php                 # Form Sales Order & CRM Bridge Entry
│   ├── FollowUp.php               # Approval & Execution Sales
│   ├── Transaksi.php              # Sales Grid & Order List
│   ├── TransaksiCrm.php           # CRM Integration Engine
│   ├── ActivityReport.php         # Laporan Penjualan
│   ├── History.php                # Riwayat Transaksi Sales
│   ├── Printing.php               # Cetak Faktur & Surat Jalan
│   ├── ViewDetails.php            # Modal Detail Penjualan (Multi-Variant Safe)
│   ├── _shoppingCart.php          # Cart Session Manager & Auto Rounding
│   ├── _selectorItem.php          # Variant Picker Controller
│   └── _processSelectProduct.php   # Product Selector (Dual-Write Stock)
└── views/
    ├── transaksi_modul.php        # UI Shell
    ├── variant_picker.php         # Modal Matrix Variant Picker UI
    ├── create_preview_crm_variant_picker.php # CRM Variant Mapping UI
    ├── shoppingCart.php           # Cart Table View
    └── printing.php               # Print Template Faktur
```

---

### 4.2 Payload Data & State Management (JSON / AJAX API)

#### A. Payload Item Penjualan dengan Varian (`_TR_582`)
```json
{
  "header": {
    "nomer": "FJ-202607-0102",
    "pihakID": 84,
    "pihakName": "PT. Sentosa Jaya",
    "dtime": "2026-07-29 11:52:00",
    "oleh_id": 5,
    "cabang_id": 1,
    "gudang_id": 2
  },
  "items": [
    {
      "cart_key": "prod_210_variant_5",
      "produk_id": 210,
      "variant_id": 5,
      "variant_nama": "Size XL - Hitam",
      "nama": "Jaket Safety High-Vis",
      "satuan": "Pcs",
      "jumlah": 10.0,
      "harga": 350000.0,
      "diskon_persen": 5.0,
      "subtotal": 3325000.0
    }
  ],
  "values": {
    "total_dpp": 3022727.0,
    "total_ppn": 302273.0,
    "total_grand": 3325000.0
  }
}
```

---

### 4.3 Panduan Langkah-demi-Langkah Developer (Step-by-Step Implementation Guide)

1. **Langkah 1: Verifikasi Setup Variant Picker (`_selectorItem.php`)**
   - Memastikan `variantPicker()` membaca stok varian dari `stock_locker_variant` dan mendukung fallback sentinel `1` bila produk tidak memiliki varian (`variant_id = 0`).

2. **Langkah 2: Terapkan Dual-Write Stock Locker pada `_processSelectProduct.php` & `_shoppingCart.php`**
   - Menggunakan `ComLockerStockDualWrite::pair()` untuk setiap perubahan jumlah item di cart.

3. **Langkah 3: Sinkronisasi Integrasi CRM Order (`TransaksiCrm.php`)**
   - Memastikan pemetaan item dari order CRM mencatat `variant_id` dengan benar di tabel `preview_crm_variant_audit`.

4. **Langkah 4: Pengujian Jurnal & Limit Kredit di `FollowUp.php`**
   - Memastikan jurnal Piutang, Penjualan, dan HPP terbentuk sempurna via `ComJurnal` dalam transaksi DB (`$this->db->trans_start()`).

5. **Langkah 5: Pengujian Syntax PHP 5.6 & Update UAT Checklist**
   - Jalankan `C:\xampp\php\php.exe -l` pada semua berkas controller/view yang diubah dan perbarui status di `docs/uat-checklist.md`.

---

### 5. KESIMPULAN & STATUS EKSEKUSI

- 🟢 **Pekerjaan Selesai (Completed & Verified)**:
  1. Reverse engineering lengkap modul `penjualan`.
  2. Dokumen [blueprint_penjualan.md](file:///c:/xampp/htdocs/new_san_variant/blueprint_penjualan.md) telah diterbitkan.
  3. Dokumen [dev-jurnal.md](file:///c:/xampp/htdocs/new_san_variant/application/modules/penjualan/docs/dev-jurnal.md) telah diperbarui.

---
*Dokumen Blueprint ini dibuat oleh Agent 7 / System Analyst untuk modul Penjualan di workspace `new_san_variant`.*