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>

server/CLAUDE.md

@@ -81,15 +81,15 @@ projects/assemblies, Clean-Architecture layers, and cross-layer dependencies.
 ```
 src/
 ├── Core/
-│   ├── Baya.Domain          Entities (User, Role, UserSession, RoleNames…, Identity/ (NurseProfile, CustomerProfile, Patient, NurseBankAccount), + Configuration/Audit/Analytics/Holidays/Notifications/SupportAlerts), BaseEntity, IEntity, ITimeModification, IAuditableEntity, IAuditable (audit-row marker)
-│   └── Baya.Application     Features/ (Commands & Queries; Identity area = auth + profiles/patients/nurse-bank-accounts; + Configuration/Audit/Analytics/Holidays/Notifications/SupportAlerts areas), Contracts/ (incl. Contracts/Common cross-cutting seams incl. IBankAccountOwnershipVerifier + the platform-signal facade contracts + Contracts/Persistence per-domain repositories on IUnitOfWork), Models/, pipeline behaviors (Common/ — validators auto-registered from this assembly)
+│   ├── Baya.Domain          Entities (User, Role, UserSession, RoleNames…, Identity/ (NurseProfile, CustomerProfile, Patient, NurseBankAccount, CustomerAddress), Geography/ (Province, City, District, NurseServiceArea), + Configuration/Audit/Analytics/Holidays/Notifications/SupportAlerts), BaseEntity, IEntity, ITimeModification, IAuditableEntity, IAuditable (audit-row marker)
+│   └── Baya.Application     Features/ (Commands & Queries; Identity area = auth + profiles/patients/nurse-bank-accounts; Geography/ServiceAreas/Addresses areas = geo hierarchy + nurse service areas + customer addresses; + Configuration/Audit/Analytics/Holidays/Notifications/SupportAlerts areas), Contracts/ (incl. Contracts/Common cross-cutting seams incl. IBankAccountOwnershipVerifier + IGeocoder + the platform-signal facade contracts + Contracts/Persistence per-domain repositories on IUnitOfWork), Models/, pipeline behaviors (Common/ — validators auto-registered from this assembly)
 ├── Infrastructure/
 │   ├── Baya.Infrastructure.Persistence     ApplicationDbContext (+ encrypted-PII value converters & phone-hash sync), ValueConversion/, Repositories/, Configuration/ (per-area EF config), Migrations/, Interceptors/ (AuditFieldInterceptor — audit-fields + audit-log rows), Services/ (DB-backed platform-signal facades + notification-retention hosted service)
 │   ├── Baya.Infrastructure.Identity        Jwt/, Identity/ (Managers, Stores, PermissionManager, Seed, CurrentUser/)
 │   ├── Baya.Infrastructure.CrossCutting    Serilog wiring + Seams/ (mock impls of the cross-cutting seams incl. LoggingSmsSender + MockBankAccountOwnershipVerifier) + AddCrossCuttingSeams
 │   └── Baya.Infrastructure.Monitoring      HealthChecks, OpenTelemetry, prometheus-net
 ├── API/
-│   ├── Baya.Web.Api         Program.cs, Controllers/V1/ (Ping + Auth/Me phone-OTP surface + admin PlatformConfig/Holidays/Audit/SupportAlerts + current-user Notifications), appsettings*.json
+│   ├── Baya.Web.Api         Program.cs, Controllers/V1/ (Ping + Auth/Me phone-OTP surface + admin PlatformConfig/Holidays/Audit/SupportAlerts + current-user Notifications + public Geo + admin AdminGeo + nurse NurseServiceAreas + customer CustomerAddresses), appsettings*.json
 │   ├── Baya.WebFramework    BaseController (incl. 401/403 OperationResult mapping), Filters/, Middlewares/, Swagger/, Routing/, ServiceConfiguration/ (rate limiting)
 │   └── Plugins/Baya.Web.Plugins.Grpc   gRPC services + .proto models (User only)
 ├── Shared/Baya.SharedKernel   Extensions + validation base
@@ -106,7 +106,7 @@ Application reference Infrastructure or the API — this is a hard rule.
 
 **Cross-cutting seams.** Application defines mock-able external dependencies as interfaces in
 `Contracts/Common/` (`IDateTimeProvider`, `IFieldEncryptor`, `ICacheService`, `IObjectStorage`,
-`INotificationDispatcher`, plus `ICurrentUser`). Their in-memory/local mock implementations live in
+`INotificationDispatcher`, `IGeocoder`, plus `ICurrentUser`). Their in-memory/local mock implementations live in
 `Baya.Infrastructure.CrossCutting/Seams/` and are registered by `AddCrossCuttingSeams(configuration)`
 (config section `Seams`); `ICurrentUser` is registered in the Identity layer. Swapping a mock for a
 real provider is a registration change — handlers depend only on the contract. Audit fields are
@@ -144,6 +144,30 @@ every `AbstractValidator<T>` in the Application assembly as `IValidator<T>` so t
 `ValidateCommandBehavior` (and the `ModelStateValidationAttribute` controller filter) actually run —
 route-supplied ids (e.g. `patients/update/{id}`) must therefore **not** be validated in the body command.
 
+**Geography, addresses & nurse service areas (backend-phase-4).** A new **`geo` schema** holds the
+`Provinces` 1:N `Cities` 1:N `Districts` reference hierarchy (tables, not code lists — new regions launch
+by admin insert; `is_active`/`sort_order` drive ordered, toggleable dropdowns) plus `NurseServiceAreas`
+(where a nurse travels). `usr.CustomerAddresses` (identity-domain) holds saved service locations. Seeded
+via `HasData` (b1 path): 31 provinces + their capital cities (covers the white-space targets) + Tehran's 22
+مناطق. Features under `Baya.Application/Features/{Geography|ServiceAreas|Addresses}/`; configs in
+`Persistence/Configuration/{GeographyConfig|IdentityConfig}/`; per-domain repos (`IGeoRepository`,
+`INurseServiceAreaRepository`, `ICustomerAddressRepository`) on `IUnitOfWork`. Load-bearing rules:
+- **`district_id = NULL` means "entire city"** — a real coverage choice, not missing data. Whole-city
+  uniqueness is enforced with a **filtered-index pair** (`UNIQUE(nurse_id, city_id) WHERE district_id IS
+  NULL …` + `UNIQUE(nurse_id, city_id, district_id) WHERE district_id IS NOT NULL …`, both `AND deleted_at
+  IS NULL`), because SQL Server treats NULLs as distinct. A duplicate area returns **409** (`OperationResult.ConflictResult` → new `IsConflict` → `BaseController` 409 mapping).
+- **Coverage is named districts, not GPS radii.** Address lat/lng exists only for the later EVV distance
+  check (b9); it is never used for coverage matching.
+- **Single primary address** per customer via filtered `UNIQUE(customer_id) WHERE is_primary=1 AND
+  deleted_at IS NULL` + clear-then-set in one transaction; the first address is primary by default.
+- **Address PII** (`address_line`, `postal_code`, recipient name/phone) is encrypted at rest through
+  `IFieldEncryptor` (converters in `ApplicationDbContext`); decrypted only in the owner's own read.
+- **`IGeocoder`** (new seam, `Contracts/Common`; mock `MockGeocoder` in CrossCutting, config
+  `Seams:Geocoding`) turns a typed address into deterministic `decimal` coordinates with no network call;
+  a config switch / `NO_GEO` marker forces the null-coordinate path.
+- **Reference reads are cached** through `ICacheService` behind a generation-token key scheme (`GeoCache`);
+  any admin geo write bumps the token, invalidating the whole geo cache namespace at once.
+
 **Keeping the Project map current.** When a change touches the architecture — adds, removes, or
 renames a project/assembly, a Clean-Architecture layer, or a major folder, or changes a cross-layer
 dependency — you **must** update this Project map (and the dependency rule above, if affected) in the