halobestie-clone/requirement/phase2-plan.md

# Phase 2 Implementation Plan: Mitra Online Status & Pairing Logic

## Summary of Clarified Requirements

| Topic | Decision |
|---|---|
| Mitra default status | Offline on app open; must explicitly toggle online |
| Auto-offline | Yes — on app close / connection loss |
| Online/offline logs | Backend + control center only; mitra don't see their own logs |
| Multi-device | No — single device per mitra |
| Customer active requests | One at a time; one active session at a time |
| Search timeout | 60 seconds, then "no bestie available" message |
| Cancel while searching | Yes |
| Pairing blast | Valkey pub/sub (in-app real-time); push notifications deferred |
| Race condition | First-come-first-served |
| Mitra decline/ignore | Allowed; request stays open until 60s timeout or customer cancel |
| Session end | Explicit end only (time-based deferred to next phase) |
| Payment placeholder | `pending_payment` status, skip to `active` for now |
| Max customer per mitra | Global config (not per-mitra) |
| Reroute | Forced assignment (acceptance-based deferred) |
| Reroute target | Online mitras only |
| Dashboard refresh | Polling-based auto-refresh now; SSE/push later |

---

## 1. Database Changes

### 1.1 New table: `mitra_online_status`

Tracks the current online/offline state per mitra.

| Column | Type | Notes |
|---|---|---|
| `id` | `SERIAL PRIMARY KEY` | |
| `mitra_id` | `INT REFERENCES mitras(id)` | Unique — one row per mitra |
| `is_online` | `BOOLEAN DEFAULT false` | |
| `last_online_at` | `TIMESTAMPTZ` | Last time they went online |
| `last_offline_at` | `TIMESTAMPTZ` | Last time they went offline |
| `updated_at` | `TIMESTAMPTZ` | |

### 1.2 New table: `mitra_online_logs`

Append-only log for control center reporting.

| Column | Type | Notes |
|---|---|---|
| `id` | `SERIAL PRIMARY KEY` | |
| `mitra_id` | `INT REFERENCES mitras(id)` | |
| `status` | `VARCHAR` | `'online'` or `'offline'` |
| `timestamp` | `TIMESTAMPTZ DEFAULT now()` | |

### 1.3 New table: `chat_sessions`

Tracks pairing and session lifecycle.

| Column | Type | Notes |
|---|---|---|
| `id` | `SERIAL PRIMARY KEY` | |
| `customer_id` | `INT REFERENCES customers(id)` | |
| `mitra_id` | `INT REFERENCES mitras(id)` | Nullable — null while searching |
| `status` | `VARCHAR` | See statuses below |
| `created_at` | `TIMESTAMPTZ DEFAULT now()` | |
| `paired_at` | `TIMESTAMPTZ` | When mitra accepted |
| `ended_at` | `TIMESTAMPTZ` | When session explicitly ended |
| `ended_by` | `VARCHAR` | `'customer'`, `'mitra'`, or `'system'` |

**Session statuses:**
- `searching` — customer requested, waiting for mitra
- `pending_acceptance` — blast sent, waiting for a mitra to accept
- `pending_payment` — mitra accepted, payment placeholder (auto-skip for now)
- `active` — session in progress
- `completed` — ended explicitly
- `cancelled` — customer cancelled during search
- `expired` — 60s timeout, no mitra accepted
- `rerouted` — session reassigned by control center (old record status)

### 1.4 New table: `chat_request_notifications`

Tracks which mitras were notified of a pairing request (for blast tracking).

| Column | Type | Notes |
|---|---|---|
| `id` | `SERIAL PRIMARY KEY` | |
| `session_id` | `INT REFERENCES chat_sessions(id)` | |
| `mitra_id` | `INT REFERENCES mitras(id)` | |
| `notified_at` | `TIMESTAMPTZ DEFAULT now()` | |
| `response` | `VARCHAR` | `'accepted'`, `'declined'`, `'ignored'` |
| `responded_at` | `TIMESTAMPTZ` | |

### 1.5 Extend `app_config`

Add new config key:

| Key | Value (JSONB) | Purpose |
|---|---|---|
| `max_customers_per_mitra` | `{ "value": 3 }` | Global max concurrent sessions per mitra |

---

## 2. Backend Changes

### 2.1 Valkey (Redis-compatible) Setup

- Add Valkey client as Fastify plugin (`src/plugins/valkey.js`)
- Used for pub/sub channels:
  - `mitra:{mitra_id}:requests` — notify specific mitra of incoming chat requests
  - `session:{session_id}:status` — notify customer of session status changes
- This pub/sub infrastructure will be reused for real-time chat in the next phase

### 2.2 New Public Routes — Mitra

| Method | Path | Purpose |
|---|---|---|
| `POST` | `/api/mitra/status/online` | Set mitra online |
| `POST` | `/api/mitra/status/offline` | Set mitra offline |
| `GET` | `/api/mitra/status` | Get own current status |
| `GET` | `/api/mitra/chat-requests/incoming` | SSE/long-poll endpoint for incoming chat request notifications |
| `POST` | `/api/mitra/chat-requests/:sessionId/accept` | Accept a chat request |
| `POST` | `/api/mitra/chat-requests/:sessionId/decline` | Decline a chat request |
| `GET` | `/api/mitra/sessions/active` | Get mitra's active sessions |
| `POST` | `/api/mitra/sessions/:sessionId/end` | End a session |

### 2.3 New Public Routes — Client

| Method | Path | Purpose |
|---|---|---|
| `POST` | `/api/client/chat/request` | Start a pairing request |
| `GET` | `/api/client/chat/request/:sessionId/status` | SSE/long-poll for pairing status updates |
| `POST` | `/api/client/chat/request/:sessionId/cancel` | Cancel a pairing request |
| `GET` | `/api/client/sessions/active` | Get customer's active session |
| `POST` | `/api/client/sessions/:sessionId/end` | End a session |

### 2.4 New Internal Routes — Control Center

| Method | Path | Purpose |
|---|---|---|
| `GET` | `/internal/dashboard/stats` | Active chats, active mitras, active requests, customers per mitra |
| `GET` | `/internal/config/max-customers-per-mitra` | Get current max config |
| `PATCH` | `/internal/config/max-customers-per-mitra` | Update max config |
| `GET` | `/internal/sessions` | List sessions (filterable by status) |
| `GET` | `/internal/sessions/:sessionId` | Session detail |
| `POST` | `/internal/sessions/:sessionId/reroute` | Reroute session to another mitra (forced) |
| `GET` | `/internal/mitras/online` | List online mitras with active session count |
| `GET` | `/internal/mitras/:mitraId/online-logs` | Online/offline log for a mitra |

### 2.5 New Services

| Service | Responsibilities |
|---|---|
| `mitra-status.service.js` | Toggle online/offline, log entries, auto-offline logic |
| `pairing.service.js` | Create pairing request, blast to mitras, handle accept/decline, timeout (60s), cancel |
| `session.service.js` | Session lifecycle (active, end, reroute), active session queries |
| `dashboard.service.js` | Aggregate stats for control center dashboard |

### 2.6 Pairing Flow (Backend Detail)

```
1. Customer calls POST /api/client/chat/request
2. Backend creates chat_session (status: searching)
3. Backend queries available mitras:
   - is_online = true
   - active_session_count < max_customers_per_mitra config
4. If no mitra available → immediately return "no bestie available"
5. If mitras available:
   - Update session status → pending_acceptance
   - Create chat_request_notifications for each available mitra
   - Publish to each mitra's Valkey channel
   - Start 60s timeout timer (via setTimeout or scheduled job)
6. Mitra calls POST /api/mitra/chat-requests/:sessionId/accept
   - Check session still in pending_acceptance (first-come-first-served)
   - If yes → pair, set session status → pending_payment → active (skip payment)
   - Publish status update to customer's session channel
   - Mark other mitra notifications as "ignored"
7. On 60s timeout with no accept:
   - Set session status → expired
   - Publish timeout to customer's session channel
8. On customer cancel:
   - Set session status → cancelled
   - Notify mitras to dismiss the request
```

### 2.7 Auto-Offline Mechanism

- Mitra app sends periodic heartbeat (`POST /api/mitra/status/heartbeat`) every 15 seconds
- Backend tracks last heartbeat timestamp in `mitra_online_status`
- A background interval (every 30s) checks for mitras with `is_online = true` but no heartbeat in the last 45 seconds → auto-set offline
- This handles force-close, network loss, and crashes

---

## 3. Mitra App Changes

### 3.1 New BLoC: `StatusBloc`

Manages online/offline toggle and heartbeat.

**Events:** `ToggleOnline`, `ToggleOffline`, `HeartbeatTick`, `AutoOfflineDetected`
**States:** `StatusInitial`, `StatusOnline`, `StatusOffline`, `StatusLoading`, `StatusError`

- On `ToggleOnline` → call API, start heartbeat timer (15s interval)
- On `ToggleOffline` → call API, stop heartbeat timer
- On app lifecycle `paused`/`detached` → call offline API, stop heartbeat

### 3.2 New BLoC: `ChatRequestBloc`

Handles incoming chat request notifications.

**Events:** `StartListening`, `StopListening`, `RequestReceived`, `AcceptRequest`, `DeclineRequest`
**States:** `Idle`, `IncomingRequest(session)`, `Accepting`, `Accepted(session)`, `Declined`, `Error`

- Listens to SSE/long-poll endpoint for incoming requests while mitra is online
- Shows incoming request UI overlay/bottom sheet

### 3.3 Screen Changes

| Screen | Changes |
|---|---|
| Home screen | Add online/offline toggle switch at the top; show active session count |
| New: Incoming request sheet | Bottom sheet showing customer request with Accept/Decline buttons |
| New: Active sessions screen | List of current active sessions (name, duration) with End button |

### 3.4 App Lifecycle Handling

- Use `WidgetsBindingObserver` to detect app going to background/foreground
- On `paused`/`detached` → call offline API
- On `resumed` → do NOT auto-set online; mitra must explicitly toggle

---

## 4. Client App Changes

### 4.1 New BLoC: `PairingBloc`

Manages the pairing request lifecycle.

**Events:** `RequestPairing`, `CancelPairing`, `PairingStatusUpdate`, `PairingTimeout`
**States:** `PairingInitial`, `Searching`, `BestieFound(mitraName)`, `Paired(session)`, `NoBestieAvailable`, `Cancelled`, `Error`

- On `RequestPairing` → call API, start listening for status updates, start 60s local timer
- On status update `active` → emit `BestieFound` briefly, then `Paired`
- On timeout / expired → emit `NoBestieAvailable`

### 4.2 Screen Changes

| Screen | Changes |
|---|---|
| Home screen | Add "Mulai Curhat" CTA button (disabled if already has active session) |
| New: Searching screen | "Searching for Bestie..." with animation and Cancel button |
| New: Bestie found screen | Brief "Bestie ditemukan, menghubungkan kamu ke Bestie" message |
| New: Session active screen | Shows paired bestie name, End Session button |
| New: No bestie screen | "No bestie available, try again later" with retry button |

### 4.3 Navigation Updates

Add new routes in GoRouter:
- `/chat/searching` — searching screen
- `/chat/session/:sessionId` — active session screen

---

## 5. Control Center Changes

### 5.1 New Pages

| Page | Purpose |
|---|---|
| Dashboard page | Real-time stats: active chats, online mitras, pending requests, customers per mitra breakdown |
| Session management page | Table of all sessions (filterable by status), reroute action |
| Session detail page | Session info, customer/mitra details, reroute button |

### 5.2 Updated Pages

| Page | Changes |
|---|---|
| Settings page | Add "Max customers per mitra" config input |
| Mitra management page | Add online status indicator column, online/offline log link |

### 5.3 Dashboard Auto-Refresh

- Use React Query with `refetchInterval: 10000` (10s polling)
- Later can be swapped to SSE push without changing component logic

---

## 6. Implementation Order

Work should be done in this sequence to allow incremental testing:

| Step | What | Apps affected |
|---|---|---|
| 1 | Database migration (new tables + config) | Backend |
| 2 | Valkey plugin setup | Backend |
| 3 | Mitra online/offline status API + service + heartbeat | Backend |
| 4 | Mitra app: status toggle + heartbeat + lifecycle handling | Mitra app |
| 5 | Control center: max config + mitra online status column + logs | Control center |
| 6 | Pairing service + chat request APIs (mitra + client) | Backend |
| 7 | Client app: pairing flow (request, searching, found, paired screens) | Client app |
| 8 | Mitra app: incoming request notification + accept/decline | Mitra app |
| 9 | Session management APIs (end, reroute, list) | Backend |
| 10 | Client/mitra app: active session screen + end session | Both apps |
| 11 | Control center: dashboard + session management + reroute | Control center |

---

## 7. New Dependencies

| App | Package | Purpose |
|---|---|---|
| Backend | `ioredis` or `@valkey/valkey-glide` | Valkey/Redis client for pub/sub |
| Mitra app | `dio` (existing) | SSE via streaming response |
| Client app | `dio` (existing) | SSE via streaming response |

No major new dependencies needed — leveraging existing stack.

---

## 8. Note for Next Phase

**Valkey vs FCM — complementary, not competing:**
- **Valkey pub/sub** is the real-time transport for in-app events (pairing blasts, status updates, and later chat messages). Works when the app is in foreground.
- **FCM (Firebase Cloud Messaging)** should be added in the next phase for push notifications when the app is backgrounded/closed (e.g. "New message from customer"). Not needed this phase because mitras auto-go offline when the app is backgrounded — they only receive pairing requests while in foreground.
- Architecture: Valkey for real-time transport, FCM for push notifications. They layer on top of each other.