# 08 — Visits

← [Back to index](README.md)

A visit is the clinical encounter. The app **auto-saves each section** as the doctor edits,
so every section endpoint returns the **full updated Visit**.

---

## Visit object
```json
{
  "id": "v1",
  "appointmentId": "a1",
  "patientId": "p1",
  "patientName": "محمد علي حسن",
  "doctorId": "u_123",
  "doctorName": "د. أحمد",
  "visitType": "firstVisit",
  "status": "inProgress",
  "startedAt": "2026-05-22T10:20:00Z",
  "completedAt": null,
  "vitals": {
    "weightKg": 82.5, "heightCm": 175, "temperatureC": 37.0,
    "systolicBp": 120, "diastolicBp": 80, "pulseRate": 72,
    "respiratoryRate": 16, "oxygenSaturation": 98,
    "recordedAt": "2026-05-22T10:22:00Z"
  },
  "chiefComplaint": "صداع متكرر",
  "clinicalNotes": "...",
  "diagnoses": [
    { "id": "d1", "name": "ارتفاع ضغط الدم", "icdCode": "I10", "notes": null, "isPrimary": true }
  ],
  "prescriptions": [
    { "id": "pi1", "medicationName": "كونكور 5مج", "dosage": "5mg",
      "frequency": "مرة يومياً", "durationDays": 30, "route": null, "instructions": "بعد الأكل" }
  ],
  "treatmentPlan": "راحة ومتابعة",
  "followUpDate": "2026-06-22T00:00:00Z"
}
```
- `status`: [VisitStatus](11-enums.md) (`inProgress`/`completed`/`signed`).
- `vitals.*` all nullable. `prescriptions[]` here are **visit medications** (shape =
  `PrescriptionItem`), distinct from the [Prescriptions](09-prescriptions.md) `RxItem`.

---

## Start / read
| Endpoint | Body / Query | Returns |
|---|---|---|
| `POST /visits/start-from-appointment` | `{ "appointmentId": "a1" }` | Visit (`201`/`200`) |
| `POST /visits/start-walk-in` | `{ "patientId": "p1", "patientName": "..." }` | Visit (`201`) |
| `GET /visits/{id}` | — | Visit |
| `GET /visits/active?patientId=p1` | — | Visit **or `null`** (patient's open visit) |
| `GET /patients/{patientId}/visits` | — | Visit[] (history) |

## Section auto-save (each returns the updated Visit `200`)
| Endpoint | Body |
|---|---|
| `PATCH /visits/{id}/vitals` | `{ "vitals": { ...Vitals } }` |
| `PATCH /visits/{id}/chief-complaint` | `{ "complaint": "..." }` |
| `PATCH /visits/{id}/clinical-notes` | `{ "notes": "..." }` |
| `PUT /visits/{id}/diagnoses` | `{ "diagnosis": { ...Diagnosis } }` (upsert by `id`) |
| `DELETE /visits/{id}/diagnoses/{diagnosisId}` | — |
| `PUT /visits/{id}/prescriptions` | `{ "item": { ...PrescriptionItem } }` (upsert by `id`) |
| `DELETE /visits/{id}/prescriptions/{itemId}` | — |
| `PATCH /visits/{id}/treatment-plan` | `{ "plan": "..." }` |
| `PATCH /visits/{id}/follow-up` | `{ "date": "<iso>" }` |

## Lifecycle
- `POST /visits/{id}/complete` → marks `completed`. **Response `200`** — Visit.
  > On completion the app POSTs a [prescription](09-prescriptions.md) built from
  > `prescriptions[]`. Default: app creates it; don't auto-create server-side unless we coordinate.
- `POST /visits/{id}/sign` → marks `signed` (immutable lock). **Response `200`** — Visit.

---

## Field contracts

### `Vitals` (all nullable)
`weightKg` (double), `heightCm` (double), `temperatureC` (double), `systolicBp` (int),
`diastolicBp` (int), `pulseRate` (int), `respiratoryRate` (int), `oxygenSaturation` (int),
`recordedAt` (datetime).

### `Diagnosis`
`id`, `name` (req), `icdCode?`, `notes?`, `isPrimary` (bool, default false).

### `PrescriptionItem` (visit medication)
`id`, `medicationName` (req), `dosage` (req), `frequency` (req), `durationDays` (int, req),
`route?`, `instructions?`.
> Distinct from `RxItem` — no `activeIngredient` / `quantity`. On visit-complete the app
> converts each to an `RxItem`, setting `activeIngredient = medicationName`, `quantity = null`.
