Phase 4 Stage 10 backend: Chat-tab feeds (pending payments + cursor history)

Backend half of Stage 10 — the new Chat tab in the customer app that
replaces /chat/history with a 3-sub-tab list (Aktif / Pembayaran /
Selesai).

- New GET /api/client/payment-sessions/pending — returns the customer's
  pending initial + extension payment sessions. Filter is status='pending'
  AND expires_at > NOW(). Mitra info comes from session_extensions →
  chat_sessions for extension rows, payment_sessions.targeted_mitra_id
  for targeted-curhat-lagi initial rows. TTL reuses the existing
  payment_session_timeout_minutes app_config row (default 20m) — no new
  config row needed since payment is still mocked.

- getCustomerHistory migrated from offset (page/limit) to cursor
  pagination. Cursor is base64url(`<endedAtIso>|<id>`) with id-tiebreak
  in ORDER BY so rows with identical timestamps don't duplicate or skip
  across pages. SELECT now JOINs payment_sessions to surface `mode`
  (chat/call) for the Selesai-row voice-call pill.

- requirement/flow_customer.mermaid.md: new §7 Chat Tab subgraph + Figma
  cross-ref entry for SChatList.

- requirement/phase4-customer-flow-plan.md: Stage 10 plan section. Also
  carries forward earlier uncommitted "Post-Stage-8 corrections" notes
  from the Stage 9 sweep (boot path / SHome1st / onboarding fixes).

Tests: +7 for getCustomerPendingPayments (initial null mitra,
targeted-mitra fill, extension-via-session JOIN, mixed-newest-first,
expired excluded, non-pending excluded, customer scoping). +10 for
cursor history (empty, exact-fit, multi-page walk, same-timestamp
tiebreak, limit clamp, customer scoping, CLOSING+COMPLETED only).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

requirement/phase4-customer-flow-plan.md

@@ -4,8 +4,8 @@
 > on master (commits `4ada7c9` through `862fc35`, plus the pre-Phase-4
 > `4680c36` OTP test infrastructure). `flutter analyze` clean across
 > both apps; backend Vitest 15/15. **Stage 9 (test sweep) is
-> operator-driven and pending** — see `project_resume_next.md` in
-> agent memory for the run-list and known TODOs.
+> operator-driven and in progress** — see "Post-Stage-8 corrections"
+> below for fixes applied during the visual sweep.
 
 > See [phase4-customer-flow.md](phase4-customer-flow.md) for the PRD,
 > [flow_customer.md](flow_customer.md) for the source-of-truth flow,
@@ -791,6 +791,74 @@ Tapping launches `url_launcher` with the deeplink. No webview.
 
 ---
 
+# Post-Stage-8 corrections (2026-05-10, uncommitted)
+
+The first visual sweep of the live app caught that the boot path was still
+on Phase 1 plumbing — Splash → `/welcome` (Phase 1 social/phone picker) →
+forms — instead of the mermaid §1 contract: **Splash → Home (1st time / returning)**.
+The new home variants (`SHome1st`, `SHomeReturning`) had not been built;
+`home_screen.dart` was the Phase 1 placeholder with a Material AppBar +
+"Mulai Curhat" button.
+
+Fixes applied in the working tree (not yet committed):
+
+## C.1 `/welcome` retired
+
+- Route + `WelcomeScreen` import + `welcome_screen.dart` file all removed.
+- Router redirects (formerly pointing at `/welcome` for `AuthInitialData`,
+  `AsyncError`, and post-onboarding-carousel cases) now point at `/home`.
+- The router carve-out comment that referenced `/welcome` as the bottom of
+  the navigation stack updated to reference `/home`.
+- **Stage 2.6 of this plan is stale**: it described editing
+  `welcome_screen.dart` to read `authProvidersProvider`; that screen no
+  longer exists. The `authProvidersProvider` itself is preserved and is
+  now consumed only at the phone-OTP / future login-recovery surfaces.
+
+## C.2 `home_screen.dart` rewritten to Figma §1 spec
+
+- Renders `SHome1st` (`screens/v3.jsx::SHome1st`) for unauthenticated users
+  (any state that isn't `AuthAuthenticatedData` / `AuthAnonymousData`).
+- Renders `SHomeReturning` (`SHomeReturning`) for authenticated /
+  anonymous users.
+- Components: login-recover banner, "halo," / "halo, {name}" greeting
+  (brand-colored name on returning), `aku mau curhat` / `curhat sama
+  bestie baru` primary CTA, "curhatan sebelumnya" history section (live
+  data via `bestieHistoryProvider`), bottom 4-tab `HBTabBar` footer
+  (home / chat / kamu / premium SOON — only home + chat wired).
+- `_NotifDeniedBanner` (Stage 4) preserved at the top.
+- `_ActiveSessionCard` preserved on SHomeReturning so a user mid-session
+  can rejoin (not in Figma §1 but a hard UX requirement).
+- Material `AppBar` removed — the Figma layout has none. Logout will land
+  on the `kamu` tab when that's built.
+
+## C.3 Onboarding carousel destination fixed
+
+- `OnboardingScreen._finish()` now navigates to `/home` instead of
+  `/welcome`. The 3-page intro carousel (`Langsung Curhat / 100% Anonim /
+  Bestie yang Relevan`) itself is kept for now — it is **not in the
+  mermaid §1**, but the operator chose minimum-touch correction. Full
+  retirement (delete `OnboardingScreen` + `onboardingDoneProvider` + the
+  `/onboarding` route + the gate at the top of `router.dart`) is a
+  follow-up.
+
+## C.4 Defensive variant gate
+
+- `HomeScreen` now treats anything that is *not* `AuthAuthenticatedData`
+  or `AuthAnonymousData` as "fresh" → renders `SHome1st`. This avoids the
+  unauthenticated-but-erroring user seeing `halo, kamu` (the returning
+  view) for a brief moment.
+
+## C.5 Open gap — Login flow not in mermaid
+
+`SHome1st`'s `masuk →` banner button currently routes to `/auth/register`
+(phone-OTP entry). This is an interpretation, not a spec: the mermaid (and
+Figma `SHome1st`'s `onLogin` callback) doesn't define the login destination.
+**The mermaid needs a Login flow diagram** added — destinations from the
+`masuk →` banner, OTP success → `AuthAuthenticatedData` → SHomeReturning.
+Tracked in agent memory as `project_phase4_login_flow_gap.md`.
+
+---
+
 # Stage 9 — Test Sweep
 
 ## 9.1 Maestro flows
@@ -819,6 +887,268 @@ endpoints).
 
 ---
 
+# Stage 10 — Chat Tab (3 sub-tabs)
+
+> Added 2026-05-12 after design review. Figma source: `SChatList` in
+> [requirement/Figma/screens/extras.jsx](Figma/screens/extras.jsx) (line 22+).
+> Not yet in `flow_customer.mermaid.md` — §10.8 adds it.
+
+## 10.1 Scope & goal
+Replace the existing `/chat/history` destination (a flat list of closed sessions
+backed by `bestie_history_provider`) with a new **Chat tab** screen that
+contains three sub-tabs:
+
+| Sub-tab | Contents | Tap behavior |
+|---|---|---|
+| `aktif` | The user's single ongoing session (0 or 1 item) | Resume the live chat room |
+| `pembayaran` | Pending initial-session + extension payments | Resume the Xendit payment flow |
+| `selesai` | Past sessions (status `COMPLETED` + `CLOSING`) — cursor-paginated 20/page | Open read-only transcript |
+
+The chat icon in `HaloTabBar` already exists and points to `/chat/history` —
+only its **destination** changes. Bottom-nav structure is unchanged.
+
+`bestie_history` (screen + provider) is **retired** in this stage.
+
+## 10.2 Figma source
+- `SChatList` — list layout, sub-tab pill counters, per-item visuals
+- `S_pembayaran_kedaluwarsa` (same file, ~line 600) — expired-payment full
+  screen. **Copy says 20 menit**, see §10.6.
+- Item visuals: `HBOrb` (avatar) + optional green `success`-color live dot;
+  name (`who`) bold; preview text muted; right-aligned timestamp
+  (`● live` when active); below-preview chips:
+  - `bayar Rp X.XXX` chip (amber) on `pembayaran` items
+  - `X menit` duration suffix on `selesai` items
+
+## 10.3 Routes & navigation (client_app)
+Each sub-tab gets its **own path** so deep links, back stack, and Maestro
+tests all agree on the active tab (URL is the source of truth):
+
+| Path | Sub-tab |
+|---|---|
+| `/chat` | Redirect → `/chat/aktif` |
+| `/chat/aktif` | Aktif (default landing) |
+| `/chat/pembayaran` | Pembayaran |
+| `/chat/selesai` | Selesai |
+
+Implementation: a single `ShellRoute` (or a shared scaffold widget passed
+the active tab id) so the three paths render the same chrome (heading,
+sub-tab pills, bottom `HaloTabBar`) with only the list body swapping.
+Tapping a sub-tab pill calls `context.go('/chat/<id>')`.
+
+Renames + cleanup:
+- `HaloTabBar` `chat` tab `onTap`: `/chat/history` → `/chat` (which then
+  redirects to `/chat/aktif`).
+- Old `/chat/history` route + `bestie_history_screen.dart` +
+  `bestie_history_provider.dart` deleted.
+- `/chat/history/:sessionId` (read-only transcript) renamed to
+  **`/chat/transcript/:sessionId`** so no route lives under the retired
+  `/chat/history` parent. All inbound `context.push('/chat/history/...')`
+  updated.
+
+Bottom-nav red-dot tap behavior: the chat tab still calls
+`context.go('/chat')` (no special-case for the red dot). The user lands on
+the default `aktif` tab. FCM payment-pending pushes (if/when wired) target
+`/chat/pembayaran` directly.
+
+## 10.4 Sub-tab content & item model
+
+### aktif
+- Backed by existing `/api/client/chat/session/active-with-unread` (already
+  wired via `activeSessionProvider`). No new endpoint.
+- Always renders the active session even when the user is currently inside
+  the chat room (per decision §10.6 below).
+- Voice-call sessions (`mode='call'`) render with a small **📞 Call** pill in
+  the same row (consistent with Stage 6.0 header-badge convention).
+- Empty state copy: `belum ada chat di sini`.
+
+### pembayaran
+- Backed by **new** `GET /api/client/payment-sessions/pending` (§10.7).
+- Two row kinds (preview copy differentiates):
+  - Initial-session: `menunggu pembayaran sesi`
+  - Extension: `menunggu pembayaran perpanjangan`
+- Amber `bayar Rp X.XXX` chip per Figma.
+- Empty state: `belum ada pembayaran tertunda`.
+
+### selesai
+- Backed by existing `GET /api/client/history` — switch from offset (`page`)
+  to cursor pagination (§10.7) and rename param.
+- Per-item: `mins` (duration), preview = closing message (mitra's if present,
+  else customer's), relative timestamp.
+- Empty state: `belum ada riwayat curhat`.
+
+## 10.5 Badges
+
+| Surface | Trigger | Visual |
+|---|---|---|
+| Bottom-nav `chat` tab | `pembayaran` count > 0 | Red dot (no number) |
+| `aktif` sub-tab pill | Unread message count > 0 | Numeric badge (uses existing `unread_count` from `active-with-unread`) |
+| `pembayaran` sub-tab pill | Pending payment count > 0 | Numeric badge (count from `/payments/pending`) |
+| `selesai` sub-tab pill | — | **No badge** (overrides the Figma count pill) |
+
+Bottom-nav red-dot data source: piggy-back on the same
+`/api/client/payment-sessions/pending` call (its `total` field). Polled when the
+`HaloTabBar` host screen mounts; refreshed by riverpod invalidation when a
+payment is created or completed.
+
+## 10.6 Decisions baked in
+
+1. **Aktif always shows the live session.** Even when the user is on the chat
+   screen, the row stays in `aktif` — it represents state, not navigation.
+2. **Voice-call sessions live in the same list with a Call pill.** Per memory
+   `project_phase4_chat_ux_improvements` and Stage 6.0.
+3. **Pembayaran TTL reuses existing `payment_session_timeout_minutes`.**
+   Payment is still mocked (per memory `project_pricing_still_mocked_3_7`);
+   real Xendit is not wired yet. The `app_config.payment_session_timeout_minutes`
+   row (default `20`) already drives `expires_at` on `payment_sessions` rows
+   via `createPaymentSession`. The Figma "pembayaran kedaluwarsa" 20-min copy
+   already matches the default — no new app_config row needed for Stage 10.
+   When real Xendit lands, the same value is reused for the invoice TTL.
+4. **Max 1 active session.** Aligns with existing pairing constraint; no
+   backend change.
+
+## 10.7 Backend changes
+
+### 10.7.1 New: `GET /api/client/payment-sessions/pending`
+Returns pending initial-session + extension payment sessions for the
+authenticated customer (not yet paid, not yet expired).
+
+Query: `payment_sessions WHERE customer_id = $1 AND status = 'pending' AND
+expires_at > NOW() ORDER BY created_at DESC`. `is_extension` drives the row
+kind. For extension rows, the originating `chat_sessions` row is joined for
+mitra info; for initial rows, mitra info is null until pairing happens.
+
+```
+GET /api/client/payment-sessions/pending
+→ 200 {
+    success: true,
+    data: {
+      items: [
+        {
+          id: "pay_…",            // payment_sessions.id
+          kind: "initial" | "extension",
+          mitra_id: "…" | null,        // populated only for extension rows
+          mitra_display_name: "kak Dimas" | null,
+          amount: 2500,
+          duration_minutes: 30,
+          mode: "chat" | "call",
+          created_at: "…",
+          expires_at: "…"          // already = created_at + payment_session_timeout_minutes
+        }
+      ],
+      total: 1                    // drives the bottom-nav red dot
+    }
+  }
+```
+
+Service: `getCustomerPendingPayments(customerId)` (new fn) in
+`payment.service.js`. The existing `expireStalePaymentSessions` sweeper +
+inline expiry check in `confirmPaymentSession` already covers the TTL flip;
+the endpoint just filters `expires_at > NOW()` defensively in case the
+sweeper hasn't run yet for a stale row.
+
+### 10.7.2 Modify: `GET /api/client/history` → cursor pagination
+- Add `cursor` (opaque, base64 of `ended_at + id`) and `limit` (default 20,
+  max 50) query params.
+- Response shape changes from `{ items, total, page, limit }` to
+  `{ items, next_cursor, has_more }`.
+- `total` removed; if a future UI needs it, expose a separate `/count`
+  endpoint.
+- `bestie_history_provider` is deleted along with the screen — the new
+  `selesai_history_provider` uses cursor pagination on this endpoint.
+
+### 10.7.3 Reuse: `GET /api/client/chat/session/active-with-unread`
+No changes. The `aktif` tab calls this directly.
+
+### 10.7.4 No new sweeper needed
+The existing `expireStalePaymentSessions` already flips
+`pending → expired` past `expires_at`. The Pembayaran query filters on
+`expires_at > NOW()` to handle the gap between TTL expiry and the next
+sweep tick, so no additional sweeper is needed for Stage 10.
+
+## 10.8 Mermaid flow update (`flow_customer.mermaid.md`)
+Add a `subgraph chat_tab` after the home subgraph:
+
+```
+chat_tab
+  chat_tab.entry  — tap "💬 chat" in HaloTabBar
+  chat_tab.aktif  — active session row → resume chat
+  chat_tab.pembayaran  — pending payment row → resume Xendit
+  chat_tab.selesai  — past session row → transcript
+  chat_tab.empty.{aktif,pembayaran,selesai}  — empty states
+```
+
+Edges:
+- `home_*  → chat_tab.entry` (from any home variant)
+- `chat_tab.aktif → S10_chat_room` (existing)
+- `chat_tab.pembayaran → S7_waiting_payment` (Stage 3.5)
+- `chat_tab.selesai → S_transcript` (existing read-only transcript)
+
+(Wording above is a description — final mermaid syntax added during the
+implementation commit.)
+
+## 10.9 Flutter file changes (preview)
+- New: `client_app/lib/features/chat_tab/screens/chat_tab_shell.dart` — the
+  shared scaffold (heading + sub-tab pills + body slot) rendered by all
+  three sub-tab paths via `ShellRoute`.
+- New: `client_app/lib/features/chat_tab/screens/{aktif_view.dart,pembayaran_view.dart,selesai_view.dart}` — the body of each sub-tab.
+- New: `client_app/lib/features/chat_tab/widgets/{chat_row.dart,sub_tab_pill.dart}`
+- New: `client_app/lib/features/chat_tab/providers/{pending_payments_provider.dart,selesai_history_provider.dart}`
+- Delete: `client_app/lib/features/home/providers/bestie_history_provider.dart`
+- Delete: `client_app/lib/features/chat/screens/bestie_history_screen.dart`
+  (or wherever it lives — confirm during code stage)
+- Modify: `client_app/lib/features/home/widgets/halo_tab_bar.dart` — change
+  `/chat/history` → `/chat`; add red-dot rendering driven by
+  `pendingPaymentsProvider.total`.
+- Modify: `client_app/lib/router.dart`:
+  - Add `/chat` (redirect → `/chat/aktif`), `/chat/aktif`, `/chat/pembayaran`,
+    `/chat/selesai` (wrapped in a single `ShellRoute`).
+  - Rename `/chat/history/:sessionId` → `/chat/transcript/:sessionId`.
+  - Remove `/chat/history`.
+- Modify: any caller that does `context.push('/chat/history/$id')` for the
+  transcript — grep and update to `/chat/transcript/$id`.
+
+## 10.10 Out of scope (this stage)
+- **Failed-payment retry from the list.** Pembayaran only shows
+  not-yet-paid + not-yet-expired. Failed/expired surface via the existing
+  S6/S7 "pembayaran kedaluwarsa" screen on direct payment-flow re-entry, not
+  the list.
+- **Refund / dispute states.** No row kind for these.
+- **Search / filter** in `selesai`.
+- **Concurrent active sessions.** Aktif is 0-or-1 by backend constraint.
+- **Voice-call as separate sub-tab.** Lives in the same list with a Call pill.
+
+## 10.11 Acceptance for Stage 10
+1. Tapping `💬 chat` navigates to `/chat`, which redirects to `/chat/aktif`.
+   Direct navigation to `/chat/pembayaran` or `/chat/selesai` lands on the
+   correct tab. Tapping a sub-tab pill updates the URL accordingly.
+2. With an active session: row appears in `aktif`, tap → live chat room with
+   composer focused. Returning to `/chat` keeps the row visible.
+3. With a pending initial-session payment: row appears in `pembayaran` with
+   `bayar Rp X.XXX` chip; tap → Stage 3.5 waiting-payment screen.
+4. With a pending extension payment: row appears in `pembayaran` with the
+   extension preview copy; tap → extension payment screen.
+5. After 20 minutes without payment: row disappears from `pembayaran`; the
+   "pembayaran kedaluwarsa" screen shows on re-entry (Stage 3.6 behavior
+   unchanged).
+6. Bottom-nav `💬 chat` shows a red dot iff `pembayaran` total > 0.
+7. `aktif` sub-tab pill shows unread count when > 0.
+8. `pembayaran` sub-tab pill shows pending count when > 0.
+9. `selesai` sub-tab pill shows no badge regardless.
+10. `selesai` scrolls past 20 items via cursor pagination without duplicates
+    or gaps.
+11. Voice-call sessions render with the 📞 Call pill in both `aktif` and
+    `selesai`.
+12. `/chat/history` is gone from `router.dart`; `/chat/history/:sessionId` is
+    renamed to `/chat/transcript/:sessionId`; no dead inbound `context.push`
+    references remain.
+13. Maestro: new flow `09_chat_tab.yaml` covering aktif → resume,
+    pembayaran → payment, selesai → transcript.
+14. Backend tests cover `getCustomerPendingPayments` (initial only,
+    extension only, mixed, expired excluded) and the new cursor-paginated
+    `getCustomerHistory`.
+
+---
+
 # Resolved Decisions (2026-05-09 — recorded from product review)
 
 | # | Decision |