halobestie-clone/requirement/phase3.5-plan.md

Phase 3.5 Implementation Plan: Mitra Chat Request History

Source PRD: requirement/phase3.5.md — open questions already resolved.

Summary of Clarified Requirements

Topic	Decision
Replaces	Home _PendingRequestsBanner Card
New CTA	"Riwayat Permintaan" Card with red count badge when pending > 0
List size	Last 20 rows, no pagination, no filters, no search
List ordering	Pending rows pinned to top (newest-first), then everything else by notified_at DESC
Pending definition	crn.response IS NULL AND cs.status = 'pending_acceptance'
Customer identity	Always show call_name. Fall back to "Anonim" only when call_name is NULL/empty (e.g., anonymous customer or OAuth without name). Never phone / email / social id / user id. The legacy anonymity_enabled config flag is being retired (set to false 2026-04-27) — it does nothing functional today and should not be re-introduced into business logic.
Live update on history list	None. Pull-to-refresh only.
Live update on home badge	Yes. Driven by existing chatRequestProvider.
Pending row tap	Re-opens the existing incoming accept/decline overlay
Non-pending row tap	Opens read-only detail screen; only accepted rows surface a "Lihat percakapan" CTA → existing transcript screen
Status labels	Pending → "Menunggu respon" (yellow); Accepted → "Diterima" (green); Declined → "Ditolak" (gray); Missed → "Terlewat" (gray); Ignored+cancelled → "Dibatalkan" (gray); Ignored+expired → "Kedaluwarsa" (gray)
Sensitivity badge	Reuse Phase 3.3 yellow "Topik sensitif" badge
New tables / columns	None

---

Prerequisites

None. No new env vars, no schema changes, no new dependencies.

---

Work Stream 1: Backend

1.1 New service function

File: backend/src/services/mitra-activity.service.js

Add a new export getRecentRequestsForMitra(mitraId, { limit = 20 } = {}). Capped at 20 even if the caller passes a higher value.

SQL (single query — call_name always returned, "Anonim" only as null-safety fallback):

SELECT
  crn.id              AS notification_id,
  crn.session_id,
  crn.notified_at,
  crn.responded_at,
  crn.response,
  cs.status           AS session_status,
  cs.topic_sensitivity,
  COALESCE(NULLIF(trim(c.display_name), ''), 'Anonim') AS customer_call_name
FROM chat_request_notifications crn
LEFT JOIN chat_sessions cs ON cs.id = crn.session_id
LEFT JOIN customers c      ON c.id = cs.customer_id
WHERE crn.mitra_id = ${mitraId}
ORDER BY
  -- pending pinned first (TRUE before FALSE in DESC ordering)
  (crn.response IS NULL AND cs.status = 'pending_acceptance') DESC,
  crn.notified_at DESC
LIMIT ${Math.min(limit, 20)}

Privacy rule (corrected 2026-04-27): The mitra-facing API returns the customer's call_name (the name they chose to be called). It is fine for that name to be a casual / non-real identifier — that's what the customer wants. The hard rule is: never return phone, email, social id, or internal user id to the mitra. Don't re-introduce a global anonymity toggle into business logic.

1.2 New route

File: backend/src/routes/public/mitra.chat.routes.js

GET /api/mitra/chat-requests/recent

Note the prefix on this router is /api/mitra/chat-requests (see app.public.js:29), so the in-file path is /recent. Final URL ends up /api/mitra/chat-requests/recent — semantically equivalent to the PRD's /api/mitra/chat/requests/recent. Calling it out so the URL matches the prefix instead of inventing a new register.

• Auth: [authenticate, resolveMitra] (same as siblings)
• Query: optional ?limit=N (clamped to 20)
• Response: { success: true, data: [ { notification_id, session_id, notified_at, responded_at, response, session_status, customer_call_name, topic_sensitivity }, ... ] }

1.3 No changes

• No migration
• No constants
• No WS event additions
• No new permissions

---

Work Stream 2: Mitra App

2.1 New API method

File: mitra_app/lib/core/api/api_client.dart — already supports get(path). No new method needed; the new provider calls apiClient.get('/api/mitra/chat-requests/recent') directly.

2.2 New Riverpod provider

File: mitra_app/lib/features/chat/notifiers/request_history_notifier.dart (new)

• AsyncNotifier<List<RequestHistoryEntry>>
• build() → [] (empty until first fetch); does NOT auto-fetch on construction. Screen calls refresh() in initState.
• refresh() → calls GET /api/mitra/chat-requests/recent, replaces state.
• No WS subscription — pull-to-refresh + screen-mount fetch only (PRD §4).

Model (request_history_entry.dart next to the notifier):

class RequestHistoryEntry {
  final String notificationId;
  final String sessionId;
  final DateTime notifiedAt;
  final DateTime? respondedAt;
  final RequestResponse? response;            // enum: accepted, declined, missed, ignored, null
  final SessionStatus sessionStatus;          // enum
  final String customerCallName;              // already masked server-side
  final TopicSensitivity topicSensitivity;
}

RequestResponse and SessionStatus enums go in core/constants.dart if not already there (per feedback_use_enums.md). Verify what already exists before adding.

2.3 Replace home banner with CTA

File: mitra_app/lib/features/home/home_screen.dart

• Delete _PendingRequestsBanner widget (line 128–171) entirely.
• Add a new _RequestHistoryButton widget styled like _ActiveSessionsButton (Card + ListTile + chevron).
• Source the badge count from chatRequestProvider.notifier.activeRequestCount — same source today's banner uses, so live-updates come for free.
• Subtitle: "$count permintaan baru" when count > 0, else "Lihat permintaan chat sebelumnya".
• Trailing: Badge(label: Text('$count')) wrapping the chevron when count > 0; chevron only when count == 0.
• onTap: context.push('/chat/requests/history').

Keep the existing Future.microtask block that drives loadPendingRequests() on mount — the live count still depends on it.

2.4 Two new routes

File: mitra_app/lib/router.dart

GoRoute(
  path: '/chat/requests/history',
  builder: (_, __) => const RequestHistoryScreen(),
),
GoRoute(
  path: '/chat/requests/history/:notificationId',
  builder: (context, state) => RequestHistoryDetailScreen(
    notificationId: state.pathParameters['notificationId']!,
  ),
),

2.5 Request History screen

File: mitra_app/lib/features/chat/screens/request_history_screen.dart (new)

• Scaffold + AppBar "Riwayat Permintaan"
• Body:
  • RefreshIndicator wrapping a ListView.separated
  • initState → ref.read(requestHistoryProvider.notifier).refresh()
  • States: loading spinner / error retry / empty ("Belum ada permintaan chat") / list
• Each row:
  • Leading: nothing, or a small status dot
  • Title: entry.customerCallName
  • Subtitle row: status badge (colored, localized text) + relative timestamp
  • Trailing: sensitivity badge ("Topik sensitif" yellow) when sensitive, else null
  • Tap: see §2.7

2.6 Detail screen (non-pending rows only)

File: mitra_app/lib/features/chat/screens/request_history_detail_screen.dart (new)

• Receives notificationId only. Pulls the matching entry from requestHistoryProvider's cached state — if not present (e.g., deep link from a future notification), refetches.
• Body: vertical card showing call name, sensitivity, status, absolute notified_at, responded_at if present.
• Footer CTA when response == accepted: FilledButton.icon(label: "Lihat percakapan") → context.push('/chat/history/$sessionId').

2.7 Tap dispatch

In the list tile onTap:

final isPending = entry.response == null
    && entry.sessionStatus == SessionStatus.pendingAcceptance;
if (isPending) {
  // Re-open the incoming overlay for this session.
  // The overlay is rendered by the global IncomingRequestOverlay listener,
  // so we just feed the chatRequestProvider:
  await ref.read(chatRequestProvider.notifier).setIncomingFromNotification(entry.sessionId);
} else {
  context.push('/chat/requests/history/${entry.notificationId}');
}

setIncomingFromNotification already exists (chat_request_notifier.dart:247) and chains to validateIncomingRequest() so a stale row gracefully transitions to the "no longer available" stale state.

2.8 Status labels + colors helper

mitra_app/lib/features/chat/utils/request_status_label.dart (new) — small pure function (response, sessionStatus) → (label, color) so the list tile + detail screen share one source of truth.

2.9 Relative timestamp helper

If a formatRelative(DateTime) helper already exists (likely from chat history screen), reuse it. If not, add a small one to the same utils file: "Baru saja" (<1m), "N menit lalu" (<60m), "N jam lalu" (<24h), "Kemarin" (<48h), "N hari lalu" (≥48h).

---

Work Stream 3: Control Center

No changes. PRD §0 lists CC as out of scope.

---

Acceptance / Test Plan

#	Scenario	Expected
1	Mitra opens home with 0 pending requests	"Riwayat Permintaan" card visible, no badge, subtitle "Lihat permintaan chat sebelumnya"
2	Mitra opens home with 2 pending	Card shows red 2 badge, subtitle "2 permintaan baru"
3	New CHAT_REQUEST arrives while on home	Badge increments without refresh
4	Customer cancels a pending request	Badge decrements without refresh
5	Tap "Riwayat Permintaan" with empty history	Empty state "Belum ada permintaan chat"
6	Tap with mixed history (1 pending, 5 accepted, 3 declined, 2 missed, 1 cancelled, 1 expired)	Pending pinned at top; rest sorted by notified_at DESC
7	Customer call_name = "Sasa"	Row shows "Sasa"
8	Customer call_name NULL or ""	Row shows "Anonim"
10	Sensitive-topic row	Yellow "Topik sensitif" badge present
11	Tap pending row	Incoming overlay reopens; shows accept/decline if still pending; shows stale state if taken/expired
12	Tap accepted row	Detail screen with "Lihat percakapan" CTA → existing transcript screen for that session
13	Tap declined / missed / ignored row	Detail screen, no transcript CTA
14	Pull-to-refresh on history screen	Re-fetches; UI updates
15	Open another mitra's session via direct URL hack	Backend returns own scope only — confirmed via SQL WHERE crn.mitra_id = self, never exposes other mitras
16	?limit=1000 on the endpoint	Backend caps at 20

Real-device E2E to perform on the SM G998B + Mac/iOS:

• (1)–(14) above
• Verify the badge stays in sync across logout/login
• Verify timestamps use the device locale's idea of "Kemarin" boundary correctly

---

Tech Debt Surfaced (Out of Scope)

1. anonymity_enabled config is dead code. The flag exists in app_config, has GET/PATCH routes (/internal/config/anonymity, /api/shared/config/anonymity), and a CC settings UI — but no service consumes it. Worth a follow-up cleanup: rip out the service functions, routes, CC page, and migration seed. (DB row + JS default already flipped to enabled: false so it's harmless until then.)
2. The PRD path /api/mitra/chat/requests/recent differs from the actual register prefix /api/mitra/chat-requests/. Going with /api/mitra/chat-requests/recent to stay consistent. If it matters for external API hygiene, we can add a route-level rename pass later.

---

Implementation Order

1. Backend: service function + route + smoke-curl ✅ green before touching app
2. Mitra app: provider + model + status helper
3. Mitra app: replace home banner
4. Mitra app: history screen
5. Mitra app: detail screen
6. Real-device E2E pass per the table above