wirabasalamah/Qris-Soundbox
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e0b8f9af9ae77fb3d1c1a6379b947b14ed75718d
Qris-Soundbox/README.md

4.6 KiB
Raw Blame History

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}/config/status
    • POST /admin/devices/{id}/config/retry-push
    • GET /admin/devices/{id}/mqtt-messages
    • GET /admin/audit-logs
    • GET /admin/ledger-entries
    • GET /admin/transactions
    • GET /admin/transactions/{transactionId}
    • POST /admin/transactions
    • POST /admin/transactions/expire-due
    • 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, expiry sweep dynamic QR, dynamic QR MQTT, device config push/retry/status/ack, dan trace MQTT config 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/status/retry/ack.

Catatan Fase 2 ops: endpoint daftar/detail device admin juga mengirim health_summary (status, score, age_seconds, reasons) untuk membantu triage device. UI device registry dan device technical detail sudah menampilkan health summary, config drift, dan retry config push.