155 lines
4.3 KiB
Markdown
155 lines
4.3 KiB
Markdown
# Fase 1 — Step 4: Device & Ops Monitoring
|
|
|
|
Dokumen ini merinci implementasi heartbeat, status device, list/detail monitoring, dan KPI dasar admin untuk selesai dari Step 4.
|
|
|
|
## 1) Tujuan Step 4
|
|
- Menyediakan visibilitas operasional untuk device dan transaksi di admin
|
|
- Menjadikan heartbeat sebagai sumber status online device
|
|
- Menyediakan metrik minimum yang dipakai tim operasi harian
|
|
- Menyediakan jalur retry/penelusuran notifikasi pending
|
|
|
|
## 2) Heartbeat Ingestion
|
|
|
|
### Endpoint
|
|
- `POST /device/heartbeat`
|
|
|
|
### Request
|
|
```json
|
|
{
|
|
"device_id": "sbx_001",
|
|
"timestamp": "2026-05-23T10:00:00Z",
|
|
"firmware_version": "1.0.3",
|
|
"network_strength": 78,
|
|
"battery_level": 92,
|
|
"state": "idle"
|
|
}
|
|
```
|
|
|
|
### Rules
|
|
- Validate token device.
|
|
- Simpan ke `device_heartbeats`.
|
|
- Update `devices.last_seen_at = timestamp`.
|
|
- Jika field missing, simpan `null` dan tetap catat validasi non-kritis:
|
|
- `network_strength` / `battery_level` boleh null
|
|
- Return response:
|
|
- `request_id`
|
|
- `device_id`
|
|
- `server_time`
|
|
|
|
### Status Derivation (Step 4)
|
|
- `online`: `last_seen_at >= now - 90 detik`
|
|
- `degraded`: `network_strength < 40` **atau** `battery_level < 20`
|
|
- `stale`: `last_seen_at < now - 90 detik` dan >= `now - 15 menit`
|
|
- `offline`: `last_seen_at < now - 15 menit`
|
|
- Kombinasi prioritas: `offline`/`stale`/`degraded`/`online` (offline paling dominan)
|
|
|
|
## 3) Endpoint Monitoring Dasar
|
|
|
|
### List Device
|
|
- `GET /admin/devices`
|
|
- query:
|
|
- `status`
|
|
- `vendor`
|
|
- `communication_mode`
|
|
- `merchant_id`
|
|
- `q` (search)
|
|
- response: include:
|
|
- `status`
|
|
- `last_seen_at`
|
|
- `heartbeat_count_24h`
|
|
- binding current summary
|
|
|
|
### Device Detail
|
|
- `GET /admin/devices/{deviceId}`
|
|
- response include:
|
|
- metadata device
|
|
- binding aktif (merchant/outlet/terminal)
|
|
- latest heartbeat
|
|
- derived status + device health
|
|
- `notifications` latest
|
|
|
|
### Heartbeat List
|
|
- `GET /admin/devices/{deviceId}/heartbeats`
|
|
- filter:
|
|
- `from`, `to`, `state`
|
|
- sort: latest first
|
|
|
|
### Transaction List/Detail (minimal lanjutan Step 4)
|
|
- `GET /admin/transactions`
|
|
- filter `status`, `merchant_id`, `from`, `to`, `partner_reference`
|
|
- `GET /admin/transactions/{transactionId}`
|
|
- include `transaction_events` timeline
|
|
|
|
## 4) KPI Dashboard Minimal (admin)
|
|
|
|
### Endpoint
|
|
- `GET /admin/dashboard/summary`
|
|
|
|
### Metrics
|
|
- `transactions_today`
|
|
- `success_rate_today` (paid / total attempt)
|
|
- `active_devices`
|
|
- `pending_notifications`
|
|
- `devices_stale`
|
|
- `devices_offline`
|
|
|
|
### Data Source
|
|
- transaksi hari ini dari `transactions.created_at`
|
|
- device status dari `devices.last_seen_at`
|
|
- pending notification dari `notifications.delivery_status in ('queued','retrying')`
|
|
|
|
## 5) Admin Retry-notification (Step 4)
|
|
|
|
### Endpoint
|
|
- `POST /admin/transactions/{transactionId}/retry-notification`
|
|
|
|
### Flow
|
|
1. validasi transaksi exists dan status `paid`
|
|
2. ambil latest notification `delivery_status` != `acknowledged`
|
|
3. jika `delivery_status` = `queued/sent/failed/retrying`:
|
|
- trigger publish ulang
|
|
- tambah `retry_count`
|
|
4. simpan hasil status setelah publish
|
|
5. return:
|
|
- `transaction_id`
|
|
- `notification_id`
|
|
- `delivery_status`
|
|
- `next_retry_at`
|
|
|
|
## 6) Monitoring Notifikasi Gagal
|
|
- endpoint ops:
|
|
- `GET /admin/notifications/failed`
|
|
- filter:
|
|
- `device_id`
|
|
- `from`
|
|
- `to`
|
|
- response:
|
|
- `notification_id`, `transaction_id`, `device_id`, `delivery_status`, `retry_count`, `reason`
|
|
|
|
## 7) Query Efficiency (Prioritas)
|
|
- buat index:
|
|
- `devices(status, last_seen_at)`
|
|
- `device_heartbeats(device_id, received_at desc)`
|
|
- `transactions(status, created_at)`
|
|
- `notifications(delivery_status, created_at)`
|
|
|
|
## 8) Acceptance Criteria Step 4
|
|
- status device berubah sesuai aturan `online/degraded/stale/offline`
|
|
- heartbeat tercatat dan `devices.last_seen_at` terupdate
|
|
- dashboard summary menampilkan 5 metrik minimal
|
|
- `GET /admin/transactions` dan device/transaction detail menampilkan data yang dibutuhkan
|
|
- endpoint retry-notification memicu publish ulang untuk status non-final
|
|
|
|
## 9) Error Handling
|
|
- `DEVICE_NOT_FOUND`
|
|
- `INVALID_HEARTBEAT_PAYLOAD`
|
|
- `TRANSACTION_NOT_ELIGIBLE_FOR_RETRY`
|
|
- `DASHBOARD_CALCULATION_ERROR` (fallback graceful: return nilai default 0 jika query gagal)
|
|
|
|
## 10) Keluaran Step 4 (End-State)
|
|
- operator bisa cek:
|
|
- device aktif/offline
|
|
- transaksi dan status payment
|
|
- kegagalan notifikasi
|
|
- sistem tetap bisa operasi manual meski tanpa UI dashboard kompleks
|