refinement phase 3

dev/contracts/domains/geography-addresses.md

@@ -72,7 +72,7 @@ Every write **invalidates the geo cache**. Names required (`nameFa`/`nameEn`); `
 ### `DELETE api/v1/nurse_service_areas/remove/{id}`
 - Soft-removes the nurse's own area. `data`: `true`. `404` if not owned/absent (existence not leaked).
 
-### `GET api/v1/nurse_service_areas/list?page=&page_size=`
+### `GET api/v1/nurse_service_areas/list?page=&pageSize=`
 - The nurse's own areas, whole-city first, paginated. `data`: `PagedResult<NurseServiceAreaDto>`.
 
 ## Customer addresses — `CustomerAddressesController` (authenticated; customer-scoped in handler)
@@ -97,7 +97,7 @@ Every write **invalidates the geo cache**. Names required (`nameFa`/`nameEn`); `
 ### `DELETE api/v1/customer_addresses/delete/{id}`
 - Soft-deletes the owned address. `data`: `true`. `404` if not owned.
 
-### `GET api/v1/customer_addresses/list?page=&page_size=`
+### `GET api/v1/customer_addresses/list?page=&pageSize=`
 - The customer's own addresses, **primary first**, paginated, with PII **decrypted for the owner**. `data`:
   `PagedResult<CustomerAddressDto>`.
 
@@ -123,3 +123,13 @@ Tehran city id `101`, Tehran districts `1001…1022`; other cities have no distr
 ## Changelog
 - b4 — initial contract: public geo lookups, admin geo CRUD + set_active, nurse service areas, customer
   addresses; `IGeocoder` seam; `409` conflict added to the envelope.
+
+---
+
+## Refinement phase 3 additions (REQ-008/009)
+
+- **`CustomerAddressDto`** gains `provinceId` (joined from `cities.province_id`) so the edit form can
+  prefill the province → city cascade from a server-loaded address.
+- **`customer_addresses/create` + `update/{id}`** now accept optional `latitude`/`longitude` (both or
+  neither). When present, the user's dropped pin is stored (`geocode_source = user_pin`, preferred for the
+  EVV distance check); when absent the server geocodes as before (`geocode_source = geocoder`).