Qris-Soundbox/CODEX_HANDOFF.md

CODEx Handoff — QRIS Soundbox Platform

Current status

• Fokus terakhir: penyelesaian gap Fase 1 backend + smoke e2e skenario wajib.
• Implementasi backend dan UI sudah mulai dikerjakan di repository (tidak lagi hanya dokumentasi).
• Tambahan terbaru:
  • audit log untuk aksi admin/webhook penting
  • ledger placeholder gross_income saat transaksi menjadi paid
  • endpoint admin GET /admin/audit-logs dan GET /admin/ledger-entries
  • awal Fase 2: capability resolver + POST /device/transactions/dynamic-qr API-direct
  • lanjutan Fase 2: MQTT dynamic QR simulator/outbox + device config push/ack
  • lanjutan Fase 2 berikutnya: config drift status + retry push config + MQTT trace untuk config ACK
  • health summary device Fase 2 untuk admin list/detail: status, score, age_seconds, reasons
  • UI ops Fase 2 di device registry/detail: health score/reasons, config drift, retry config push
  • dynamic QR expiry sweep via POST /admin/transactions/expire-due
  • smoke e2e mencakup duplicate callback, invalid signature, ledger, audit, terminal tanpa binding, dynamic QR API-direct, dynamic QR expiry sweep, dynamic QR MQTT, dan device config push/status/retry/ack
  • fix UI lokal:
    • CSP Helmet dilonggarkan untuk Tailwind CDN, Google Fonts/Material Symbols, dan image Googleusercontent agar desain render normal
    • panel kanan login admin dibuat dark glass supaya teks putih terbaca
    • input login admin diubah dari email ke username text agar credential dev admin/admin bisa dipakai
• Smoke test Fase1 jalannya:
  • smoke:cleanup ✅
  • smoke:flow jalan jika server aktif di localhost:3100
  • smoke:e2e ✅ setelah server auto-start di port 3100 (cleanup + full flow berhasil).

Files baru/terbaru yang sudah dibuat

• UI: admin-system-dashboard
  • Dashboard API wiring dipastikan terhubung ke backend untuk token admin, endpoint summary, dan retry/realtime UI.
• UI: merchant-onboarding-flow
  • Form onboarding disinkron ke API (create merchant, outlet, terminal, device, binding) + status badge flow.
• UI: merchant-detail-view
  • Detail merchant kini ambil data API untuk merchant/outlet/transactions list.
• UI: device-technical-detail
  • Device detail sinkronisasi data API: detail device, binding terbaru, heartbeats, events, metrics device, dan stream log.
• UI: transaction-history-monitoring
  • Search/filter outlet-terminal dan path transaksi sudah memakai endpoint API admin.
• README
  • Sudah ada script dan langkah smoke test (smoke:cleanup, smoke:flow, smoke:e2e) siap dipakai dan mencakup skenario Fase 1 tambahan.
• DECISIONS_LOG.md
  • Sudah memuat keputusan merchant bank account dan keputusan audit log + ledger placeholder Fase 1.
• Backend: auditLogStore
  • Store audit log untuk aksi admin/webhook penting.
• Backend: ledgerStore
  • Store ledger placeholder untuk transaksi paid Fase 1.
• Backend: deviceCapabilityResolver
  • Resolver capability untuk flow dynamic QR API/MQTT.
• Backend: dynamicQrOrchestrator
  • Membuat transaksi dynamic awaiting_payment dan mock QR payload.
• Backend: dynamicQrExpiry
  • Sweep transaksi dynamic QR awaiting_payment yang sudah melewati expired_at.
• Backend: mqttMessageStore
  • Outbox/trace MQTT uplink dan downlink.
• Backend: deviceConfigStore
  • Config versioned dan ACK device.
• Backend: deviceConfigStatus
  • Derivasi status drift config: applied, pending_ack, failed_ack, stale_ack, never_pushed.
• UI: device-registry-monitoring
  • Drawer ops menampilkan health score/reasons, config drift, latest push/ACK, dan retry config push.
• UI: device-technical-detail
  • Detail device menampilkan health summary dan config delivery panel dengan retry push.
• App CSP
  • Helmet CSP disesuaikan agar asset desain eksternal dapat dimuat di lokal.
• UI: admin-login
  • Login admin API-wired, input username dev, dan kontras panel kanan diperbaiki.
• UI: admin-login-portal
  • Baseline portal login ikut diselaraskan untuk username dan kontras.

Keputusan penting yang harus diikuti saat lanjut

1. Fase 1 Step 1–4 harus tetap jalan berurutan sebelum pengembangan Fase 2.
2. Backend target Postgres di local (qris_soundbox_platform) sudah dipakai di smoke test.
3. Jalankan smoke dari kondisi bersih (smoke:cleanup) untuk hasil yang konsisten.
4. Untuk sementara, pencairan dana mengikuti pola rekening merchant sendiri (sesuai permintaan terakhir), bukan rekening terpusat.
5. Pertahankan format error API yang konsisten: code, message, details, request_id, timestamp.
6. Ledger Fase 1 masih placeholder gross_income; jangan perluas fee/payable sebelum Fase 3 kecuali diminta eksplisit.
7. Dynamic QR Fase 2 saat ini memakai mock QRIS payload lokal; integrasi partner sungguhan belum dipasang.
8. MQTT Fase 2 saat ini memakai simulator HTTP + mqtt_messages outbox; broker sungguhan belum dipasang.
9. Config retry Fase 2 mengirim ulang config version yang sama; jangan naikkan versi kecuali settings berubah.
10. Dynamic QR expiry sweep saat ini endpoint admin/manual; bisa dinaikkan menjadi scheduler/background worker.
11. Untuk cek UI lokal, gunakan http://127.0.0.1:3100/ui/admin-login; credential dev adalah username admin, password admin.

Urutan kerja selanjutnya (disarankan)

1. UI/manual sanity lanjut dari titik terakhir:
   • Merchant detail page
   • Merchant list/filter
   • Device technical detail
   • Device list + heartbeat view
   • Transaction history + outlet/terminal filter
2. Jalankan lagi npm run smoke:e2e sebelum lanjut Fase 2 atau sebelum commit besar.
3. Jika ada regresi, cek log server di /tmp/qris-smoke-e2e-server.log.
4. Lanjut Fase 2 berikutnya:
   • adapter broker MQTT sungguhan dari mqtt_messages outbox
   • scheduler otomatis untuk dynamic QR expiry sweep
   • filter/sorting UI berbasis health_summary.score dan health_summary.reasons
   • manual visual QA device registry/detail untuk layout mobile dan drawer
5. Sebelum wiring UI baru, pastikan halaman tetap mengikuti desain design/*/code.html dan cek kontras teks pada panel transparan/overlay.

Note kalau meneruskan sesi berikutnya

• Kode dan screen yang sudah dimodifikasi tidak perlu diulang dari nol; lanjut dari state saat ini.
• Prioritas saat lanjut: verifikasi “jalur UI sinkron API” lalu lanjutkan smoke flow end-to-end berkala.
• Gunakan [DECISIONS_LOG.md] sebagai rujukan wajib untuk keputusan yang sudah disepakati.

Selesai untuk off

• Sudah ada gabungan perubahan di repo: doc + UI + API integration + smoke validation.