Initial commit

12-fase1-step1-core-foundation-spec.md

@@ -0,0 +1,206 @@
+# Fase 1 — Step 1: Core Foundation (Spesifikasi Implementasi)
+
+Dokumen ini memecah Step 1 menjadi paket kerja per service, API, schema, dan acceptance detail agar bisa langsung jadi ticket development.
+
+## 1) Service yang Dibangun Dulu (Urutan Implementasi)
+
+1. `shared` — tracing, idempotency key store, error envelope, request context
+2. `identity` — admin auth + device auth + RBAC baseline
+3. `merchant` — merchant onboarding dasar
+4. `location` — outlet dan terminal
+5. `device-tms` — registrasi device dan binding
+6. `core-db` — migrasi schema MVP + seed data
+7. `ingress` — endpoint admin yang membutuhkan service di atas
+
+## 2) Kontrak Data dan ID Standard
+
+### 2.1 ID
+- `merchant_id`, `outlet_id`, `terminal_id`, `device_id`, `binding_id`, `transaction_id`, `notification_id`
+- format rekomendasi: ULID/UUID v4
+
+### 2.2 Standard Trace/Event
+- Setiap request HTTP dan MQTT message harus membawa:
+- `request_id` (wajib di inbound entry API / webhook / mqtt)
+- `trace_id` (inherit antar service)
+- `event_id` (untuk emission / audit event)
+
+### 2.3 Idempotency
+- Table `idempotency_keys` baru:
+  - `id`
+  - `scope` (`merchant_create`, `outlet_create`, `terminal_create`, dll)
+  - `key` (unique)
+  - `response_hash`
+  - `created_at`, `expires_at`
+- Rule: hit yang sama + key sama => response deterministic dari cache/replay.
+
+## 3) Skema DB (MVP Step 1) — Detail Migrasi
+
+### 3.1 Tabel Inti yang Harus Ada
+- `merchants`
+- `outlets`
+- `terminals`
+- `devices`
+- `device_bindings`
+- `device_heartbeats`
+- `transactions`
+- `transaction_events`
+- `notifications`
+- `audit_logs`
+- `users`
+- `roles`
+- `idempotency_keys` (tambah)
+
+### 3.2 Field Wajib Step 1 per Tabel
+
+#### `merchants`
+- id, merchant_code, legal_name, brand_name
+- status, onboarding_status
+- settlement_account_reference, settlement_account_type, fee_profile_id
+- created_at, updated_at
+
+#### `outlets`
+- id, merchant_id(FK), outlet_code, name, address, status
+- created_at, updated_at
+
+#### `terminals`
+- id, outlet_id(FK), terminal_code, qr_mode, partner_reference, status
+- created_at, updated_at
+
+#### `devices`
+- id, device_code, serial_number, vendor, model
+- communication_mode, capability_profile_json, auth_method, status
+- last_seen_at, firmware_version
+- created_at, updated_at
+
+#### `device_bindings`
+- id, device_id(FK), merchant_id(FK), outlet_id(FK), terminal_id(FK)
+- active_flag, bound_at, unbound_at
+- unique index: (`device_id`, `active_flag` where active_flag=true)
+
+#### `device_heartbeats`
+- id, device_id(FK), received_at
+- network_strength, battery_level, firmware_version, state, payload_json
+
+#### `transactions`
+- id, transaction_code, merchant_id(FK), outlet_id(FK), terminal_id(FK), device_id(FK)
+- qr_mode, initiation_mode, partner_reference, amount, currency, status, created_at, paid_at, expired_at, updated_at
+
+#### `transaction_events`
+- id, transaction_id(FK), event_type, source, payload_json, created_at
+
+#### `notifications`
+- id, transaction_id(FK), device_id(FK), delivery_channel, payload_type
+- delivery_status, retry_count, ack_status, sent_at, ack_at
+
+#### `audit_logs`
+- id, actor_type, actor_id, action, entity_type, entity_id
+- before_json, after_json, source_ip, created_at
+
+#### `users` / `roles` (minimal)
+- users: id, name, email, password_hash, role_id, status, created_at
+- roles: id, name, permissions_json, created_at
+
+### 3.3 Index Prioritas Step 1
+- `device_bindings(device_id, active_flag)`
+- `transactions(partner_reference)`
+- `transactions(merchant_id, created_at)`
+- `transactions(status, created_at)`
+- `notifications(device_id, delivery_status)`
+- `device_heartbeats(device_id, received_at)`
+- `audit_logs(entity_type, entity_id, created_at)`
+
+## 4) Modul API Step 1 (Spesifikasi Ringkas)
+
+### 4.1 Admin/Auth
+- `POST /auth/login` (bila auth service belum ada, temporary token stub boleh pakai untuk sprint 1)
+- `POST /auth/token/refresh` (opsional)
+- Validasi RBAC untuk endpoint admin:
+  - `admin` minimal bisa akses semua CRUD Fase 1
+- Error standar:
+  - `UNAUTHORIZED`, `FORBIDDEN`, `VALIDATION_ERROR`
+
+### 4.2 Merchant
+- `POST /admin/merchants`
+  - body:
+    - `legal_name`, `brand_name`, `settlement_account_reference`, `settlement_account_type`, `fee_profile_id`
+    - `settlement_account_type` contoh: `merchant_virtual_account`, `merchant_bank_account`, `partner_payout_reference`
+    - `payout_mode` (opsional): `merchant_direct` (default), `manual`
+      - `merchant_direct` = payout diarahkan via reference payout merchant
+      - `manual` = pencairan dibantu operasional, belum otomatis
+  - validasi: `legal_name` required
+  - idempotency: `Idempotency-Key` optional untuk create
+- `GET /admin/merchants`
+- `GET /admin/merchants/{merchantId}`
+- `PATCH /admin/merchants/{merchantId}`
+- `DELETE /admin/merchants/{merchantId}` (opsional; bisa soft delete via status=inactive)
+
+### 4.3 Outlet
+- `POST /admin/merchants/{merchantId}/outlets`
+- `GET /admin/outlets`
+- `GET /admin/outlets/{outletId}`
+- `PATCH /admin/outlets/{outletId}`
+
+### 4.4 Terminal
+- `POST /admin/outlets/{outletId}/terminals`
+- `GET /admin/terminals`
+- `GET /admin/terminals/{terminalId}`
+- `PATCH /admin/terminals/{terminalId}`
+
+### 4.5 Device & Binding
+- `POST /admin/devices`
+- `GET /admin/devices`
+- `GET /admin/devices/{deviceId}`
+- `PATCH /admin/devices/{deviceId}`
+- `POST /admin/devices/{deviceId}/bind`
+  - body: `{ merchant_id, outlet_id, terminal_id }`
+  - rule: endpoint ini membuat record `device_bindings` baru dan menonaktifkan binding aktif lama
+- `POST /admin/devices/{deviceId}/unbind`
+  - body: `{ reason }`
+
+## 5) Acceptance Criteria per Paket
+
+### 5.1 Merchant/Location
+- merchant, outlet, terminal bisa dibuat, diubah, list, detail
+- semua response memuat `request_id`
+- duplikasi create request dengan idempotency key yang sama menghasilkan resource yang sama
+
+### 5.2 Device Binding
+- bind mengikat hanya satu binding aktif/device pada saat yang sama
+- unbind membuat binding aktif jadi nonaktif dan merekam `unbound_at`
+- binding referensi invalid menyebabkan endpoint device/transaction terkait ditolak di tahap berikutnya
+
+### 5.3 Observability/Platform
+- semua response error mengikuti envelope:
+  - `code`, `message`, `details`, `request_id`
+- log audit tersimpan saat create/update pada merchant, device, bind/unbind
+
+### 5.4 Operasional
+- `last_seen_at` device berubah saat heartbeat valid (step 2 nantinya lebih lengkap)
+- pipeline dasar bisa menjalankan 10 request bersamaan tanpa crash (smoke test)
+
+## 6) Definisi File/Artefak
+
+### 6.1 Yang Harus Dibuat di Step 1
+- `12-fase1-step1-core-foundation-spec.md` (dokumen ini)
+- `DECISIONS_LOG.md` (dibuat bersama)
+- migration file untuk tabel Step 1
+- endpoint handlers sesuai list di atas
+- seed file:
+  - 2 merchant
+  - 2 outlet + 2 terminal
+  - 3 devices (static, dynamic-mqtt, dynamic-api)
+
+### 6.2 Testing Wajib (manual smoke, tanpa alat tambahan)
+- login/admin auth
+- CRUD merchant
+- CRUD outlet/terminal
+- bind/unbind device
+- seed device bisa dilihat di GET list
+
+## 7) Handover ke Step 2
+
+Step 2 tidak dimulai sampai:
+- endpoint binding dan auth stabil
+- transaksi memiliki struktur minimal `transactions + transaction_events`
+- event/error format terstandardisasi
+- idempotency baseline aktif