hamid
65 lines
3.5 KiB
Markdown
65 lines
3.5 KiB
Markdown
# geography — provinces, cities, districts
|
|
|
|
> Client seam `client/src/services/geography/` · `USE_GEOGRAPHY_MOCK = false` (**real**) · 13 server ops
|
|
> Last verified: 2026-07-30 against commit `d3ec723` and swagger.v1.json (2026-07-29).
|
|
|
|
The reference hierarchy every address, service area and search filter is keyed on. Also the home of the
|
|
single most load-bearing null in the schema.
|
|
|
|
## Endpoints
|
|
|
|
| Method | Path | Auth | Verdict |
|
|
| --- | --- | --- | --- |
|
|
| GET | `/api/v1/geo/provinces` | **anonymous** | wired |
|
|
| GET | `/api/v1/geo/cities` | **anonymous** | wired |
|
|
| GET | `/api/v1/geo/districts` | **anonymous** | wired |
|
|
| GET | `/api/v1/geo/tree` | **anonymous** | **unwired** — the client fetches the three levels separately and caches each |
|
|
| POST | `/api/v1/admin_geo/create_province` | admin | **unwired** — no console screen |
|
|
| POST | `/api/v1/admin_geo/update_province/{id}` | admin | **unwired** |
|
|
| POST | `/api/v1/admin_geo/set_province_active/{id}` | admin | **unwired** |
|
|
| POST | `/api/v1/admin_geo/create_city` | admin | **unwired** |
|
|
| POST | `/api/v1/admin_geo/update_city/{id}` | admin | **unwired** |
|
|
| POST | `/api/v1/admin_geo/set_city_active/{id}` | admin | **unwired** |
|
|
| POST | `/api/v1/admin_geo/create_district` | admin | **unwired** |
|
|
| POST | `/api/v1/admin_geo/update_district/{id}` | admin | **unwired** |
|
|
| POST | `/api/v1/admin_geo/set_district_active/{id}` | admin | **unwired** |
|
|
|
|
No phantoms. The nine `admin_geo` routes are `DynamicPermission` + `sensitive`; geography is seeded, so
|
|
there is no console editor. Mutations are **action-style** (`admin_geo/create_city`, never
|
|
`admin_geo/cities`).
|
|
|
|
## `districtId = null` means whole-city
|
|
|
|
This is the one rule to get right, and it reads in **both** directions:
|
|
|
|
- **On a nurse service area** (see [service-areas.md](service-areas.md)), `districtId = null` means the
|
|
nurse covers the **entire city**, not "no district".
|
|
- **On a search query**, a customer in district *D* must match both a nurse whose area names *D* and a
|
|
nurse whose area is whole-city. See [search.md](search.md).
|
|
- **On an address** it is genuinely optional metadata — a missing district does not widen anything.
|
|
|
|
Never coerce the null to 0 or to a sentinel id, and never write a query that drops whole-city rows.
|
|
|
|
## Shape rules the JSON does not express
|
|
|
|
- Every level returns **both** `nameFa` and `nameEn`; the client picks by locale.
|
|
- `isActive` filters the pickers. An inactive city must stay **resolvable** — an existing address or
|
|
booking references it — so it is filtered from selection, never deleted.
|
|
- **Two Neshan keys exist and they are different products.** The server's geocoder key is
|
|
`Seams:Geocoding:ApiKey` (server-side address→point); the client's map key is
|
|
`NEXT_PUBLIC_NESHAN_KEY` (a *web* key for the embeddable map/search). Never share one value between
|
|
them. With the client key unset, `AddressMapPicker` falls back to a bounded-canvas grid, which is why
|
|
dev, CI and jsdom all work without it. See [../config-matrix.md](../config-matrix.md).
|
|
- Geocoding is a seam: `Seams:Geocoding:Provider` = `mock` (default) or `neshan`. The mock resolves a
|
|
deterministic point near the city centroid; an address containing `NO_GEO` resolves to null coordinates
|
|
so the "saved without a map pin" state is testable per-request.
|
|
|
|
## Enums
|
|
|
|
None. All three levels are integer ids with localised names.
|
|
|
|
## Open REQs
|
|
|
|
None. REQ-008 (accept the client-picked pin) and REQ-009 (`provinceId` on the address DTO) were delivered
|
|
and are documented in [addresses.md](addresses.md).
|