frontend phase 15

client/CLAUDE.md

@@ -173,11 +173,27 @@ client/
     │       │   │   ├── earnings/               # /nurse/earnings — f12 nurse earnings (read-only): page.tsx = EarningsBalanceHeader (net payable balance + 4 buckets, negative "owed back") + cadence/dispute-window explainer + state-segmented EarningsRow list (deep-links to /nurse/visits/[id]) ↔ payouts/page.tsx (PayoutHistoryRow list) → payouts/[id]/page.tsx (payout/batch reconciliation detail: money decomposition + masked IBAN + booking links)
     │       │   │   ├── support/tickets/        # /nurse/support/tickets — f14 nurse "My Tickets" (same TicketInboxScreen/TicketThreadScreen, role="nurse") ↔ support/tickets/[id]/page.tsx
     │       │   │   └── notifications/page.tsx  # /nurse/notifications — f14 notification center (role="nurse"); the nurse-shell bell deep-links here
-    │       │   └── admin/                      # Admin/backoffice (/admin/…) — desktop sidebar shell
-    │       │       ├── layout.tsx              # 'use client' — wraps AdminLayout
-    │       │       ├── page.tsx                # /admin (overview)
-    │       │       ├── users/page.tsx          # /admin/users
-    │       │       └── notifications/page.tsx  # /admin/notifications
+    │       │   ├── admin/                      # Admin/backoffice (/admin/…) — desktop sidebar shell (f15). Every screen is role-gated via useAdminCapabilities(); the sidebar hides a console the current admin role can't act on (server still enforces).
+    │       │   │   ├── layout.tsx              # 'use client' — wraps AdminLayout (capability-gated nav)
+    │       │   │   ├── page.tsx                # /admin — f15 overview landing: a capability-gated grid of console cards
+    │       │   │   ├── verification/           # /admin/verification — f15 review queue (page.tsx: status-filtered nurse worklist) ↔ [nurseId]/page.tsx per-nurse case (DocumentViewer signed-URL docs, pass/reject+reason per step, structured credential entry, Approve enabled only when all steps pass — client never writes is_verified)
+    │       │   │   ├── tickets/                # /admin/tickets — f15 global ticket queue (page.tsx: filter status/category/referenceCode) ↔ [id]/page.tsx admin thread (AdminMessageBubble renders isInternal notes distinctly; internal-note composer; RefundPanel opens from a refund ticket)
+    │       │   │   ├── payouts/                # /admin/payouts — f15 batch dashboard (page.tsx: batches + preview-next-batch dialog → run, idempotency-keyed) ↔ [batchId]/page.tsx per-nurse rows + failed-payout retry + transfer-reference reconcile
+    │       │   │   ├── reviews/page.tsx        # /admin/reviews — f15 moderation queue: publish/hide/reject (reason on hide/reject); low-rating flag; client never computes the aggregate
+    │       │   │   ├── config/page.tsx         # /admin/config — f15 config editor: typed input by data_type + 0–1 rate validation + audited-save dialog + change-history drawer
+    │       │   │   ├── holidays/page.tsx       # /admin/holidays — f15 Iranian-holiday manager (is_bank_closed toggle; client never computes the payout shift)
+    │       │   │   ├── alerts/page.tsx         # /admin/alerts — f15 internal support-alert worklist (assign/resolve); NEVER surfaced to a non-admin
+    │       │   │   ├── audit/page.tsx          # /admin/audit — f15 append-only audit viewer (filtered, paginated, expandable changedFields diff; no edit/delete)
+    │       │   │   ├── partners/               # /admin/partners — f15 partner-center management (page.tsx: list + create) ↔ [id]/page.tsx detail (verify/activate/suspend + edit + sponsored-nurse roster + assign-nurse; IBAN write-then-masked)
+    │       │   │   ├── roles/page.tsx          # /admin/roles — f15 RBAC grant/revoke grid (DEFERRED-IF-MISSING — mock-backed until the b15 role endpoints land)
+    │       │   │   ├── users/page.tsx          # /admin/users
+    │       │   │   └── notifications/page.tsx  # /admin/notifications
+    │       │   └── partner/                    # Partner-center portal (/partner/…) — a SEPARATE authz scope (f15). A center admin is not a Balinyaar admin; each page resolves the caller's OWN center (useMyPartnerCenter → access-denied on 403/404).
+    │       │       ├── layout.tsx              # 'use client' — wraps PartnerLayout (own partner nav)
+    │       │       ├── page.tsx                # /partner — center home: onboarding/verification state banner + license fields + is_merchant_of_record indicator
+    │       │       ├── nurses/page.tsx         # /partner/nurses — the center's sponsored nurses (verification badge)
+    │       │       ├── bookings/page.tsx       # /partner/bookings — the bookings the center legally covers (read-only summaries)
+    │       │       └── settlement/page.tsx     # /partner/settlement — rendered ONLY when is_merchant_of_record: per-booking commission invoices (commission/VAT decomposition via PartnerSettlementRow, signed-URL PDF, masked IBAN); non-MoR shows the "settlement via Balinyaar" state
     │       └── (public-routes)/
     │           ├── layout.tsx                  # 'use client' — wraps PublicLayout
     │           └── login/page.tsx              # /login — phone-OTP login (A1/A2 customer, B1/B2 nurse switch)
@@ -281,6 +297,14 @@ client/
     │   ├── patientRecords/  # F13 continuity-of-care (b14) — patient-scoped, NOT booking-scoped. usePatientCareRecord(family record)/useRecordAccess(gates before any clinical fetch)/usePatientHistory(paged visit-note history)/useUpdateCareRecord(CUSTOMER-only edit → setQueryData)/useCreateVisitNote(NURSE-only append → invalidates history). seam+mock(PRIMARY)+client. The nurse-authored visit-note history/append (getPatientHistory/createVisitNote) are REAL b14 (GET/POST patients/{id}/care_records, mapped 1:1; the append folds the ticked task checklist into the note body); the family-owned editable record (medications/routine/tasks) + the access check have NO backend (REQ-027) and are mocked. Nurse is APPEND-ONLY (never wires useUpdateCareRecord). Access-denied (canView=false / 403) is a first-class non-leaking state; MOCK_FOREIGN_PATIENT_ID=8888 exercises it. Clinical text is never logged/localStorage/query-string
     │   ├── tickets/         # F14 tickets — the ONLY sanctioned post-booking channel (b15). useMyTickets/useTicket(one detail(id) = the whole thread; no message pagination)/useTicketThread(select over detail)/useOpenTicket(invalidates lists)/usePostMessage(OPTIMISTIC: onMutate append pending, onError rollback+keep composer draft, onSuccess replace by clientMessageId, onSettled invalidate). seam+mock(PRIMARY)+client(maps b15 1:1). **is_internal NEVER modelled in the user-app types** — both mappers DROP any internal message (server-strip mimic); no internal affordance anywhere. Mock stores an internal note it never returns (no-leak demo), seeds a booking-linked coordination ticket (idempotent for coordination+bookingId → "jump to existing"), tracks the last viewer so an optimistic message reconciles as mine, MOCK_SEND_FAIL_SENTINEL='/fail' drives the failure→retry path. Wire summary lacks unreadCount/lastMessageAt (REQ-028) → mock-only
     │   ├── notifications/   # F14 in-app notification center (b1) — polled, no push. useNotifications(unread-first, growing limit)/useUnreadCount(the POLLING bell: refetchInterval 60s + staleTime 45s + refetchOnFocus, auth-gated — count only, list never polled)/useMarkNotificationRead+useMarkAllRead(OPTIMISTIC setQueryData flips isRead + decrements/zeros the cached count, rollback on error, invalidate on settle). seam+mock(PRIMARY)+client(maps b1 1:1). data_json is a TYPED contract: parseNotificationData(type,dataJson)→discriminated NotificationData union (snake/camel tolerant, degrades to {kind:'none'} on malformed/unknown/missing id — never trusts a blob); notificationDeepLink(n,role) centralises the role-aware route (null when nothing to open). Mock seeds every deep-link class + __mockPushNotification for the bell-increment demo
+    │   ├── admin/         # F15 backoffice-owned data (b1 + b15): config, holidays, audit, support-alerts, RBAC. usePlatformConfigs/useUpdatePlatformConfig/useConfigChangeHistory/useHolidays/useUpsertHoliday/useAuditLogs/useSupportAlerts/useAssignSupportAlert/useResolveSupportAlert/useAdminRoles/useGrantRole/useRevokeRole; seam+mock(PRIMARY)+client. Filters+page in each key (worklist filters cache separately). Mock-primary: config updatedAt/updatedBy + rich audit filters + the whole RBAC surface are gaps (REQ-029/030/031). support_alerts are internal-only — never rendered outside an admin route
+    │   ├── partnerCenter/ # F15 partner centers (b15): admin management + the center-scoped portal. usePartnerCenters/usePartnerCenter/useCenterSponsoredNurses/useCreate/useUpdate/useVerify/useSetActive/useAssignNurse (admin) + useMyPartnerCenter/useMySponsoredNurses/useMySponsoredBookings/useMySettlement (portal); seam+mock(PRIMARY)+client. settlement_iban masked last-4 (write-then-masked); merchant-of-record gates the settlement view; VAT on the commission line only (config vat_rate); deriveCenterState(isActive,verifiedAt). Mock-primary: portal split reads + activate/suspend + invoice total are gaps (REQ-032/033)
+    │   │   # Admin-endpoint ADDITIONS to existing domains (the staff lens — NOT new domains):
+    │   │   #  verification → useVerificationQueue/useVerificationCase/useVerificationDocumentUrl(on-demand signed URL)/useDecideStep/useApproveVerification/useRejectVerification (b6; REQ-034)
+    │   │   #  refunds      → useRefundPreview/useInitiateRefund/useApproveRefund/useRejectRefund (b11, ticket-linked; REQ-035)
+    │   │   #  payouts      → usePayoutBatches/usePayoutBatchDetail/usePreviewPayoutBatch/useRunPayoutBatch(idempotency-keyed)/useRetryPayout/useRecordTransferReference (b13; REQ-036)
+    │   │   #  reviews      → useModerationQueue/useModerateReview (b14; REQ-037)
+    │   │   #  tickets      → useAdminTickets/useAdminTicket/useAdminTicketThread/usePostAdminMessage (b15; the ADMIN ticket types carry isInternal — the user-app types deliberately do NOT)
     │   └── {domain}/
     │       ├── types.ts       # Request/response types + the domain's Api interface (the seam)
     │       ├── keys.ts        # React Query key factory (hierarchical)
@@ -385,9 +409,12 @@ async function MyServerComponent() {
 - `'tickets'` — the f14 messaging surface (tickets are the only post-booking channel): the inbox (`title`/`contact_support`/`empty_*`/`error_body`), the category + status labels keyed off the code (`category_{support,coordination,refund,emergency}`/`status_{open,closed}`), the linked-entity hints (`linked_booking`/`linked_refund` with `{id}`), `ref_code_label`, the new-ticket dialog (`new_ticket_title`/`category_label`/`subject_label`/`message_label`/`submit`/`created_*`/`view_thread`), the thread (`back_to_tickets`/`thread_*`/`closed_notice`), the composer (`sending`/`send`/`send_failed`/`composer_placeholder`), the author-role labels (`author_{customer,nurse,support,system}` — `admin`→support), and the **emergency playbook** (`emergency_title`/`emergency_body`/`emergency_call {name}`/`emergency_call_generic`/`emergency_open_ticket`) + `open_from_booking`; consumed by the ticket screens, `MessageBubble`/`TicketListCard`/`EmergencyBanner`/`ContactSupportDialog`/`MessageComposer`/`BookingSupportEntry`
 - `'notifications'` — the f14 notification center + bell: `title`, `empty_*`, `error_body`, `retry`, `mark_all_read`, `load_more`, and the polled-bell aria (`bell_aria` with `{count, number}`); the row `title`/`body` are **server-rendered** copy, not keys. Consumed by `NotificationCenter` + `NotificationBell`
 - `'auth'` — the phone-OTP login flow, role router, and SelectRole screen (`common.brand`/`brand_tagline` for the wordmark)
+- `'admin'` — the f15 backoffice consoles: verification queue/case, refund panel, payout dashboard/detail, review moderation, config editor + change-history, holiday manager, support-alert board, audit viewer, admin ticket queue/thread, RBAC grid, and admin-side partner management. Includes the **Persian legal terms** (پروانه تأسیس / مسئول فنی / نماد اعتماد الکترونیکی) and the enum-label prefixes keyed off the stable code (`step_*`/`agg_*`/`atype_*`/`astatus_*`/`sev_*`/`htype_*`/`dtype_*`/`batch_status_*`/`pstatus_*`/`channel_*`/`rstatus_*`/`mstatus_*`/`center_state_*`/`role_*`/`tcat_*`/`tstatus_*`). Consumed by the `/admin/*` screens + the `@/components/admin` composites
+- `'partner'` — the f15 partner-center portal (a separate authz scope): center home/onboarding-state, sponsored nurses/bookings, and the merchant-of-record settlement/invoice view (سامانه مودیان, commission/VAT decomposition). Consumed by the `/partner/*` screens + `PartnerSettlementRow`
 
 **Namespace conventions for the phases to come** (seed each when its feature lands, in both locale
-files): `admin` (f15). Keep top-level keys as namespaces and both files in sync.
+files): none — **MVP namespaces complete** (f15 seeded `admin` + `partner`). Keep top-level keys as
+namespaces and both files in sync.
 
 **Never hard-code UI strings in English.** Any user-visible text must have a translation key in both locale files.
 
@@ -690,9 +717,20 @@ client design, but some hardening needs *server* coordination — don't silently
 - **The middleware check is UX-only, not a security boundary:** it decodes the JWT and checks `exp` but
   does **not** verify the signature. The API is the only authority; never gate real authorization on the
   middleware or `isTokenAlive`.
-- **Role gating is coarse:** the shells pick chrome from `currentUser.roles`, but cross-actor route access
-  isn't hard-guarded client-side yet (the server authorizes each call). Add route guards when a phase needs
-  them.
+- **Role gating is coarse for chrome, fine for the backoffice:** the shells pick chrome from the collapsed
+  `currentUser.roles` (`useActorRole`). **f15 adds `useAdminCapabilities()` (`@/hooks`)** — a memoized selector
+  over the session's **fine-grained** `roleCodes` (hydrated from `/me` by `useSessionRoleSync`; `super_admin`/
+  `admin`/`support`/`finance`/`moderation`) that returns per-console booleans (`canVerify`/`canRefund`/
+  `canPayout`/`canModerate`/`canConfig`/`canManageAlerts`/`canManageTickets`/`canManagePartners`/`canViewAudit`/
+  `canManageRoles`). The `AdminLayout` nav and every admin action **hide/disable** on it so a role never sees a
+  control that will 403 — but it is a **display convenience only; the server authorizes every command** (never
+  gate real authz on it). Cross-actor route access still isn't hard-guarded client-side; add route guards when a
+  phase needs them. The **partner portal is a separate scope** — its pages resolve the caller's own center via
+  `useMyPartnerCenter()` (a 403/404 renders a non-leaking access-denied state), never a raw id.
+- **Signed URLs are fetched on demand, never cached long-lived (f15):** verification documents load via a
+  short-lived signed URL fetched by `useVerificationDocumentUrl(documentId)` (short `staleTime`, `retry:false`) —
+  `DocumentViewer` re-requests it on expiry/error rather than reading the embedded URL from the long-lived case
+  query. Reuse this pattern for any short-lived signed asset (invoice PDFs, etc.).
 - **Refresh-token rotation is wired** client-side (fetch-layer silent refresh + `useRefresh`), matching the
   server's rotation + reuse-detection. The `refresh_token` cookie TTL (7d) is shorter than the server session
   default (30d) — a follow-up can align the cookie `maxAge` to `refreshExpiresAt`.