# Frontend phase 2 (f2-b3) — Onboarding & profiles — report

**Track:** frontend · **Consumes:** [`dev/contracts/domains/identity-profiles.md`](../../contracts/domains/identity-profiles.md) (backend-phase-3) · **Date:** 2026-07-02

## What was built

### Domain services (f0 `services/{domain}` pattern: types ← contract, keys factory, apis[client+mock+seam], one-hook-per-file, hooks-only barrel)
- **`services/patients`** — rewritten from the f0 reference stub to the b3 `PatientDto`. Full CRUD seam
  (`list`/`get`/`create`/`update`/`archive`) + real `patientsClientApi` (action routes `patients/{list,get,create,
  update,archive}`) + `patientsMockApi`. Hooks: `usePatients` (staleTime), `useCreatePatient`, `useUpdatePatient`
  (both invalidate lists), `useArchivePatient` (**optimistic** remove + rollback + settle-invalidate). Helpers
  `age.ts` (age↔birthDate) and the client-augmented `relation`/`conditions` (REQ-005, mock-persisted).
- **`services/profiles`** — customer + nurse profile. Seam `getCustomerProfile`/`upsertCustomerProfile`/
  `getNurseProfile`/`upsertNurseProfile`/`uploadAvatar`; real client maps 404→`null` (no profile yet). Hooks
  `useCustomerProfile`/`useNurseProfile` (queries) and `useUpsertCustomerProfile`/`useUpsertNurseProfile`
  (setQueryData + invalidate `/me` for profile-completion) and `useUploadAvatar`.
- **`services/nurse`** — payout bank accounts (kept separate). Seam `list`/`add`/`setPrimary`/`verifyOwnership`;
  `iban.ts` (Sheba `IR`+24 validate/normalize + bank-name from the 3-digit code). Hooks `useNurseBankAccounts`
  (poll via `refetchInterval` **only while any account is pending**), `useAddNurseBankAccount`,
  `useSetPrimaryBankAccount`. `deriveBankStatus` maps `matchedNationalId` (null→pending, false→mismatch,
  true→verified).

### Shared composites (`src/components/…`, each with a co-located `*.test.tsx`)
`GenderToggle` (required male/female, never defaulted, can't deselect), `ConditionChips` (multi-select codes),
`RelationSelect` (radio cards), `PatientForm` (the A4 form — name/age/gender/conditions/relation, reused
create+edit), `PatientCard` (E1 card), `BankStatusPanel` (the three ownership states, masked IBAN, non-accusatory
mismatch). Reused the f0 `StepperHeader`/`StatusChip`/`PhoneNumberField` (not re-implemented). Added `--bal-primary-soft`
token (both schemes) and 5 AppIcon registry names (edit/archive/bank/camera/warning).

### Screens
- **A3→A4 onboarding** (`(customer)/onboarding/page.tsx`) — 2-step stepper: relation → patient form; creates the
  first patient and lands on Home.
- **A5 Home** (`(customer)/page.tsx`, now a client component) — first-login gate: a customer with 0 patients is
  redirected into onboarding (waits for a settled list so a post-create refetch never bounces back); otherwise the
  "complete patient record" nudge (+ a profile nudge until `hasCustomerProfile`).
- **E1 patients** (`(customer)/patients/page.tsx`) — cached list, skeleton + empty states, add/edit dialog (A4 form),
  soft-archive with confirm.
- **Customer profile** (`(customer)/profile/page.tsx`) — name + preferred language + emergency contact (reused
  phone field). **No national-ID field.**
- **Nurse profile** (`nurse/profile/page.tsx`) — avatar upload + bio + years; unverified/not-bookable placeholder
  → verification; services/availability correctly deferred (a caption, not a stub).
- **Nurse bank** (`nurse/bank/page.tsx`) — IBAN + holder form; renders each account via `BankStatusPanel` in its
  pending/verified/mismatch state; mismatch offers re-enter.
- **NurseLayout** sidebar gains Profile + Bank.

## What is now testable and exactly how (`npm run dev`, mocks default on — no backend needed)
- **Onboarding:** log in as customer → land on **A3** (step 1) → pick a relation → **A4**; submit **without gender**
  → blocked + "gender required"; fill it + submit → lands on **Home (A5)** with the nudge; the flow doesn't
  re-trigger (a patient now exists).
- **Patients (E1):** Patients tab shows the new patient card (relation/name/age·gender/conditions). "+ Add patient"
  → dialog (A4 form) → appears without a full reload (invalidate). Edit → persists. Archive (confirm) → card
  disappears (soft, `isActive=false`), not hard-deleted. Fresh session → empty state with add CTA. React Query
  Devtools shows the list cached + invalidated on mutation.
- **Customer profile:** edit name + emergency contact → save → Home profile nudge clears. No national-ID field.
- **Nurse profile + bank:** log in as nurse → bootstrap profile (avatar + bio) → saves, shows **unverified /
  not-bookable**. Bank settings → enter an IBAN → **pending** "در حال استعلام" panel → (after ~1 poll) **verified**
  green with **masked** IBAN (last-4). Enter `IR000000000000000000000000` → **mismatch** with re-enter CTA.
- **i18n / RTL:** toggle locale → strings flip fa↔en, `dir` flips, gender toggle / chips / stepper mirror.

## What is mocked client-side + how to make it real
All three services default to `USE_*_MOCK = true` (real HTTP clients fully wired for a one-line flip). See the
[mock registry](./mocks-registry.md) rows for `PatientsApi`, `ProfilesApi`, `NurseBankAccountsApi`. The b3
endpoints are live; the mocks stay on because of the three filed gaps:
- **REQ-005** — `PatientDto.relation` + `conditions` (client-augmented meanwhile).
- **REQ-006** — avatar/object-storage upload route + `avatarUrl` (real `uploadAvatar` throws `501`).
- **REQ-007** — customer `firstName`/`lastName`/`preferredLanguage` home (name is `/me`-only, read-only today).
Once each lands, flip the corresponding flag — no hook/component/call-site change.

## Contracts consumed
`identity-profiles.md` (b3) as the type source: `NurseProfileDto`, `CustomerProfileDto`, `PatientDto`,
`NurseBankAccountDto`, the enums (`gender` load-bearing), IBAN masking (last-4), guarded `isVerified`, tenancy-404.
Gaps filed in `requests/for-backend.md` (REQ-005/006/007) — no shapes guessed; augmented fields are clearly marked.

## Follow-ups for later phases
- **f3 (addresses & geo):** reuse this profile shell + the `services/{domain}` pattern; the A4/E1 sibling address
  book slots in.
- **f4 (catalog & service builder):** the nurse **services-and-prices** builder and **available-days** picker slot
  onto the B7 profile (both deferred here; a caption marks them).
- **f5 (verification):** replaces the neutral unverified placeholder on the nurse profile with the real
  "not bookable until verified" banner; flips `isVerified` inside the backend transaction.
- **f7 (booking):** consumes the patient (needs a known `gender`) created here.
- When REQ-005/006/007 land, flip the three mock flags.