# 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/transactions`
  - `GET /admin/transactions/{transactionId}`
  - `POST /admin/transactions`
  - `GET /admin/transactions/{transactionId}/events`
  - `POST /admin/transactions/{transactionId}/retry-notification`
  - `POST /admin/seed`

### 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.

### 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`).

Langkah berikutnya sesuai handoff: lanjut ke Task Pack B.1 (transaction core), lalu C.1–C.3.