Qris-Soundbox/08-implementation-roadmap.md

Implementation Roadmap - QRIS Soundbox Platform v1

1. Prinsip Delivery

• kerjakan fondasi domain lebih dulu
• prioritaskan flow yang paling cepat memberi nilai bisnis
• buat modul yang bisa dipakai ulang untuk static, dynamic MQTT, dan dynamic API
• selesaikan admin visibility lebih awal untuk membantu operasi

2. Fase 0 - Persiapan Pra-Pelaksanaan

Tujuan

menyelaraskan fondasi teknis, governance, dan alur kerja supaya pembangunan fase berikutnya stabil dan konsisten

Deliverable Awal

• Tim dan role pelaksana disepakati (PO, Tech Lead, Backend, Infra, QA, Ops)
• Definisi source control workflow dan branching strategy
• CI/CD base pipeline siap (build, lint, security scan dasar)
• Lingkungan dev/test/staging dipastikan terpisah
• Standar kontrak siap pakai:
  • API contract final v1
  • MQTT topic dan payload final v1
  • schema migration baseline
• Skema status, kode error, dan idempotency key standar disepakati
• Definisi tracing & logging baseline (request_id, trace_id, event_id, correlation_id)
• Definition of Done (DoD) tim sinkron untuk tiap fase

Setup Operasional

• Issue tracker dan sprint board aktif
• Template ticket siap (story, acceptance criteria, checklist testing)
• Test environment data seed untuk merchant, outlet, terminal, device baseline
• Device simulator untuk static + MQTT-only + API-direct
• Monitoring awal:
• uptime endpoint
• callback receiver readiness check
• MQ publish/subscribe smoke test

Risiko Persiapan

• Scope creep pada Fase 0 -> batasi sampai API/MQTT contract dan baseline infrastruktur
• Ketidaksinkronan data model -> gunakan satu schema owner untuk review harian
• Keterlambatan perangkat test -> sediakan mock/simulator lebih awal
• Akses keamanan belum stabil -> pastikan IAM/token policy baseline sebelum endpoint sensitive dibuka

DoD Fase 0

• semua dokumen kontrak dan skema siap untuk implementasi
• repositori, pipeline, dan environment awal siap dipakai
• template sprint dan ticket aktif
• device simulator bisa mensimulasikan callback dan heartbeat
• tim siap masuk Fase 1 tanpa menunggu keputusan besar

3. Fase 1 - Foundation MVP

Tujuan

mengaktifkan merchant, device registry dasar, callback payment, dan static soundbox notification

Scope

• merchant registry dasar
• outlet dan terminal management dasar
• device registry/TMS dasar
• device binding
• callback/webhook receiver
• transaction registry
• notification service dasar
• MQTT push basic
• admin dashboard basic
• transaction monitoring basic

Output

• static soundbox flow berjalan end-to-end
• admin dapat melihat merchant, device, transaksi, status notif

Breakdown Implementasi Fase 1

Sprint 1 — Auth & Core Platform

• Setup repo struktur service dan pipeline
• Setup observability dasar (request_id/trace_id, structured log)
• Setup RBAC baseline untuk admin dan service-to-service auth
• Setup auth device token + rotation policy awal
• Setup migrasi awal sesuai schema MVP
• Endpoint onboarding merchant basic (/admin/merchants CRUD minimal)
• Endpoint outlet dan terminal basic (/admin/merchants/{merchantId}/outlets, /admin/outlets/{outletId}/terminals)
• Kriteria Selesai: data merchant/outlet/terminal bisa dibuat, diupdate, ditampilkan, dan dihapus sesuai kebutuhan flow

Sprint 2 — Device Foundation & Binding

• Endpoint device registry (/admin/devices CRUD)
• Endpoint konfigurasi awal device (/admin/devices/{deviceId}/bind, /unbind)
• Simpan binding aktif ke merchant, outlet, terminal dengan history
• Endpoint heartbeat device (/device/heartbeat) + tabel device_heartbeats
• Endpoint get device dan list heartbeat untuk ops
• Status device derived: online/stale/offline (berdasarkan last_seen_at)
• Kriteria Selesai: device bisa didaftarkan, di-bind, kirim heartbeat, dan terlihat statusnya di dashboard ops

Sprint 3 — Transaction Engine + Webhook Static

• Model transaksi inti untuk mode static (transactions + transaction_events)
• Webhook callback (/integrations/qris/callback) dengan verifikasi signature
• Idempotency key untuk callback dan penanganan duplicate callback
• State machine transaksi minimal: initiated, paid, failed, expired
• Audit dasar pada perubahan status transaksi
• Kriteria Selesai: callback memutakhirkan status transaksi dan terekam eventnya

Sprint 4 — Notifikasi Berbasis MQTT

• Event notification orchestrator sederhana dari status transaksi paid
• Publisher ke topic device devices/{deviceId}/downlink/payment/success
• Format payload sesuai kontrak MQTT draft
• Tabel notifications + status pengiriman (queued/sent/acknowledged/failed)
• Retry basic untuk status gagal dengan backoff sederhana (tanpa DLQ penuh di sprint ini)
• Kriteria Selesai: transaksi static memicu notifikasi sukses ke device yang terikat

Sprint 5 — Admin Monitoring & Readiness

• Admin transaction list + detail (/admin/transactions, /admin/transactions/{transactionId})
• Admin device/merchant list dasar
• Admin dashboard KPI minimal (tx hari ini, success rate, device online, pending notif)
• Endpoint retry notifikasi (/admin/transactions/{transactionId}/retry-notification)
• Monitoring kegagalan callback dan notifikasi
• Kriteria Selesai: alur static end-to-end terlihat utuh di admin (input callback -> status tx -> notif -> ack/failed)

Acceptance Criteria Fase 1

• Static QR flow end-to-end berjalan untuk minimal 1 merchant dan 1 device
• Callback duplicate tidak menambah transaksi ganda
• transaksi yang berhasil bayar tercatat paid dan membuat ledger entry placeholder
• status device online tersimpan saat heartbeat berhasil
• notifikasi sukses terkirim dengan event_id
• audit log mencatat aksi CRUD penting dan callback state changes

Dependency Diagram (Ringkas)

• Auth & Core dibutuhkan sebelum semua API/device flow
• Device Binding dibutuhkan sebelum transaksi menargetkan device
• Webhook dipasang sebelum notifikasi payment
• Notifikasi MQTT dipasang setelah transaction status paid stabil
• Admin monitoring dipasang setelah data transaksi dan notification pipeline berfungsi

Risiko Awal & Mitigasi (Fase 1)

• Mapping merchant-transaksi-device salah -> hard binding + validasi binding aktif saat kirim notifikasi
• Callback retry menyebabkan duplicate -> key composite pada partner reference + event idempotent check
• Device offline saat notify -> queue retry + status retrying
• Data konsistensi merchant/outlet/terminal tidak stabil -> blokir pembuatan transaksi jika binding tidak valid
• Audit minim -> tambahkan actor/action/entity id di setiap state mutasi penting

Definisi Selesai Fase 1

• static flow: scan-pay callback sukses -> transaksi paid -> notifikasi success diterima
• dashboard ops melihat transaksi, merchant, device, notification status
• retry basic untuk callback dan notification tersedia
• skenario utama: normal, duplicate callback, device tanpa binding, webhook invalid signature, device offline

4. Fase 2 - Dynamic QR Enablement

Scope

• QRIS dynamic orchestration
• MQTT uplink request flow
• API direct create QR flow
• capability resolver
• heartbeat dan online status
• config management dasar

Output

• support 3 jenis device flow
• dynamic QR bisa berjalan melalui MQTT-only dan API-direct

Breakdown Implementasi Fase 2

Sprint 1 — Capability & Routing

• Implementasi capability profile pada devices.capability_profile_json
• Resolver untuk menentukan flow:
  • STATIC device: tidak boleh create QR
  • DYNAMIC_MQTT device: create via MQTT request
  • DYNAMIC_API device: create via API langsung
• Middleware validasi capabilty dan izin per endpoint/action
• Kriteria Selesai: request invalid akan reject dengan error yang jelas (DEVICE_CAPABILITY_NOT_SUPPORTED, DEVICE_NOT_BOUND)

Sprint 2 — API-direct Dynamic QR

• Finalisasi endpoint POST /device/transactions/dynamic-qr
• Validasi payload: amount, terminal_id, request_id, device binding, capabilty
• Idempotency handling pada request device (idempotency key / request_id)
• Orchestrator QRIS dynamic:
  • panggil partner QRIS
  • simpan transactions status awaiting_payment
  • set transaction_events
• Response standard:
  • transaction_id, qr_payload, expires_at, status, request_id
• Kriteria Selesai: device API mendapatkan QR dinamis dan dapat memantau status pembayaran via callback

Sprint 3 — MQTT Dynamic Uplink/Downlink

• Implementasi handler uplink MQTT untuk request:
  • devices/{deviceId}/uplink/dynamic-qr/request
• Mapping request_id -> correlation_id untuk response
• Publish response ke:
  • devices/{deviceId}/downlink/dynamic-qr/response
• Idempotent request handling untuk MQTT retry
• Kriteria Selesai: device MQTT-only bisa membuat QR sukses minimal untuk normal flow

Sprint 4 — Heartbeat & Status Online yang Lebih Akurat

• Peningkatan endpoint heartbeat:
  • POST /device/heartbeat + MQTT heartbeat ingest terstandar
  • health score dari network_strength, battery_level, last_seen_at
• Derivasi status:
  • online, degraded, stale, offline
• Filter admin untuk status dan rentang health metric
• Kriteria Selesai: ops bisa memfilter device berdasarkan health dan mengurangi retry pada kondisi degraded

Sprint 5 — Konfigurasi Device Dasar

• Endpoint config:
  • GET /device/config
  • POST /device/config/ack
• Command config push via MQTT:
  • devices/{deviceId}/downlink/config/push
• Versioned config (config_version) dan idempotent ACK
• Kriteria Selesai: perubahan config tidak memutus flow pembayaran dan bisa disinkronkan ulang

Acceptance Criteria Fase 2

• 3 mode device berfungsi:
  • static: hanya notifikasi
  • dynamic-MQTT: request dan response QR via broker
  • dynamic-API: request dan response via API
• duplikasi request tidak membuat transaksi ganda
• setiap request punya korelasi penuh request_id/correlation_id
• callback tetap jadi sumber truth status bayar
• notifikasi sukses tetap melalui MQTT dengan payload terstandar

Dependency Diagram (Ringkas)

• Fase 2 dimulai setelah Fase 1 merchant/device/binding dan callback stabil
• API-direct bisa mulai setelah capability resolver dan transaksi core siap
• MQTT uplink membutuhkan MQTT adapter dan auth device yang siap dari Fase 1

DoD Fase 2

• Fitur create dynamic QR untuk API dan MQTT berfungsi
• dynamic-qr request/reply korelatif dan idempotent
• heartbeat/status device dipakai untuk operasional dan retry
• config push/ack dasar berjalan
• semua path mencatat trace/request IDs konsisten

5. Fase 3 - Finance Core

Scope

• ledger entries
• merchant payable
• fee engine
• settlement batch
• payout/disbursement
• settlement monitoring
• reconciliation basic

Output

• merchant balance dan settlement dapat dihitung dan dibayarkan

Breakdown Implementasi Fase 3

Sprint 1 — Ledger Foundation

• Finalisasi skema ledger_entries dan index query balance
• Implementasi akun per-merchant saldo running (materialized atau computed-on-read)
• Masukkan entri ledger saat transaksi berubah ke paid:
  • gross_income
  • platform_fee
  • merchant_payable
• Integrasi reconciliation placeholder agar entri ledger bisa ditandai reconciled=false
• Kriteria Selesai: setiap transaksi sukses menambah entri ledger yang benar

Sprint 2 — Fee Engine

• Mapping fee profile per merchant (fixed + percentage jika berlaku)
• Formula payout per transaksi:
  • merchant_payable = gross - fee
• Validasi konsistensi nilai (rounding, precision uang)
• Simpan audit metadata fee calculation
• Kriteria Selesai: perubahan fee profile langsung memengaruhi simulasi payable

Sprint 3 — Settlement Batch

• Buat job pembuat settlement periodik (harian/mingguan/period custom)
• Generate settlements dan settlement_items
• Auto-status: draft -> ready_to_pay -> paid / failed
• API basic:
  • POST /admin/settlements/run
  • GET /admin/settlements
  • GET /admin/settlements/{settlementId}
• Kriteria Selesai: batch untuk periode tertentu bisa dibuat dan diekspor

Sprint 4 — Disbursement/Payout

• Implementasi eksekusi payout via connector bank/disbursement
• Simpan payout_attempts (attempt, payload, response, status)
• Retry payout dasar + endpoint retry payout
• Fallback status jika payout gagal / pending
• Kriteria Selesai: payout attempt sukses atau tercatat gagal dengan alasan terstruktur

Sprint 5 — Monitoring Finance Dasar

• Dashboard settlement: gross, fee, net, status payout
• Reconciliation basic:
  • compare internal gross/net vs feed partner
  • status matched, mismatch, missing_internal, missing_external
• Kriteria Selesai: perbedaan finansial terlihat dan bisa di-escalate

Acceptance Criteria Fase 3

• saldo merchant dapat dihitung dari transaksi settled
• settlement batch dan payout tidak bergantung pada notifikasi device
• failed payout tidak menghapus transaksi dan tetap terjaga jejaknya
• fitur finance dapat dijalankan dengan idempotency dasar

Dependency Diagram (Ringkas)

• Bergantung penuh pada Fase 1–2 untuk transaction lifecycle + terminal/merchant/terminal binding
• Fee engine perlu fee profile dan transaksi yang valid
• Payout memerlukan settlement batch dan reconciliation record yang konsisten

DoD Fase 3

• ledger entries otomatis terbentuk saat transaksi paid
• settlement batch bisa dibuat, dipreview, dan dieksekusi
• payout attempt dan status payout terekam
• laporan mismatch reconciliation dasar tersedia
• audit log menutup operasi finance kritis

6. Fase 4 - Operations Hardening

Scope

• alerting
• audit log lengkap
• command center device
• duplicate suppression matang
• retry policies formal
• reconciliation exception handling
• role-based access matang

Output

• sistem siap dioperasikan dengan volume lebih tinggi

Breakdown Implementasi Fase 4

Sprint 1 — Audit & Governance

• Audit log lengkap pada aksi kritis:
  • onboarding approve/reject
  • binding/unbinding device
• Capture before_json dan after_json
• Searchable audit view dengan filter actor/entity/action/time
• Kriteria Selesai: perubahan konfigurasi penting dapat ditelusuri 1 klik

Sprint 2 — Alerting & Observability

• Alert dasar:
  • callback failure rate naik
  • notification failed spike
  • heartbeat timeout massal
  • payout failed beruntun
• Integrasi dashboard metrics dasar + error budget sederhana
• Kriteria Selesai: alert operasional muncul ke channel ops

Sprint 3 — Retry & Duplicate Suppression Matang

• Idempotency layer diperluas:
  • callback
  • dynamic QR request
  • MQ downlink
• Retry policy configurable per class event
• DLQ / dead-letter untuk kegagalan permanen
• Kriteria Selesai: event gagal tidak membeku dan dapat ditindaklanjuti

Sprint 4 — Device Command Center

• Endpoint command:
  • POST /admin/devices/{deviceId}/commands
  • track ack melalui device_commands
• Command push via MQTT
• Retry command terbatas + timeout handling
• Kriteria Selesai: ops bisa mengirim perintah tes/diagnostic

Sprint 5 — Security & RBAC Matang

• RBAC matrix admin ops / finance / support
• Audit permission perubahan role
• Peningkatan token/device auth (exp, rotasi, revocation)
• Kriteria Selesai: akses sesuai prinsip least privilege

Acceptance Criteria Fase 4

• kejadian kritis punya jejak audit lengkap
• sistem lebih stabil pada kondisi gagal sementara
• device command operasional tersedia
• kontrol akses sesuai tugas/otoritas

Dependency Diagram (Ringkas)

• Audit dan RBAC dimulai paralel, paling optimal setelah model user-role stabil
• Alerting memerlukan observability baseline dari phase sebelumnya
• Retry matang mengunci keandalan Fase 2–3

DoD Fase 4

• audit log searchable dan immutable
• alert operasional aktif untuk skenario kegagalan utama
• duplicate suppression menutup 95% replay issue normal
• command center mencatat status end-to-end
• role permission change tervalidasi dan tercatat

7. Fase 5 - Merchant Experience

Scope

• merchant portal
• merchant transaction view
• merchant settlement view
• device visibility untuk merchant
• support/help flow

Output

• merchant bisa self-serve melihat transaksi, settlement, dan device miliknya

Breakdown Implementasi Fase 5

Sprint 1 — Portal Dasar

• GET /merchant/me, GET /merchant/dashboard/summary
• Tabel transaksi dan settlement merchant
• Akses terbatas ke entitas milik merchant
• Kriteria Selesai: merchant dapat login dan melihat saldo/riwayat dasar

Sprint 2 — Transaction Detail & Device Visibility

• Detail transaksi merchant (status timeline + raw callback summary)
• Tabel device merchant, status online, last seen
• Pembatasan data per tenant/merchant
• Kriteria Selesai: merchant bisa menyaring sendiri transaksi/perangkatnya

Sprint 3 — Settlement & Support

• Halaman settlement history + settlement detail
• Informasi payout status dan retry reason
• Support center untuk tiket/FAQ awal
• Kriteria Selesai: merchant bisa memantau proses pencairan

Sprint 4 — Self-Serve Preferences

• Pengaturan notifikasi merchant dan outlet/terminal sederhana
• Delegasi role akses team merchant
• Kriteria Selesai: pengelolaan akun merchant lebih mandiri

Acceptance Criteria Fase 5

• merchant self-serve tidak bergantung pada ops untuk data transaksi normal
• hak akses tenant kuat, tidak bocor ke merchant lain
• settlement & device informasi cukup untuk operasional harian merchant

Dependency Diagram (Ringkas)

• Fase 5 menunggu Fase 1–4 untuk data transaksi, settlement, binding, audit, dan RBAC
• Fitur support berjenjang setelah data core stabil

DoD Fase 5

• merchant login dan melihat dashboard, transaksi, settlements
• tenant isolation valid di semua query merchant
• device visibility dan riwayat pembayaran sesuai tenant
• dokumentasi onboarding pengguna internal merchant siap dipakai

8. Rekomendasi Urutan Pengerjaan Tim

1. finalisasi entity dan schema awal
2. finalisasi API dan MQTT contract
3. bangun admin/tms/transaction monitoring dasar
4. bangun static notification flow
5. bangun dynamic QR flows
6. bangun ledger dan settlement
7. bangun merchant portal

9. Execution Now (Tanpa Jadwal)

Fase 0 — Segera Dijalankan Hari Ini

• finalisasi dokumen API contract dan MQTT contract ke versi stabil untuk coding
• finalize ownership field API: siapa yang maintain merchant, transaction, device, ledger, settlement
• finalisasi error code standar dan mapping HTTP status
• buat branch awal feat/phase-0 dan template commit message
• siapkan repositori pipeline baseline untuk lint/build/test smoke
• setup environment list: dev, staging, production target
• siapkan dataset seed:
• minimal 2 merchant
• minimal 2 outlet dan terminal
• minimal 3 device: static, dynamic-mqtt, dynamic-api
• siapkan MQTT broker topik minimal:
• devices/{deviceId}/downlink/payment/success
• devices/{deviceId}/uplink/dynamic-qr/request
• devices/{deviceId}/downlink/dynamic-qr/response
• devices/{deviceId}/downlink/config/push
• simpan semua hasil keputusan di DECISIONS_LOG.md (buat file baru nanti)

Fase 1 — Langkah Eksekusi Urutan Langsung

Step 1 — Core Foundation

• setup service skeleton sesuai arsitektur layer
• implement RBAC baseline admin + device auth
• implement migrasi DB awal untuk merchant, outlet, terminal, device, binding, transaksi, notifications
• implement request_id, trace_id, event_id generator standar
• buat endpoint create/get/list merchant
• buat endpoint create/get/list outlet dan terminal
• buat endpoint binding device (bind/unbind)
• acceptance: CRUD merchant/device/terminal bisa dipakai dari admin

Referensi Step 1 Detail

• gunakan 12-fase1-step1-core-foundation-spec.md untuk API detail, schema, dan acceptance per paket
• keputusan teknis wajib mengikuti DECISIONS_LOG.md

Step 2 — Callback dan State Transaction

• implement webhook callback /integrations/qris/callback dengan signature check
• implement idempotency callback dan event store transaction_events
• implement state machine transaksi minimal
• simpan data callback raw di event
• acceptance: duplicate callback tidak duplikasi state akhir

Referensi Step 2 Detail

• gunakan 13-fase1-step2-callback-transaction-spec.md untuk validasi event, idempotency callback, dan state machine

Step 3 — Static Notification

• implement notification orchestrator pada state paid
• implement publish MQTT success ke device target
• simpan delivery state dan retry sekali-dua kali
• implement endpoint retry notification admin
• acceptance: static flow menghasilkan notifikasi sukses ke device bound

Referensi Step 3 Detail

• gunakan 14-fase1-step3-notification-spec.md untuk event flow, payload, status retry, dan endpoint retry

Step 4 — Device & Ops Monitoring

• implement heartbeat endpoint dan status derivation
• implement admin list device, transaction, merchant + detail basic
• implement dashboard KPI minimal
• acceptance: operator bisa melihat health device, transaksi hari ini, dan notifikasi pending

Referensi Step 4 Detail

• gunakan 16-fase1-step4-monitoring-spec.md untuk endpoint heartbeat, status derivation, KPI dashboard, dan retry-notification

Cara Mulai Kode Hari Pertama (Checklist)

• buat modul shared untuk idempotency + tracing + error format
• buat modul auth untuk admin dan device token
• buat modul merchant dan location (outlet/terminal) terlebih dulu
• buat modul device dan binding service
• buat modul transaction state machine dan callback handler
• buat modul notification publisher MQTT
• buat modul monitoring KPI dasar admin
• verifikasi Fase 1 DoD sebelum lanjut Fase 2
• ikuti urutan kerja di 17-fase1-implementation-task-pack.md

Aturan Kerja Eksekusi

• jangan buka perangkat lain jika API contract belum final
• jangan lanjut dynamic QR sebelum callback + static notification stabil
• setiap PR harus menyertakan:
• skenario happy path
• 1 edge case
• 1 idempotency case