127 lines
4.6 KiB
Markdown
127 lines
4.6 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
npm install
|
|
cp .env.example .env
|
|
npm run dev
|
|
npm run build && npm start
|
|
```
|
|
|
|
### Cleanup data smoke test
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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)
|
|
|
|
```bash
|
|
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.
|