# Checklist & Rencana Kerja Integrasi pyPOS <-> ERP

Tanggal dokumen: 2026-04-09  
Status: Draft konteks teknis (belum eksekusi perbaikan kode)

## 1. Tujuan Dokumen

Dokumen ini dipakai sebagai konteks kerja lanjutan untuk:

1. Menyamakan contract antara pyPOS (consumer) dan ERP (provider).
2. Menurunkan risiko duplikasi, data tidak konsisten, dan celah keamanan.
3. Menjadi checklist eksekusi bertahap yang aman untuk sistem legacy mission-critical.

## 2. Ringkasan Alur Saat Ini

1. pyPOS upload file transaksi ke endpoint ERP.
2. ERP proses file masuk ke `transaksi_consolidasi_v2`.
3. ERP generate ke `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.

## 3. Peta Contract Endpoint (Ringkas)

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

## 4. Risiko Utama

### 4.1 Risiko Persisten (sedang aktif)

- [ ] Settlement bisa dipanggil tanpa auth enforcement yang aktif penuh.
- [ ] Guard JWT global dapat efektif tidak enforced jika config default tetap longgar.
- [ ] pyPOS masih mengarah ke endpoint upload legacy, bukan endpoint contract baru.
- [ ] Endpoint `checkFreeProdukQuota` menulis data (side effect pada endpoint check).
- [ ] Controller CLI transaksi dapat dipanggil via web (bukan CLI-only guard).

### 4.2 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/bermasalah (non-blocking).
- [ ] Metadata response menyatakan policy auth ketat saat runtime guard belum benar-benar enforced.

## 5. 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 (tidak campur aduk).

### B. Security & Access Control

- [ ] Aktifkan enforcement JWT sesuai policy produksi.
- [ ] Kembalikan guard auth pada endpoint kritikal yang saat ini di-comment.
- [ ] Terapkan pembatasan CLI-only pada endpoint proses batch/kompilasi.
- [ ] Audit endpoint publik yang boleh no-auth dan dokumentasikan justifikasinya.

### C. Data Integrity & Idempotency

- [ ] Migrasi pyPOS ke endpoint upload idempotent (`setUploadStream__GLG`) secara bertahap.
- [ ] Wajibkan `idempotency_key` tersedia 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 untuk error operasional vs debug.
- [ ] Definisikan alert dasar untuk antrean compile/settlement yang 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 untuk upload dan settlement.
- [ ] Uji rollback dan recovery setelah kegagalan parsial.

## 6. Rencana Kerja Bertahap

## Phase 0 - Baseline & Freeze Contract (Prioritas P0)

Tujuan:
- Membekukan contract sekarang sebagai baseline sebelum ubah perilaku.

Output:
- Dokumen contract v1.
- Matriks endpoint: auth, idempotency, effect (read/write), SLA retry.
- Daftar endpoint yang boleh no-auth (jika ada) beserta alasan.

## Phase 1 - Security Hardening (P0)

Tujuan:
- Menutup akses tidak sah pada endpoint kritikal tanpa memutus operasional existing.

Output:
- Guard auth aktif untuk endpoint kritikal.
- Policy JWT runtime konsisten (enabled + enforce).
- Guard CLI-only untuk proses batch yang seharusnya tidak web-exposed.

## Phase 2 - Upload Pipeline Contract Alignment (P1)

Tujuan:
- Menyamakan pyPOS dan ERP pada jalur upload + compile status.

Output:
- pyPOS memakai endpoint upload idempotent.
- `idempotency_key` hadir konsisten di response dan log.
- Mekanisme fallback terkontrol untuk client lama selama masa transisi.

## Phase 3 - Business Logic Hygiene (P1)

Tujuan:
- Menjaga endpoint sesuai semantic (check tidak boleh write) dan mencegah race.

Output:
- Refactor endpoint free produk menjadi read-only check dan write terpisah.
- `use_preorder` punya mekanisme lock/consume atomik.

## Phase 4 - Stabilization & Monitoring (P2)

Tujuan:
- Memastikan perubahan aman di produksi legacy multi-user.

Output:
- Contract tests + regression tests lulus.
- Dashboard/SQL health checks untuk antrean upload/compile/settlement.
- Runbook troubleshooting dan rollback singkat.

## 7. Kebutuhan Data/Konteks Saat Lanjut Eksekusi

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

## 8. Artefak Referensi Teknis

### ERP

- `application/controllers/eusvc/NonRest.php`
- `application/controllers/eusvc/DataSync.php`
- `application/controllers/eusvc/ProDiskon.php`
- `application/modules/penjualan/controllers/ActivityReportApi.php`
- `application/controllers/CliTransaksi.php`
- `application/controllers/eusvc/JwtAuthHelper.php`
- `docs/POS_PAYLOAD_CHECKLIST.md`
- `docs/POS_PRECHECK_2026-03-02.json`

### pyPOS (Read-Only)

- `W:\pypos_4april\Python POS\config.json`
- `W:\pypos_4april\Python POS\pypos\core\base_service.py`
- `W:\pypos_4april\Python POS\pypos\modules\sinkronisasi\services\export_upload_api_service.py`
- `W:\pypos_4april\Python POS\pypos\modules\sinkronisasi\services\export_upload_service.py`
- `W:\pypos_4april\Python POS\pypos\modules\sinkronisasi\services\settlement_direct_service.py`
- `W:\pypos_4april\Python POS\pypos\modules\sinkronisasi\services\sync_api_service.py`
- `W:\pypos_4april\Python POS\pypos\modules\penjualan\services\preorder_api_service.py`

### Sampel File Upload

- `W:\cdn\pos\sumber_boga_pypos\2026\04\08`

## 9. Open Questions (Untuk Sesi Berikutnya)

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

## 10. Catatan Kompatibilitas Legacy

Dokumen ini disusun untuk konteks sistem:

- PHP 5.6
- CodeIgniter 3
- MariaDB 10
- CentOS 7

Prinsip eksekusi perubahan berikutnya:

1. Jaga backward compatibility selama transisi contract.
2. Hindari modernisasi stack yang mengubah risk profile sistem inti.
3. Prioritaskan integritas data transaksi, audit trail, dan stabilitas operasional.

## 11. Dokumen Lanjutan

Blueprint arsitektur 1 pintu + plugin ada di:

- `docs/PYPOS_GATEWAY_BLUEPRINT_2026-04-09.md`