# Phase 3.7 — Implementation Plan

> See [phase3.7.md](phase3.7.md) for the PRD and [phase3.7-questions.md](phase3.7-questions.md) for the answered question doc.

This document is the build sequence: **what** files change, **in what order**, with **API contracts** for new endpoints. The "why" is in the PRD — don't restate it here.

---

## Build Order (4 stages)

The dependency graph forces this order:

1. **Backend foundation** — schema + config + new services (nothing user-visible yet)
2. **Backend routes** — endpoints, blast/extension behavior changes (smoke-testable via curl)
3. **Apps** — client_app + mitra_app cut over to the new flow
4. **Control center** — Failed Pairings screen + new config UI

Within each stage, items are listed in the order they should land.

---

# Stage 1 — Backend Foundation

## 1.1 Schema additions ([backend/src/db/migrate.js](../backend/src/db/migrate.js))

> The repo uses a single `migrate.js` script (no per-file migrations). Append new DDL to the existing script.

### New table: `payment_sessions`
```sql
CREATE TABLE IF NOT EXISTS payment_sessions (
  id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  customer_id     UUID NOT NULL REFERENCES users(id),
  amount          INTEGER NOT NULL DEFAULT 0,        -- mocked, in IDR (rupiah, no decimals)
  duration_minutes INTEGER NOT NULL,
  is_free_trial   BOOLEAN NOT NULL DEFAULT false,
  status          TEXT NOT NULL DEFAULT 'pending'
                  CHECK (status IN ('pending','confirmed','consumed','failed_pairing','abandoned','expired')),
  targeted_mitra_id UUID REFERENCES mitras(id),       -- NULL for general blast; set for "Curhat lagi"
  created_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
  confirmed_at    TIMESTAMPTZ,
  consumed_at     TIMESTAMPTZ,
  expires_at      TIMESTAMPTZ NOT NULL                 -- created_at + payment_session_timeout_minutes
);

CREATE INDEX IF NOT EXISTS idx_payment_sessions_customer ON payment_sessions(customer_id);
CREATE INDEX IF NOT EXISTS idx_payment_sessions_status_expires ON payment_sessions(status, expires_at);
```

### New table: `pairing_failures`
```sql
CREATE TABLE IF NOT EXISTS pairing_failures (
  id                  UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  payment_session_id  UUID NOT NULL REFERENCES payment_sessions(id) ON DELETE CASCADE,
  customer_id         UUID NOT NULL REFERENCES users(id),
  targeted_mitra_id   UUID REFERENCES mitras(id),
  cause_tag           TEXT NOT NULL
                      CHECK (cause_tag IN (
                        'no_mitra_available',
                        'all_mitras_rejected',
                        'targeted_mitra_offline',
                        'targeted_mitra_rejected',
                        'targeted_mitra_timeout',
                        'payment_session_expired',
                        'customer_cancelled'
                      )),
  amount              INTEGER NOT NULL,
  operator_action     TEXT
                      CHECK (operator_action IS NULL OR operator_action IN ('refunded','credited','no_action')),
  actioned_by         UUID REFERENCES cc_users(id),
  actioned_at         TIMESTAMPTZ,
  created_at          TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE INDEX IF NOT EXISTS idx_pairing_failures_created_at ON pairing_failures(created_at DESC);
CREATE INDEX IF NOT EXISTS idx_pairing_failures_cause ON pairing_failures(cause_tag);
CREATE INDEX IF NOT EXISTS idx_pairing_failures_unactioned ON pairing_failures(created_at DESC) WHERE operator_action IS NULL;
```

### `chat_sessions` — add nullable FK
```sql
ALTER TABLE chat_sessions ADD COLUMN IF NOT EXISTS payment_session_id UUID REFERENCES payment_sessions(id);
CREATE INDEX IF NOT EXISTS idx_chat_sessions_payment ON chat_sessions(payment_session_id);
```
> Nullable for backward compat with pre-3.7 sessions; required for newly-created rows (enforced at service layer, not DB).

### Seed new config rows
Append to seed step:
```sql
INSERT INTO app_config (key, value) VALUES
  ('payment_session_timeout_minutes', '20'),
  ('returning_chat_confirmation_timeout_seconds', '20'),
  ('extension_default_action_on_timeout', 'auto_approve'),
  ('pairing_blast_timeout_seconds', '<existing-Phase-2-default>')   -- only if not already present
ON CONFLICT (key) DO NOTHING;
```
Also: in the same seed step, **update** `extension_timeout_seconds` default to `10` ONLY for new installs (use `ON CONFLICT DO NOTHING`; existing dev DB will need a manual one-line update or CC change).

---

## 1.2 New service: `payment.service.js`

**File:** `backend/src/services/payment.service.js` (new)

Exports:
- `createPaymentSession({ customerId, durationMinutes, amount, isFreeTrial, targetedMitraId? })` → returns `{ id, status: 'pending', expiresAt }`. Reads `payment_session_timeout_minutes` from config to compute `expires_at`.
- `confirmPaymentSession(paymentSessionId, customerId)` → transitions `pending → confirmed`. Throws if not owned by customer / wrong status / expired.
- `consumePaymentSession(paymentSessionId)` → transitions `confirmed → consumed`. Called from pairing service when chat starts.
- `failPaymentSession(paymentSessionId, causeTag)` → transitions `confirmed → failed_pairing`, writes a `pairing_failures` row in the same transaction. Idempotent (no-op if already failed/consumed).
- `expireStalePaymentSessions()` → background sweeper: `pending` rows past `expires_at` → `expired`; `confirmed` rows past `expires_at` AND not consumed → `failed_pairing` with `cause_tag = 'payment_session_expired'`.
- `getPaymentSession(id)` — for routes.

## 1.3 New service: `pairing-failure.service.js`

**File:** `backend/src/services/pairing-failure.service.js` (new)

Exports:
- `recordFailure({ paymentSessionId, customerId, targetedMitraId?, causeTag, amount })` — used by `payment.service.failPaymentSession`. Kept in its own service for clean CC queries.
- `listFailures({ causeTags?, dateFrom?, dateTo?, limit, offset })` — for CC.
- `setOperatorAction(failureId, ccUserId, action)` — for CC operator action menu.

## 1.4 Modify: `mitra-status.service.js`

**File:** [backend/src/services/mitra-status.service.js](../backend/src/services/mitra-status.service.js)

Add a Valkey-only function:
- `countAvailableMitrasFromCache()` → reads online-mitra set + per-mitra active session counters from Valkey, compares against `max_customers_per_mitra` (cached value, refreshed on config change), returns `{ available: boolean, count: number }`. **No Postgres queries on the hot path.**

> The existing `getOnlineMitras()` joins to active session counts via DB — that's too heavy for a 5s poll. Build a parallel cached path. The capacity cap is read once on cold start and kept in memory; bust the cache when CC updates the config (existing config-update path can publish a Valkey invalidate event).

## 1.5 Modify: `extension.service.js`

**File:** [backend/src/services/extension.service.js](../backend/src/services/extension.service.js)

Changes (do not change the timeout numeric — just the action):
- Read `extension_default_action_on_timeout` from `app_config` when timer fires.
- If `auto_approve`: at timer fire, check **mitra connectivity** (WS + Valkey online status). If both OK → call existing approve path (which will trigger the mock charge). If either is offline/disconnected → treat as auto-reject (no charge). Update the `cause_tag` if a payment row is involved.
- If `auto_reject`: existing behavior unchanged (back-compat with the data-driven flag).
- Update extension-request creation: customer must pass `extension_payment_session_id` (separate payment session for the extension cost). If `is_free_trial = true` is not allowed for extensions — enforce server-side per PRD §5.2.

## 1.6 Modify: `pairing.service.js`

**File:** [backend/src/services/pairing.service.js](../backend/src/services/pairing.service.js)

Changes:
- `createPairingRequest()` now requires `paymentSessionId`. On entry: load the payment session, assert `status = confirmed` and ownership. Refuse with 409 if not.
- New variant: `createTargetedPairingRequest({ paymentSessionId, customerId, targetedMitraId })` for "Curhat lagi". Skips the broad blast — sends a single targeted notification, starts a server-side 20s timer (read from `returning_chat_confirmation_timeout_seconds`).
  - Pre-check: targeted mitra online? If not → fail immediately with `cause_tag = targeted_mitra_offline` (call `payment.service.failPaymentSession`), return 409 with `{ reason: 'targeted_mitra_offline' }`.
  - Pre-check: targeted mitra at capacity AND not mid-session with this customer? → same as offline.
  - On timer fire (no response): mark request as `auto_rejected`, fail payment with `cause_tag = targeted_mitra_timeout`, push WS event `RETURNING_CHAT_TIMEOUT` to customer.
  - On explicit decline: fail payment with `cause_tag = targeted_mitra_rejected`, push WS event `RETURNING_CHAT_REJECTED`.
  - On accept: existing accept path → `consumePaymentSession`, chat starts.
- `respondToPairingRequest()` (general blast) on success: call `consumePaymentSession`. On blast-window expiry without acceptance: call `failPaymentSession` with `cause_tag = no_mitra_available`. On every-mitra-rejected before timeout: `cause_tag = all_mitras_rejected`.
- New: `cancelPaymentSearch(paymentSessionId, customerId)` — customer-initiated cancel during searching/waiting → fail payment with `cause_tag = customer_cancelled`.
- New: `fallbackToGeneralBlast(paymentSessionId, customerId)` — used when "Chat dengan bestie lain" is tapped after a returning-chat fail. Reuses the same payment session (no new charge), runs the standard blast.

## 1.7 Modify: `pricing.service.js`

**File:** [backend/src/services/pricing.service.js](../backend/src/services/pricing.service.js)

- Add `getExtensionPriceTiers(customerId)` — same shape as initial pricing but always returns `is_free_trial = false` for every tier (per PRD §5.2 "no trial for extensions"). Existing `getPriceTiers()` for initial chat is unchanged.

## 1.8 Background sweeper

**File:** new entry in `backend/src/index.js` (or wherever existing intervals live; check for an existing `setInterval` pattern in the chat-session timer code).
- Run `paymentService.expireStalePaymentSessions()` every 60 seconds.
- When we scale to multi-instance, this should move to Valkey keyspace notifications (consistent with the existing memory item "Session Timer Scaling").

---

# Stage 2 — Backend Routes

## 2.1 New: `client.mitra-availability.routes.js`

**File:** `backend/src/routes/public/client.mitra-availability.routes.js` (new)

```
GET /api/client/mitra-availability
  → 200 { "available": true|false, "count": number? }
```
- Auth: customer JWT.
- Backed entirely by `countAvailableMitrasFromCache()`.
- No rate limit needed — this is a hot endpoint by design (every 5s per active customer).

## 2.2 New: `client.payment.routes.js`

**File:** `backend/src/routes/public/client.payment.routes.js` (new)

```
POST /api/client/payment-sessions
  body: { duration_minutes, tier_id?, targeted_mitra_id? }
  → 201 { id, amount, is_free_trial, expires_at, status: "pending" }

POST /api/client/payment-sessions/:id/confirm
  → 200 { id, status: "confirmed" }

POST /api/client/payment-sessions/:id/cancel
  → 200 { id, status: "abandoned" }       # only valid while pending; failed_pairing for already-confirmed search-cancel uses 2.3

GET  /api/client/payment-sessions/:id
  → 200 { ...full row }
```

Free-trial logic: the `POST` checks `pricingService.isCustomerEligibleForFreeTrial(customerId)` and computes `amount = 0, is_free_trial = true` accordingly.

## 2.3 Modify: `client.chat.routes.js` (existing)

**File:** [backend/src/routes/public/client.chat.routes.js](../backend/src/routes/public/client.chat.routes.js)

Changes:
- The "start search" route now requires `payment_session_id` in the body. Old shape rejected with 400.
- Add `POST /api/client/chat-requests/cancel` → forwards to `pairing.service.cancelPaymentSearch`.
- Add `POST /api/client/chat-requests/returning` → body `{ payment_session_id, mitra_id }`, forwards to `createTargetedPairingRequest`.
- Add `POST /api/client/chat-requests/:paymentSessionId/fallback-to-blast` → forwards to `fallbackToGeneralBlast`.

Existing routes that bypass payment (any "start blast directly") — **delete**.

## 2.4 Modify: `client.chat.routes.js` (extension)

Update extension request route to require `extension_payment_session_id`. Free-trial path is forbidden (return 400 if `is_free_trial = true`).

## 2.5 New: `internal.failed-pairings.routes.js`

**File:** `backend/src/routes/internal/failed-pairings.routes.js` (new)

```
GET  /internal/failed-pairings
  query: cause_tags[]?, date_from?, date_to?, limit=50, offset=0
  → 200 { rows: [...], total }

POST /internal/failed-pairings/:id/action
  body: { action: "refunded"|"credited"|"no_action" }
  → 200 { ...updated row }
```
Auth: existing CC JWT. Mount on the internal listener (port 3001).

## 2.6 Modify: `internal/config.routes.js`

**File:** [backend/src/routes/internal/config.routes.js](../backend/src/routes/internal/config.routes.js)

Add the four new keys to the allow-list (PRD §6.1):
- `pairing_blast_timeout_seconds` (int)
- `payment_session_timeout_minutes` (int)
- `returning_chat_confirmation_timeout_seconds` (int)
- `extension_default_action_on_timeout` (enum: `auto_reject` | `auto_approve`)

On any of these keys being updated, publish a Valkey invalidate event so the in-memory caches in `mitra-status.service` and `extension.service` refresh.

## 2.7 Smoke test (curl) — must pass before Stage 3

- Happy path: `POST payment-sessions` → `POST confirm` → `POST chat-requests` → mitra accepts → chat starts → `payment_sessions.status = consumed`.
- No-mitra path: same as above but no mitra accepts within blast window → `pairing_failures` row created with `cause_tag = no_mitra_available`.
- Returning-chat happy: `POST chat-requests/returning` → mitra accepts within 20s → chat starts.
- Returning-chat timeout: no mitra response in 20s → `cause_tag = targeted_mitra_timeout`.
- Returning-chat → fallback: `POST .../fallback-to-blast` → general blast runs against same payment session.
- Mitra-availability: `GET /api/client/mitra-availability` returns `{ available: true }` while at least one mitra is online and has spare capacity; flips to `false` when capacity hits cap.

---

# Stage 3 — Apps

## 3.1 client_app — Mitra availability poll

**File:** `client_app/lib/core/availability/mitra_availability_notifier.dart` (new)

Riverpod `AsyncNotifier`:
- `build()` — emits `AsyncData(false)` initially.
- Starts a 5s `Timer.periodic` only when the home screen is in the foreground (`AppLifecycleState.resumed`). Pauses on `paused`/`inactive`. Hook via `WidgetsBindingObserver` in the home screen.
- `refresh()` — manual trigger for pull-to-refresh.
- On HTTP failure → emit `AsyncData(false)` (default to disabled per PRD §1.3).

**File:** [client_app/lib/features/home/home_screen.dart](../client_app/lib/features/home/home_screen.dart)

Changes:
- Watch `mitraAvailabilityProvider`.
- "Mulai Curhat" CTA: enabled when `available == true`, otherwise greyed-out with subtitle "Belum ada bestie tersedia".
- Add lifecycle observer to gate the polling.

## 3.2 client_app — Payment screen

**File:** `client_app/lib/features/payment/screens/payment_screen.dart` (new)

- Reuses existing `pricingProvider` for tier list + free-trial check.
- Layout: tier picker + "Total" line ("Gratis" if free trial, else "Rp X") + primary CTA "Bayar" (or "Mulai" if free trial).
- On confirm tap → `POST /api/client/payment-sessions/:id/confirm` → push to searching screen with `payment_session_id`.
- On back/dispose: call `POST .../cancel` if status still `pending` (best-effort).

**File:** `client_app/lib/features/payment/payment_notifier.dart` (new)

Riverpod notifier managing the payment-session state for the screen.

**Routes:** add `/payment` to GoRouter. Replace the current `_onStartChatPressed` handler in `home_screen.dart` to push `/payment` instead of opening the pricing bottom-sheet directly.

## 3.3 client_app — Pairing notifier rewrite

**File:** [client_app/lib/core/pairing/pairing_notifier.dart](../client_app/lib/core/pairing/pairing_notifier.dart)

Changes:
- `startSearch()` now requires `paymentSessionId`. The HTTP body changes accordingly.
- New state variants:
  - `PairingTargetedWaitingData(mitraName, secondsRemaining)` — for the 20s returning-chat overlay.
  - `PairingFailedData(causeTag, fallbackOffered: bool)` — for the failed-pairing terminal screen.
- Listen to new WS events: `RETURNING_CHAT_TIMEOUT`, `RETURNING_CHAT_REJECTED`.

## 3.4 client_app — Searching/found/no-bestie screens

**Reuse** [searching_screen.dart](../client_app/lib/features/chat/screens/searching_screen.dart), [bestie_found_screen.dart](../client_app/lib/features/chat/screens/bestie_found_screen.dart) as-is.

**Modify** [no_bestie_screen.dart](../client_app/lib/features/chat/screens/no_bestie_screen.dart): becomes the **failed-pairing terminal screen**. Shows the standard copy from PRD §2.5 ("Maaf, kami tidak bisa menemukan bestie...") + "Kembali ke beranda" CTA.

**New widget:** `client_app/lib/features/chat/widgets/targeted_waiting_overlay.dart` — modal overlay shown above the searching screen during the 20s window. Cancel button → `POST /api/client/chat-requests/cancel`.

**New widget:** `client_app/lib/features/chat/widgets/bestie_unavailable_dialog.dart` — popup for §3.4/§3.8: title "Bestie sedang tidak online" + "Chat dengan bestie lain" CTA (only if general availability allows) + "Kembali" CTA. The "Chat dengan bestie lain" CTA calls `POST .../fallback-to-blast` then transitions to the searching screen.

## 3.5 client_app — Chat history "Curhat lagi" CTA

**File:** [client_app/lib/features/chat/screens/chat_history_screen.dart](../client_app/lib/features/chat/screens/chat_history_screen.dart)

Add a **"Curhat lagi"** trailing button on every row. On tap:
1. Push `/payment?targetedMitraId=<id>` (payment screen reads the param; passes `targeted_mitra_id` to `POST /payment-sessions`).
2. After confirm → `POST /chat-requests/returning` → push the searching screen with the targeted-waiting overlay shown.

## 3.6 mitra_app — Returning-chat card

**File:** [mitra_app/lib/core/chat/widgets/chat_request_overlay.dart](../mitra_app/lib/core/chat/widgets/chat_request_overlay.dart)

- Reuse the existing component for general blast requests.
- Add a 20s countdown when the WS payload indicates `request_type = 'returning'`. Overlay closes itself if no action by 0s (UI follows server; server is the source of truth on auto-reject).

**File:** [mitra_app/lib/core/chat/chat_request_notifier.dart](../mitra_app/lib/core/chat/chat_request_notifier.dart)

- Handle the new WS payload field `request_type`. Branch the overlay rendering accordingly.

## 3.7 mitra_app — Extension card copy

**File:** existing extension card widget (find via grep for `ExtensionRequestData` — likely in `mitra_app/lib/features/chat/widgets/extension_request_card.dart` or similar).

- Update copy: "Tidak menjawab dalam 10 detik = otomatis disetujui" (or whatever the team prefers in Bahasa).
- No behavior change — the auto-approve fires server-side.

## 3.8 client_app — Extension flow

- Customer-side: extension request still opens an in-app picker for duration + price (reuse the pricing UX, omit the free-trial path).
- On submit → create an `extension_payment_session` (calls the new payment route with no `targeted_mitra_id`, just an `is_extension: true` flag — small adjustment in `client.payment.routes.js`).
- On mitra approve / auto-approve → existing extended-session UX kicks in.
- On mitra reject within 10s → existing rejected UX, no charge.

---

# Stage 4 — Control Center

## 4.1 Settings page additions

**File:** [control_center/src/pages/settings/SettingsPage.jsx](../control_center/src/pages/settings/SettingsPage.jsx)

Add four new rows (follow the existing `useQuery`+`useMutation` pattern at lines 14-76):
- `payment_session_timeout_minutes` — number input
- `returning_chat_confirmation_timeout_seconds` — number input
- `extension_default_action_on_timeout` — radio/select: "Auto-approve" / "Auto-reject"
- `pairing_blast_timeout_seconds` — number input (only if not already present)

Use the same Indonesian labels and explanations from PRD §6.1.

## 4.2 New: Failed Pairings page

**File:** `control_center/src/pages/failed-pairings/FailedPairingsPage.jsx` (new)

- Table per PRD §6.2.
- Filters: cause-tag multi-select, date range.
- Per-row action menu: "Mark as refunded" / "Mark as credited" / "Mark as no-action" → `POST /internal/failed-pairings/:id/action`.

**File:** [control_center/src/components/Layout.jsx](../control_center/src/components/Layout.jsx)

Add a sidebar entry "Failed Pairings" → `/failed-pairings`.

**File:** wherever the React Router routes live — register the new page.

---

# Verification Checklist

Before declaring done:

- [ ] Stage 1: `node backend/src/db/migrate.js` runs cleanly; new tables and config rows exist.
- [ ] Stage 2: All curl smoke tests in §2.7 pass.
- [ ] Stage 3 client_app: home CTA disables when last mitra goes offline; payment screen renders; happy-path E2E chat starts; "Curhat lagi" path works end-to-end including the targeted-mitra-offline popup; cancel mid-search creates a failed-pairing row.
- [ ] Stage 3 mitra_app: returning-chat card shows the 20s countdown; auto-reject lands in failed-pairing; extension card shows new copy; auto-approve fires when mitra ignores it; auto-reject fires when mitra goes offline mid-extension-window.
- [ ] Stage 4: Failed Pairings page lists all rows from a test run and lets operator action a row; new config rows save and take effect (test by changing `returning_chat_confirmation_timeout_seconds` to 5 and watching auto-reject fire faster).
- [ ] Old instant-blast code paths are gone — grep confirms no remaining call sites.

---

# Risk Notes

- **Cache invalidation for `countAvailableMitrasFromCache()`** — if we get the config-update Valkey publish wrong, the 5s poll will lie about availability for stale-cache duration. Mitigation: keep the cache TTL short (10s) as a backstop even when invalidate isn't published.
- **Server-side timer for the 20s returning-chat window** — uses `setTimeout` per the existing pattern. Will not survive a backend restart mid-window. Acceptable for single-instance deploy; for multi-instance, fold into the existing Valkey-keyspace-notification follow-up (memory item "Session Timer Scaling").
- **Background sweeper race** — `expireStalePaymentSessions` runs every 60s; an extension request that lands on an expiring payment session in the same minute could see a confusing state. Mitigate by checking expiry inline at every state transition (`confirmPaymentSession`, `consumePaymentSession`).
- **Failed-pairing copy is a placeholder** — PRD §2.5 explicitly notes the copy will be revised. Don't over-invest in the design.

---

# Open Questions

_None — ready to start coding from Stage 1._