baya-monorepo/archive/docs/integration/domains/patients.md

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.

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). 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) — 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