Initial commit

2026-05-25 08:22:12 +07:00
commit a152c99cce
154 changed files with 39033 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,112 @@
+# 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.