Initial commit

06-mqtt-contract-draft.md

@@ -0,0 +1,103 @@
+# MQTT Contract Draft - QRIS Soundbox Platform v1
+
+## 1. Prinsip MQTT
+- topic harus namespaced per device atau tenant
+- device hanya boleh publish/subscribe ke topic yang diizinkan
+- semua pesan request harus punya request_id
+- semua pesan response harus punya correlation_id
+- notifikasi harus punya event_id untuk dedup
+
+## 2. Topic Convention
+### Uplink dari device
+- `devices/{deviceId}/uplink/heartbeat`
+- `devices/{deviceId}/uplink/dynamic-qr/request`
+- `devices/{deviceId}/uplink/config/ack`
+- `devices/{deviceId}/uplink/command/ack`
+
+### Downlink ke device
+- `devices/{deviceId}/downlink/dynamic-qr/response`
+- `devices/{deviceId}/downlink/payment/success`
+- `devices/{deviceId}/downlink/config/push`
+- `devices/{deviceId}/downlink/command`
+
+## 3. Heartbeat Payload
+```json
+{
+  "message_type": "heartbeat",
+  "device_id": "sbx_001",
+  "timestamp": "2026-05-23T10:00:00Z",
+  "firmware_version": "1.0.3",
+  "state": "idle",
+  "network_strength": 78,
+  "battery_level": 92
+}
+```
+
+## 4. Dynamic QR Request Payload
+```json
+{
+  "message_type": "dynamic_qr_request",
+  "request_id": "req_123",
+  "device_id": "sbx_001",
+  "terminal_id": "term_001",
+  "amount": 50000,
+  "currency": "IDR",
+  "created_at": "2026-05-23T10:00:00Z"
+}
+```
+
+## 5. Dynamic QR Response Payload
+```json
+{
+  "message_type": "dynamic_qr_response",
+  "correlation_id": "req_123",
+  "transaction_id": "tx_123",
+  "status": "success",
+  "qr_payload": "000201010212...",
+  "expires_at": "2026-05-23T10:05:00Z"
+}
+```
+
+## 6. Payment Success Notification Payload
+```json
+{
+  "message_type": "payment_success",
+  "event_id": "evt_123",
+  "transaction_id": "tx_123",
+  "merchant_name": "Toko Berkah",
+  "amount": 50000,
+  "currency": "IDR",
+  "paid_at": "2026-05-23T10:02:10Z",
+  "audio_text": "Pembayaran diterima lima puluh ribu rupiah",
+  "display_text": "Pembayaran diterima Rp50.000"
+}
+```
+
+## 7. Config Push Payload
+```json
+{
+  "message_type": "config_push",
+  "config_version": 3,
+  "settings": {
+    "volume": 80,
+    "language": "id-ID",
+    "heartbeat_interval_seconds": 60
+  }
+}
+```
+
+## 8. Command Payload
+```json
+{
+  "message_type": "command",
+  "command_id": "cmd_123",
+  "command_name": "test_speaker",
+  "parameters": {}
+}
+```
+
+## 9. QoS dan Delivery
+- heartbeat dapat memakai QoS rendah sesuai kebutuhan
+- payment success sebaiknya QoS lebih tinggi
+- retained message jangan dipakai untuk notifikasi sukses transaksi
+- ack command dan ack config harus dicatat