halobestie-clone/requirement/phase3.7.md

# PRD: Phase 3.7 — Paid Pairing Flow + Returning-Chat + Extension Flip

# Overview

**Goal:** Reshape the customer pairing path so that **payment precedes blast** (today: blast fires immediately on CTA, no payment in path), gate the home CTA on real-time mitra availability, add a "chat with the same bestie again" path from chat history, give mitras a short approval window on returning-chat requests (20s, auto-reject), and **flip extension behavior** from auto-reject to auto-approve (10s).

**Success looks like:**
- A customer can only tap "Mulai Curhat" when at least one mitra is online and has spare capacity.
- Tapping the CTA leads to a payment screen → confirmation → blast → mitra accept → chat.
- A customer can re-engage a previous bestie directly from chat history; that bestie has 20s to confirm before auto-reject.
- An in-progress chat extension is auto-approved if the mitra doesn't respond within 10s (current behavior auto-rejects); customer is charged at approval moment, never before.
- Every payment that does not result in a chat is persisted with a cause-tag and surfaced in the control center for manual review/refund.

**Affects:** `client_app`, `mitra_app`, `backend`, `control_center`

## Background

- **Phase 2** introduced instant blast on CTA tap — no payment in path, first-mitra-to-accept wins via DB-level uniqueness.
- **Phase 3** introduced WebSocket chat, an extension flow that **auto-rejects** on timeout, mock pricing service (free-trial + tiered prices), and FCM push for incoming requests.
- **Phase 3.5** exposed chat-request history for mitras with a CTA badge on home.
- **Pricing remains mocked** for Phase 3.7 — no real Xendit; real pricing/tiers + real Xendit are deferred to a later phase. (See memory: "Pricing Still Mocked Through Phase 3.7".)
- **Anonymity rule unchanged** (mitra always sees customer call_name; phone+email private; no legacy masking).

## Phase numbering note

Originally captured under "Phase 4" filename. Renamed to **Phase 3.7** at user request — same scope, different number.

---

# Functional Requirements

## 1. CTA Gating on Customer Home (mitra availability)

### 1.1 Polling
- The "Mulai Curhat" CTA on customer home polls `GET /api/client/mitra-availability` **every 5 seconds** while the home screen is **foregrounded**. Polling pauses on background and resumes on foreground.
- No background poll. No FCM-triggered refresh. Pull-to-refresh on home triggers an immediate poll.

### 1.2 Endpoint
- **New:** `GET /api/client/mitra-availability`
- **Response:** `{ "available": boolean, "count"?: number }`
- `available = true` ⟺ **at least one mitra is online AND below their max-customer capacity** (per existing `app_config.max_customers_per_mitra`).
- `count` is optional, included for control-center debugging only — the client must read only `available`.
- **Implementation constraint:** the endpoint must compute availability from **Valkey only** (existing online-status keys + active-session counters). It must NOT issue per-poll Postgres queries.

### 1.3 CTA visual state
| State | Visual | Subtitle |
|---|---|---|
| `available = true` | Enabled (default style) | Existing copy ("Mulai cerita ke bestie") |
| `available = false` OR poll failed | Greyed-out, non-tappable | "Belum ada bestie tersedia" |

- Binary only — **never show the count** (e.g. "3 bestie tersedia") in the customer UI.
- On poll failure (network error, 5xx, timeout): default to greyed-out — do **not** keep the last-known state.

---

## 2. New Pairing Flow: CTA → Payment → Blast → Accept → Chat

### 2.1 Flow overview
```
[Customer Home: CTA enabled]
        ↓ tap
[Payment Screen]
        ↓ confirm (mock)
[Backend: payment_session row created (status=confirmed)]
        ↓
[Existing "Searching for bestie..." screen]
        ↓ blast to all available mitras
        ↓ first accept wins (existing DB uniqueness)
[Chat starts — existing WS chat flow]
```

### 2.2 Payment screen (mocked)
- New screen: **Pilih Sesi & Bayar** (or whatever copy fits the existing style).
- Reuses the existing **mock pricing service** (Phase 3 tiers + free trial). No new pricing tables, no Xendit SDK, no webview.
- Layout: tier/duration picker + "Total" line + primary CTA "Bayar".
- **Free-trial-eligible customer:** the screen shows the tier picker but the Total displays "Gratis" / Rp 0. Primary CTA reads "Mulai" (still goes through the same confirm step — does **not** skip directly to blast).
- On confirm tap → backend creates a `payment_session` row with `status = confirmed`, returns `{ payment_session_id }`.
- Customer is then routed to the existing "Searching for bestie..." screen, carrying `payment_session_id`.

### 2.3 Payment-session lifecycle
- **Status enum:** `pending` (screen open, not confirmed yet) → `confirmed` (confirm tap succeeded) → `consumed` (chat session started against this payment) | `failed_pairing` (no mitra accepted) | `abandoned` (customer closed payment screen) | `expired` (TTL elapsed before confirm).
- **TTL:** payment session expires after `payment_session_timeout_minutes` (default **20 min**, **CC-configurable**) from creation. Background sweeper transitions stale `pending` rows to `expired`.
- **Abandonment:** if the customer closes the payment screen / backs out before tapping confirm, the row is left in `pending` (will eventually expire). No active rollback needed.

### 2.4 Blast & accept
- Once the screen receives `payment_session_id`, the existing Phase 2 blast logic runs as today, with one change: the resulting `chat_session` row carries a `payment_session_id` foreign key.
- **Idempotency unchanged:** the existing DB-level unique constraint on session acceptance (Phase 2) ensures first-mitra-wins.
- On successful accept → `payment_session.status = consumed`, chat begins (existing WS flow).

### 2.5 Failed pairing — single consistent model (also applies to Sections 5 and 6)
When a payment is `confirmed` but no chat starts (no mitra accepts within blast window, all mitras explicitly reject, targeted mitra rejects/auto-rejects, payment expires before consume, customer cancels mid-search):

1. The `payment_session` row stays in DB; status transitions to `failed_pairing` (or `expired` / `abandoned` as appropriate).
2. A **failed-pairing event** row is written to a new `pairing_failures` table (or equivalent) with a **`cause_tag`** for filter/audit:
   - `no_mitra_available` — no mitra accepted within the general blast window
   - `all_mitras_rejected` — every blasted mitra explicitly declined
   - `targeted_mitra_offline` — returning-chat target was offline at request time
   - `targeted_mitra_rejected` — returning-chat target explicitly declined within the 20s window
   - `targeted_mitra_timeout` — returning-chat target did not respond within 20s
   - `payment_session_expired` — TTL elapsed before customer confirmed or before chat started
   - `customer_cancelled` — customer abandoned during searching/waiting
3. Surfaced to the **control center** in a new **"Failed Pairings"** review screen (filterable by `cause_tag` and date), where an operator can manually mark a row as: refunded / credit issued / no-action. The actual refund/credit operation is mock for Phase 3.7 (no real money movement) — operator action just records the decision in the row.
4. **Customer-facing copy** (used everywhere a failed pairing terminates the flow): _"Maaf, kami tidak bisa menemukan bestie untuk sesimu. Tim kami akan menghubungimu segera."_ — with a "Kembali ke beranda" CTA. This copy will be revised in a later phase; ship the placeholder for now.

### 2.6 Customer screen during blast
- Reuse the existing Phase 2 "Searching for bestie..." screen as-is. Real visual design will land in a later UI-design pass.

### 2.7 Blast timeout
- The general blast timeout reuses the Phase 2 value. If it is not already CC-configurable, expose it as `pairing_blast_timeout_seconds` in the same CC config screen.

---

## 3. "Curhat lagi" — Returning Chat from Chat History

### 3.1 CTA placement
- Every row in the customer's chat-history list gets a **"Curhat lagi"** CTA. Per-row, not per-unique-mitra.
- The CTA targets the mitra of that specific session.

### 3.2 Flow
```
[Chat History Row: "Curhat lagi"]
        ↓ tap
[Payment Screen — same as Section 2.2]
        ↓ confirm
[Backend: targeted-request created against this mitra]
        ↓ FCM push + WS event to that mitra
[Customer overlay: "Menunggu konfirmasi bestie..." + Cancel]
        ↓ within 20s: mitra accepts → chat starts
        ↓ within 20s: mitra rejects OR 20s expires (auto-reject)
        ↓ at request time: mitra is offline OR at-capacity-not-mid-session
[Popup: "Bestie sedang tidak online" (or analogous)
        + option "Chat dengan bestie lain" if any other mitra is available]
```

### 3.3 Pre-tap: targeted mitra status
- "Curhat lagi" does **not** depend on the Section 1 availability poll — it depends only on the targeted mitra's status (queried at tap time, not pre-cached on each row).
- The targeted-mitra status check happens server-side as part of creating the targeted request.

### 3.4 Targeted mitra unavailable at request time
If, at the moment of tapping "Curhat lagi" (before the 20s window starts):
- The targeted mitra is **offline** (not online in Valkey), or
- The targeted mitra is **at capacity AND not mid-session with the requesting customer**

then the request is **not** sent. Customer sees a popup:
- **Title:** "Bestie sedang tidak online"
- **Body:** brief explanation copy
- **CTAs:**
  - If any other mitra is available (per Section 1 logic): primary "Chat dengan bestie lain" — invokes the general blast flow against the same payment session (no double-charge)
  - Always: "Kembali"

### 3.5 Targeted mitra is mid-session with someone else (concurrency)
- If the targeted mitra is online and currently in another active chat: still send the targeted request card. Let the mitra decide (they may wrap up the active chat, or they may decline). No automatic block.

### 3.6 During the 20s window — mitra side
See Section 4.

### 3.7 During the 20s window — customer side
- Customer sees an overlay on top of the searching/payment-confirmed state:
  - **Copy:** "Menunggu konfirmasi bestie..."
  - **Cancel button:** customer can cancel before the mitra responds. On cancel: targeted request is closed, payment session enters `failed_pairing` with `cause_tag = customer_cancelled`.

### 3.8 On rejection / 20s auto-reject
- The same fallback popup as Section 3.4 is shown ("Bestie sedang tidak online" / similar copy):
  - Primary CTA "Chat dengan bestie lain" (if other mitras available) — fires general blast with the **same payment session**, no double-charge.
  - "Kembali" — terminates the flow; payment_session ends in `failed_pairing` with `cause_tag = targeted_mitra_rejected` or `targeted_mitra_timeout`.
- If general blast also fails: payment ends in `failed_pairing` with `cause_tag = no_mitra_available` (or `all_mitras_rejected` per Section 2.5), and the standard failed-pairing copy from Section 2.5 is shown.

### 3.9 Anonymity
- Unchanged. Mitra sees the customer's `call_name`. No phone, no email.

---

## 4. Returning-Chat Approval Window (Mitra Side, 20s, Auto-Reject)

### 4.1 Mitra UX
- Reuse the existing incoming-request notification component (FCM background push + foreground accept/decline card).
- **Add a visible 20s countdown** to the card (the only visual change).
- The card's accept/decline buttons retain current behavior; on tap → existing accept endpoint.

### 4.2 Auto-reject on timeout
- If the mitra does not tap accept or decline within 20s: backend marks the targeted request as auto-rejected (`response = ignored` or a new `auto_rejected` value — implementation detail for the plan doc).
- Triggers the customer-side fallback popup (Section 3.8).

### 4.3 Mitra offline at request time
- If the targeted mitra is offline in Valkey at the moment the request would be created: do **not** send the request. Trigger the customer-side popup (Section 3.4) immediately. Do not wait the full 20s.

### 4.4 Mitra mid-session with someone else
- See Section 3.5. Card is sent regardless; mitra decides.

### 4.5 New CC config
- **Row:** `returning_chat_confirmation_timeout_seconds`
- **Default:** `20`
- **CC label:** "Batas waktu konfirmasi chat lanjutan (detik)"
- **CC explanation:** "Berapa detik bestie punya waktu untuk menerima/menolak permintaan chat lanjutan dari customer sebelum otomatis ditolak."
- **Effective immediately** on save (no app restart required) — read by backend per request.

---

## 5. Extension Approval Flip (10s, Auto-Approve)

### 5.1 Behavior change — confirmed intentional
Phase 3 today: extension request **auto-rejects** on mitra non-response.

Phase 3.7: extension request **auto-approves** on mitra non-response within 10s, with safeguards (Section 5.5).

### 5.2 Customer flow (price-then-charge)
- Extension is **never auto-charged**. The customer first chooses extension duration + price (same UX as initial chat request, but **without the free trial path**).
- Once the customer confirms duration + price → request is sent to mitra with a 10s window.
- The customer sees an overlay: "Menunggu konfirmasi extension..." (existing copy, just shorter timer).

### 5.3 Charge timing
- **At approval moment**: when the mitra explicitly approves OR the 10s timer auto-approves, the extension is charged (mock charge — same `payment_session` mechanism as Section 2 but bound to the existing chat session).
- If the mitra explicitly rejects within 10s: **no charge**.
- If auto-approve fires due to mitra non-response → charge fires.
- If safeguard auto-rejects (Section 5.5) → no charge.

### 5.4 Mitra UX
- Existing extension card stays visually the same; copy adjusted to reflect auto-approve (e.g. "Tidak menjawab dalam 10 detik = otomatis disetujui").
- Buttons unchanged.

### 5.5 Safeguard — mitra disconnected/offline during the 10s
Auto-approve does **not** fire if the mitra:
- Is **disconnected** from WS at the moment the 10s timer expires, OR
- Has flipped themselves to **offline** (Valkey state) since receiving the extension request.

In either case, treat as **auto-reject** — no charge, customer sees the standard extension-rejected UX.

> **Domain rule (memory: "Mitra Can Go Offline Mid-Session"):** A mitra can go offline during an active session. Never use "in-session" as a proxy for "online".

### 5.6 New CC config
- **Existing row:** the Phase 3 `extension_timeout_seconds` config stays. Default value updated to **10** during the 3.7 migration.
- **New row:** `extension_default_action_on_timeout` — enum (`auto_reject` | `auto_approve`), default `auto_approve`.
- **CC label:** "Aksi default jika bestie tidak menjawab extension"
- **CC explanation:** "Jika bestie tidak merespon permintaan extension dalam batas waktu, sistem akan otomatis menerima atau menolak sesuai pilihan ini."

This data-driven approach means we can flip the behavior back to auto-reject without a deploy if needed.

---

## 6. Control Center — New Configs and Failed-Pairings Screen

### 6.1 Config additions
| Key | Type | Default | Label | Explanation |
|---|---|---|---|---|
| `pairing_blast_timeout_seconds` | int | (existing Phase 2 value, if not already configurable) | "Batas waktu blast pairing (detik)" | "Berapa lama backend menunggu mitra menerima sebelum blast dianggap gagal." |
| `payment_session_timeout_minutes` | int | 20 | "Batas waktu sesi pembayaran (menit)" | "Sesi pembayaran customer akan kedaluwarsa otomatis setelah durasi ini jika belum dikonfirmasi atau belum menghasilkan chat." |
| `returning_chat_confirmation_timeout_seconds` | int | 20 | "Batas waktu konfirmasi chat lanjutan (detik)" | (per Section 4.5) |
| `extension_default_action_on_timeout` | enum | `auto_approve` | "Aksi default jika bestie tidak menjawab extension" | (per Section 5.6) |

### 6.2 Failed Pairings screen
- New CC route: `/failed-pairings`.
- Table columns: `created_at`, `customer_call_name`, `targeted_mitra_call_name` (nullable), `cause_tag`, `payment_amount` (mock), `operator_action` (none / refunded / credited / no-action), `actioned_by`, `actioned_at`.
- Filters: `cause_tag` (multi-select), date range.
- Per-row action menu: **Mark as refunded**, **Mark as credited**, **Mark as no-action**. All three just record the decision (no real money movement in 3.7).
- No bulk actions in this phase.

### 6.3 Existing CC screens — no changes other than the config row additions and the failed-pairings entry in the navigation.

---

## 7. Migration — Replace Phase 2 Instant Blast Entirely

### 7.1 Removals (no kill-switch, no feature flag)
- Customer-side: the existing direct CTA → blast wiring in `client_app` is removed.
- Backend: the route(s) that bypass payment to start a blast are removed (existing endpoints are repurposed: blast no longer fires until a confirmed `payment_session` exists).
- Any client-side state assuming "tap CTA = immediate searching" is updated to route through payment first.

### 7.2 Reuse vs. replace (per 2c.2)
- **Reuse:** "Searching for bestie..." screen, "Found bestie" screen, "No bestie found" screen, ChatBloc, ChatRequestBloc/notifier, mitra incoming-request card.
- **Replace / new:** Payment screen (new), payment-session lifecycle service (new), `pairing_failures` table + service (new), failed-pairings CC screen (new).

### 7.3 Data migration
- New tables: `payment_sessions`, `pairing_failures`. Migrations created per backend convention.
- New column: `chat_sessions.payment_session_id` (nullable for backward compat with any pre-3.7 rows; required for newly-created rows).
- No backfill of historical sessions.

---

## 8. Edge Cases

- **Customer logs out mid-payment** — payment_session left as `pending`, expires on TTL.
- **Customer logs out mid-search** — payment_session transitions to `failed_pairing` with `cause_tag = customer_cancelled` (signal: WS disconnect + no consume within blast window).
- **Targeted mitra accepts after auto-reject fired** — race rejected by the existing DB uniqueness; mitra sees a "request no longer available" state via existing UX.
- **Customer hits "Curhat lagi" on a session whose mitra has been deactivated** — treat as `targeted_mitra_offline` (offline in Valkey will be true for deactivated mitras).
- **Free-trial customer abandons the Gratis confirmation** — payment_session left `pending` with mock `amount = 0`; expires on TTL; no failed-pairing event (never confirmed).
- **Customer taps CTA exactly as the last available mitra goes offline** — payment screen still renders (gating is best-effort, not transactional). After confirmation, blast fires and falls into the standard "no_mitra_available" failed-pairing path.
- **Extension auto-approve fires; mitra reconnects 1s later** — they see the extended session as already extended; no surprise UX needed.
- **Mitra force-quits app during the 20s returning-chat window** — auto-reject fires at 20s; this is the desired safer behavior (matches Section 4.2).

---

## 9. Non-Goals (this phase)

- Real Xendit checkout / webview / redirect (deferred).
- Real pricing or finalized tiers (deferred — keeps mock).
- Auto-refund / auto-credit transactions (CC operator records the decision; no actual money movement).
- New customer chat-history UI design (reuses existing rows + adds CTA only).
- New "Searching for bestie..." visual design (reuses existing).
- Bulk actions on failed-pairings.
- Mitra-side history of returning-chat requests (covered by Phase 3.5 chat-request history; same component).
- Push-notification preferences for the new fallback popup.
- Wallet / credit balance UX on the customer app (failed-pairings handled CC-side only for now).

---

# Open Questions

_None — ready for `phase3.7-plan.md`._