Qris-Soundbox/DECISIONS_LOG.md

# Decisions Log — QRIS Soundbox Platform

Log keputusan arsitektur dan implementasi yang harus dijadikan acuan eksekusi.

## Format Entri
- ID: [D-XXX]
- Tanggal:
- Keputusan:
- Alasan:
- Dampak / implikasi:
- Status:

## D-001 — Basis Implementasi Fase 0 dan 1
- Tanggal: 2026-05-23
- Keputusan:
  - Menjalankan eksekusi langsung berdasarkan fase roadmap, tanpa pembuatan jadwal rinci.
- Alasan:
  - Tim sudah punya pembagian fase yang jelas dan siap mulai implementasi langsung.
- Dampak / implikasi:
  - Fokus pada deliverable per fase dan DoD, bukan timeline.
- Status: Active

## D-002 — Scope Fase 1 Step 1
- Tanggal: 2026-05-23
- Keputusan:
  - Step 1 Fase 1 dibatasi pada core foundation: auth baseline, schema MVP, merchant/outlet/terminal/device/binding, observability dasar.
- Alasan:
  - Memastikan jalur static payment bisa dipersiapkan stabil sebelum dynamic flow.
- Dampak / implikasi:
  - Fitur lain (settlement, dynamic QR, merchant portal) ditunda sampai Step 1 stabil.
- Status: Active

## D-003 — API Contract Error Standard
- Tanggal: 2026-05-23
- Keputusan:
  - Semua response error mengikuti envelope seragam:
    - `code`, `message`, `details`, `request_id`, `timestamp`.
- Alasan:
  - Memudahkan debug dan tracing lintas service/device.
- Dampak / implikasi:
  - Semua handler API harus mematuhi middleware response formatter yang sama.
- Status: Active

## D-004 — Traceability Requirement
- Tanggal: 2026-05-23
- Keputusan:
  - Semua request harus membawa `request_id`; webhook/device callback harus dihubungkan dengan `trace_id` jika multi-step.
- Alasan:
  - Root-cause analysis perlu konteks end-to-end dari callback sampai notifikasi.
- Dampak / implikasi:
  - Framework logging dan parser event wajib men-generate field ini secara konsisten.
- Status: Active

## D-005 — Idempotency Rule
- Tanggal: 2026-05-23
- Keputusan:
  - Setiap path sensitif terhadap duplicate (create merchant/create device/binding/webhook request/dynamic QR nanti) wajib men-support idempotency key/table.
- Alasan:
  - Menghindari double create, double binding, dan state drift akibat retry.
- Dampak / implikasi:
  - Menambah kebutuhan service/DB untuk `idempotency_keys` sejak awal Fase 1.
- Status: Active

## D-006 — Device Binding
- Tanggal: 2026-05-23
- Keputusan:
  - Notifikasi pembayaran hanya boleh dipush ke device dari binding aktif yang valid (active_flag=true).
- Alasan:
  - Mencegah notifikasi salah kirim jika device pernah dipindahkan antar outlet/terminal.
- Dampak / implikasi:
  - Query notification selalu harus resolve binding aktif secara explicit.
- Status: Active

## D-007 — Fallback Strategy untuk Fase 1
- Tanggal: 2026-05-23
- Keputusan:
  - Retry MQTT pada Fase 1 memakai retry sederhana (fixed/backoff pendek), tanpa DLQ kompleks.
- Alasan:
  - Menghemat effort awal sambil menjaga fitur core berjalan.
- Dampak / implikasi:
  - Fase 4 mengelola policy DLQ dan retry matang.
- Status: Active

## D-008 — Minimal RBAC untuk Mulai Eksekusi
- Tanggal: 2026-05-23
- Keputusan:
  - Implement RBAC baseline minimum di Fase 1 (admin-only) sambil menjaga token device terpisah.
- Alasan:
  - Mengurangi risiko akses silang awal tanpa memperlambat pengembangan.
- Dampak / implikasi:
  - Permission matrix akan disempurnakan di Fase 4.
- Status: Active

## D-009 — Dokumentasi Eksekusi Step 1
- Tanggal: 2026-05-23
- Keputusan:
  - Spesifikasi detail Step 1 dituangkan di `12-fase1-step1-core-foundation-spec.md`.
- Alasan:
  - Menghindari ketidakpastian saat tim mulai coding.
- Dampak / implikasi:
  - Semua implementer wajib merujuk dokumen ini saat menyiapkan branch dan PR.
- Status: Active

## D-010 — Webhook Signature dan Parsing
- Tanggal: 2026-05-23
- Keputusan:
  - Semua callback harus divalidasi signature-nya terlebih dahulu; jika tidak valid, respons harus `401` dan tidak boleh melakukan perubahan state apapun.
- Alasan:
  - Payment callback adalah sumber trust utama dan harus dijaga dari spoofing/replay.
- Dampak / implikasi:
  - Service callback wajib mengimplementasikan validator HMAC (atau skema cryptographic sesuai partner) sebelum mapping transaksi.
- Status: Active

## D-011 — Callback Idempotency di Level Transaksi
- Tanggal: 2026-05-23
- Keputusan:
  - Callback duplikat harus diidentifikasi deterministik dari `partner_reference + payment_status + partner_event_id` dan diperlakukan idempotent.
- Alasan:
  - Callback retry sangat umum dari partner dan dapat memicu double state update.
- Dampak / implikasi:
  - state transition dilakukan hanya jika perubahan state valid sesuai mesin state.
- Status: Active

## D-012 — Evented Transaction State Change
- Tanggal: 2026-05-23
- Keputusan:
  - Setiap perubahan state transaksi harus menghasilkan `transaction_events` agar Step 3 dan observability bisa berjalan.
- Alasan:
  - Auditability dan troubleshooting menuntut timeline per transaksi.
- Dampak / implikasi:
  - update transaksi tanpa menulis event dianggap bug di Step 1.
- Status: Active

## D-013 — Terminal Event `paid` sebagai Trigger Notification
- Tanggal: 2026-05-23
- Keputusan:
  - Notifikasi pembayaran di Step 3 harus dipicu dari event internal status `paid`, bukan dari polling callback.
- Alasan:
  - Menghindari race dan duplikasi notifikasi.
- Dampak / implikasi:
  - Implementasi Step 3 harus subscribe dan consume event transaction paid.
- Status: Active

## D-014 — Retry Notifikasi Fase 1
- Tanggal: 2026-05-23
- Keputusan:
  - Step 3 menggunakan retry dasar maksimum 3 kali dengan jadwal 15/30/60 detik.
- Alasan:
  - Menyeimbangkan reliability dan kecepatan operasional tanpa kompleksitas DLQ penuh pada fase awal.
- Dampak / implikasi:
  - `notifications.retry_count` wajib ditulis dan dibatasi maksimal 3.
- Status: Active

## D-015 — Notifikasi Tanpa Ack Fase 1
- Tanggal: 2026-05-23
- Keputusan:
  - Pada fase 1, absence of MQTT ack tidak dianggap error akhir; status sukses ditentukan dari publish outcome, bukan ack dari device.
- Alasan:
  - Device ecosystem belum konsisten untuk ack schema, dan goal fase 1 adalah stabilitas flow utama.
- Dampak / implikasi:
  - `ack_status` bisa `not_supported`, dan operasi tetap lanjut dengan monitoring via retry/publish status.
- Status: Active

## D-016 — Heartbeat Status Threshold Fase 1
- Tanggal: 2026-05-23
- Keputusan:
  - Definisi status device ditetapkan: online (<90s), degraded (signal/battery buruk), stale (<15 menit), offline (>15 menit) berdasarkan `last_seen_at`.
- Alasan:
- Konsistensi status dibutuhkan untuk ops triage cepat.
- Dampak / implikasi:
- Setiap list/detail device menampilkan status yang dihitung dari rule yang sama.
- Status: Active

## D-017 — Dashboard KPI Fase 1
- Tanggal: 2026-05-23
- Keputusan:
  - Dashboard ops minimum menampilkan: transaksi hari ini, success rate hari ini, active devices, pending notifications, stale/offline counts.
- Alasan:
  - Tim operasi perlu indikator cepat tanpa menunggu custom analytics.
- Dampak / implikasi:
- Endpoint summary dashboard wajib dihitung dari data transaksi/device/notification inti.
- Status: Active

## D-018 — Pencairan Dana Non-Tersentral per Merchant
- Tanggal: 2026-05-24
- Keputusan:
  - Pencairan dana tidak dilakukan di rekening perusahaan; setiap merchant memakai rekening tujuan sendiri (atau reference payout miliknya) untuk settlement.
- Alasan:
  - Menghindari ketergantungan izin/operasional PJP di tahap awal dan mempercepat launch MVP.
- Dampak / implikasi:
  - Schema dan model onboarding merchant memakai `payout_account_reference`/rekening merchant, bukan rekening vault pusat.
  - Modul settlement platform difokuskan ke rekonsiliasi, status payout, dan visibility, bukan pengelolaan rekening pusat.
  - Callback payout dan payout execution dianggap partner-oriented (tergantung integrasi penyedia), bukan core di fase awal.
- Status: Active

## D-019 — Fase 1 Audit Log dan Ledger Placeholder
- Tanggal: 2026-05-26
- Keputusan:
  - Fase 1 mencatat audit log untuk aksi admin/webhook penting dan membuat ledger placeholder `gross_income` saat transaksi berubah ke `paid`.
- Alasan:
  - Acceptance Fase 1 membutuhkan audit aksi CRUD penting, callback state changes, dan placeholder ledger untuk transaksi sukses tanpa menunggu modul finance penuh.
- Dampak / implikasi:
  - `audit_logs` menjadi sumber trace operasional awal untuk entity penting.
  - `ledger_entries` Fase 1 hanya placeholder gross income; fee/platform payable detail tetap masuk Fase 3.
  - Duplicate paid callback tetap idempotent dan tidak membuat ledger duplikat karena unique key per `transaction_id + entry_type`.
- Status: Active

## D-020 — Awal Fase 2 Dynamic QR API-Direct
- Tanggal: 2026-05-26
- Keputusan:
  - Fase 2 dimulai dari capability resolver dan endpoint `POST /device/transactions/dynamic-qr` untuk device `communication_mode=api`.
  - Dynamic QR API-direct memakai mock QRIS payload lokal sampai integrasi partner QRIS tersedia.
- Alasan:
  - Capability/routing harus stabil sebelum MQTT dynamic dan config push dibangun.
  - Mock partner memungkinkan transaksi dynamic tersimpan dan callback Fase 1 tetap diuji sebagai source of truth.
- Dampak / implikasi:
  - Device static/MQTT yang tidak memiliki capability `dynamic_qr.api_direct` ditolak dengan `DEVICE_CAPABILITY_NOT_SUPPORTED`.
  - Device wajib punya binding aktif ke terminal `qr_mode=dynamic_api`; jika tidak, API mengembalikan `DEVICE_NOT_BOUND`.
  - Response dynamic QR idempotent memakai `Idempotency-Key` atau `request_id`, dan transaksi dibuat `awaiting_payment`.
  - Callback paid tetap memakai endpoint webhook yang sama untuk mengubah transaksi menjadi `paid` dan memicu notifikasi.
- Status: Active

## D-021 — MQTT Dynamic QR dan Device Config Fase 2
- Tanggal: 2026-05-26
- Keputusan:
  - MQTT dynamic QR Fase 2 diimplementasikan sebagai HTTP simulator endpoint `POST /device/mqtt/uplink/dynamic-qr/request` yang mencatat uplink/downlink ke `mqtt_messages`.
  - Config push memakai `PATCH /admin/devices/{deviceId}/config`, disimpan di `device_configs`, dipublish ke MQTT outbox, lalu device mengirim `POST /device/config/ack`.
- Alasan:
  - Belum ada broker MQTT sungguhan di stack lokal, tapi kontrak topic/payload dan idempotency perlu bisa diuji end-to-end.
  - Outbox membuat downlink response/config push observable lewat admin sebelum integrasi broker asli.
- Dampak / implikasi:
  - Saat broker MQTT dipasang, `mqtt_messages` bisa menjadi outbox/trace awal untuk adapter broker.
  - Dynamic MQTT request memakai `request_id` sebagai `correlation_id` dan idempotency key.
  - Device config selalu versioned; ACK dicatat terpisah di `device_config_acks`.
- Status: Active

## D-022 — Config Drift dan Retry Push Fase 2
- Tanggal: 2026-05-26
- Keputusan:
  - Fase 2 menambahkan status drift config device melalui `GET /admin/devices/{deviceId}/config/status`.
  - Retry config dilakukan via `POST /admin/devices/{deviceId}/config/retry-push` tanpa menaikkan `config_version`.
  - ACK config dari device juga dicatat sebagai uplink trace di `mqtt_messages` dengan `message_type=config_ack`.
- Alasan:
  - Operasi perlu membedakan config `applied`, `pending_ack`, `failed_ack`, `stale_ack`, dan `never_pushed` sebelum broker MQTT sungguhan dipasang.
  - Retry harus mengirim ulang desired config yang sama agar idempotent dan tidak membuat drift versi buatan.
- Dampak / implikasi:
  - Config yang sudah `applied` tidak boleh di-retry kecuali admin mengirim `force=true`.
  - `mqtt_messages` menjadi timeline awal untuk config push dan ACK device.
  - Saat broker MQTT asli masuk, endpoint retry tetap menjadi trigger adapter/outbox, bukan tempat menyimpan logic konfigurasi baru.
- Status: Active

## D-023 — Health Summary Device Fase 2
- Tanggal: 2026-05-26
- Keputusan:
  - Endpoint admin device menambahkan `health_summary` berisi `status`, `score`, `age_seconds`, dan `reasons`.
  - `derived_status` tetap dipertahankan untuk kompatibilitas UI, namun nilainya berasal dari rule health summary yang sama.
- Alasan:
  - Operasi membutuhkan konteks kenapa device online/degraded/stale/offline, bukan hanya label status.
  - Skor 0-100 memudahkan sorting/filter dashboard tanpa mengubah threshold status Fase 1.
- Dampak / implikasi:
  - Status masih mengikuti threshold Fase 1: online <90 detik, stale >90 detik, offline >15 menit, degraded untuk sinyal/baterai buruk.
  - UI dapat memakai `health_summary.reasons` untuk badge/tooltip ops.
- Status: Active

## D-024 — UI Ops Device Fase 2
- Tanggal: 2026-05-26
- Keputusan:
  - UI device registry dan device technical detail menampilkan `health_summary` dan config delivery status.
  - Retry config push tersedia dari drawer device registry dan halaman detail device.
- Alasan:
  - Operator perlu melihat status Fase 2 tanpa membuka raw payload/API response.
  - Retry config adalah tindakan operasional langsung, sehingga harus dekat dengan status drift config.
- Dampak / implikasi:
  - UI memakai endpoint `GET /admin/devices/{deviceId}/config/status` dan `POST /admin/devices/{deviceId}/config/retry-push`.
  - `derived_status` tetap dipakai sebagai fallback/compatibility, sementara health score/reasons menjadi konteks tambahan.
- Status: Active

## D-025 — Dynamic QR Expiry Sweep Fase 2
- Tanggal: 2026-05-26
- Keputusan:
  - Dynamic QR `awaiting_payment` yang melewati `expired_at` dapat ditutup oleh sweep internal `POST /admin/transactions/expire-due`.
  - Sweep hanya berlaku untuk transaksi `qr_mode=dynamic` dan status `awaiting_payment`.
- Alasan:
  - Fase 2 tidak boleh bergantung penuh pada callback partner untuk menutup QR yang kadaluarsa.
  - Expiry internal menjaga daftar transaksi pending tetap akurat untuk ops dan device flow.
- Dampak / implikasi:
  - Sweep menulis `STATE_CHANGED` event dengan reason `dynamic_qr_expired`.
  - Callback paid yang datang setelah transaksi sudah `expired` tetap ditolak oleh state transition guard.
  - Endpoint admin ini bisa menjadi dasar scheduler/background worker saat fase operasional berikutnya.
- Status: Active