ui phase 9

dev/shared-working-context/reports/ui-phase-9-report.md

@@ -0,0 +1,176 @@
+# UI Phase 9 — Customer account & care circle — Report (2026-07-19)
+
+## What was built
+
+### Account hub (`profile/page.tsx`)
+- Rebuilt from a flat settings form into an account hub: `ProfileSummary` identity header (avatar/initials
+  via the new `initialsFallback` prop + name + server-masked phone), grouped tappable rows (اطلاعات شخصی /
+  مخاطب اضطراری / نشانی‌ها / زبان / اعلان‌ها / پشتیبانی / خروج), an emergency-contact status card (complete →
+  success check + `tel:`-only link; incomplete → a warm nudge), and a working خروج row (`ConfirmDialog` →
+  `useLogout()`, the single logout path).
+- `/profile` stays the single route — اطلاعات شخصی/زبان/مخاطب اضطراری open `FormDialogShell` sheets, not
+  sub-routes. زبان's sheet hosts the phase-2 `LocaleSwitcher` (the actual UI locale switch) alongside the
+  server-stored `preferredLanguage` field — two distinct concerns, no second locale mechanism built.
+- The silent-load-error/blank-form defect (§3.1.4 of the phase doc) was **already fixed** before this phase
+  started (confirmed against the current code, not the audit's snapshot — see "Docs updated" below); this
+  phase's profile work is the hub redesign, not that fix.
+- `ActorSwitcher` preserved verbatim (renders nothing for a single-role session).
+
+### Care-circle reframe (`patients/page.tsx`, `PatientCard`, `PatientHeader`)
+- **Naming decision:** «بیماران» → **«حلقهٔ مراقبت»** for the list/page title, nav label, and empty
+  states (the safer default per the audit, given the «خودم» self-care relation). Individual-action copy
+  (the add button, archive confirm) uses the neutral **«فرد»** ("person") rather than «عزیز» ("loved one"),
+  which reads oddly for self-care. This is a **copy-only** rename — the `/patients` route, `services/patients`
+  module, and every `patients.*`/`nav.patients` i18n **key name** are unchanged; only the translated
+  **values** changed (both `en.json` and `fa.json`). Applied consistently: page title, nav tab, empty
+  states, and the Home screen's `nudge_patient_*`/`patients_error` copy.
+- **Avatars:** a new `InitialsAvatar` component (warm auto-colored initials, deterministic per-name hash →
+  one of 6 new `--bal-avatar-*` token pairs added to `tokens.css`, both scheme blocks) is now a slot on the
+  shared `PatientHeader`, so both the E1 card and the E2 record viewer got a face in one change.
+  `ProfileSummary` also gained an `initialsFallback` prop (same util) for the account hub's identity header.
+- **Visible record affordance:** `PatientCard`'s invisible `component="button"` area is now a pressable
+  `ButtonBase` surface (hover/press + a trailing «forward» chevron) with an optional `lastVisitLabel` prop —
+  **never populated** (the cached customer bookings list, `BookingListItemDto`, carries no `patientId` at
+  all, so no client-side join is possible without an N+1 fetch per row; filed as REQ-057).
+- Soft-archive semantics + copy kept (generalized wording, same behavior); `isError`/empty-state handling
+  was already correct (see note above) and is unchanged.
+
+### Care-record editing (`patients/[id]/record/page.tsx`)
+- Replaced the whole-list free-text edit mode with **per-item bottom sheets** (`Drawer anchor="bottom"` on
+  mobile, `Dialog` on desktop, each with its own dirty-gated discard-confirm): medications get name +
+  structured **dose amount + unit** (قرص/کپسول/قطره/سی‌سی/واحد) + **frequency presets**
+  (روزی ۱/۲/۳ بار، هر ۸ ساعت، در صورت نیاز + a free-text fallback when no preset fits) + **time-of-day
+  chips** (stable codes `morning|noon|evening|night`); routine items get the same time-of-day chip row
+  instead of the old free-text `routine_time`; tasks get a per-item sheet too (label + done), with a quick
+  inline checkbox for toggling done without opening a sheet. Killing the whole-list mode removes the
+  silent tab-switch draft loss by construction (each sheet is its own short-lived mount).
+- **REQ-027 addendum** recorded in `requests/for-backend.md` (not a new REQ number): the structured shape
+  (dose amount/unit, frequency preset codes, time-of-day codes) so the eventual real table matches what the
+  UI now collects. `services/patientRecords/types.ts` + `apis/mockApi.ts` updated to the new shape.
+- **سوابق (history)** is now a Shamsi month-grouped timeline (a subtle rail), each `VisitNoteCard` gains a
+  done/undone task-summary line (`{done} از {total} انجام شد`) and, when `VisitNote.bookingId` is non-null, a
+  «مشاهده رزرو» link to `/bookings/[id]` — the service name is shown only when best-effort derivable from an
+  **already-cached** booking snapshot (`queryClient.getQueryData`, never fetched per-note — that would be an
+  N+1). Paging kept (grouped within a page).
+- The access gate (`useRecordAccess` before any clinical fetch, the access-denied card, the ownership
+  banner) is untouched, verbatim.
+
+### Addresses + the real map (`addresses/page.tsx`, `components/geography/`)
+- `isError` was **not** handled before this phase (confirmed against current code) — fixed: `ErrorState` +
+  retry, no more false-empty.
+- **Real Neshan map behind the existing `AddressMapPicker` boundary.** `{ latitude, longitude }` in/out is
+  unchanged, so `AddressForm` needed zero changes. `AddressMapPicker` now branches on `NESHAN_WEB_KEY`
+  (`@/config`, from `NEXT_PUBLIC_NESHAN_KEY`):
+  - **Set:** dynamically imports (`next/dynamic`, `ssr:false`) a new `NeshanMap` component — Leaflet
+    (`leaflet` + `@types/leaflet`, newly added `npm` dependencies) with a Neshan raster tile layer, an
+    address search box (`services/geography/neshan.ts`'s `searchNeshan`), a locate-me button (browser
+    Geolocation), a draggable/tappable pin (a brand-colored `L.divIcon`, never Leaflet's default marker
+    images), and a reverse-geocoded preview line (`reverseGeocodeNeshan`) — raw coordinates are never
+    rendered. The container stays `dir="ltr"` (same RTL hazard `AddressMapPicker`'s own doc comment already
+    called out for the grid stand-in's marker).
+  - **Unset:** falls back to the original bounded-canvas grid stand-in, **kept verbatim** (including its
+    raw lat/lng captions — this is the preserved dev/CI/jsdom path, not the primary experience) except the
+    hard-coded `rgba()` pin drop-shadow is now the new `--bal-pin-shadow` token.
+  - **Honest flag (operating-rules §9 — external unknown, not stalled on):** the Neshan tile URL template
+    (`services/geography/constants.ts`'s `NESHAN_TILE_URL_TEMPLATE`) and the Search/Reverse response field
+    names (`services/geography/neshan.ts`) were set from Neshan's public documentation **without live
+    verification** — this sandbox has no network route to `platform.neshan.org`/`api.neshan.org` for a
+    fetch tool, only for `WebSearch`. Endpoints (`api.neshan.org/v1/search`, `api.neshan.org/v5/reverse`)
+    and the `Api-Key` header are confirmed via search-result snippets; the exact JSON field names
+    (`items[].location.x/y`, `formatted_address`) and the raster tile host/path are best-effort. Every read
+    is defensive (optional-chained, try/catch), so a shape drift degrades to "no results"/"no tiles" rather
+    than a crash. **Re-verify against the current Neshan developer portal before relying on this with a
+    real key.**
+- `AddressCard` gained the pin-quality cue: «پین ثبت شده» / «پین ندارد» (warm warning tone) from
+  `Address.latitude`/`longitude` being non-null.
+- Fixed the `line_hint` fa copy bug (`messages/fa.json`) — «برای یافتن در نیاز دارد» → «برای یافتن درِ منزل
+  نیاز دارد» — flagging it here so phase 12's global copy sweep doesn't double-edit it.
+- Patient (`patients/page.tsx`) and address (`addresses/page.tsx`) forms now open in the new shared
+  `FormDialogShell` (`components/common/FormDialogShell/`): full-screen below the `sm` breakpoint (a single
+  scroll region, fixing the old double-scroll-against-keyboard defect), an app-bar header (title + close),
+  and a dirty-gated discard-confirm on close/backdrop/escape — `PatientForm`/`AddressForm` report `dirty`
+  via a new `onDirtyChange` prop (compares current fields to the `initial` prop).
+
+### Form quality
+- `PatientForm`: the single guessed full-name field is now **نام** / **نام خانوادگی** (structured, the wire
+  already carries `firstName`/`lastName`); `lastName` falls back to `firstName` only when left blank (the
+  wire's `lastName` is a required string) — never a client-side guess-split.
+- Verified no surface renders the fabricated Jan-1 `birthDate` — every display path already went through
+  `birthDateToAge` before this phase; age-only, as required.
+- `GenderToggle` gained `width: '100%'` so its `flex: 1` children actually split evenly.
+- `RelationSelect`'s selected state gained a check icon (+ a soft-tint background), no longer color-only
+  (WCAG 1.4.1).
+- Profile's `AppLoading` full-page spinner replaced with a form-shaped `Skeleton` (identity header + row
+  placeholders), matching the loading language of patients/addresses/record.
+
+## What is now testable (and exactly how)
+
+1. Log in as a seeded customer (`0912000000x`) on a mobile viewport at `/fa`. Open the Profile tab → identity
+   header (initials + name + masked LTR phone), rows for اطلاعات شخصی/مخاطب اضطراری/نشانی‌ها/زبان/اعلان‌ها/
+   پشتیبانی/خروج. Tap خروج → confirm → lands on `/login`, session revoked.
+2. Clear the emergency contact (via the row's edit) → the incomplete-state warm nudge; fill it in → a
+   success check + `tel:` link.
+3. Stop the API, reload `/profile`, `/patients`, `/addresses` → each shows `ErrorState` with retry (no
+   blank form, no false-empty). Start the API, tap retry → data returns without a full reload.
+4. Open the care circle (`/patients`) → every person has a colored-initials avatar and a visible chevron
+   affordance; tap the card body → the record opens; the renamed «حلقهٔ مراقبت» title appears in the tab
+   bar and the page header.
+5. In the record, tap "افزودن دارو" → the bottom sheet (mobile) with dose amount + unit, frequency preset
+   chips (+ free-text fallback when none is chosen), and صبح/ظهر/عصر/شب chips; save → the row shows the
+   structured summary. Switch tabs mid-edit and come back → nothing lost (the sheet only exists while open).
+   Try closing a dirty sheet → discard-confirm.
+6. Open سوابق → notes grouped by Shamsi month on a rail; a note whose `bookingId` is set shows «مشاهده رزرو»
+   linking to `/bookings/[id]`.
+7. Add an address on mobile → the form opens full-screen with an app-bar header. Without
+   `NEXT_PUBLIC_NESHAN_KEY` set (the default in this environment), the grid stand-in still works exactly as
+   before (raw lat/lng shown — the documented fallback). With a real key set, the real map (search box,
+   locate-me, draggable pin, reverse-geocoded preview) should appear instead — **not verified end-to-end
+   in this sandbox** (no real Neshan key available; see the honest flag above). Back on the list, an
+   address without a pin shows «پین ندارد»; one with a pin shows «پین ثبت شده».
+8. Repeat 1, 4, 5, 7 on `/en` (LTR) and in dark mode.
+
+## What is mocked / waiting on a real service
+
+- `patientRecords` stays **mock-primary** for the family-owned record (REQ-027 — unchanged domain
+  boundary); this phase only changed the **shape** collected/persisted by the mock (see the REQ-027
+  addendum above), not the mock/real seam itself.
+- The Neshan web map is **client config**, not a backend seam (per the phase doc: "not a backend seam —
+  with a grid-stand-in fallback when unset") — no `mocks-registry.md` entry filed; the fallback grid *is*
+  the registered dev/CI behavior, already documented in `AddressMapPicker`'s own doc comment.
+- `services/geography/neshan.ts`'s tile URL and response-shape assumptions are unverified against live
+  Neshan documentation (see the honest flag above) — this is a **content-accuracy risk to re-check before
+  production use with a real key**, not a mock.
+
+## Contracts
+
+- Consumed: no new backend contract this phase (the touched domains — profiles/patients/addresses/
+  patientRecords — already had their contracts from earlier phases).
+- Filed to `dev/shared-working-context/frontend/requests/for-backend.md`:
+  - **REQ-027 addendum** (not a new number) — the structured medication/routine field shape.
+  - **REQ-057** — `lastVisitAt` (+ optional `visitCount`) on the patient read model (`PatientDto`).
+  - **REQ-058** (deferred, non-blocking) — optional patient photo upload; the shipped solution is
+    initials-only and needs no backend.
+
+## Docs updated
+
+- `client/CLAUDE.md` "Project Structure": `profile/`, `patients/`, `patients/[id]/record/`, `addresses/`
+  route notes; the `components/common/` list (new `InitialsAvatar/`, `FormDialogShell/`); `PatientForm`,
+  `PatientCard`, `PatientHeader`, `ProfileSummary`, and `geography/` component bullets.
+- `client/.env.sample`: documented `NEXT_PUBLIC_NESHAN_KEY` (the client web key — separate from the
+  server's `NeshanGeocoder` key, which lives in server config and is never touched here).
+- **Correction to the phase's own premise:** the audit (`dev/post-phase/ui/audit/customer-account.md`,
+  authored 2026-07-17 13:22) predates a same-day `ui phase 2` commit (2026-07-17 19:05) that already added
+  the `isError`/`ErrorState` handling the audit describes as missing in `profile/page.tsx` and
+  `patients/page.tsx`. Verified against the current code (not re-derived from the stale audit text) before
+  starting — `addresses/page.tsx` genuinely still lacked it and was fixed in this phase. Flagging this so a
+  future phase doesn't re-"fix" an already-fixed defect based on the audit's original wording.
+
+## Follow-ups for later phases
+
+- Re-verify `services/geography/neshan.ts` + `NESHAN_TILE_URL_TEMPLATE` against the current
+  `platform.neshan.org` developer docs once a real web key is available to test against.
+- REQ-057 (`lastVisitAt`) — once served, wire `PatientCard`'s existing `lastVisitLabel` prop in
+  `patients/page.tsx`.
+- Phase 12's global copy sweep: the `address.line_hint` fa fix already landed here — don't re-edit it.
+- A read-mode "daily schedule" view (meds grouped صبح/ظهر/شب) and an `AddressCard` static-map thumbnail are
+  both explicitly deferred per the phase doc (§3.3.3, §3.4.3) — not started.