# BE Handoff - Full API & Realtime Readiness

Dokumen ini untuk diteruskan ke tim Backend agar FE `bazzar.softcomp.io` bisa berjalan penuh via API `apibazzar.softcomp.io` tanpa fallback manual.

## 1) Environment Produksi (Aktif Saat Ini)

- FE domain: `https://bazzar.softcomp.io`
- API domain: `https://apibazzar.softcomp.io`
- FE base API: `https://apibazzar.softcomp.io/api/v1`
- SSL FE dan API: aktif (valid)

## 2) Status Verifikasi Terkini

- Login endpoint `POST /api/v1/auth/login`: **OK** (sudah 200, token keluar)
- Product list `GET /api/v1/products`: **OK** (200)
- Promo list `GET /api/v1/prices/change-requests`: **404** (belum tersedia / belum terdaftar)

Kesimpulan: issue yang tersisa saat ini dominan di ketersediaan endpoint BE, bukan di FE.

## 3) Endpoint yang Dipakai FE (Harus Ready)

Semua endpoint di bawah ini dipanggil FE dengan prefix `/api/v1`.

### A. Auth

- `POST /auth/login`
- `GET /auth/me`

### B. Master Product & POS

- `GET /products`
- `GET /products/:id`
- `PUT /products/:id`
- `DELETE /products/:id`
- `GET /members`
- `POST /pos/cart/price-preview`
- `POST /pos/checkout`
- `POST /pos/returns`
- `GET /pos/sales/:id/receipt`
- `GET /reports/sales`

### C. Import / Export

- `POST /import/products` (multipart form-data + `dry_run`)
- `GET /import/jobs/:id`
- `GET /export/products` (response file/blob)

### D. Pricing / Promo Approval

- `GET /prices/change-requests`
- `POST /prices/change-requests`
- `POST /prices/change-requests/:id/approve`
- `POST /prices/change-requests/:id/reject`

### E. Settings (Admin Panel)

- `GET /settings/general`
- `PUT /settings/general`
- `GET /settings/users`
- `POST /settings/users`
- `DELETE /settings/users/:id`
- `POST /settings/data/purge`
- `PUT /settings/session-policy`

## 4) Kontrak Minimal Response (Supaya FE Stabil)

## Auth Login

- Request body:
  - `username` (string)
  - `password` (string)
- Response 200:
  - `access_token` (string)
  - `refresh_token` (string, jika dipakai)
  - `user` (object)

## List Endpoint (produk/member/report/promo)

- Response 200:
  - `items` (array)
  - `meta`:
    - `page`
    - `limit` (atau `per_page`, konsistenkan)
    - `total_items`
    - `total_pages`

## Error Handling

- 401: unauthorized / token invalid
- 403: forbidden (RBAC)
- 404: route/data tidak ditemukan
- 422: validation error
- 500: internal server error
- Format error konsisten (mis. `{ "message": "..." }`)

## 5) Requirement "Full API" (Tanpa Data Dummy)

- FE tidak lagi memakai asumsi data lokal untuk data master, promo, settings.
- Semua fitur utama harus punya endpoint resmi dan documented.
- Jangan return HTML/text untuk endpoint API; gunakan JSON terstruktur.
- CORS production wajib:
  - `ALLOWED_ORIGINS=https://bazzar.softcomp.io`

## 6) Requirement "Realtime"

Untuk kebutuhan POS, minimum realtime yang direkomendasikan:

- **Harga/Promo berubah**: kasir aktif harus menerima update tanpa reload penuh.
- **Update stock/transaksi**: panel laporan/stock ikut update cepat.
- **Import job status**: progress berubah otomatis (`queued -> processing -> success/failed`).

Implementasi yang disarankan (pilih salah satu, konsisten):

- **SSE** (`/events`) untuk notifikasi satu arah dari server ke FE, atau
- **WebSocket** untuk two-way channel.

Jika realtime channel belum siap, sementara gunakan polling dengan SLA jelas:

- interval 2-5 detik
- endpoint status ringan
- response cepat (<500ms target internal)

## 7) Action Items Prioritas ke Tim BE

### P0 (harus beres dulu)

- Aktifkan endpoint yang masih 404:
  - `GET /api/v1/prices/change-requests`
- Pastikan semua endpoint di section 3 mengembalikan JSON kontrak yang konsisten.
- Pastikan seed user role kritikal ada di DB production:
  - `superadmin`, `admin`, `cashier`

### P1 (sesudah P0)

- Standarisasi pagination param (`page` + `limit`) di semua list endpoint.
- Lengkapi endpoint settings agar panel settings FE fully functional.
- Tambahkan audit log pada approval promo dan data changes.

### P2 (hardening realtime)

- Implement SSE/WebSocket untuk event:
  - `promo_updated`
  - `stock_updated`
  - `import_job_updated`
  - `order_created`
- Tambahkan versioning payload event.

## 8) Catatan Operasional

- Base path API final yang dipakai FE: `/api/v1`
- Endpoint root `/` boleh 404, itu normal. Yang wajib adalah path API di atas.
- Jika FE terlihat gagal setelah perubahan BE, lakukan:
  - clear token lama FE
  - login ulang
  - cek devtools network (status code + response body)