halobestie-clone/requirement/phase3.2.md

# PRD: Mitra Chat Request Overlay & Pairing UX

# Overview

**Goal:** Reliable incoming chat request experience for Mitra — always visible, non-blocking, works in all app states (foreground, background, killed)

**Success looks like:** When a customer requests a chat, the mitra is always notified and can accept/reject without leaving their current screen. The notification works regardless of whether the app is in foreground, background, or opened from a push notification.

## Background
- Current bottom sheet approach (`showModalBottomSheet`) fails silently when the app is backgrounded
- Flutter UI cannot render when the app is not in foreground
- Push notifications work in background but the in-app response (bottom sheet) doesn't show reliably when the user taps the notification
- The state change from WebSocket gets "consumed" by listeners while backgrounded, so returning to foreground shows stale data
- Need a solution that is non-blocking (doesn't interrupt active chat sessions) and works on any page


# Functional Requirement

## Incoming Chat Request Overlay

### Trigger
- Overlay watches `chatRequestProvider` state — it does NOT depend on any specific page or lifecycle event
- Three sources can trigger the overlay:
    1. **WebSocket** — real-time delivery when app is in foreground
    2. **FCM notification tap** — user taps push notification, app opens, state is set from notification payload
    3. **App resume** — app returns to foreground, validates pending request with backend

### Appearance
- Slides up from the bottom of the screen, like a bottom sheet
- Rounded top corners
- Page behind is partially dimmed to get mitra's attention
- Shows on top of ANY page (home, chat, history, settings, etc.)

### Content
- Session information (duration, etc.)
- Accept button
- Reject button
- Swipe down to close (= ignore, NOT reject)

### Behavior
- **Accept** → overlay dismisses, navigate to chat session with customer
- **Reject** → overlay dismisses, mitra continues what they were doing
- **Swipe down / close** → overlay dismisses, request is ignored (no explicit reject sent to backend)
- **Request cancelled by customer** → overlay updates to show "Permintaan dibatalkan oleh customer"
- **Request accepted by other mitra** → overlay updates to show "Permintaan diterima oleh Bestie lain"
- **Request expired (60s timeout)** → overlay updates to show "Permintaan kedaluwarsa"
- Stale messages do NOT auto-dismiss — mitra must acknowledge by tapping OK or swiping down

### Multiple Requests
- Show one request at a time
- Requests are queued — when current request is resolved (accepted/rejected/ignored/expired), next queued request appears
- Future enhancement: dedicated `/chat-requests` page with full list

## Push Notification (Background/Killed)

### When App is Backgrounded
- Local notification with sound + vibration (already implemented via WebSocket listener)
- FCM push notification as fallback when WebSocket is disconnected

### When Notification is Tapped
- App opens → `chatRequestProvider` state is set from notification payload (`session_id`)
- Overlay appears with the request detail
- Backend validation confirms request is still pending before showing accept/reject

### Stale Notification Handling
- If user taps a notification for an already-resolved request, overlay shows appropriate message ("dibatalkan" / "diterima Bestie lain" / "kedaluwarsa") then auto-dismisses


## Mitra Request Activity Log

### Goal
Track every mitra's response to incoming chat requests for QC measurement — how many accepted, rejected, ignored (expired without action), and how many active sessions they had at the time.

### Logged Data
For each incoming request delivered to a mitra, log:
- `mitra_id` — which mitra received the request
- `session_id` — which chat request
- `response` — `accepted`, `rejected`, `ignored` (expired without action), `missed` (taken by other mitra before response)
- `response_time_seconds` — how long it took the mitra to respond (null if ignored)
- `active_session_count` — how many active sessions the mitra had at the time of the request
- `notified_at` — when the request was delivered to the mitra
- `responded_at` — when the mitra responded (null if ignored)

### When to Log
All logging is **backend-side and event-driven** — no polling or constant monitoring needed. The frontend only triggers `accepted` and `rejected` through existing API calls.

| Response | Triggered by | Frontend action? |
|---|---|---|
| `accepted` | Backend — when mitra calls `POST /:sessionId/accept` | Yes — mitra taps Accept |
| `rejected` | Backend — when mitra calls `POST /:sessionId/decline` | Yes — mitra taps Reject |
| `missed` | Backend — when `acceptPairingRequest` marks other mitras' notifications (another mitra accepted first) | No — fully backend |
| `ignored` | Backend — when `expirePairingRequest` fires after 60s timeout with no response | No — fully backend |

### Existing Infrastructure
The `chat_request_notifications` table already tracks `notified_at`, `response`, `responded_at`. Current changes needed:
- Distinguish `missed` from `ignored` (currently both stored as `ignored`)
- Add `active_session_count` column — recorded when the notification is created
- `response_time_seconds` can be calculated from `responded_at - notified_at` (no new column needed)

### Control Center
- New dedicated page: Mitra Request Activity
- Dashboard: mitra acceptance rate, average response time, rejection count, ignore count per mitra
- Filter by date range and mitra
- Auto-flagging mitras with high rejection/ignore rate is **out of scope** for this phase (planned for future)


## Technical Implementation

### Overlay Component
- Single `OverlayEntry` managed from `main.dart`
- Wrapped around `MaterialApp.router` in a `Stack`
- Watches `chatRequestProvider` — shows/hides based on state
- Uses `AnimatedPositioned` or `SlideTransition` for bottom-up animation
- `GestureDetector` for swipe-to-dismiss

### State Flow
```
WebSocket  ──→
FCM tap    ──→  chatRequestProvider  ──→  Overlay shows/hides
App resume ──→
```

### No Changes Required
- Backend pairing service (already sends WS + FCM)
- Push notification payload (already contains session_id + type)
- Chat request notifier (already manages state from WS + FCM)

### Cleanup from Phase 3.1
- Remove `showModalBottomSheet` for incoming requests from home screen
- Remove `IncomingRequestSheet` widget
- Remove `didChangeAppLifecycleState` incoming request check from home screen


# Tech Stack
- Flutter `Overlay` / `OverlayEntry` or `Stack` with `AnimatedPositioned`
- Existing Riverpod `chatRequestProvider`
- No backend changes