Qris-Soundbox/README.md

QRIS Soundbox Platform Package

Paket ini berisi blueprint final v1 untuk platform merchant aggregator QRIS + soundbox universal.

Isi paket

• 01-executive-blueprint.md
• 02-system-architecture.md
• 03-domain-modules.md
• 04-device-flows.md
• 05-api-contract-draft.md
• 06-mqtt-contract-draft.md
• 07-database-schema-draft.md
• 08-implementation-roadmap.md
• 09-screen-inventory.md
• 10-design-blueprint.md
• 11-low-fi-wireframes.md

Tujuan

Dokumen ini dibuat supaya tim bisa langsung mulai:

• desain UI/UX
• breakdown engineering
• desain backend
• integrasi device
• cicil implementasi per fase

Quick Start Implementasi (Lanjutan dari CODEx Handoff)

• Backend bootstrap Fase 1 sudah dibuat di src/.
• Fitur awal yang sudah aktif:
  • request context + request_id di middleware
  • error envelope (code, message, details, request_id, timestamp)
  • auth token minimal untuk endpoint admin
  • middleware idempotency untuk endpoint sensitif
• endpoint awal:
  • GET /health
  • GET /admin/health (dengan Authorization: Bearer <token>)
  • POST /admin/login
  • POST /admin/sample-idempotent
  • POST /admin/merchants
  • GET /admin/merchants
  • GET /admin/merchants/{id}
  • PATCH /admin/merchants/{id}
  • POST /admin/merchants/{merchantId}/outlets
  • POST /admin/merchants/{merchantId}/approve
  • POST /admin/merchants/{merchantId}/reject
  • GET /admin/outlets
  • GET /admin/outlets/{id}
  • POST /admin/outlets/{outletId}/terminals
  • GET /admin/terminals
  • GET /admin/terminals/{id}
  • POST /admin/devices
  • GET /admin/devices
  • GET /admin/devices/{id}
  • POST /admin/devices/{id}/bind
  • POST /admin/devices/{id}/unbind
  • POST /admin/devices/{id}/commands
  • GET /admin/devices/{id}/commands
  • GET /admin/devices/{id}/commands/{commandId}
  • GET /admin/devices/{id}/notifications
  • GET /admin/devices/{id}/config
  • PATCH /admin/devices/{id}/config
  • GET /admin/devices/{id}/mqtt-messages
  • GET /admin/audit-logs
  • GET /admin/ledger-entries
  • GET /admin/transactions
  • GET /admin/transactions/{transactionId}
  • POST /admin/transactions
  • GET /admin/transactions/{transactionId}/events
  • POST /admin/transactions/{transactionId}/retry-notification
  • POST /admin/seed
  • POST /device/transactions/dynamic-qr
  • POST /device/mqtt/uplink/dynamic-qr/request
  • GET /device/config
  • POST /device/config/ack

Menjalankan lokal

npm install
cp .env.example .env
npm run dev
npm run build && npm start

Cleanup data smoke test

PGHOST=127.0.0.1 PGPORT=5432 PGUSER=postgres PGPASSWORD=postgres PGDATABASE=qris_soundbox_platform npm run smoke:cleanup

Cleanup hanya menarget entitas smoke (Smoke Merchant, PR-, DEV-) agar data seed demo tidak ikut terhapus.

PORT=3100 ADMIN_TOKEN=admin-dev-token DEVICE_TOKEN=device-dev-token INTEGRATION_WEBHOOK_SECRET=dev-callback-secret PGHOST=127.0.0.1 PGPORT=5432 PGUSER=postgres PGPASSWORD=postgres PGDATABASE=qris_soundbox_platform npm run smoke:flow

Smoke flow akan melakukan create merchant/device/transaction + heartbeat + callback paid + verifikasi event/heartbeat/notification, duplicate callback, invalid signature, audit log, ledger placeholder, skenario terminal tanpa binding, dynamic QR API-direct, dynamic QR MQTT, dan device config push/ack.

Smoke test end-to-end (bootstrap + flow + cleanup)

PGHOST=127.0.0.1 PGPORT=5432 PGUSER=postgres PGPASSWORD=postgres PGDATABASE=qris_soundbox_platform npm run smoke:e2e

Perintah ini menjalankan:

• cleanup data smoke
• start server lokal di port 3100
• wait sampai /health aktif
• jalankan flow smoke lengkap
• hentikan server setelah selesai

Endpoint device lain

• POST /device/commands/ack

Quick screen preview

• GET /ui => katalog halaman UI dari seluruh design/*.
• GET /ui/:page => buka halaman berdasarkan slug (contoh: /ui/admin-login, /ui/admin-dashboard-overview, /ui/merchant-login).

Status lanjutan: Fase 1 core flow sudah tercakup smoke e2e. Fase 2 sudah aktif untuk capability resolver, dynamic QR API-direct, dynamic QR MQTT via outbox, dan device config push/ack.