baya-monorepo/dev/phases/frontend/frontend-phase-6-b7.md

Frontend Phase 6 — Search & discovery (find a verified, same-gender nurse)

Mission: build the family-facing discovery experience — the heart of the marketplace. A customer picks a care category, narrows by city / gender / price, and gets a rating-sorted list of only verified, accepting nurses; opening one shows their trust badges, attribute chips, priced services, and latest review, ending in the "درخواست رزرو" call-to-action that hands off to the booking flow. This phase implements wireframe screens C1 (search & filter), C2 (results), and C3 (nurse profile) against the search domain (backend phase b7), and establishes the shared nurse-result card + price-row components that the booking flow will reuse.

Track: frontend · Depends on: frontend-phase-4-b5 (catalog browse & service builder) · frontend-phase-5-b6 (verified-nurse / trust badge) · backend b7 contract (dev/contracts/domains/search.md) · Unlocks: frontend-phase-7-b8 (booking request flow) Before you start, read ../_shared/agent-operating-rules.md. It is not optional.

---

1. Context — where this sits

We are at the pivot of the customer journey: everything before this phase let a family enter the app (auth f1), describe who needs care (onboarding f2), say where (addresses f3), and browse the catalog (f4). This phase is the first time a family sees real nurses and chooses one. It is the screen the product calls the trust funnel: discovery surfaces only platform-vetted, same-gender-filterable caregivers, which is Balinyaar's entire differentiation versus opaque incumbents. The output of this phase — a selected nurse + the carried filter intent (especially required_caregiver_gender) — is the input to the booking request (f7).

What already exists (do not rebuild) — link, extend, never re-create:

• f0 foundations (frontend-phase-0): the customer mobile shell with the 5-tab bottom nav (خانه/رزروها/بیماران/کیف‌پول/پروفایل), the services/{domain} + TanStack Query caching pattern (keys.ts factory, apis/clientApi.ts, one-hook-per-file, mutation invalidation), the money/format util (formatIrrToToman, integer-safe IRR-string parse, Shamsi date display) in src/utils/, the i18n namespace conventions (incl. the search namespace), the RTL baseline, and the shared composite primitives (status chip, stepper, etc.). Copy the auth service shape — do not invent a new data pattern.
• f4 catalog (frontend-phase-4-b5): the catalog service + the category grid (مراقبت سالمند / پرستار کودک / تزریقات و سرم / فیزیوتراپی) and category cards used on the customer Home (A5). C1 reuses that category grid component and the catalog query — do not rebuild category fetching here.
• f5 verified-nurses (frontend-phase-5-b6): the trust badge component(s) — ✓ تاییدشده (verified) and نظام پرستاری (INO membership) — and the verification-status vocabulary. C2/C3 reuse those badges; do not re-implement the verified mark.
• Money/format: prices render through the f0 formatIrrToToman util (IRR Rials string → Toman display). Never format money inline.

Data note: b7's GET /search/nurses reads the denormalized nurse_search_index, which by invariant contains a row only when the nurse is is_verified AND not suspended AND is_accepting_bookings AND the variant is_active. So every result you receive is already bookable — the UI must not need to re-filter for verification. (See §5.)

2. Required reading (do this first)

• ../_shared/agent-operating-rules.md and ../_shared/frontend-conventions-checklist.md.
• ../../../client/CLAUDE.md — the engineering contract (RSC/client boundary, the [locale] layout rule, i18n, theme/tokens, clientFetch/serverFetch, the services/{domain} layout, TanStack Query setup, the cookie manager). Don't break the boundary.
• Invoke the frontend-designer skill before any visual work — it is the design/brand contract (palette: teal #1d4a40, terracotta #d98c6a, cream; tokens; typography; the App* library; the mobile shell; the hard UI rules). C1/C2/C3 must come out branded, RTL, dark-mode-ready. All visual work goes through it.
• ../../../product/wireframes/index.html — Section C (screens C1, C2, C3): the exact layout, copy, and controls you implement. C1 = selected category + filter pills (تهران/location, تاریخ/date, جنسیت/gender) + category grid + "مشاهده ۲۴ پرستار" results CTA; C2 = result count + "مرتب‌سازی: امتیاز" sort + nurse cards (photo, name, ✓ تاییدشده, rating/review count, distance km, "from X تومان/ساعت"); C3 = avatar, name, rating, verified + نظام پرستاری badges, attribute chips, services-and-prices rows, latest review snippet, "درخواست رزرو".
• ../../../product/business/04-search-and-matching.md — the business rules: category + city/(optional district) geo search, rating sort, and the same-gender caregiver near-hard requirement (nurse_gender filter + the requested required_caregiver_gender carried before booking, not after).
• The contract ../../contracts/domains/search.md (b7) + ../../contracts/conventions/money-and-types.md and api-conventions.md — the envelope, the IRR-as-string money rule, gender = male/female/any, price_unit = per_hour/per_session/per_half_day/per_day/per_24h, enums-as-codes (labels are i18n keys, never derived from the code), pagination params, and the exact request/response shapes for GET /search/nurses and the nurse-profile/variant payloads. Types come from this doc — do not guess server shapes (if a shape is missing, follow §4 + operating-rules §6).
• The backend handoff ../../shared-working-context/backend/handoff/after-backend-phase-7.md — which endpoints are live, what's mocked, what to consume.
• The existing src/services/auth/* (the template) and the f4 catalog + f5 trust-badge code — the patterns you copy and the components you reuse.

3. Scope — build this

A vertical slice: services/search (types/keys/apis/hooks) → the three screens (C1, C2, C3) → the two shared components (nurse-result card, price-row), all RTL/i18n/cache-correct.

3.1 The search domain service (src/services/search/)

Copy the f0/auth service shape exactly:

• types.ts — mirror the b7 contract as string-literal unions / interfaces (don't guess):
  • NurseSearchFilters — serviceCategoryId: number, cityId: number, districtId?: number, nurseGender?: 'male' | 'female' (omit = any), priceMin?: string, priceMax?: string (IRR strings), sort: 'rating' (the only MVP sort), page, pageSize.
  • NurseSearchResult — the C2 card row: nurseId, variantId, displayName/nurseName, avatarUrl, isVerified (always true by invariant), averageRating, totalReviews, distanceKm?, priceFromIrr (string), priceUnit (the per_* union), nurseGender.
  • NurseProfile — the C3 payload: identity (nurseName, avatarUrl, bio, yearsExperience), averageRating/totalReviews/totalCompletedBookings, isVerified, inoMembership (نظام پرستاری badge flag), attributeChips (specialties/تخصص‌ها labels), services: NurseProfileServiceRow[] (each = variantId, displayName, priceIrr string, priceUnit, optional sessionCount), and a latestReview? snippet (rating, body, authorMasked, createdAt).
  • Paged<T> — reuse the f0 paginated envelope type.
• keys.ts — the query-key factory: searchKeys.results(filters) keyed on the full filter object (this is the cache contract — see §5), searchKeys.profile(nurseId).
• apis/clientApi.ts — wraps clientFetch (never raw fetch):
  • searchNurses(filters): Promise<Paged<NurseSearchResult>> → GET /search/nurses (filters as query params; omit absent optional filters so the key/URL stay stable).
  • getNurseProfile(nurseId): Promise<NurseProfile> → the b7 nurse-profile endpoint (consume the exact route from the contract).
  • Add a serverApi.ts only if you prefetch C2/C3 from an RSC to remove a client round-trip (optional, see §5).
• hooks/ (one hook per file):
  • useNurseSearch.ts — useQuery({ queryKey: searchKeys.results(filters), queryFn }) with a deliberate staleTime (results are read-heavy and change slowly) and keepPreviousData so the list doesn't flash empty while a new filter loads.
  • useNurseProfile.ts — useQuery on searchKeys.profile(nurseId); enabled only when an id is present.
  • useDebouncedSearchFilters.ts (or fold the debounce into the C1 controller) — debounce the free-text/quick-filter input so keystrokes don't fan out one request per character.
• index.ts — barrel.

3.2 C1 — Search & filter screen (جستجو و فیلتر)

The entry screen (reachable from Home/A5 search bar and category tap). Build:

• Selected-category header + the category grid (reuse the f4 catalog category grid; selecting a category sets serviceCategoryId). Categories shown per wireframe: مراقبت سالمند، پرستار کودک، تزریقات و سرم، مراقبت زخم (driven by the live catalog, not hardcoded labels).
• Filter pills (the C1 row): city (تهران ▾ — required; the cascading province→city→district picker reused from f3 geo — district optional, "leaving district empty searches the whole city" helper copy), date (تاریخ ▾ — capture intent only; availability is soft at MVP and is not a hard search filter — pass it through to booking, don't filter results on it), gender (جنسیت ▾ — خانم / آقا / فرقی ندارد → male/female/omit). Make gender a prominent, early, first-class control with one line of copy on why same-gender matters for bodily care.
• An optional price-range control (min/max → IRR strings) and the results CTA that mirrors the wireframe's "مشاهده ۲۴ پرستار" — i.e. show the live result count and navigate to C2. (Wire the count off a lightweight useNurseSearch head/totalCount, or navigate and show the count on C2 — your call, but the number must be real, not hardcoded.)
• Hold filter state in a small colocated controller (a useSearchFilters hook or local reducer) — not in a high context provider (it changes fast). The filter object is what becomes the query key.

3.3 C2 — Results screen (نتایج جستجو)

• Header: result count ("۲۴ پرستار") + sort control "مرتب‌سازی: امتیاز ▾" (rating is the only MVP sort — render it as a control but it has one option; tag other sorts (DEFERRED)).
• List of NurseResultCard (§3.5) rendered from useNurseSearch(filters), paginated (infinite scroll or a "load more" — reuse the f0 paginated pattern). The customer bottom tab nav stays visible (this is a shell screen).
• States (all required): loading = skeleton cards (not a spinner); empty = the "no nurses match → relax your filters" state with concrete suggestions (remove the gender filter / widen to whole city by clearing district / try a nearby city — lean on the white-space cities Mashhad/Isfahan/Shiraz); error = retry; populated = rating-sorted cards. Tapping a card → C3.
• Changing a filter on C1 and returning re-queries with the new key; reverting to a prior filter set reuses the cached result (no refetch) — this is an acceptance criterion (§5, §7).

3.4 C3 — Nurse profile screen (پروفایل پرستار)

From useNurseProfile(nurseId):

• Header: avatar, name, rating (+ review count), and badges — ✓ تاییدشده (reuse f5 verified badge) and نظام پرستاری (INO membership; render only when inoMembership is true).
• Attribute chips: specialties / experience (سالمندان، تزریقات، ۸ سال سابقه) from attributeChips / yearsExperience.
• Services & prices: a list of ServicePriceRow (§3.5) — one row per offered variant (displayName + price rendered via formatIrrToToman + the localized price_unit label, e.g. "۲۸۰٬۰۰۰ تومان/ساعت", and a 12h night-shift variant). These are the bookable units.
• Latest review snippet (latestReview) — rating + masked author + truncated body; "no reviews yet" empty state. (The full reviews tab is (DEFERRED) → frontend-phase-13-b14.)
• Primary CTA: "درخواست رزرو" — navigates to the booking request form (f7), carrying the selected nurse + variant + the filter intent (especially required_caregiver_gender derived from the C1 gender filter, and the city/category). f7 owns the form; this phase only hands off the intent — pass it via route params / a small handoff, do not build the request form here. Tag the form itself (DEFERRED → f7).
• States: loading skeleton, not-found (404 → "this nurse is no longer available"), error/retry.

3.5 Shared components (built once, reused by f7+)

At the shared level (src/components/…), composed from MUI/App* primitives (never re-implement a root primitive), each with a co-located *.test.tsx and i18n in both locales:

• NurseResultCard — the C2 card: Avatar (photo), name, the reused verified badge, rating + review count, distance chip (km, only when distanceKm present), and the "from X تومان/ساعت" price line (via formatIrrToToman + localized unit). Pure/presentational, memoized, stable props so a list of N cards doesn't re-render on unrelated state.
• ServicePriceRow — the C3 service line and a reusable price row: localized service name + the money formatting + the price_unit label. Reused on C3 now and by the booking summary later.

These two are the load-bearing reusable pieces. The category grid (f4), trust badges (f5), geo picker (f3), and status chip (f0) are reused, not rebuilt.

3.6 i18n

Fill the search namespace (seeded in f0) in both messages/en.json and messages/fa.json, in sync, RTL-first: filter labels (شهر/تاریخ/جنسیت/خانم/آقا/فرقی ندارد), sort label, result-count pluralization, every empty/error/loading copy, badge labels (تاییدشده/نظام پرستاری), price-unit labels (ساعتی/per_hour … per_24h), and the "درخواست رزرو" CTA. No display label is derived from an enum code — each price_unit/gender/sort code maps to an i18n key.

4. Mocks & seams in this phase

This is a frontend phase — it introduces no backend seam; it consumes the b7 contract.

• Reuse the services/{domain} seam pattern from f0. All data goes through clientFetch inside services/search/apis/.
• If b7 is not yet merged (or a needed shape is missing): build a mock clientApi behind the same services/search seam (real-shaped fixtures: a handful of verified nurses with ratings, distances, prices, badges; one profile with services + a review) so C1/C2/C3 are fully demoable, and (a) append the exact missing/mismatched shape to ../../shared-working-context/frontend/requests/for-backend.md (operating-rules §6 — you never edit backend files), and (b) record the mock in your frontend report so it's swapped out cleanly when the real endpoint lands. Selection between mock and real clientApi is by the seam (one import swap), never an if (mock) scattered through components.

No new entry is needed in the backend mocks-registry.md (that registry is for backend DI seams); the client-side mock is recorded in your frontend report instead.

5. Critical rules you must not get wrong

• Only verified + accepting nurses appear — and the UI must not have to enforce it. The b7 nurse_search_index invariant guarantees every returned row is verified, not suspended, accepting, and on an active variant. Never add client logic that re-includes hidden nurses, and never display an unverified/paused nurse. If a result somehow lacks the verified flag, treat it as a data defect and file it via for-backend.md — do not paper over it.
• The filter object IS the query key — identical filters reuse cache, never refetch. queryKey = searchKeys.results(filters) must be a stable, canonical serialization (sorted keys, omitted optional filters rather than undefined, IRR as strings). Changing a filter and reverting to a previous set must hit the React Query cache with zero network calls (verify in Devtools — §7). Use keepPreviousData so the list doesn't flash. This is the whole point of the phase's caching design.
• Debounce input. Free-text / quick-filter typing must not fire one request per keystroke — debounce before it becomes part of the query key.
• Same-gender is first-class and carried before booking. The gender filter (male/female/any) is a prominent, early control with explanatory copy; the chosen value is carried into the booking handoff as required_caregiver_gender (f7) — surfaced before booking, never discovered after. Never default or silently drop gender.
• Geography semantics: city is required; district is optional and "empty district = whole city" — the picker copy must say so; don't send a bogus district. (Backend matches city-only + district rows; the client just leaves districtId absent.)
• Availability is soft at MVP — never a hard search filter. The date pill captures intent for the booking flow; it must not remove nurses from results. Tag availability-window filtering (DEFERRED).
• Money renders through the f0 util only — IRR Rials are integer strings, no floats, Toman is display-only. Format with formatIrrToToman; never parse IRR into a JS number for math, never compute a "from" price client-side beyond picking the min the server sent.
• Enums are codes; labels are i18n keys. price_unit, gender, and sort never render their raw code; each maps to a localized label in both en.json/fa.json.
• RSC/client boundary + caching discipline: prefetch C2/C3 from an RSC with initialData only if it removes a round-trip; otherwise client-fetch. No next/headers/next-intl/server in client components.
• Minimal re-renders: NurseResultCard is presentational/memoized; keep fast-changing filter state colocated (not in a high provider); use select to subscribe to slices where it helps.
• MUI primitives stay MUI; the two new composites live shared — not inline in a page.

6. Definition of Done

The shared definition-of-done.md, plus:

• services/search exists (types/keys/apis/hooks/index), copying the f0 pattern; types derive from the b7 contract (or a mock behind the seam + a for-backend.md request if b7 isn't ready).
• C1, C2, C3 are built per the wireframe, RTL, with category grid (reused), city/gender/(optional district)/price filters, rating sort, and the prominent same-gender control.
• C2 has all four states (loading skeletons / empty "relax filters" / error-retry / populated); C3 has loading / not-found / error states.
• Caching proven: the filter object is the query key; reverting a filter reuses cache with no network call; input is debounced; keepPreviousData set. (Demonstrable in Devtools — §7.)
• NurseResultCard + ServicePriceRow are shared components with co-located tests; the verified badge (f5), category grid (f4), geo picker (f3) are reused, not rebuilt.
• Prices render via the f0 money util; every string is an i18n key in both locales, in sync; no label derived from an enum code.
• "درخواست رزرو" hands off the selected nurse + variant + required_caregiver_gender + city/category to the f7 route (form itself deferred to f7).
• npm run check green; npm run test:ci green (the two new shared components are covered); client/CLAUDE.md Project Structure updated for the new services/search, the two shared components, and the C1/C2/C3 routes.

7. How to test (what a human can verify after this phase)

Run npm run dev (point NEXT_PUBLIC_API_URL at a b7-enabled server, or use the seam mock if b7 isn't merged):

• End-to-end discovery: from Home, open C1 → pick a category (e.g. مراقبت سالمند), set city (تهران), set gender (خانم) → the results CTA shows a real count → tap it → C2 lists only verified nurses, rating-sorted, each card showing photo, name, ✓ تاییدشده badge, rating + review count, distance, and "from X تومان/ساعت". Confirm no unverified/paused nurse ever appears.
• Profile: tap a card → C3 shows avatar, rating, ✓ تاییدشده + نظام پرستاری badges, attribute chips, the services-and-prices rows (correct Toman formatting + Persian unit labels), and the latest review snippet; "درخواست رزرو" navigates to the f7 route carrying nurse + variant + gender intent.
• Empty state: search a white-space city/category/gender combo with no matches → the "no nurses match → relax your filters" state with concrete suggestions (clear district / drop gender / try Mashhad).
• Caching (the headline check): open React Query Devtools → apply filter set A (cache entry A) → change to set B (entry B, one fetch) → revert to A → the list shows instantly with zero new network requests (cache hit on key A). Type quickly in the search input → confirm one debounced request, not one per keystroke.
• i18n/RTL: flip locale fa↔en → all C1/C2/C3 labels, badges, unit labels, and empty/error copy translate and mirror correctly; dark mode still renders.
• Gate: npm run check and npm run test:ci pass.

8. Hand off & document (close the phase)

• Docs: update the Project Structure tree in ../../../client/CLAUDE.md for the new services/search, the C1/C2/C3 routes/segments, and the two new shared components (NurseResultCard, ServicePriceRow); note the "filter-object-as-query-key" caching pattern as a reusable convention. Fix any doc drift you touch.
• Contracts: consume ../../contracts/domains/search.md (b7) — derive services/search/types.ts from it; do not edit it. Any missing/ambiguous shape (e.g. the nurse-profile services array, the latestReview shape, distance units, or the count head) goes to ../../shared-working-context/frontend/requests/for-backend.md as an append — the backend delivers it in a later change; you never edit backend files.
• Handoff & report: append your summary to ../../shared-working-context/frontend/STATUS.md; write ../../shared-working-context/reports/frontend-phase-6-report.md — what was built (C1/C2/C3 + services/search + the two shared components), what is now testable and exactly how (the steps in §7), what (if anything) is mocked behind the services/search seam and how f-next swaps it for the real b7 endpoint, the contract consumed + any for-backend requests filed, and the follow-ups (the f7 booking handoff contract for the carried intent; the C3 reviews tab deferred to f13).
• Memory: save a project-type memory note for the non-obvious decisions this phase locks in — the filter-object-as-query-key caching contract, the verified-only invariant the UI relies on (so a future agent doesn't add a client-side verification re-filter), and the required_caregiver_gender carried-before-booking handoff to f7 — with a one-line pointer added to MEMORY.md.