# 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 |