hamid
54 lines
2.6 KiB
Markdown
54 lines
2.6 KiB
Markdown
# service-areas — nurse coverage
|
|
|
|
> Client seam `client/src/services/serviceAreas/` · `USE_SERVICE_AREAS_MOCK = false` (**real**) · 3 server ops
|
|
> Last verified: 2026-07-30 against commit `d3ec723` and swagger.v1.json (2026-07-29).
|
|
|
|
Where a nurse will travel. Three endpoints, one rule that everything else depends on.
|
|
|
|
## Endpoints
|
|
|
|
| Method | Path | Verdict |
|
|
| --- | --- | --- |
|
|
| GET | `/api/v1/nurse_service_areas/list` | wired · paginated |
|
|
| POST | `/api/v1/nurse_service_areas/add` | wired |
|
|
| DELETE | `/api/v1/nurse_service_areas/remove/{id}` | wired |
|
|
|
|
All `[Authorize]`. No phantoms. The domain maps 1:1. There is no update — coverage is add/remove.
|
|
|
|
## `districtId = null` means whole-city
|
|
|
|
A service area is `(cityId, districtId?)`. **`districtId = null` is the affirmative claim "I cover this
|
|
entire city"** — not missing data, not "no district".
|
|
|
|
The consequences reach three other domains:
|
|
|
|
- **Search** must match a whole-city area against a district-filtered query, in both directions. A query
|
|
that drops nulls silently hides every whole-city nurse. See [search.md](search.md).
|
|
- **`is_searchable`** requires at least one area covering the queried city — coverage is one of its four
|
|
conditions. See [search.md](search.md).
|
|
- **Geography** owns the ids and the same null convention. See [geography.md](geography.md).
|
|
|
|
The client models this as a **single control**: the coverage editor offers "whole city" as a first-class
|
|
choice alongside individual districts, so a nurse can never accidentally express it as an empty district
|
|
list. Do not reintroduce a two-step "city, then optionally districts" flow — an empty selection is
|
|
ambiguous in a way `null` is not.
|
|
|
|
## Shape rules the JSON does not express
|
|
|
|
- **A duplicate area is a `409`.** Adding `(city, null)` when district rows for that city already exist —
|
|
or the reverse — is a conflict the server resolves; the client surfaces it rather than pre-checking.
|
|
- **Removing the last area for a city removes the nurse from search in that city** in the same
|
|
transaction, via `ISearchIndexMaintainer`. There is no lag and no reconciliation job.
|
|
- Coverage is independent of `isAcceptingBookings`: a nurse can keep coverage while pausing bookings, and
|
|
both are conditions of `is_searchable`.
|
|
- `list` is paginated even though the practical row count is small — the platform paginates every
|
|
unbounded list without exception.
|
|
|
|
## Enums
|
|
|
|
None. Both fields are geography ids; `districtId` is nullable and the null is meaningful.
|
|
|
|
## Open REQs
|
|
|
|
None. REQ-008/REQ-009 concern addresses, not coverage — see [addresses.md](addresses.md).
|