# Flow: Structured Clinical Documentation

**Actors**: Doctor (any specialty, including a nutritionist)
**Phase**: 6 (core) + 7 (specialty tabs)

## Recording an encounter

1. Doctor opens a booking or an ad-hoc follow-up from `Doctor\ScheduleController::index()` /
   `Doctor\PatientController::show()` → `Doctor\VisitController::show($booking)` (extended, not
   replaced — see `09-roadmap-phase6-13.md` Phase 6).
2. `EncounterService::start($booking, $doctor)` creates a `draft` `Encounter` row, linking
   `booking_id` when present.
3. Doctor fills chief complaint / history / examination / assessment / plan, and the vitals block
   (weight, height → BMI auto-computed client-side and server-validated, waist, BP, pulse,
   temperature, glucose spot-check) → `EncounterService::saveVitals()` upserts the `Vital` row.
4. Doctor adds one or more `Diagnosis` rows from the assessment (free text or ICD-10 code, status
   active/resolved/chronic) → `EncounterService::addDiagnosis()`.
5. If relevant to the visit, doctor opens the conditional specialty tab(s) added in Phase 7:
   - **Diabetes Screening** tab → `DiabetesScreening` row (retinopathy/nephropathy/neuropathy/foot
     checklist, next-due date).
   - **Bariatric Assessment** tab → `BariatricAssessment` row (comorbidities checklist, psych
     eval, proposed procedure, readiness).
   - **Nutrition Plan** tab (typically only for a nutritionist `Doctor`) → `NutritionPlan` row
     (calorie/macro targets, follow-up interval).
   Tabs are shown based on the doctor's own specialty or explicit selection — never forced.
6. Doctor finalizes → `EncounterService::finalize($encounter)` sets `status = 'finalized'`,
   `finalized_at = now()`. Once finalized, edits go through the same "edit after publish" audit
   rule as `04-visit-consultation-flow.md` step 7 (`ActivityLog` entry + patient notification via
   `NotificationService`).

## Reading it back

7. `Site\Clinic\MedicalRecordController` (extended) shows the patient their finalized encounters —
   narrative sections plus a simple vitals trend (weight/BMI over time, BP over time) queried
   directly from `clinic_vitals` for that patient.
8. Admin-side screens (`Admin\Clinic\PatientController::show()`) continue to show only
   non-clinical booking/administrative data — the field-level restriction from
   `03-permissions-and-roles.md` §4 / `08-permissions-and-roles-expansion.md` applies unchanged:
   diagnosis, vitals detail, and specialty-assessment content are never selected/loaded there.

## Feeds into

- Phase 8 (`09-prescription-flow.md`) — a prescription is created from a finalized-or-in-progress encounter.
- Phase 9 (`10-lab-order-flow.md`) — a lab order is created from an encounter; results feed back into the diabetes/lipid trend view referenced in step 7.
- Phase 10 (`11-surgery-scheduling-flow.md`) — a `BariatricAssessment.surgical_readiness = 'ready'` is what a surgeon checks before scheduling a case.
- Phase 11 (`12-billing-and-posting-flow.md`) — finalizing an encounter with billable content (consultation fee at minimum) is what drafts the `ClinicInvoice`.