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/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.