# POS Gateway dan Integrasi pyPOS <-> ERP: Dokumen Arsitektur Sintesis

Subjudul: Konsolidasi Blueprint, Mapping Endpoint, Payload Contract, Phase 0/1, dan Rencana ERP (basis dokumen 2026-04-09)

## 1. Ringkasan Eksekutif

ERP perlu melayani banyak POS (pyPOS, RaptorPOS, dan vendor lain) tanpa menambah endpoint
khusus vendor di core ERP. Solusi yang disepakati adalah membangun satu pintu masuk integrasi
bernama POS Gateway, dengan setiap POS diperlakukan sebagai plugin connector. pyPOS menjadi
connector pertama dan referensi.

Dokumen sumber menunjukkan fondasi teknis sudah dibuat (Phase 0) dan hook facade endpoint lama
sudah dipasang (Phase 1), namun semuanya masih default OFF dan belum mengubah perilaku endpoint
legacy. Status di sumber: "belum eksekusi coding gateway" dan "belum eksekusi perbaikan kode".

Dua endpoint gateway baru saat ini tersedia secara desain:

1. `POST /pos_gateway/PosGatewayApi/ingest`
2. `GET|POST /pos_gateway/PosGatewayStatus/query`

Contract gateway berbasis `event_type`, bukan satu endpoint terpisah per fitur. Tujuh endpoint
pyPOS ditandai "siap (hook ada)" (Grup A), tujuh endpoint lain masih legacy (Grup B).

Rencana dipecah Phase 0 (Foundation), Phase 1 (Legacy Facade), Phase 2 (Stabilization), Phase 3
(Multi Provider). Checklist ERP memakai penomoran Phase 0-4 yang berbeda namun sejalan.
Tema risiko berulang: auth/JWT tidak dienforce penuh, idempotency, side effect pada endpoint
`check`, race `use_preorder`, dan kompatibilitas legacy mission-critical.

## 2. Latar Belakang & Masalah

### 2.1 Konteks Sistem (dari `PYPOS_ERP_CHECKLIST_RENCANA_2026-04-09.md`)

1. PHP 5.6
2. CodeIgniter 3 (CI3)
3. MariaDB 10
4. CentOS 7

Prinsip eksekusi: jaga backward compatibility selama transisi contract; hindari modernisasi
stack yang mengubah risk profile sistem inti; prioritaskan integritas data transaksi, audit
trail, dan stabilitas operasional. Blueprint menambahkan: nama class PascalCase, hindari fitur
PHP 7+, logic bisnis di service/model, controller tetap tipis.

### 2.2 Masalah yang Dituju

1. ERP berisiko membuat endpoint terpisah per vendor POS di core.
2. Endpoint legacy pyPOS memiliki gap contract, idempotency, dan guard auth.
3. pyPOS masih mengarah ke endpoint upload legacy, bukan endpoint contract baru.
4. Beberapa endpoint memiliki side effect yang tidak sesuai namanya.
5. Diperlukan jalur korelasi/trace yang bisa diikuti end-to-end.

### 2.3 Alur Saat Ini (pyPOS -> ERP)

1. pyPOS upload file transaksi ke endpoint ERP.
2. ERP proses file masuk ke tabel `transaksi_consolidasi_v2`.
3. ERP generate ke tabel `transaksi_point`.
4. ERP build blob settlement versi lama ke payment source.
5. ERP jalankan proses lanjutan sales point customer.
6. pyPOS juga bisa kirim settlement direct ke endpoint settlement.

### 2.4 Tujuan Utama

1. Integrasi POS masuk lewat satu gateway yang seragam.
2. Jalur pyPOS ditempatkan benar sebagai connector pertama.
3. Backward compatibility endpoint lama dijaga selama transisi.
4. Onboarding POS baru tanpa mengubah logic ERP core.
5. Menyamakan contract pyPOS (consumer) dan ERP (provider); menurunkan duplikasi, data tidak
   konsisten, dan celah keamanan; menjadi checklist eksekusi bertahap yang aman.

## 3. Prinsip Arsitektur (Gateway Tunggal + Plugin Connector)

### 3.1 Prinsip (Blueprint)

1. ERP core hanya menerima format canonical, tidak tahu format vendor POS.
2. Endpoint lama tetap aktif sebagai facade, lalu forward ke service gateway.
3. Setiap vendor POS diisolasi dalam connector plugin.
4. Operasi kritikal memakai `idempotency_key`, `trace_id`, dan audit log.
5. Proses berat dilakukan async worker/CLI, bukan sinkron penuh di controller.

### 3.2 Komponen Target

1. `PosGatewayApi` sebagai ingress tunggal eksternal.
2. `LegacyFacade` (controller lama) sebagai compatibility adapter ke gateway service.
3. `ConnectorResolver` untuk memilih plugin berdasarkan provider + tenant/device.
4. `ConnectorPlugin` (pyPOS, raptor, dst) untuk validasi dan mapping payload vendor.
5. `CanonicalIngestService` untuk simpan inbox, claim idempotency, enqueue proses.
6. `IngestWorker` untuk proses bisnis lanjutan ke modul ERP transaksi/settlement/sync.
7. `StatusService` untuk cek status by `trace_id`/`idempotency_key`.

### 3.3 Aliran Data Ringkas

1. Request masuk ke gateway (atau endpoint lama facade).
2. Auth + signature/JWT diverifikasi.
3. Connector dipilih (`provider_code`).
4. Payload vendor diubah ke canonical envelope.
5. Inbox + idempotency registry ditulis atomik.
6. Worker memproses ke tabel ERP existing.
7. Client cek status lewat endpoint status gateway.

### 3.4 Interface Plugin Connector

Interface minimum (konseptual, dari Blueprint):

```php
interface ConnectorInterface {
    public function getProviderCode();
    public function supportsEvent($eventType);
    public function validateInbound($eventType, $rawRequest);
    public function normalizeInbound($eventType, $rawRequest);
    public function mapToCanonical($eventType, $normalized);
    public function buildResponse($eventType, $canonicalResult);
}
```

`PyPosConnector` menjadi implementasi pertama dan referensi connector berikutnya. Blueprint
menyarankan struktur `application/modules/pos_gateway/` (controllers, libraries/connectors,
models, services), namun file aktual Phase 0 memakai lokasi berbeda (lihat bagian 11).

## 4. Fase 0: Execution Pack

Sumber: `POS_GATEWAY_PHASE0_EXECUTION_PACK_2026-04-09.md` (2026-04-09). Tujuan: menyiapkan
fondasi teknis POS Gateway tanpa mengubah endpoint pyPOS lama.

### 4.1 Scope yang Sudah Dibuat

1. Konfigurasi gateway (default OFF).
2. Skeleton controller gateway baru.
3. Skeleton plugin connector pyPOS.
4. Service ingest canonical + model inbox/registry/binding.
5. SQL schema draft untuk tabel baru.

### 4.2 File Baru (Phase 0)

Config:

- `application/config/pos_gateway.php`

Controller baru (tidak menggantikan endpoint lama):

- `application/controllers/pos_gateway/PosGatewayApi.php`
- `application/controllers/pos_gateway/PosGatewayStatus.php`

Library POS Gateway:

- `application/libraries/PosGateway/ConnectorInterface.php`
- `application/libraries/PosGateway/ConnectorResolver.php`
- `application/libraries/PosGateway/Connectors/PyPosConnector.php`
- `application/libraries/PosGateway/CanonicalIngestService.php`

Model baru:

- `application/models/MdlPosGatewayInbox.php`
- `application/models/MdlPosGatewayRegistry.php`
- `application/models/MdlPosGatewayBinding.php`

SQL:

- `docs/sql/POS_GATEWAY_PHASE0_SCHEMA_2026-04-09.sql`

### 4.3 Cara Aktivasi Bertahap (Staging Dulu)

1. Jalankan SQL schema di staging.
2. Set config `pos_gateway_enabled = true` hanya di staging.
3. Uji endpoint baru: `.../pos_gateway/PosGatewayApi/ingest` dan
   `.../pos_gateway/PosGatewayStatus/query`.
4. Endpoint lama tetap dipakai normal (belum reroute).

### 4.4 Contoh Request Minimum (Staging)

```json
{
  "provider_code": "pypos",
  "event_type": "sales_batch",
  "tenant_id": "SBG01",
  "cabang_id": 12,
  "machine_id": "118933446257318",
  "file_hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "payload": { "example": "phase0" }
}
```

### 4.5 Catatan Penting & Next Step

1. Ini baru pondasi ingest; dispatch worker bisnis belum diaktifkan.
2. Endpoint lama pyPOS belum diubah sama sekali.
3. Config default OFF untuk mencegah aktivasi tidak sengaja di production.
4. Next Step (Phase 1): tambah event dispatcher worker internal; tambah facade method di
   endpoint lama untuk forward ke gateway service (tetap kompatibel response lama); tambah
   contract tests upload + settlement + sync.
5. Status update: facade endpoint lama sudah disiapkan pada
   `docs/POS_GATEWAY_PHASE1_LEGACY_FACADE_2026-04-09.md`.

## 5. Fase 1: Legacy Facade & Backward Compatibility

Sumber: `POS_GATEWAY_PHASE1_LEGACY_FACADE_2026-04-09.md` (2026-04-09). Tujuan: menambahkan
facade internal pada endpoint pyPOS lama agar bisa forward ke POS Gateway secara opsional,
tanpa mengubah perilaku default endpoint lama.

### 5.1 Prinsip Safety

1. Endpoint lama tetap aktif dan tetap menjadi jalur utama.
2. Facade default nonaktif (`OFF`).
3. Tersedia mode `shadow` untuk observasi tanpa mengubah response endpoint lama.
4. Tersedia mode `active` untuk endpoint tertentu saat siap cutover bertahap.

### 5.2 Config Flag

File: `application/config/pos_gateway.php`. Key penting:

1. `pos_gateway_enabled`
2. `pos_gateway_legacy_facade_enabled`
3. `pos_gateway_legacy_facade_mode` (`off|shadow|active`)
4. `pos_gateway_legacy_facade_endpoint_map` (toggle per endpoint)

### 5.3 Endpoint Lama yang Sudah Dipasang Hook Facade

| Hook Key | event_type |
|---|---|
| `nonrest_setuploadstream` | `sales_batch` |
| `nonrest_getuploadcompilestatus` | `compile_status_query` |
| `nonrest_get_preorder` | `preorder_get` |
| `nonrest_use_preorder` | `preorder_use` |
| `datasync_serversync` | `sync_pull` |
| `prodiskon_checkfreeprodukquota` | `promo_quota_check` |
| `activityreportapi_settlement` | `settlement_push` |

### 5.4 File yang Diubah pada Phase 1

1. `application/config/pos_gateway.php`
2. `application/libraries/PosGateway/LegacyFacadeBridge.php`
3. `application/controllers/eusvc/NonRest.php`
4. `application/controllers/eusvc/DataSync.php`
5. `application/controllers/eusvc/ProDiskon.php`
6. `application/modules/penjualan/controllers/ActivityReportApi.php`

### 5.5 Cara Pakai Bertahap

Tahap A - Shadow Observability (disarankan awal): set `pos_gateway_enabled = true`,
`pos_gateway_legacy_facade_enabled = true`, `pos_gateway_legacy_facade_mode = "shadow"`, lalu
enable endpoint map satu per satu. Hasil: endpoint lama tetap memproses seperti biasa; gateway
dipanggil paralel untuk observasi dan log; tidak ada perubahan contract response ke client lama.

Tahap B - Active untuk Endpoint Terpilih: pastikan data shadow stabil, ubah mode ke `"active"`,
aktifkan hanya endpoint map yang siap, uji regresi response contract sebelum memperluas.

Catatan: hook facade belum mengubah endpoint lama secara permanen; cutover via toggle config,
bukan edit kode ulang; untuk production aktifkan bertahap per endpoint agar rollback mudah.

## 6. Mapping Endpoint pyPOS <-> ERP

### 6.1 Mapping Endpoint Modalitas (Blueprint)

| Endpoint Lama | Metode | Event Canonical | Connector Awal | Status Migrasi | Sumber |
|---|---|---|---|---|---|
| `/eusvc/NonRest/setUploadStream` | tidak dispesifikasikan | `sales_batch` | `PyPosConnector` | facade dahulu | Blueprint |
| `/eusvc/NonRest/setUploadStream__GLG` | tidak dispesifikasikan | `sales_batch` | `PyPosConnector` | sumber utama pyPOS v2 | Blueprint |
| `/eusvc/NonRest/getUploadCompileStatus` | tidak dispesifikasikan | `compile_status_query` | `PyPosConnector` | expose via status service | Blueprint |
| `/penjualan/ActivityReportApi/settlement` | tidak dispesifikasikan | `settlement_push` | `PyPosConnector` | route ke settlement service | Blueprint |
| `/eusvc/DataSync/serverSync` | tidak dispesifikasikan | `sync_pull` | `PyPosConnector` | route bertahap | Blueprint |
| `/eusvc/ProDiskon/checkFreeProdukQuota` | tidak dispesifikasikan | `promo_quota_check` | `PyPosConnector` | pisah read-only | Blueprint |
| `/eusvc/NonRest/get_preorder` | tidak dispesifikasikan | `preorder_get` | `PyPosConnector` | route bertahap | Blueprint |
| `/eusvc/NonRest/use_preorder` | tidak dispesifikasikan | `preorder_use` | `PyPosConnector` | tambah lock atomik | Blueprint |

### 6.2 Grup A: Sudah Siap Dipindah (Mapping)

| Endpoint pyPOS Saat Ini | Target Gateway | event_type | Status | Sumber |
|---|---|---|---|---|
| `/eusvc/NonRest/setUploadStream` | `POST /pos_gateway/PosGatewayApi/ingest` | `sales_batch` | siap (hook ada) | Mapping |
| `/eusvc/NonRest/getUploadCompileStatus` | `GET|POST /pos_gateway/PosGatewayStatus/query` (disarankan) atau ingest | `compile_status_query` | siap (hook ada) | Mapping |
| `/eusvc/DataSync/serverSync` | `POST /pos_gateway/PosGatewayApi/ingest` | `sync_pull` | siap (hook ada) | Mapping |
| `/eusvc/NonRest/get_preorder` | `POST /pos_gateway/PosGatewayApi/ingest` | `preorder_get` | siap (hook ada) | Mapping |
| `/eusvc/NonRest/use_preorder` | `POST /pos_gateway/PosGatewayApi/ingest` | `preorder_use` | siap (hook ada) | Mapping |
| `/eusvc/ProDiskon/checkFreeProdukQuota` | `POST /pos_gateway/PosGatewayApi/ingest` | `promo_quota_check` | siap (hook ada) | Mapping |
| `/penjualan/ActivityReportApi/settlement` | `POST /pos_gateway/PosGatewayApi/ingest` | `settlement_push` | siap (hook ada) | Mapping |

### 6.3 Grup B: Belum Siap Dipindah (Tetap Legacy Dulu)

| Endpoint pyPOS Saat Ini | Rencana event_type Gateway | Status | Sumber |
|---|---|---|---|
| `/eusvc/DataSync/doSync_auto` | `sync_check_update_legacy` (atau merge ke `sync_pull`) | belum | Mapping |
| `/eusvc/DataSync/publicBranchLookup` | `branch_lookup_public` | belum | Mapping |
| `/eusvc/DataSync/uiAssets` | `ui_assets_manifest` | belum | Mapping |
| `/eusvc/NonRest/postDeviceRegistrasi` | `device_register` | belum | Mapping |
| `/eusvc/NonRest/checkDevRegisV2` | `device_registration_status` | belum | Mapping |
| `/eusvc/NonRest/server_CheckUpdate` | `sync_check_update` | belum | Mapping |
| `/eusvc/ProDiskon/saveFreeProduk` | `promo_quota_consume` | belum | Mapping |

### 6.4 Peta Contract Endpoint (Ringkas, Checklist ERP)

| Endpoint | Metode | Ekspektasi pyPOS | Kondisi ERP Saat Ini | Gap Kontrak | Sumber |
|---|---|---|---|---|---|
| `/eusvc/NonRest/setUploadStream` | tidak dispesifikasikan | Upload file + metadata + status sukses | Legacy aktif, belum idempotency key terstruktur | pyPOS modern butuh key untuk compile check | Checklist |
| `/eusvc/NonRest/setUploadStream__GLG` | tidak dispesifikasikan | Upload dengan `id_machine`, `file_hash`, `file_seq`, idempotency | Ada validasi hash + idempotency registry + kick compile | Belum dipakai config pyPOS default | Checklist |
| `/eusvc/NonRest/getUploadCompileStatus` | tidak dispesifikasikan | Polling status compile berdasarkan idempotency | Ada, butuh key | Lewat endpoint legacy, key bisa tidak tersedia | Checklist |
| `/penjualan/ActivityReportApi/settlement` | tidak dispesifikasikan | Direct settlement + `X-Idempotency-Key` + auth | Idempotency kuat, guard auth ada namun nonaktif (commented) | Risiko keamanan, mismatch policy | Checklist |
| `/eusvc/DataSync/serverSync` | tidak dispesifikasikan | Sync incremental + bootstrap awal | Ada bypass bootstrap terkontrol | Perlu policy contract tertulis | Checklist |
| `/eusvc/DataSync/doSync_autoV2` | tidak dispesifikasikan | Sinkronisasi data terproteksi | Guard JWT di-comment | Endpoint terlindungi menjadi terbuka | Checklist |
| `/eusvc/ProDiskon/checkFreeProdukQuota` | tidak dispesifikasikan | Read-only check quota | Alias ke method yang insert DB | Nama endpoint tidak sesuai efek samping | Checklist |
| `/eusvc/NonRest/get_preorder` & `/use_preorder` | tidak dispesifikasikan | Ambil dan pakai preorder | Validasi sudah ada | Perlu lock/mark-used atomik cegah race | Checklist |

### 6.5 Rekomendasi Migrasi Praktis & Config Uji

Opsi 1 (paling aman, tanpa ubah pyPOS): biarkan pyPOS ke endpoint lama; aktifkan facade mode
`shadow` untuk validasi log + idempotency; naikkan endpoint tertentu ke `active` bertahap.

Opsi 2 (pyPOS diubah langsung): ubah endpoint Grup A ke `PosGatewayApi/ingest`; sertakan
`provider_code=pypos` dan `event_type`; compile/status query pakai `PosGatewayStatus/query`.

Config facade saat uji (`application/config/pos_gateway.php`): `pos_gateway_enabled = true`;
`pos_gateway_legacy_facade_enabled = true`; `pos_gateway_legacy_facade_mode = "shadow"` (awal);
`pos_gateway_legacy_facade_endpoint_map` hanya endpoint yang diuji. Default saat ini OFF untuk
keamanan. Grup B tetap legacy sampai event gateway-nya ditambahkan.

## 7. Kontrak Payload

### 7.1 Canonical Contract (V1)

Sumber: Blueprint. Semua connector harus menghasilkan envelope berikut:

```json
{
  "tenant_id": "SBG01",
  "branch_id": 12,
  "device_id": "118933446257318",
  "provider_code": "pypos",
  "event_type": "sales_batch",
  "trace_id": "trc_20260409_abc123",
  "idempotency_key": "sha256(...)",
  "sent_at": "2026-04-09 10:00:00",
  "payload_codec": "xz",
  "payload_version": "v1",
  "payload": {}
}
```

| Field | Tipe/Nilai Contoh | Keterangan | Sumber |
|---|---|---|---|
| `tenant_id` | `"SBG01"` | Identitas tenant | Blueprint |
| `branch_id` | `12` | Cabang | Blueprint |
| `device_id` | `"118933446257318"` | Device/mesin POS | Blueprint |
| `provider_code` | `"pypos"` | Pemilih connector | Blueprint |
| `event_type` | `"sales_batch"` | Jenis event canonical | Blueprint |
| `trace_id` | `"trc_20260409_abc123"` | Korelasi end-to-end | Blueprint |
| `idempotency_key` | `"sha256(...)"` | Anti duplikasi | Blueprint |
| `sent_at` | `"2026-04-09 10:00:00"` | Waktu kirim | Blueprint |
| `payload_codec` | `"xz"` | Codec payload | Blueprint |
| `payload_version` | `"v1"` | Versi contract | Blueprint |
| `payload` | `{}` | Isi vendor/canonical | Blueprint |

`event_type` awal yang wajib disiapkan: `sales_batch`, `compile_status_query`,
`settlement_push`, `sync_pull`, `promo_quota_check`, `preorder_get`, `preorder_use`.

### 7.2 Payload Strict Compile (Checklist POS)

Sumber: `POS_PAYLOAD_CHECKLIST.md`. Untuk tim POS agar payload selalu lolos `compileFilesV2`,
`compileFilesDataV2`, dan `compileFilesDataRegistryV2` tanpa fallback dinamis di server.

Aturan umum: jangan kirim `null` untuk kolom `NOT NULL`; field numerik tidak dipakai kirim `0`;
field string tidak dipakai kirim string (`""` atau sentinel `"none"`); field kunci transaksi
wajib ada dan tidak kosong: `machine_id`, `nomer`, `fulldate`, `dtime`, `x_id`.

Wajib non-empty (string) untuk tabel `transaksi`:

| Field | Type | Rekomendasi jika tidak digunakan |
|---|---|---|
| `kontainer_size` | `varchar(255)` | `"none"` |
| `ekspedisi_status` | `varchar(32)` | `"none"` |
| `print_oleh_nama` | `varchar(255)` | nama user POS, fallback `"system"` |

Wajib non-null (numerik/flag) untuk tabel `transaksi`. Semua default aman `0`, kecuali
`status` default `1`; field decimal default `0.000` atau `0.0000000000`:

| Field | Type | Default aman jika null |
|---|---|---|
| `cabang_id`, `customers_id`, `suppliers_id`, `bank_id`, `bank_rekening_id`, `jatuh_tempo`, `ekspedisi_id`, `kontainer_approve_id`, `bank_id_from`, `bank_rekening_id_from`, `referensi_id2`, `seller_id`, `tpl_alamat_id`, `penerima_id`, `approvals_batal_id`, `orders_id`, `print_oleh_id`, `counters_customers_id`, `counters_customers_id_all`, `counters_suppliers_id`, `counters_approvals_id`, `counters_gudang_id`, `counters_gudang_id_all`, `approvals_harga_id`, `approvals_batal_kirim_id` | `int(11)` (masing-masing) | `0` |
| `cli`, `kontainer_size_id`, `inv_dollar`, `next_step_num`, `print_counter`, `setor_status`, `status_4`, `trash_4` | `tinyint(3)` (masing-masing) | `0` |
| `kontainer_status`, `returned`, `returns`, `trash2`, `r_jenis`, `_temp`, `status_edit`, `print_status`, `sinkron_cache`, `auto_pemindahan`, `batal_kirim`, `cek`, `r_sales`, `r_maju`, `r_mundur` | `tinyint(1)` (masing-masing) | `0` |
| `status` | `tinyint(1)` | `1` |
| `cli_loop` | `tinyint(4)` | `0` |
| `inv` | `varchar(46)` | `0` |
| `deposit_persen_in` | `decimal(6,3)` | `0.000` |
| `transaksi_nilai_ori`, `kontainer_valas_nilai`, `tambahan_nilai` | `decimal(24,10)` (masing-masing) | `0.0000000000` |

Wajib khusus tanpa default DB: `counters` (`mediumblob`) wajib kirim non-null; rekomendasi
kirim object/array counters valid, minimal jangan `null` (fallback aman contoh `{}` lalu
serialize sesuai format export POS).

Kontrak minimal endpoint lain:

- `compileFilesDataV2` (tabel `transaksi_data`): wajib non-empty `machine_id`, `x_id`,
  `transaksi_id`, `dtime`; hindari `null` untuk field numerik/detail penting (`produk_id`,
  `produk_ord_jml`, `produk_ord_hrg`, dll).
- `compileFilesDataRegistryV2` (tabel `transaksi_data_registry`): wajib non-empty `machine_id`,
  `transaksi_id`, `main`; `main` harus bisa decode dan mengandung `dtime`.

Sanitizer POS (pseudocode JS) di sumber memakai `nzNum(v, d=0)` dan `nzStr(v, d="")`, lalu
`sanitizeTransaksi(row)` menormalkan seluruh field di atas dan menetapkan `row.counters = {}`
bila null/undefined.

## 8. Checklist & Rencana ERP

Sumber utama: `PYPOS_ERP_CHECKLIST_RENCANA_2026-04-09.md`.

### 8.1 Checklist Perbaikan (Belum Dieksekusi)

A. Contract Governance: tetapkan 1 contract resmi per endpoint (request, response, error code,
auth, idempotency); buat versi contract (`v1`) dan aturan kompatibilitas backward; definisikan
deprecate plan endpoint legacy upload; definisikan reason code standar lintas endpoint.

B. Security & Access Control: aktifkan enforcement JWT sesuai policy produksi; kembalikan
guard auth pada endpoint kritikal yang di-comment; terapkan pembatasan CLI-only pada endpoint
proses batch/kompilasi; audit endpoint publik yang boleh no-auth dan dokumentasikan justifikasi.

C. Data Integrity & Idempotency: migrasi pyPOS ke endpoint upload idempotent
(`setUploadStream__GLG`) bertahap; wajibkan `idempotency_key` end-to-end untuk tracing upload
-> compile; pisahkan endpoint check vs write pada modul diskon free produk; tambahkan
lock/consume marker atomik untuk `use_preorder`.

D. Operasional & Observability: standarkan `trace_id` di semua endpoint pyPOS integration;
simpan korelasi `machine_id`, `idempotency_key`, `file_hash`, `file_seq`; rapikan log level
error operasional vs debug; definisikan alert dasar untuk antrean compile/settlement macet.

E. QA & Regression Safety: buat contract test provider (ERP) untuk endpoint utama; buat
consumer compatibility test (pyPOS mock) untuk payload nyata; uji replay/duplikasi upload dan
settlement; uji rollback dan recovery setelah kegagalan parsial.

### 8.2 Rencana Kerja Bertahap (Checklist ERP)

- Phase 0 - Baseline & Freeze Contract (P0): membekukan contract sebagai baseline. Output:
  dokumen contract v1; matriks endpoint (auth, idempotency, effect read/write, SLA retry);
  daftar endpoint boleh no-auth beserta alasan.
- Phase 1 - Security Hardening (P0): menutup akses tidak sah tanpa memutus operasional.
  Output: guard auth aktif untuk endpoint kritikal; policy JWT runtime konsisten
  (enabled + enforce); guard CLI-only untuk proses batch yang tidak boleh web-exposed.
- Phase 2 - Upload Pipeline Contract Alignment (P1): menyamakan jalur upload + compile status.
  Output: pyPOS memakai endpoint upload idempotent; `idempotency_key` konsisten di response
  dan log; fallback terkontrol untuk client lama selama transisi.
- Phase 3 - Business Logic Hygiene (P1): menjaga semantic (check tidak write) dan mencegah
  race. Output: endpoint free produk read-only check + write terpisah; `use_preorder` punya
  lock/consume atomik.
- Phase 4 - Stabilization & Monitoring (P2): memastikan perubahan aman di produksi legacy
  multi-user. Output: contract + regression tests lulus; dashboard/SQL health checks antrean
  upload/compile/settlement; runbook troubleshooting dan rollback singkat.

### 8.3 Checklist Eksekusi Teknis (Blueprint)

1. Buat migration SQL untuk tabel gateway.
2. Buat `ConnectorInterface` + `ConnectorResolver`.
3. Buat `PyPosConnector` (event yang sudah berjalan sekarang).
4. Buat service ingest + dispatch.
5. Ubah endpoint lama pyPOS jadi facade (tanpa breaking response awal).
6. Buat contract test minimal untuk upload + settlement + sync.
7. Tambah monitoring dashboard query sederhana.

### 8.4 pyPOS-First Refactor Scope

P0 (wajib dulu): aktifkan policy auth konsisten untuk endpoint kritikal pyPOS; jadikan jalur
upload idempotent sebagai default pyPOS; matikan side-effect pada endpoint semantik `check`;
batasi endpoint CLI batch agar tidak callable dari web; tambahkan korelasi log
`trace_id + idempotency_key + machine_id`.

P1 (sesudah stabil): pindahkan parsing payload pyPOS ke `PyPosConnector`; controller lama
jadi facade ringan ke gateway service; tambahkan status endpoint canonical; tambahkan
contract tests provider/consumer.

### 8.5 Rencana Rollout Bertahap (Blueprint)

- Phase 0 - Foundation: tambah modul `pos_gateway` dan contract canonical v1; registry
  idempotency/inbox gateway; tenant-device-provider binding table.
- Phase 1 - pyPOS Bridge Hardening: endpoint pyPOS lama tetap aktif tapi internal call ke
  gateway service; gunakan `PyPosConnector`; aktifkan guard auth dan log korelasi.
- Phase 2 - Operational Stabilization: status endpoint canonical; health checks antrean
  inbox/worker; alert pending lama dan failure berulang.
- Phase 3 - Multi Provider Enablement: tambah `RaptorPosConnector`; aktifkan provider per
  tenant/branch/device via konfigurasi; uji coexistence pyPOS + provider eksternal.

## 9. Status Implementasi & Temuan

### 9.1 Status Artefak (per dokumen 2026-04-09)

| Artefak | Status di Sumber |
|---|---|
| Blueprint arsitektur | Blueprint implementasi (belum eksekusi coding gateway) |
| Checklist ERP | Draft konteks teknis (belum eksekusi perbaikan kode) |
| Mapping endpoint Phase 1 | Berbasis hook "siap (hook ada)"; gateway tersedia |
| Phase 0 Execution Pack | Scope sudah dibuat (config, controller, library, model, SQL draft) |
| Phase 1 Legacy Facade | Hook facade sudah dipasang; default OFF |
| Payload checklist | Panduan strict compile; tidak menyatakan status kode |

### 9.2 Temuan Kode/Sistem (Checklist ERP)

Risiko persisten (sedang aktif): settlement bisa dipanggil tanpa auth enforcement aktif penuh;
guard JWT global dapat efektif tidak enforced jika config default longgar; pyPOS masih mengarah
ke endpoint upload legacy; endpoint `checkFreeProdukQuota` menulis data (side effect pada check);
controller CLI transaksi dapat dipanggil via web (bukan CLI-only guard).

Risiko laten (potensi muncul): variabel undefined pada jalur kompilasi settlement (`$dataSpec`)
dapat meledak saat branch tertentu; `use_preorder` berpotensi dipakai ganda tanpa lock/flag
konsumsi atomik; pyPOS menandai upload sukses walau compile status masih pending (non-blocking);
metadata response menyatakan policy auth ketat saat runtime guard belum benar-benar enforced.

### 9.3 Kebutuhan Data/Konteks Lanjut

1. Nilai config runtime aktual: `jwt_enabled`, `jwt_enforce_protected`,
   `upload_stream_strict_legacy_path`.
2. Keputusan mode transisi upload: full switch ke endpoint baru, atau dual-write period.
3. Daftar endpoint yang harus tetap no-auth untuk bootstrap awal (jika wajib).
4. Sampel payload pyPOS terbaru (normal, duplikat, gagal parsial).
5. Persetujuan business owner untuk perubahan semantic endpoint diskon/preorder.

### 9.4 Open Questions

- Apakah endpoint settlement harus mandatory JWT di semua mode, atau ada whitelist device?
- Apakah compile status tetap non-blocking di sisi pyPOS, atau strict saat close/settlement?
- Apakah endpoint legacy upload akan ditutup total setelah cutover?
- Siapa pemilik final keputusan contract (tim ERP, tim POS, atau gabungan)?

### 9.5 Acceptance Criteria (Blueprint)

1. pyPOS existing tetap jalan tanpa ubah besar di sisi toko.
2. Semua request pyPOS memiliki trace yang bisa diikuti end-to-end.
3. Tidak ada duplicate insert pada replay request yang sama.
4. Endpoint lama masih kompatibel selama masa transisi.
5. POS baru dapat ditambahkan tanpa ubah logic ERP core.

### 9.6 Risiko & Mitigasi (Blueprint)

1. Breaking response legacy -> facade mempertahankan shape response lama.
2. Latensi bertambah karena lapisan baru -> ingest cepat + proses berat async worker.
3. Perbedaan business rule antar POS -> rule adapter di connector, bukan core ERP.
4. Operasional saat cutover -> feature flag per endpoint dan rollback switch cepat.

### 9.7 Keputusan yang Perlu Ditetapkan Owner

1. Deadline penghentian endpoint legacy (tanggal target).
2. Policy auth final untuk bootstrap scenario.
3. Prioritas provider setelah pyPOS (mis. RaptorPOS dulu atau lain).
4. SLA retry + timeout standar untuk semua connector.

## 10. Temuan Lintas-Dokumen & Kontradiksi

1. Lokasi file Phase 0 vs rekomendasi Blueprint. Blueprint menyarankan
   `application/modules/pos_gateway/...`; Phase 0 Execution Pack menempatkan di
   `application/controllers/pos_gateway/`, `application/libraries/PosGateway/`, dan
   `application/models/`. Tidak dispesifikasikan mana yang final.
2. Nama library service. Blueprint menyebut `PosEventDispatchService`,
   `PosSettlementService`, `PosSyncService`, `PosPromoService`; Phase 0 hanya menyebut
   `CanonicalIngestService`. Service lain tidak dispesifikasikan sebagai file aktual.
3. Penomoran Phase. Blueprint: Phase 0 Foundation, 1 pyPOS Bridge Hardening, 2 Operational
   Stabilization, 3 Multi Provider. Checklist ERP: Phase 0 Baseline & Freeze Contract,
   1 Security Hardening, 2 Upload Pipeline Alignment, 3 Business Logic Hygiene,
   4 Stabilization. Sejalan tujuan, berbeda penomoran.
4. Endpoint `setUploadStream__GLG`: Blueprint menyebut "sumber utama pyPOS v2"; Mapping tidak
   memasukkannya ke Grup A/B; Checklist menyebut belum dipakai config pyPOS default. Status
   implementasi tidak dispesifikasikan eksplisit di Mapping.
5. Event `sync_check_update_legacy` vs `sync_pull` untuk `/eusvc/DataSync/doSync_auto`;
   keputusan final tidak dispesifikasikan.
6. Nama device: envelope canonical memakai `device_id`, request minimum Phase 0 memakai
   `machine_id`; relasi/pemetaan tidak dispesifikasikan eksplisit.
7. Status hook facade: Phase 1 menyatakan tujuh hook sudah dipasang; Mapping menyatakan tujuh
   endpoint "siap (hook ada)"; namun coding gateway "belum dieksekusi" dan config default OFF
   (hook ada tetapi belum aktif).
8. Jumlah event canonical: Blueprint menetapkan tujuh `event_type` wajib; Mapping Grup B
   menambahkan tujuh rencana event baru (belum diimplementasikan).
9. Tabel target ERP: Checklist menyebut `transaksi_consolidasi_v2`, `transaksi_point`; Payload
   checklist menyebut `transaksi`, `transaksi_data`, `transaksi_data_registry`. Relasi antar
   tabel tidak dipetakan eksplisit di satu dokumen.

## 11. Lampiran: Daftar File Sumber

| Nama File | Ukuran (bytes) | Topik H1 | Peran |
|---|---|---|---|
| `PYPOS_GATEWAY_BLUEPRINT_2026-04-09.md` | 8058 | Blueprint pyPOS-First Menuju POS Gateway Plugin Architecture | Arsitektur induk: prinsip, komponen, canonical contract, rollout, acceptance criteria |
| `PYPOS_ERP_CHECKLIST_RENCANA_2026-04-09.md` | 8845 | Checklist & Rencana Kerja Integrasi pyPOS <-> ERP | Checklist perbaikan, risiko, rencana Phase 0-4, kebutuhan data/kontrak |
| `PYPOS_ENDPOINT_GATEWAY_MAPPING_2026-04-09.md` | 3184 | Mapping Endpoint pyPOS -> POS Gateway (Phase 1) | Daftar endpoint Grup A/B, opsi migrasi, config facade |
| `POS_PAYLOAD_CHECKLIST.md` | 7932 | POS Payload Checklist (Strict Compile) | Aturan payload strict compile: field wajib, default aman, sanitizer |
| `POS_GATEWAY_PHASE0_EXECUTION_PACK_2026-04-09.md` | 2317 | POS Gateway Phase 0 Execution Pack | Fondasi teknis: file baru, SQL, aktivasi staging, contoh request |
| `POS_GATEWAY_PHASE1_LEGACY_FACADE_2026-04-09.md` | 2426 | POS Gateway Phase 1 - Legacy Facade Safe Mode | Facade endpoint lama, config flag, mode shadow/active, daftar hook |

Catatan: semua ukuran diambil dari filesystem sumber (byte). Semua dokumen bertanggal
2026-04-09 kecuali `POS_PAYLOAD_CHECKLIST.md` yang tidak mencantumkan tanggal.
