backend phase 4: geography, addresses & nurse service areas

Adds the province -> city -> district reference hierarchy (geo schema,
seeded with 31 provinces + capital cities + Tehran's 22 districts),
nurse service areas (district_id NULL = whole city, filtered-index-pair
uniqueness -> 409), and encrypted, geocoded customer addresses with a
single-primary invariant. Introduces the IGeocoder seam (mocked) and
409 Conflict on the result envelope. Public cascading lookups are cached
behind a generation-token scheme with invalidate-on-admin-write.

One EF migration (GeographyAddressesServiceAreas, applied). Contract +
swagger snapshot + handoff/report/registry updated. 103 tests pass.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

dev/shared-working-context/backend/STATUS.md

@@ -12,6 +12,28 @@ One block per completed backend phase. Newest at the top. Backend lane writes he
 - **Notes for frontend:** <anything load-bearing>
 -->
 
+## backend-phase-4 — Geography, addresses & nurse service areas — 2026-07-02
+- **Shipped:** five tables via one migration (`GeographyAddressesServiceAreas`) — new **`geo`** schema
+  `Provinces` 1:N `Cities` 1:N `Districts` (+ `NurseServiceAreas`) and `usr.CustomerAddresses`; seed
+  (31 provinces + capital cities + Tehran's 22 مناطق via `HasData`); 20 CQRS slices across 4 controllers
+  (`geo` public lookups incl. `/tree`, `admin_geo` CRUD + set_active, `nurse_service_areas`,
+  `customer_addresses`); new **`IGeocoder`** seam (deterministic mock, `Seams:Geocoding`); per-domain
+  repos on `IUnitOfWork`; enc value converters for the address PII columns; **`409 Conflict`** added to
+  `OperationResult`/`BaseController`. Whole-city (`district_id NULL`) uniqueness via a **filtered-index
+  pair**; single-primary address via filtered `UNIQUE(customer_id) WHERE is_primary=1`; geo reads cached
+  behind a generation-token scheme with invalidate-on-admin-write.
+- **Contracts:** dev/contracts/domains/geography-addresses.md + openapi snapshot refreshed (yes — 20 new
+  geo/service-area/address paths).
+- **Mocked:** `IGeocoder` → 🟡 (see reports/mocks-registry.md).
+- **Gate:** build clean (0 new code warnings) / tests green (103 pass: +16 `Baya.Test.Api` integration,
+  +12 handler unit tests). Migration `GeographyAddressesServiceAreas` applies on startup; swagger exposes
+  all b4 paths.
+- **Handoff:** backend/handoff/after-backend-phase-4.md
+- **Notes for frontend:** `districtId=null` means **whole city** (a real choice) everywhere. Duplicate
+  service area → **409**. Addresses come back **decrypted for the owner** with `latitude`/`longitude`
+  (nullable when ungeocoded — geocoding is mocked). Routes are action-style (`admin_geo/create_city`,
+  `nurse_service_areas/add`, `customer_addresses/create`, …). Admin geo needs an admin token.
+
 ## backend-phase-3 — Identity: profiles, patients & nurse bank accounts — 2026-07-02
 - **Shipped:** four `usr` tables via one migration (`IdentityProfilesPatientsBankAccounts`) —
   `NurseProfiles` (1:1 `Users`; guarded `is_verified` **no public setter**; read-only aggregates;

dev/shared-working-context/backend/handoff/after-backend-phase-4.md

@@ -0,0 +1,61 @@
+# After backend-phase-4 — geography, addresses & nurse service areas are live
+
+The geographic spine the marketplace stands on now exists. There is a real province→city→district
+hierarchy (tables, not code lists), nurses can declare where they travel, and customers can save
+encrypted, geocoded service addresses. Contract:
+[`dev/contracts/domains/geography-addresses.md`](../../../contracts/domains/geography-addresses.md);
+machine schema: `dev/contracts/openapi/swagger.v1.json` (refreshed).
+
+## What the frontend (f3-b4) can now build
+- **Cascading province/city/district dropdowns** — `GET api/v1/geo/provinces`,
+  `…/geo/cities?province_id=`, `…/geo/districts?city_id=` (each active-only, ordered by `sortOrder`), or
+  the whole active tree in one call via `GET api/v1/geo/tree`. **An empty district list is normal** — that
+  city is whole-city-only; let the user pick "whole city".
+- **Nurse coverage-area editor** — `POST api/v1/nurse_service_areas/add` `{ cityId, districtId? }`
+  (omit `districtId` = whole city), `DELETE …/nurse_service_areas/remove/{id}`,
+  `GET …/nurse_service_areas/list`. Each row carries an `isWholeCity` flag. Requires a nurse profile first
+  (b3 `nurse_profiles/upsert`).
+- **Address book + map-pin picker** — `POST api/v1/customer_addresses/create`
+  `{ title, cityId, districtId?, addressLine, postalCode?, recipientName?, recipientPhone?, isPrimary? }`,
+  `update/{id}`, `set_primary/{id}`, `delete/{id}`, `list` (primary first). The create/update response and
+  the list return `latitude`/`longitude` for the map pin (**nullable** — render a "pin not set" state when
+  null), and the address is **decrypted for the owner**.
+
+## Rules baked into the API (don't fight them client-side)
+- **`districtId = null` means "the entire city"** — a deliberate coverage choice, not "unset". Show it as a
+  first-class option; a whole-city service area matches every district in that city when search lands (b7).
+- **Duplicate service area → `409`** (including a duplicate whole-city row), never a `500`. Surface it as
+  "you already cover this".
+- **Single primary address** — the first address is primary automatically; setting another primary clears
+  the previous one. There is always exactly one.
+- **`is_active` hides, never deletes** — a deactivated region simply drops out of the dropdowns.
+- **Address PII is encrypted at rest** and only ever returned to the owning customer. Coordinates and the
+  `title` label are not PII.
+- **Tenancy** — service areas and addresses are strictly owner-scoped; another owner's id returns `404`.
+- **Refresh after `select_role`** still applies (nurse/customer scoping reads the role claim in the token).
+- **Routes are action-style** (`admin_geo/create_city`, `nurse_service_areas/add`,
+  `customer_addresses/create`, …) — see the contract for the full list.
+
+## What's mocked
+- **Geocoding (`IGeocoder` → 🟡).** `MockGeocoder` returns deterministic coordinates around the city
+  centroid with no network call. A config switch (`Seams:Geocoding:ReturnNullCoordinates`) or a `NO_GEO`
+  marker in the address text forces the null-coordinate path so the "saved without a map pin" UI state is
+  testable. Real Neshan/Google geocoding is a drop-in registration swap (see mocks-registry).
+
+## Schema / migration
+Migration **`20260702093332_GeographyAddressesServiceAreas`** (applies on startup): `geo.Provinces`,
+`geo.Cities`, `geo.Districts`, `geo.NurseServiceAreas`, `usr.CustomerAddresses`. Whole-city uniqueness is a
+**filtered-index pair** (`UNIQUE(nurse_id, city_id) WHERE district_id IS NULL AND deleted_at IS NULL` +
+`UNIQUE(nurse_id, city_id, district_id) WHERE district_id IS NOT NULL AND deleted_at IS NULL`); addresses
+carry a filtered `UNIQUE(customer_id) WHERE is_primary=1 AND deleted_at IS NULL`; coordinates are
+`decimal(9,6)`; address PII columns are encrypted. Seed: 31 provinces (Tehran id `1`), capital cities
+(Tehran city id `101`), Tehran districts `1001…1022`.
+
+## Deferred to later phases (do not build against these yet)
+- **`nurse_search_index` fan-out** on service-area add/remove → **b7** (the add/remove handlers are the
+  clean trigger point).
+- **GPS-radius / "nurses near me" map discovery** → not planned; coverage is named districts, full stop.
+- **EVV distance check** that *consumes* the address `latitude`/`longitude` → **b9** (this phase only
+  *produces* the coordinates).
+- **Region bulk-import feed** (`IGeoDataImporter`) → deferred; the idempotent seed + admin CRUD is enough
+  for MVP.