Qris-Soundbox/12-fase1-step1-core-foundation-spec.md

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