Add frontend phase 15 updates: complete MVP for admin backoffice and partner-center consoles, including new services and endpoints; document requests for backend enhancements.
This commit is contained in:
hamid
@@ -0,0 +1,133 @@
|
||||
# Frontend Phase 15 (b15) — Admin backoffice & partner-center consoles — report
|
||||
|
||||
**Date:** 2026-07-10 · **Track:** frontend · **Status:** ✅ complete — **this is the final frontend phase; MVP is complete.**
|
||||
**Gate:** `npm run check` green (0 errors / 0 warnings) · `npm run test:ci` green (**325 tests, +36**) · `npm run build` green (all 18 new routes compile) · `admin`/`partner` i18n in sync · i18n key audit clean.
|
||||
|
||||
---
|
||||
|
||||
## 1. What was built
|
||||
|
||||
The internal **operational cockpit** that runs the marketplace: a role-gated **admin backoffice** in the f0 desktop
|
||||
sidebar shell, plus a separately-scoped **partner-center portal**. All of it is a *read-and-act* surface over data
|
||||
other domains own — the client renders the contract's values and issues the sanctioned commands; it **never**
|
||||
computes eligibility, money decomposition, holiday shifts, the `is_verified` flip, or the review aggregate (§5).
|
||||
|
||||
### Two new domain services (the `auth`-service shape)
|
||||
- **`services/admin`** — config, holidays, audit, support-alerts, RBAC. 12 hooks; filters + page in every key so
|
||||
each worklist filter/page caches independently. Mock-primary.
|
||||
- **`services/partnerCenter`** — admin-side center management + the center-scoped portal reads. 12 hooks. Mock-primary.
|
||||
|
||||
### Admin-endpoint additions to 5 existing domains (the staff lens — *not* new domains)
|
||||
- **verification** (b6): `useVerificationQueue` / `useVerificationCase` / `useVerificationDocumentUrl` (on-demand
|
||||
signed URL) / `useDecideStep` / `useApproveVerification` / `useRejectVerification`.
|
||||
- **refunds** (b11): `useRefundPreview` / `useInitiateRefund` / `useApproveRefund` / `useRejectRefund` (ticket-linked).
|
||||
- **payouts** (b13): `usePayoutBatches` / `usePayoutBatchDetail` / `usePreviewPayoutBatch` / `useRunPayoutBatch`
|
||||
(idempotency-keyed) / `useRetryPayout` / `useRecordTransferReference`.
|
||||
- **reviews** (b14): `useModerationQueue` / `useModerateReview`.
|
||||
- **tickets** (b15): `useAdminTickets` / `useAdminTicket` / `useAdminTicketThread` / `usePostAdminMessage`. The **admin**
|
||||
ticket types carry `isInternal`; the **user-app** types deliberately do not — the two surfaces stay distinct so an
|
||||
internal note can never bleed into a user view (§5).
|
||||
|
||||
### Shared composites — `@/components/admin` (13, each with a co-located `*.test.tsx`; 36 tests)
|
||||
`AdminPageHeader`, `AdminEmptyState`, `AdminErrorState`, `AdminPager`, `ConfirmDialog` (optional required-reason),
|
||||
`AdminDataTable` (generic dense worklist table, horizontal-scroll-contained), `ConfigRow`, `AuditLogRow` (expandable
|
||||
diff), `SupportAlertCard`, `PartnerSettlementRow` (reconciling commission/VAT breakdown via the f0 `PriceBreakdown`),
|
||||
`DocumentViewer` (signed-URL on-demand + expired→re-request), `RefundPanel` (server-computed preview → initiate →
|
||||
provider-failure retry / reject), `AdminMessageBubble` (internal-note styled distinctly).
|
||||
|
||||
### Screens (18 new routes)
|
||||
- **Admin** (`/admin/*`, role-gated): overview landing · verification (queue + `[nurseId]` case) · tickets (queue +
|
||||
`[id]` thread w/ internal-note composer + RefundPanel) · payouts (dashboard + `[batchId]` detail) · reviews
|
||||
(moderation) · config · holidays · alerts · audit · partners (list + `[id]` detail) · roles (**DEFERRED-IF-MISSING**).
|
||||
- **Partner portal** (`/partner/*`, separate scope): home · nurses · bookings · settlement (MoR-gated).
|
||||
|
||||
### Foundation
|
||||
- **`useAdminCapabilities()`** (`@/hooks`) — a memoized selector over the session's fine-grained `roleCodes`
|
||||
(added to `SessionUser`, hydrated from `/me` by `useSessionRoleSync`). Drives per-console `can*` booleans that
|
||||
hide/disable controls a role can't use (server still authorizes every command).
|
||||
- **`PartnerLayout`** + the `(private-routes)/partner/` route group (a separate authz scope).
|
||||
- The `admin` + `partner` i18n namespaces in both locales (incl. پروانه تأسیس / مسئول فنی / نماد اعتماد الکترونیکی /
|
||||
سامانه مودیان and the enum-label prefixes keyed off stable codes).
|
||||
- New `AppIcon` registry entries; new `ROUTES.ADMIN_*` / `ROUTES.PARTNER_*` + path helpers.
|
||||
|
||||
---
|
||||
|
||||
## 2. What is now testable, and exactly how
|
||||
|
||||
Run `npm run dev`, sign in as an **admin** (mock-primary, so no live backend needed). The §7 acceptance steps:
|
||||
|
||||
1. **Verify a nurse.** `/admin/verification` → pick a pending nurse → the case loads each document via a **signed URL**
|
||||
(`DocumentViewer`; sentinel `documentId 9999` exercises the error→re-request path). Pass the steps (reject one with a
|
||||
required reason), enter a **structured credential** on a credential-bearing step; **Approve** is disabled until every
|
||||
step is `passed` → confirm → the nurse leaves the queue. The client never wrote `is_verified`.
|
||||
2. **Process a refund.** `/admin/tickets` → open the **refund** ticket (bookingId + refundId seeded) → **RefundPanel**
|
||||
shows the **server-computed** tiered % + fee/payout decomposition (reconciles to the rial) + channel + BNPL ETA;
|
||||
the post-payout booking shows the read-only **clawback notice**; the decline **sentinel** shows **retry**.
|
||||
3. **Preview + run a payout batch.** `/admin/payouts` → **preview next batch** → eligibility breakdown (eligible +
|
||||
no-IBAN-skipped + clawback line + **holiday-shifted** processing date) → **run batch** (confirm requires an
|
||||
**idempotency key** — a double-click can't double-pay) → `processing`. `[batchId]` detail → a **failed** payout →
|
||||
**retry**; reconcile a `transfer_reference`.
|
||||
4. **Moderate a review.** `/admin/reviews` → a `pending_moderation` review (low-rating flag) → **publish/hide/reject**
|
||||
(reject/hide require a reason) → it leaves the queue; the client never computed the aggregate.
|
||||
5. **Edit a config value.** `/admin/config` → edit `vat_rate` → the input validates **0–1** (`1.5` blocked) → save →
|
||||
the dialog states it is **audited, immediate, non-retroactive** → the **history drawer** shows old→new + actor + Shamsi time.
|
||||
6. **Resolve a support alert.** `/admin/alerts` → filter to **open** → **assign to me** → **resolve** with a note.
|
||||
It appears in **no** customer/nurse/partner view.
|
||||
7. **Holiday manager.** `/admin/holidays` → add a holiday with **`is_bank_closed` on** → listed (the client never
|
||||
computes the shift; the payout preview in step 3 shows the server-shifted date).
|
||||
8. **Audit viewer.** `/admin/audit` → filter by entity/actor/date → paginated; expand a row for the `changedFields`
|
||||
diff. **No** edit/delete control exists.
|
||||
9. **Partner portal.** Sign in mapping to a center admin → `/partner` shows onboarding state + license + MoR;
|
||||
`/partner/nurses` + `/partner/bookings` show only that center's data; `/partner/settlement` renders the commission/VAT
|
||||
invoices + signed-URL PDF + **masked IBAN** **only when merchant-of-record** (a non-MoR center shows the "via
|
||||
Balinyaar" state). Back as an admin → `/admin/partners` → create/verify/activate + assign a nurse; IBAN is
|
||||
write-then-masked (submit full, only last-4 ever shows).
|
||||
10. **RBAC + i18n + RTL + caching.** A `support` role sees no payout/refund controls; a `moderation` role sees only
|
||||
moderation (drive via `useAdminCapabilities`). `fa`↔`en` translates every label (incl. the Persian legal terms) and
|
||||
the sidebar mirrors. Switching worklist filters/pages caches separately (filters+page in the key) — no refetch of
|
||||
loaded data.
|
||||
|
||||
---
|
||||
|
||||
## 3. What is mocked, and how to make it real
|
||||
|
||||
All f15 data is **mock-primary** (the real `clientApi` in each domain maps the live routes and targets proposed slugs
|
||||
for the gaps; the swap is a one-line flag flip per domain — no hook/component change). Full detail in
|
||||
`reports/mocks-registry.md` (three new/updated rows). Seams + flags:
|
||||
- `services/admin` — `USE_ADMIN_MOCK` (config/holidays/audit/support-alerts live at b1; RBAC + config audit columns +
|
||||
rich audit filters are gaps → REQ-029/030/031).
|
||||
- `services/partnerCenter` — `USE_PARTNER_MOCK` (admin CRUD/verify/sponsor live at b15; portal split reads +
|
||||
activate/suspend + invoice total are gaps → REQ-032/033).
|
||||
- verification/refunds/payouts/reviews/tickets admin methods — the owning domain's flag (REQ-034/035/036/037).
|
||||
|
||||
**No backend seams were introduced** — `IObjectStorage`/`IBankTransferProvider`/`IBnplProvider`/`IMoadianClient`/
|
||||
`ILicenseVerificationService`/the audit interceptor/the notification dispatcher are all server-side (b1/b6/b11/b13/b14/b15);
|
||||
the frontend never touches them.
|
||||
|
||||
---
|
||||
|
||||
## 4. Contracts consumed
|
||||
`messaging-notifications-admin.md` (b15, primary) + `verification.md` (b6) + `refunds-invoices.md` (b11) +
|
||||
`payouts.md` (b13) + `reviews-records.md` (b14) + `config-reference.md` (b1). All types derived from these — none guessed.
|
||||
|
||||
## 5. Requests filed (`frontend/requests/for-backend.md`)
|
||||
**REQ-029** config `updatedAt`/`updatedBy` · **REQ-030** audit actor/action/date filters · **REQ-031** RBAC role endpoints ·
|
||||
**REQ-032** partner-portal split reads + activate/suspend + IBAN write-then-masked · **REQ-033** center-scoped invoice list
|
||||
+ invoice `totalIrr` · **REQ-034** verification nurse-level queue + on-demand doc URL + whole-verification approve/reject ·
|
||||
**REQ-035** refund preview + explicit approve/reject · **REQ-036** payout single-preview + `holidayShifted` +
|
||||
record-transfer-reference · **REQ-037** moderation `tagCodes`.
|
||||
|
||||
---
|
||||
|
||||
## 6. MVP-complete closeout
|
||||
This is the **final frontend phase** — every customer, nurse, admin, and partner surface in the build plan now exists.
|
||||
|
||||
- **Deferred-if-missing:** the **RBAC roles console** (`/admin/roles`) is built against the mock and tagged
|
||||
DEFERRED-IF-MISSING; it activates when the b15 role endpoints land (REQ-031). It is not on the testable acceptance path.
|
||||
- **Modeled-but-inactive, no UI (as specified):** `organizations` / `organization_nurses` (employer model),
|
||||
`fraud_flags` (ML console), `recurring_booking_schedules` (recurrence) — data-model/13. Also **no UI** for: full
|
||||
سامانه مودیان e-invoice automation / digital-signature (the portal only *views* the issued invoice ref + PDF),
|
||||
push/SMS channels, an analytics-warehouse dashboard, on-demand/instant payout, per-nurse payout-frequency settings.
|
||||
- **Minor i18n substitutions the screen agents flagged** (all use existing keys; cosmetic, non-blocking): the payout
|
||||
retry-success toast reuses `admin.saved`; the partner nurse verified/unverified column borrows `center_state_*`
|
||||
labels; partner booking-status renders the raw stable status code. Add dedicated keys later if desired.
|
||||
Reference in New Issue
Block a user