clean and refine product docs structure

2026-06-24 01:32:46 +03:30
parent be07c703ec
commit 1df3cd9f64
113 changed files with 6078 additions and 4973 deletions
@@ -0,0 +1,23 @@
+# 4. Search & Matching
+
+[← Business Requirements](index.md)
+
+## (a) Business requirements
+- Families search by **service category**, **geography** (city, and optionally district), price, and availability, with results sortable by rating.
+- **Geography** is driven by nurse-declared **service areas**: a nurse covers one or more cities, optionally specific districts; a city-level row (no district) means the whole city.
+- **Search must be cheap from day one.** The naive query joins nurse profile (verified + accepting) → variants (category/price) → variant options → service areas → rating across 4+ tables. Instead a **denormalized `nurse_search_index`** holds one flat row per active, bookable variant with all search-relevant fields, maintained on write. A row exists **only** when the nurse is `is_verified` and not suspended and the variant `is_active`. This is far cheaper than introducing Elasticsearch at MVP stage.
+- **Same-gender caregiver matching** is a first-class filter and a near-hard requirement: in Iranian bodily-care (bathing, toileting, intimate post-surgical care) same-gender caregiving is culturally decisive, not optional. The customer specifies a required caregiver gender on the booking request (`required_caregiver_gender`), and nurse gender is an exposed search filter so families can narrow to same-gender caregivers up front. The patient's gender (`patients.gender`) and the nurse's gender support this matching.
+
+## (b) Iran-specific considerations
+- District granularity varies: in Tehran, districts map to the 22 official municipal مناطق; in smaller cities they are major neighborhoods. Districts are optional.
+- **Same-gender matching is the single most Iran-specific matching constraint** — every real elder/post-surgical bodily-care request implies it. It must be surfaced before booking, not discovered after.
+- White-space opportunity: incumbents concentrate ~99% in Tehran/Karaj; the search/area model must work for under-served second-tier cities (Mashhad, Isfahan, Shiraz, Tabriz, Ahvaz, Qom).
+
+## (c) MVP vs DEFERRED
+- **MVP:** category + city/district geo search; `nurse_search_index` denormalization; same-gender filter via `required_caregiver_gender`; rating sort.
+- **DEFERRED:** map-based discovery; availability-window filtering as a hard constraint (availability slots are soft guidance at launch); algorithmic ranking beyond rating; continuity-of-carer "preferred nurse" suggestions.
+
+## (d) Supporting database entities
+`nurse_service_areas`, `cities`, `districts`, **`nurse_search_index`**, `nurse_service_variants`, `nurse_profiles` (rating, gender via `users`), `patients.gender`; `booking_requests.required_caregiver_gender` (the requested constraint).
+
+> **Related:** Data model — [Services & Pricing](../data-model/03-services-and-pricing.md).