# 📜 TRANSKRIP ARSITEKTUR & MASTER BLUEPRINT MIGRASI PENJUALAN (SESI 2)
## Penyempurnaan Bounded Context, Ekosistem Modul, Native Pipeline, dan Universal Value Builder DTO
**Waktu Penyusunan:** 8 September 2026 (Sesi Malam)
**Status Dokumen:** FINAL & TERVERIFIKASI
**Tujuan Dokumen:** Membekukan seluruh hasil dialektika arsitektural, audit kode CI3, dan kesepakatan desain sistem dari sesi diskusi mendalam kedua, agar menjadi panduan eksekusi absolut tanpa ada distorsi atau kehilangan konteks bisnis.
---
## 1. 🧭 RANGKUMAN EKSEKUTIF SESI 2
Pada sesi ini, telah disepakati 5 resolusi arsitektural fundamental:
1. **Disiplin Bounded Context Murni**: Menghentikan god-module di `Penjualan`. Mengembalikan `NumberingCounterService` ke `Modules/Core` (Shared Kernel), `StockEngine` & `SerialNumberValidator` ke `Modules/Inventory`, dan Jurnal GL ke `Modules/Akuntansi` via Domain Events.
2. **Kepatuhan Standar Industri & Literatur**: Mengadopsi prinsip Eric Evans (Ch. 14 Shared Kernel), Vaughn Vernon (Subdomain Classification), standar SAP S/4HANA (SD vs MM vs Basis NRIV), dan Odoo ERP (`sale` vs `stock` vs `base`).
3. **Audit 100% Paritas Fitur CI3**: Menginventarisasi 7 kapabilitas domain CI3 yang sempat terlewat (Reversal/Storno, Stepping Follow-Up, Undone Queue, Auto-Authorization, Payment Source & DP, Bundling Serial Number, Printing Engine) dan membaginya ke dalam 3 Milestone Rilis.
4. **Transformasi 7 Tahapan Pipeline**: Mengonversi 993 baris kode imperatif `ComTransactionPipelineEngine.php` menjadi kelas-kelas *Single Responsibility Pipe* pada `Illuminate\Pipeline\Pipeline` dengan DTO `SalesOrderContext`.
5. **Ketetapan Universal Value Builder & Value Maker**: Menegaskan bahwa `he_value_builder` bukan "pricing", melainkan jembatan rekapitulasi universal seluruh transaksi yang memanggil `he_value_maker` (`makeValue`). Karena sistem berpindah ke DTO, **HANYA** varian *non-session* (`_ns`): `resetValues_he_value_builder_ns` dan `fillValues_he_value_builder_ns` yang dimigrasikan ke `Modules/Core/Domain/Services/TransactionValueBuilder.php`.
---
## 2. 🏛️ RESOLUSI BOUNDED CONTEXT & PEMBAGIAN SERVICE
### A. Evaluasi Empiris & Penempatan Service
| Service | Hakikat Bisnis Sebenarnya | Penempatan yang Sah | Alasan Arsitektural (DDD & ISO 25010) |
| :--- | :--- | :--- | :--- |
| **`NumberingCounterService`** | Generator nomor nota atomik (`counters_custom_number`) | **`Modules/Core`** *(Shared Kernel)* | Dipakai oleh 40+ modul transaksi di CI3 (SO 582, PO 466, Kas 334, Mutasi 663). Menaruhnya di Penjualan memicu ketergantungan terbalik (*inverted coupling*). |
| **`StockEngine`** | Saldo fisik gudang, alokasi/booking stok, batas minus | **`Modules/Inventory`** *(Supporting Subdomain)* | Otoritas mutlak atas fisik barang di gudang. Penjualan hanya bertindak sebagai *konsumen query* via Interface/ACL (`StockAvailabilityInterface`). |
| **`SerialNumberValidator`** | Status keberadaan fisik nomor seri/IMEI di rak gudang | **`Modules/Inventory`** *(Supporting Subdomain)* | Serial number adalah unit fisik inventaris. Penjualan hanya memvalidasi status `AVAILABLE` sebelum membuat Surat Jalan. |
| **`SalesPricingEngine`** | Matriks harga jual pelanggan, diskon tier, PPN floor | **`Modules/Penjualan`** *(Core Subdomain)* | Murni aturan komersial penjualan ke pelanggan. Tidak boleh dinamai generic "Pricing" agar tidak rancu dengan biaya beli supplier (*Purchasing Cost*). |
| **`Jurnal Posting`** | Pembukuan berpasangan (Debit = Kredit, GL, COA) | **`Modules/Akuntansi`** *(Fase 7)* | Modul operasional dilarang menyentuh tabel jurnal GL secara langsung. Penjualan hanya memancarkan *Domain Events*. |
---
### B. Referensi Teoretis & Pembuktian Industri Nyata
1. **Eric Evans — *Domain-Driven Design* (The Blue Book, 2003)**:
* **Bab 14: Shared Kernel**: Kapabilitas yang dibutuhkan bersama oleh banyak bounded context (seperti penomoran dokumen urut dan kalkulator ekspresi matematika) wajib diisolasi menjadi *Shared Kernel* eksplisit.
* **Bab 14: Anti-Corruption Layer (ACL)**: Modul Penjualan dilarang menelan model pergudangan; komunikasi wajib via antarmuka adapter/kontrak.
2. **Vaughn Vernon — *Implementing Domain-Driven Design* (The Red Book, 2013)**:
* **Bab 2**: Mengklasifikasikan domain menjadi *Core Domain* (Sales), *Supporting Subdomain* (Inventory), dan *Generic Subdomain* (Counter & Core Utilities). Menempatkan Generic Subdomain ke Core Domain adalah pelanggaran integritas model.
3. **Standar SAP S/4HANA**:
* Modul **SD (Sales)** tidak memiliki tabel stok fisik. Pengecekan stok dilakukan via **ATP (*Available-to-Promise*)** ke modul **MM-IM (Inventory)**.
* Penomoran nota dikelola terpusat oleh objek **NRIV (*Number Range*)** pada layer **SAP Basis (Core)**, bukan di SD atau MM.
4. **Standar Odoo ERP**:
* Modul `sale` dan `purchase` sama-sama bergantung ke modul `stock` (Inventory).
* Generator penomoran nota (`ir.sequence`) berada di modul `base` (Core).
5. **Standar ISO/IEC 25010 (Software Product Quality)**:
* **Sub-klausul 4.3.1 (Modularity)** & **4.3.2 (Reusability)**: Perubahan aturan stok atau counter tidak boleh memicu efek domino (*ripple effect*) pada modul penjualan.
---
## 3. 🗺️ TOPOLOGI EKOSISTEM MODUL (CONTEXT MAP)
```mermaid
graph TD
subgraph CoreLayer ["1. Modules/Core (Shared Kernel / Generic)"]
Counter[NumberingCounterService
Atomic Lock Counter]
ValMaker[ValueMakerService
makeValue Expression Evaluator]
ValBuilder[TransactionValueBuilder
resetValues_ns & fillValues_ns DTO Bridge]
AuditLog[AuditTrailService
Immutable JSONB]
end
subgraph MasterLayer ["2. Modules/MasterData (Single Source of Truth)"]
Kontak[Kontak & Mitra Bisnis
Plafon Kredit, TOP, NPWP/NIK]
Katalog[Produk & Satuan
SKU, UOM, Harga Dasar]
end
subgraph InventoryLayer ["3. Modules/Inventory (Otoritas Fisik Gudang)"]
StockEng[StockEngine
Saldo Fisik, Booking, Minus Rule]
SNEng[SerialNumberValidator
Status IMEI/SN Rak Gudang]
Mutasi[Mutasi Antar-Gudang & Opname]
end
subgraph SalesLayer ["4. Modules/Penjualan (Otoritas Komersial Penjualan)"]
Pricing[SalesPricingEngine
Aturan Komersial Konsumen]
SO[SalesOrder & SalesDelivery Orchestrator]
Invoice[SalesInvoice & Tax Standby Generator]
Reversal[SalesOrderReversalService]
FollowUp[SalesOrderFollowupService]
end
subgraph TreasuryLayer ["5. Modules/Keuangan (Treasury & Payment Source)"]
PaySource[PaymentSourceEngine
Alokasi DP, Kasir, Split Payment]
BankRec[Kasir & Rekonsiliasi Bank]
end
subgraph AccountingLayer ["6. Modules/Akuntansi (Fase 7 - General Ledger)"]
GL[Auto-Journaling Listener
HPP, Piutang, Pendapatan, Kas/Bank]
COA[Buku Besar & Laporan Keuangan]
end
%% Relasi Sinkron (Kontrak / Interface)
SalesLayer -.->|Query Plafon & Harga| MasterLayer
SalesLayer -.->|Ambil No Nota SO/DO/INV| Counter
SalesLayer -.->|Rekapitulasi DTO via makeValue| ValBuilder
ValBuilder -.->|Evaluasi Rumus Matematika| ValMaker
SalesLayer -->|Cek & Booking Stok| InventoryLayer
%% Relasi Asinkron (Domain Events)
SalesLayer ==>|Event: DeliveryDispatched| AccountingLayer
SalesLayer ==>|Event: SalesInvoiceIssued| AccountingLayer
SalesLayer ==>|Alokasi DP & Pelunasan Kasir| TreasuryLayer
TreasuryLayer ==>|Event: PaymentReceived| AccountingLayer
```
---
## 4. 🧮 KETETAPAN UNIVERSAL VALUE BUILDER & VALUE MAKER
### A. Hakikat Faktual di CI3
Di CI3, [he_value_builder_helper.php](file:///z:/everest_refaktor/application/helpers/he_value_builder_helper.php) bukan domain pricing, melainkan **Jembatan Rekapitulasi Transaksi Universal** yang menghubungkan baris rincian (`items`, `items2`, `rsltItems`) dengan header master (`main`). Di dalamnya, ia mengevaluasi ekspresi matematika dinamis menggunakan [he_value_maker_helper.php](file:///z:/everest_refaktor/application/helpers/he_value_maker_helper.php) (`makeValue`).
### B. Strategi Porting ke Laravel: Stateless DTO Architecture
Karena di Laravel seluruh ketergantungan `$_SESSION` dieliminasi total dan digantikan oleh DTO ([SalesOrderContext.php](file:///y:/everest_re/Modules/Penjualan/app/Domain/Contexts/SalesOrderContext.php)), maka dari 7.053 baris kode CI3:
* **HANYA varian *non-session* (`_ns`) yang dimigrasikan**:
1. `resetValues_he_value_builder_ns($tr, $configCoreJenis, $sessionData)` (baris 4940)
2. `fillValues_he_value_builder_ns($tr, $fromStep, $intoStep, $configCoreJenis, $configUiJenis, $configValuesJenis, $ppnFactor, $sessionData)` (baris 4956)
* Keduanya dienkapsulasi menjadi method bersih di dalam kelas:
📁 `Modules/Core/app/Domain/Services/TransactionValueBuilder.php`
* Evaluator formula string diekstrak menjadi:
📁 `Modules/Core/app/Domain/Services/ValueMakerService.php` (porting `makeValue` + `FieldCalculator`).
* **Hasil**: 100% rumus rekapitulasi CI3 (Value Gates, Recap Items $\rightarrow$ Main, Value Builders, Value Spreaders, TableIn mapping) dapat dieksekusi murni di memori (*in-memory*) tanpa menyentuh session web browser.
---
## 5. 🔄 TRANSFORMASI 7 TAHAP PIPELINE CI3 KE LARAVEL NATIVE PIPELINE
Proses imperatif di `ComTransactionPipelineEngine.php` (993 baris) di CI3 ditransformasikan menjadi pipa-pipa mandiri pada `Illuminate\Pipeline\Pipeline`:
```
┌─────────────────────────────────────────────────────────────────────────┐
│ PIPELINE PEMBUATAN PESANAN (SalesOrderContext) │
├─────────────────────────────────────────────────────────────────────────┤
│ 1. ValidateCustomerCreditPipe (Cek Plafon Kredit & Piutang Macet) │
│ 2. ValidateStockAvailabilityPipe (Query Stok ke Modules/Inventory) │
│ 3. ExtractSerialNumbersPipe (Validasi SN ke Modules/Inventory) │
│ 4. RecapitulateOrderValuesPipe (Panggil TransactionValueBuilder::ns) │
│ 5. CalculatePricingAndTaxPipe (Panggil SalesPricingEngine PPN Floor)│
│ 6. GenerateOrderNumberPipe (Atomic Lock di Modules/Core) │
│ 7. PersistSalesOrderPipe (Simpan sales_orders & items dalam TX)│
│ 8. ApplyDownPaymentPipe (Alokasi DP jika ada) │
│ 9. FreezeSnapshotJsonbPipe (Simpan snapshot payload JSONB) │
│ 10. BindSerialNumbersPipe (Ikat nomor seri ke pesanan) │
│ 11. DispatchDomainEventsPipe (Lepas Event SalesOrderConfirmed) │
└─────────────────────────────────────────────────────────────────────────┘
```
---
## 6. 📋 AUDIT LENGKAP FITUR CI3 & PEMBAGIAN 3 MILESTONE RILIS
Seluruh 10 kapabilitas modul Penjualan CI3 telah terinventarisasi dan dipetakan:
### 🟢 MILESTONE 1: Fondasi Inti Penjualan (*Core Pipeline & Happy Path*) — [PRIORITAS SEKARANG]
* `Modules/Core`:
* `NumberingCounterService.php` (Atomic lock `lockForUpdate()`, paritas `counters_custom_number`).
* `ValueMakerService.php` (Evaluator ekspresi formula `makeValue`).
* `TransactionValueBuilder.php` (Jembatan rekapitulasi DTO `resetValues_ns` & `fillValues_ns`).
* Migrasi tabel counter PostgreSQL 16.
* `Modules/Inventory`:
* `StockAvailabilityInterface.php` & `SerialNumberValidationInterface.php` (Service Contracts).
* `StockEngine.php` (Saldo fisik, booking, minus rule).
* `SerialNumberValidator.php` (Validasi unit instance IMEI/SN).
* `Modules/Penjualan`:
* `SalesPricingEngine.php` (Diskon bertingkat, PPN 11% Coretax floor).
* DTO `SalesOrderContext.php` & `SalesDeliveryContext.php`.
* Rangkaian Pipeline Pembuatan Pesanan (`Order Pipelines` 1–11) & Pengiriman (`Delivery Pipelines` 1–3).
* Orchestrator `SalesOrderService.php` & `SalesDeliveryService.php`.
* Migrasi penyesuaian kolom PostgreSQL 16 (`snapshot_payload` JSONB, kolom otorisasi: `qty_approved`, `qty_outstanding`, `qty_closed`, `sisa_action`).
* Rich Domain Events: `SalesOrderConfirmed`, `DeliveryDispatched`, `SalesInvoiceIssued`, `SalesPaymentReceived`.
* Listeners: `AutoGenerateInvoiceListener` (PSAK 72 Goods Issued) & `RegisterTaxStandbyListener` (Coretax Standby).
---
### 🔵 MILESTONE 2: Siklus Hidup Lanjutan, Reversal & Treasury Kasir
* `SalesOrderFollowupService.php`: Transisi multi-step `5822` (`5822so` $\rightarrow$ `5822pkd` $\rightarrow$ `5822spd`) dengan otorisasi parsial (*Close Remaining* vs *Backorder*).
* `SalesOrderReversalService.php`: Pembalikan langkah tunggal (`doRevert`), pembatalan transaksi penuh (`doRevertAll`), pembatalan kemas gudang (`doCancelPacking`), pelepasan booking stok, unbinding serial number, dan pencatatan audit storno.
* `PaymentSourceEngine.php` (di `Modules/Keuangan`): Alokasi Uang Muka (DP), kasir split payment (Tunai + Transfer + EDC), pelunasan piutang bertahap.
* `UndoneQueueService.php`: Antrean kerja kasir (pesanan siap bayar) dan antrean gudang (barang siap kemas).
* `AutoAuthorizationService.php`: Persetujuan otomatis transaksi retail POS tanpa antre approval manajer.
---
### 🟡 MILESTONE 3: Ekstensi Bisnis, Bundling & Printing Engine
* `BundleSerialNumberExtractor.php` (di `Modules/Inventory`): Dekomposisi produk paket/komposit (1 SKU bundle terdiri dari beberapa item fisik ber-serial number).
* `SalesPrintingService.php`: Mesin pencetakan dokumen PDF Surat Jalan 3 rangkap, Faktur Pajak/Komersial, Kwitansi, dan Struk Kasir POS Thermal.
* `SalesOrderQueryService.php`: Penelusuran silsilah transaksi (`id_top`, `ids_prev`, `inv`) dan resume riwayat audit transaksi.
---
## 7. 🛡️ SYARAT MUTU & DEFINITION OF DONE (QUALITY GATES)
1. **Zero Math Tolerance**: Perhitungan nilai akhir, DPP, dan PPN 11% Coretax wajib 0 rupiah selisih terhadap formula acuan CI3.
2. **ACID Transaction Guaranteed**: Seluruh penulisan database dibungkus dalam `DB::transaction()` dengan pessimistic locking pada nomor nota dan stok.
3. **Immutable Audit Trail (ISO 27001)**: Setiap transaksi membekukan payload historis ke kolom native `JSONB` (`snapshot_payload`).
4. **Decoupled Architecture (ISO 25010)**: Modul Penjualan tidak memiliki relasi langsung atau penulisan langsung ke tabel jurnal Akuntansi atau mutasi fisik gudang.
---
*Dokumen ini disusun, diverifikasi, dan dibekukan oleh Lead Software Architect & Financial Auditor untuk menjamin kesempurnaan implementasi Everest ERP Laravel 13.*