baya-monorepo/dev/shared-working-context/reports/backend-phase-4-report.md

Backend phase 4 report — Geography, addresses & nurse service areas

What was built

• New geo schema + 5 tables (one migration GeographyAddressesServiceAreas): Provinces 1:N Cities 1:N Districts (reference hierarchy), NurseServiceAreas (nurse coverage), and usr.CustomerAddresses (identity-domain saved locations). Each has an IEntityTypeConfiguration<T>, a deleted_at IS NULL soft-delete filter, and audit-field wiring via the b0 interceptor.
• Idempotent seed (b1 HasData path): all 31 Iranian provinces (Tehran first, deterministic sort_order), each province's capital city (covers the product's white-space targets — Tehran, Karaj, Mashhad, Isfahan, Shiraz, Tabriz, Ahvaz, Qom), and Tehran's 22 municipal مناطق. Fixed ids (city = 100 + provinceId; Tehran city 101; Tehran districts 1001…1022).
• 20 CQRS slices across 4 controllers:
  • GeoController (public): provinces, cities?province_id=, districts?city_id=, tree — projected, cached, active-only with parent-active honoured.
  • AdminGeoController (dynamic-permission): create/update/set_active for province/city/district; every write invalidates the geo cache.
  • NurseServiceAreasController (nurse): add (whole-city or city+district), remove/{id}, list.
  • CustomerAddressesController (customer): create, update/{id}, set_primary/{id}, delete/{id}, list.
• New IGeocoder seam (Application Contracts/Common; MockGeocoder in CrossCutting; DI in AddCrossCuttingSeams; config Seams:Geocoding). Address create/update sets coordinates from it.
• 409 Conflict added to the result envelope (OperationResult.ConflictResult / IsConflict / BaseController → 409) — used for duplicate service areas.
• Per-domain repositories (IGeoRepository, INurseServiceAreaRepository, ICustomerAddressRepository) on IUnitOfWork; encrypted value converters for the address PII columns.

What is now testable and exactly how (per phase §7)

1. Seed — GET api/v1/geo/provinces → 31 (Tehran first); …/geo/cities?province_id=1 includes Tehran (city 101); …/geo/districts?city_id=101 → 22; …/geo/districts?city_id=105 (Mashhad) → empty.
2. Cascading dropdown / tree — the three lazy lookups or GET api/v1/geo/tree (one payload).
3. Admin toggle — POST api/v1/admin_geo/set_city_active/{id} {isActive:false} → the city disappears from geo/cities; {isActive:true} → it returns (not deleted).
4. Nurse whole-city area — POST api/v1/nurse_service_areas/add {cityId:101} → isWholeCity:true.
5. Duplicate rejected — repeat the same add → 409; add {cityId:101, districtId:1001} → ok; repeat → 409.
6. Geocoded address — POST api/v1/customer_addresses/create {..., isPrimary:true} → latitude/ longitude populated; list shows it primary-first with the address decrypted for the owner.
7. Single primary — a second isPrimary:true create (or set_primary/{id}) clears the previous; exactly one isPrimary row remains.
8. PII not leaked — address_line/postal_code/recipient fields are encrypted at rest; only the owner's own read decrypts them.

Covered by tests: +16 Baya.Test.Api integration (Geo/AdminGeo/NurseServiceAreas/CustomerAddresses — happy path, 401, validation 400, 409 duplicate, single-primary, geocode, is_active hide/show) and +12 handler unit tests (NSubstitute — duplicate→conflict, geocode wiring, single-primary clear, tenancy 404, role checks). Full suite: 103 pass, dotnet build Baya.sln with 0 new code warnings.

Decisions fixed here (recorded in product docs / CLAUDE.md)

• Whole-city (district_id NULL) uniqueness = a filtered-index pair (not a plain unique index, which SQL Server would let duplicate NULLs through). Both filters also exclude soft-deleted rows so a removed area can be re-declared.
• district_id NULL is a meaningful "entire city" coverage value, never "unset".
• Named districts, not GPS radii — address lat/lng is only for the later EVV distance check.
• Single-primary address = filtered unique index + clear-then-set in one transaction; first address is primary by default.
• Address PII columns (address_line, postal_code, recipient_name, recipient_phone) encrypted through IFieldEncryptor.
• Action-style routes kept (over the phase's resource-style sketch) for codebase + dynamic-permission consistency.

Mocked + how to make it real

• IGeocoder → 🟡. MockGeocoder = deterministic point around the city centroid (FNV-1a jitter), no network. Config Seams:Geocoding:{ReturnNullCoordinates, LowConfidenceMarker, ResolvedConfidence}; the NO_GEO marker or the switch forces null coordinates. Make it real: add a Neshan (or Google) geocoding client package, add Seams:Geocoding:{ApiKey,BaseUrl}, implement IGeocoder.GeocodeAsync mapping the vendor response to (lat, lng, formatted_address, confidence) (decimal coords), add rate-limit/retry, swap the registration in AddCrossCuttingSeams — handlers unchanged; test a known Tehran address resolves within expected bounds.

Contract produced

dev/contracts/domains/geography-addresses.md + refreshed dev/contracts/openapi/swagger.v1.json (20 new paths). This is what f3-b4 consumes.

Follow-ups for later phases

• b7: wire the nurse_search_index fan-out into the (already-isolated) service-area add/remove trigger points.
• b9: the EVV distance check that consumes customer_addresses.latitude/longitude.
• Region bulk-import feed (IGeoDataImporter): deferred; the idempotent seed + admin CRUD suffices for MVP.