Continue phase 2 device ops and dynamic QR lifecycle

This commit is contained in:
2026-05-26 21:25:07 +07:00
parent 5624b92872
commit e0b8f9af9a
22 changed files with 1050 additions and 92 deletions

View File

@ -233,3 +233,58 @@ Log keputusan arsitektur dan implementasi yang harus dijadikan acuan eksekusi.
- 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