wirabasalamah/Qris-Soundbox
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
8a2e202606d83aaac812ee01ecc6307cf1bd7d25
Qris-Soundbox/CODEX_HANDOFF.md
Wira Basalamah 8a2e202606 Prepare QF100 pilot and Debian app deploy
2026-06-04 11:20:16 +07:00

11 KiB
Raw Blame History

Codex Handoff - QRIS Soundbox Platform

Tanggal update: 2026-06-03, Asia/Jakarta.

Dokumen ini adalah snapshot kerja terakhir untuk melanjutkan project tanpa perlu membaca ulang seluruh chat.

Status Terakhir

  • Fokus hari ini bergeser dari production readiness umum ke integrasi device soundbox QF100.
  • Folder SDK lokal QF100-60s-l511-SecondApp-260107/ ditemukan dan dianalisis. Folder ini sengaja tidak dimasukkan git.
  • Backend sekarang sudah punya adapter awal untuk firmware QF100 sample:
    • config server vendor-compatible;
    • payload MQTT payment success format QF100;
    • smoke script backend untuk static + dynamic QF100.
  • Target milestone berikutnya: dua soundbox real, satu static dan satu dynamic, bisa ambil config dari backend, connect MQTT, lalu static payment test bunyi dan tercatat di dashboard.
  • Worktree aktif/dirty karena perubahan backend QF100 dan update handoff. Jangan revert perubahan yang tidak eksplisit diminta.

Verifikasi Terakhir

  • npm run typecheck: pass setelah perubahan QF100.
  • npm install: sudah dijalankan untuk memasang dependency lokal; perubahan lockfile accidental sudah dibalik.
  • npm run smoke:qf100: script sudah dibuat, belum dijalankan end-to-end di DB/server lokal pada turn ini.
  • Verifikasi lama yang masih relevan:
    • npm run db:migrate: sebelumnya pass dan idempotent sampai migration 003_export_job_storage.sql.
    • npm audit --json: sebelumnya pass, 0 vulnerability.
    • npm run ui:qa: sebelumnya pass.
    • npm run smoke:e2e: sebelumnya pass.
    • Real MQTT smoke sebelumnya pernah pass terhadap mqtts://broker.bizone.id:8883.

SDK QF100 Yang Ditemukan

  • Folder lokal: QF100-60s-l511-SecondApp-260107/.
  • Sudah ditambahkan ke .gitignore:
    • QF100-60s-l511-SecondApp-260107/
  • Struktur penting:
    • docs/Config Server.docx: kontrak config server vendor.
    • docs/Cloud Speaker API Spec V2.8.7.pdf: API spec cloud speaker.
    • app/source/MainApp/globalDefine.h: device model, demo mode, CONFIG_ADDR.
    • app/source/MainApp/demo.c: alur config server, MQTT connect/subscribe, parse payment payload.
    • app/source/MainApp/demo.h: MQTT TLS/QoS/clean session/cert config.
    • app/source/MainApp/main.c: boot flow dan monitor network/MQTT.
    • app/inc/MercuryMqtt.h: header MQTT SDK.
    • app/release/user_app.bin: firmware build existing.

Kesimpulan SDK QF100

  • SDK ini memungkinkan develop/patch aplikasi firmware sendiri, tetapi bentuknya embedded C firmware app, bukan SDK backend.
  • Strategi dipilih: firmware hanya hardcode URL config server backend kita, bukan hardcode broker MQTT.
  • Firmware sample boot lalu call CONFIG_ADDR ke endpoint vendor /speaker/dev-config.
  • Request config berisi field seperti:
    • dev-model
    • item-number
    • dev-sn
    • fw-version
    • fw-build
    • app-config-version
    • imei
    • imsi
    • iccid
  • Response yang firmware cari memiliki blok:
    • mqtt.broker-ip
    • mqtt.broker-port
    • mqtt.client-id
    • mqtt.user-name
    • mqtt.password
    • mqtt.subscribe-topic
    • mqtt.keep-alive
  • Payment success payload yang firmware sample bisa bunyikan: 
    {
  "header": {
    "category": 1
  },
  "data": {
    "pay-amount": 15000
  }
}
  • MQTT_TLS_ENABLE di SDK sample masih 0. Jika broker production memakai mqtts://...:8883, firmware perlu patch TLS atau pilot perlu listener non-TLS terbatas.

Implementasi QF100 Backend Hari Ini

1. Config Server Vendor-Compatible

  • Route baru:
    • GET /speaker/dev-config
  • File:
    • src/routes/speaker.ts
    • mounted di src/app.ts
  • Perilaku:
    • menerima query/body vendor;
    • lookup device memakai dev-sn -> devices.serial_number;
    • jika device aktif, update:
      • vendor
      • model
      • communication_mode
      • last_seen_at
      • firmware_version
    • mencatat heartbeat state: config_pull;
    • balas JSON vendor top-level, bukan wrapper internal successResponse.
  • Error vendor style:
    • 1001: dev-sn kosong;
    • 1002: device tidak terdaftar atau inactive;
    • 1003: broker MQTT belum dikonfigurasi.

2. Env QF100

  • Env baru di src/config/env.ts dan .env.example:
    • QF100_MQTT_BROKER_HOST
    • QF100_MQTT_BROKER_PORT
    • QF100_MQTT_USERNAME
    • QF100_MQTT_PASSWORD
    • QF100_MQTT_KEEP_ALIVE_SECONDS
  • Jika host/port QF100 kosong, endpoint mencoba parse dari MQTT_BROKER_URL.
  • Catatan penting: password MQTT yang dikirim ke QF100 diambil dari QF100_MQTT_PASSWORD atau fallback MQTT_PASSWORD. Sistem saat ini menyimpan credential device sebagai fingerprint, jadi plaintext per-device tidak bisa dibaca ulang dari DB.

3. Payload MQTT QF100

  • File:
    • src/shared/services/mqttPublisher.ts
    • src/shared/orchestrators/notificationOrchestrator.ts
  • Topic QF100:
    • devices/{deviceId}/downlink/qf100
  • Adapter memilih format QF100 jika:
    • device.model mengandung QF100; atau
    • capability_profile_json.mqtt_payload_profile, protocol_profile, atau vendor_protocol bernilai qf100.
  • Downlink payment sekarang juga dicatat ke mqtt_messages, sehingga dashboard device detail bisa melihat topic/payload yang dikirim.

4. Device Store dan Schema

  • Lookup baru:
    • getDeviceBySerialNumber(serialNumber) di src/shared/store/deviceStore.ts.
  • Schema bootstrap menambahkan index:
    • idx_devices_serial_number.

5. Smoke QF100

  • Script baru:
    • scripts/smoke-qf100-adapter.mjs
  • Package script baru:
    • npm run smoke:qf100
  • Script ini:
    • create merchant/outlet/terminal/device static;
    • create merchant/outlet/terminal/device dynamic MQTT;
    • set model: QF100 dan capability_profile_json.mqtt_payload_profile: qf100;
    • hit /speaker/dev-config untuk dua SN;
    • validasi MQTT config vendor;
    • trigger static QRIS paid callback;
    • validasi mqtt_messages downlink QF100 payload category: 1;
    • trigger backend dynamic QR MQTT flow untuk device dynamic.
  • Untuk memakai SN real: 
    QF100_STATIC_SN=<sn-static> \
QF100_DYNAMIC_SN=<sn-dynamic> \
BASE_URL=http://127.0.0.1:3000 \
npm run smoke:qf100

Device Flow Yang Disepakati

Static Soundbox

  1. Device boot.
  2. Firmware call backend /speaker/dev-config.
  3. Backend balas MQTT config.
  4. Device connect MQTT dan subscribe devices/{deviceId}/downlink/qf100.
  5. QRIS callback paid masuk backend.
  6. Backend publish payload QF100 category: 1.
  7. Device bunyi nominal.
  8. Dashboard melihat transaction, notification, mqtt message, last seen/config pull.

Dynamic Soundbox

  • Prinsip: trigger tetap via MQTT, bukan polling terus-menerus.
  • HTTP polling dynamic QR dianggap tidak cocok untuk skala 20 ribu device karena gap=30s berarti sekitar 40 ribu request/menit.
  • Desain lanjutan:
    1. Backend/admin/merchant membuat dynamic QR request.
    2. Backend publish MQTT command ke device.
    3. Device menampilkan QR langsung atau HTTP fetch QR detail dari URL.
    4. Payment callback tetap jadi source of truth.
    5. Payment success tetap via MQTT category: 1.
  • Firmware dynamic handler belum dipatch. Perlu tambah handler misalnya category == 10 di demo.c.

Dashboard Yang Perlu Disiapkan Berikutnya

Prioritas UI/dashboard untuk test dua soundbox real:

  1. Device detail QF100 panel:
    • SN;
    • model/profile;
    • config pull terakhir;
    • broker host/port yang dikirim;
    • client-id;
    • subscribe-topic;
    • keepalive.
  2. Test payment button:
    • nominal quick actions, misalnya Rp1.000 dan Rp15.000;
    • create dummy tx/callback internal;
    • tampilkan notification dan MQTT payload result.
  3. MQTT timeline:
    • direction;
    • topic;
    • message_type;
    • payload JSON;
    • publish_status/reason;
    • timestamp.
  4. Dynamic QR panel:
    • input nominal;
    • create dynamic QR;
    • tampilkan QR payload/status;
    • nanti Send to Soundbox via MQTT command setelah firmware handler siap.
  5. Ops summary:
    • total soundbox;
    • online/stale/offline;
    • config pull terbaru;
    • payment notification sent/failed;
    • dynamic QR active/paid/expired.

Endpoint Penting Saat Ini

  • Health:
    • GET /health
    • GET /health/deep
  • QF100 vendor config:
    • GET /speaker/dev-config
  • Admin auth/session:
    • POST /admin/login
    • POST /admin/logout
    • GET /admin/me
  • Admin device:
    • POST /admin/devices
    • GET /admin/devices
    • GET /admin/devices/{id}
    • POST /admin/devices/{id}/credentials/rotate
    • POST /admin/devices/{id}/bind
    • POST /admin/devices/{id}/unbind
    • GET /admin/devices/{id}/mqtt-messages
    • GET /admin/devices/{id}/notifications
  • Device API:
    • POST /device/heartbeat
    • POST /device/transactions/dynamic-qr
    • POST /device/mqtt/uplink/dynamic-qr/request
    • GET /device/config
    • POST /device/config/ack
  • Integrations:
    • POST /integrations/qris/callback
  • Observability:
    • GET /admin/observability/summary
    • GET /admin/observability/mqtt-status

Package Scripts Penting

  • npm run typecheck
  • npm run db:migrate
  • npm run smoke:qf100
  • npm run smoke:e2e
  • npm run smoke:mqtt-real
  • npm run smoke:mqtt-acl
  • npm run ui:qa
  • npm run deploy:check-env
  • npm run load:test
  • npm run load:test:staging
  • npm run mqtt:provision-device
  • npm run mqtt:check-acl
  • npm run admin:create-user
  • npm run merchant:create-user

File Kunci Yang Sering Disentuh

  • App bootstrap: src/app.ts
  • Env config: src/config/env.ts
  • QF100 config route: src/routes/speaker.ts
  • Device route: src/routes/device.ts
  • Admin route: src/routes/admin.ts
  • MQTT publisher: src/shared/services/mqttPublisher.ts
  • MQTT subscriber: src/shared/services/mqttSubscriber.ts
  • Notification orchestrator: src/shared/orchestrators/notificationOrchestrator.ts
  • Device store: src/shared/store/deviceStore.ts
  • MQTT message store: src/shared/store/mqttMessageStore.ts
  • Heartbeat store: src/shared/store/heartbeatStore.ts
  • Schema bootstrap: src/shared/db/pool.ts
  • QF100 smoke: scripts/smoke-qf100-adapter.mjs
  • Env sample: .env.example

Sisa Gap Utama

  1. Jalankan npm run smoke:qf100 terhadap backend + DB lokal/staging.
  2. Register dua device real:
    • static SN -> device static;
    • dynamic SN -> device dynamic.
  3. Patch firmware QF100:
    • CONFIG_ADDR ke backend kita;
    • TLS setting sesuai broker.
  4. Test static device real:
    • config pull;
    • MQTT connect;
    • payment success bunyi;
    • dashboard melihat downlink.
  5. Patch firmware dynamic:
    • tambah handler command dynamic QR, kemungkinan category == 10;
    • pilih direct QR payload vs HTTP fetch detail.
  6. Siapkan dashboard QF100 detail/test panel.
  7. Putuskan credential strategy production:
    • shared pilot password saat ini cukup untuk lab;
    • production sebaiknya credential per-device yang bisa diprovisioning aman.
  8. Tetap perlu staging rehearsal, restore drill, export storage strategy, dan manual visual QA dari handoff lama.

Catatan Penting

  • Folder SDK QF100 adalah artefak lokal dan jangan dimasukkan git.
  • Jangan hardcode broker credential production di firmware.
  • Firmware cukup hardcode config server URL; broker/topic/credential dikirim dari backend.
  • Jangan gunakan wildcard MQTT subscribe di production kecuali maintenance terkontrol.
  • Jika memakai MQTT TLS (mqtts://...:8883), firmware QF100 perlu MQTT_TLS_ENABLE=1 dan sertifikat yang sesuai.
  • Rate limiting aktif default; /speaker memakai limiter device.
  • CODEX_HANDOFF.md ini adalah snapshot operasional terbaru; untuk detail historis keputusan, baca DECISIONS_LOG.md.