doc clean up phase 2

2026-07-30 12:49:46 +03:30
parent c889c46110
commit c841bded26
36 changed files with 2970 additions and 51 deletions
@@ -0,0 +1,53 @@
+# 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).