baya-monorepo/dev/shared-working-context/reports/frontend-phase-4-report.md

Frontend Phase 4 — Catalog browse (Home A5) & nurse service builder (B7) — Report (2026-07-05)

Lights up the two faces of the configurable catalog: the customer Home (A5) front door and the nurse "add a service" builder + offerings list (B7 services half), over a new cached services/catalog domain. Consumes the b5 catalog contract. Unlocks search & discovery (f6).

What was built

services/catalog domain (client/src/services/catalog/)

• types.ts — DTOs mirrored from catalog.md (camelCase wire): ServiceCategory, ServiceOptionGroup (serviceCategoryId: number|null = cross-category, isRequired), ServiceOptionValue, NurseServiceVariant (price = IRR digit-string, priceUnit, sessionCount, options[]), CreateVariantInput/UpdateVariantInput, the CatalogApi seam, and helpers isGroupApplicable / optionSetSignature (the duplicate-listing signature). PriceUnit +the PRICE_UNITS array are the only closed enum — categories/groups/values are data-driven.
• keys.ts — catalogKeys: categories(), categoryOptionGroups(id), myVariants(params) / myVariantsLists() (invalidation prefix), variant(id).
• constants.ts — USE_CATALOG_MOCK (default true); CATALOG_REFERENCE_STALE_TIME = Infinity + CATALOG_REFERENCE_GC_TIME (reference data cached session-long, like geography); MY_VARIANTS_STALE_TIME; page sizes.
• apis/ — clientApi.ts (real, action-style routes, camelCase bodies, pageSize pagination), mockApi.ts + seed.ts (in-memory, behind the seam), index.ts (config-selected seam).
• hooks/ (one per file) — useServiceCategories, useCategoryOptionGroups (cached reference data); useMyVariants (paginated, auth-gated, self-scoped); useCreateVariant, useUpdateVariant (setQueryData the row + invalidate), useSetVariantActive (deactivate/reactivate). index.ts barrels hooks.
• names.ts — pickCatalogName(row, locale) locale-label helper (fa primary).

Shared components (client/src/components/, each with a co-located *.test.tsx)

• CategoryTile — data-driven, tappable category tile (icon disc + localised label; selected state for the builder; robust iconKey→icon fallback to a generic category icon).
• PriceDisplay — renders {Toman} {unit} via the f0 money util + an i18n unit label off price_unit, and the unit-aware estimated total (price × sessionCount, integer-safe) only when a duration is present.
• VariantCard — a nurse offering: display_name, PriceDisplay, active/deactivated distinction (dimmed + neutral chip + "can't be booked" hint), Edit + Deactivate/Reactivate actions — no delete affordance.

Money util (client/src/utils/money.ts)

• tomanToRial(value) — the sanctioned Toman→IRR digit-string conversion at the field boundary.
• multiplyIrr(value, count) — integer-safe price × count for the estimated total (never from price alone).
• Both unit-tested (money.test.ts).

Screens

• Customer Home (A5) — app/[locale]/(private-routes)/(customer)/page.tsx (rewritten): greeting + avatar (useMe firstName / initial), search bar (navigates toward /search?q=…; execution deferred to f6), data-driven category grid (useServiceCategories; loading skeletons / empty / error+retry; tiles carry service_category_id → /search?category_id=), the complete-patient-record nudge (reuses the cached f2 usePatients — no new fetch), and the preserved first-login onboarding gate.
• /search — deferred PlaceholderScreen stub so the Home CTAs don't dead-end (echoes the q/category).
• Nurse Services & prices (B7) — app/[locale]/(private-routes)/nurse/services/ (new sidebar tab). page.tsx switches between MyServicesList (offerings — active/inactive, edit, soft-deactivate w/ confirm, reactivate, empty/skeleton) and VariantBuilder (create/edit).

Builder (VariantBuilder.tsx)

• Create = 3-step stepper (reuses the f0 StepperHeader): category (CategoryTile grid) → options (single-select ToggleButtonGroup per group; required badge; blocks advancing until every required group is answered, cross-category groups included) → price+unit+duration. Price entered in Toman → submitted as an IRR digit-string (tomanToRial, no float on the path); live unit-aware estimated total via PriceDisplay; editable auto-generated display_name. The duplicate-listing 409 shows a friendly inline warning. Edit locks the category + option-set and edits only price/unit/duration/display.

Wiring

• i18n: catalog / services / search namespaces + home additions + nav.services (both locales, in sync, 313 keys). Icons: services, category, elderly, post_surgery, infant, chronic, companionship. Routes: SEARCH, NURSE_SERVICES. Nurse sidebar gains Services.

What is now testable (and exactly how)

Run npm run dev (mock is on by default — no backend needed). Follow the phase §7 steps:

1. Home — sign in as a customer → greeting + avatar, search bar, and the category grid (5 seeded categories ordered by sortOrder); the patient nudge shows/hides off the cached patient state (React Query Devtools: the patients query is reused, not refetched).
2. Locale + RTL — toggle fa↔en: labels translate, dir flips, tiles/grid mirror; Persian unit labels (ساعتی/روزانه/شبانه‌روزی) read correctly.
3. Build a variant — sign in as a nurse → /nurse/services → + افزودن خدمت → pick مراقبت از سالمند; in options, try Next without answering نوع شیفت (required) → blocked, the required badge turns red; answer it → Next; enter a Toman price + unit (ساعتی) + a duration → the estimated total updates from price × duration; edit the auto display_name; submit → the card appears (… تومان ساعتی).
4. Duplicate — create a second variant with the same category + same option-set → the friendly 409 duplicate warning shows inline; no crash / no generic toast.
5. Edit + deactivate — edit a variant's price/name → the list reflects it without a full refetch (Devtools: setQueryData + single invalidation). Deactivate → confirm dialog → the row dims to the deactivated state with the "can't be booked" hint; no delete option. Reactivate from the inactive row.
6. Caching — Devtools: catalogKeys.categories() / categoryOptionGroups are served from cache across Home and every builder step (no per-step refetch); a variant mutation invalidates only myVariants.
7. Gate — npm run check + npm run test:ci pass.

What is mocked / waiting on a real service

• CatalogApi — client/src/services/catalog/apis/mockApi.ts (+ seed.ts), behind USE_CATALOG_MOCK (default true). Faithfully reproduces the b5 create validation (400 missing-required / bad-price) and the (nurse, category, option-set) duplicate 409; categories mirror the real seed; the variant store starts empty (so the empty state demos). See mocks-registry.md (CatalogApi row). Swap = one line (USE_CATALOG_MOCK = false); catalogClientApi is already wired to the action-style routes. Caveat recorded there: the mock seeds representative option groups the fresh backend does not (an admin authors them per category) — after the swap, categories have no groups until seeded server-side.

Contracts

• Consumed: dev/contracts/domains/catalog.md (backend-phase-b5) — types/services derive from it; no shape guessed.
• Requested: REQ-010 in for-backend.md — confirm/align the list pagination query-param name (pageSize, per the proven b4 binding, vs the doc's page_size).
• Produced: none (frontend produces no contract).

Docs updated

• client/CLAUDE.md — Project Structure (customer search stub, nurse services route, services/catalog domain, CategoryTile/PriceDisplay/VariantCard); the reference-data caching note (catalog = second long-lived cached domain); the i18n namespaces list (catalog/services/search, home).
• This report + STATUS.md + mocks-registry.md + for-backend.md (REQ-010).
• No product-doc rule change was needed; the estimated-total presentation rule (total only from price × session_count, never price alone) is captured here and enforced in PriceDisplay/the builder.

Follow-ups for later phases

• f6 (search & discovery) — the Home search bar hands a q / service_category_id to /search (today a placeholder); f6 builds the results, filters, and nurse cards, and can reuse CategoryTile, PriceDisplay, the cached useServiceCategories/useCategoryOptionGroups, and the catalog/search namespaces. The variant builder is what populates the index f6 reads (a nurse must have ≥1 active variant + coverage to appear).
• Backend — deliver REQ-010 (pagination param confirmation), then f6 can flip USE_CATALOG_MOCK=false.
• Deferred (unchanged): admin catalog manager (→ f15), nurse availability slots, public nurse-profile service rows (→ f6 C3), holiday/surge pricing.