Initial commit

04-device-flows.md

@@ -0,0 +1,93 @@
+# Device Flows - QRIS Soundbox Platform v1
+
+## 1. Soundbox Static Flow
+### Karakteristik
+- QR merchant bersifat statis
+- customer input nominal di aplikasi bank/e-wallet
+- device menerima notifikasi hasil transaksi
+
+### Sequence
+1. customer scan QR statis merchant
+2. customer input nominal dan submit pembayaran
+3. partner/bank memproses pembayaran
+4. callback payment masuk ke backend
+5. backend verifikasi signature dan status
+6. transaction state diupdate
+7. ledger internal diupdate
+8. backend lookup binding merchant -> outlet -> terminal -> device
+9. notification event dibuat
+10. MQTT push ke device
+11. device memainkan audio dan/atau menampilkan nominal
+
+### Catatan
+- challenge utama adalah mapping transaksi ke device yang tepat
+- perlu binding yang presisi dan fallback jika device offline
+
+## 2. Soundbox Dynamic MQTT-only Flow
+### Karakteristik
+- device tidak bisa hit API langsung
+- request create QR lewat MQTT
+- response dan success notification lewat MQTT
+
+### Sequence
+1. merchant input nominal di device
+2. device publish request create QR ke topic uplink
+3. backend MQTT adapter menerima request
+4. device auth dan capability check dilakukan
+5. backend validasi nominal, merchant binding, idempotency key
+6. backend request QR dynamic ke partner QRIS
+7. transaction dibuat dengan status pending/awaiting_payment
+8. response QR payload dipublish ke topic device
+9. device render QR di layar
+10. customer scan dan bayar
+11. callback payment masuk ke backend
+12. backend verifikasi dan update transaction
+13. ledger internal diupdate
+14. notification success dipublish ke device
+15. device memainkan audio sukses
+
+### Catatan
+- wajib ada request_id / correlation_id
+- retry device tidak boleh menimbulkan double create
+- MQTT handler jangan jadi pusat logic, hanya ingress adapter
+
+## 3. Soundbox Dynamic API-direct Flow
+### Karakteristik
+- device dapat call API backend langsung
+- create QR dilakukan secara sinkron via API
+- success notification tetap realtime via MQTT
+
+### Sequence
+1. merchant input nominal di device
+2. device call API create dynamic QR
+3. backend auth device dan validasi payload
+4. backend check capability dan idempotency
+5. backend request QR dynamic ke partner QRIS
+6. transaction dibuat dengan status pending
+7. response API berisi QR payload + expiry + transaction reference
+8. device render QR
+9. customer scan dan bayar
+10. callback payment masuk ke backend
+11. backend verifikasi dan update transaction
+12. ledger internal diupdate
+13. success notification dikirim via MQTT
+14. device memainkan audio sukses
+
+### Catatan
+- ini flow paling bersih untuk engineering
+- request-response lebih natural, observability lebih baik
+
+## 4. Heartbeat Flow
+1. device kirim heartbeat secara periodik
+2. backend update last_seen_at
+3. backend simpan health metrics yang tersedia
+4. status device diturunkan menjadi online/stale/offline/degraded
+5. ops dashboard menampilkan alert bila perlu
+
+## 5. Provisioning Flow
+1. device didaftarkan di TMS
+2. credential/token/certificate dibuat
+3. device dibinding ke merchant/outlet/terminal
+4. config profile ditetapkan
+5. device mengambil config awal atau dikirimkan via channel yang tersedia
+6. device aktif dan mulai heartbeat