create mvp path

2026-08-02 20:01:31 +03:30
parent 72ab290da1
commit fb58ca54e1
203 changed files with 863 additions and 156 deletions
@@ -0,0 +1,52 @@
+# patients — the care circle
+
+> Client seam `client/src/services/patients/` · `USE_PATIENTS_MOCK = false` (**real**) · 5 server ops
+> Last verified: 2026-07-30 against commit `d3ec723` and swagger.v1.json (2026-07-29).
+
+The people a customer books care *for* — «حلقهٔ مراقبت» in the UI. A patient is owned by the customer who
+created them, never by a nurse. Clinical content about a patient lives in
+[patient-records.md](patient-records.md).
+
+## Endpoints
+
+| Method | Path | Verdict |
+| --- | --- | --- |
+| GET | `/api/v1/patients/list` | wired · paginated (`Page`/`PageSize`) |
+| GET | `/api/v1/patients/get/{id}` | wired |
+| POST | `/api/v1/patients/create` | wired |
+| POST | `/api/v1/patients/update/{id}` | wired |
+| POST | `/api/v1/patients/archive/{id}` | wired — **archive, not delete** |
+
+All `[Authorize]`. No phantoms. The domain maps 1:1.
+
+## Shape rules the JSON does not express
+
+- **`relation` and `conditions` are on `PatientDto`** (REQ-005, delivered). `relation` is the family
+  relationship shown on the record sheet; `conditions` is the coarse condition list used for triage.
+- **`gender` is load-bearing.** It drives same-gender caregiver matching, which is a near-hard requirement
+  in this market. Never defaulted, never dropped, never inferred from a name.
+- **`initialMedicalNotes` is encrypted at rest** and readable only by the owning customer (and, post-
+  confirmation, the assigned nurse via the booking's care-instructions read — see
+  [bookings.md](bookings.md)). It is not the care record.
+- **Archive, never delete.** A patient referenced by a booking must stay resolvable; `isActive = false`
+  removes them from pickers. There is no delete endpoint and there should not be.
+- **`displayName` is server-composed** from first/last name. The client renders `displayName` and uses the
+  parts only in the edit form — so a naming-convention change is a server change, not a client one.
+- `birthDate` is a date; the client derives the age band (`age.ts`) for display. The **server** stamps
+  `patientAge` on the nurse-facing booking-request list row (see
+  [booking-requests.md](booking-requests.md)) — the nurse never receives a birth date.
+
+## Enums
+
+| Vocabulary | Values |
+| --- | --- |
+| `Gender` | `male` `female` |
+
+`bloodType` is a free string, not an enum.
+
+## Open REQs
+
+| REQ | Status | Effect |
+| --- | --- | --- |
+| REQ-057 | open | `PatientDto` has no `lastVisitAt` (or `visitCount`), and `BookingListItemDto` has no `patientId`, so the booking card can render no care teaser. Either field unblocks it |
+| REQ-058 | deferred, non-blocking | No patient photo upload. `PatientDto` has no `avatarUrl` and no UI reads one — `InitialsAvatar` ships either way |