# HMS outpatient visit prototype

Branch: feature/compact-ui-visit-workflow

## Visit lifecycle

1. Receptionist registers a patient (internal reference generated; not entered on UI).
2. Receptionist books a direct GP or specialist appointment with a practitioner assigned to the facility. The appointment records the booking staff member.
3. Receptionist checks the patient in. Check-in user/time is recorded.
4. Nurse records appointment-specific vital signs.
5. The scheduled physician opens a consultation. Patient and facility are inherited from the appointment and vital observations must exist before a routine consultation can start.
6. Physician records history, assessment, plan and lifestyle advice.
7. Physician requests laboratory investigations. Lab technician records patient arrival and enters draft results against each order.
8. Physician prescribes medication with destination **external pharmacy** or **facility pharmacy** (the latter is a request, not availability confirmation); the prescription and lifestyle advice can be printed.
9. Physician can refer to a specialist. Reception may schedule the referral as a new appointment or book a specialist directly without a referral.
10. Completing the consultation completes the linked appointment.
11. The visit page shows date/time, receptionist/check-in staff, nurse and measurements, practitioner, findings, lab requests/results, referral and prescriptions. Receptionists and managers see only administrative visit metadata, not the clinical record.

## Role model

- Platform administrator: organization provisioning and controlled organization selector.
- Organization manager: facilities, departments, staff and organization administration; **no organization selector** and no clinical authoring rights.
- Receptionist: patient registration, appointment booking and check-in.
- Nurse: triage/vital signs entry.
- Physician: consultations, labs and prescriptions, GP or specialty recorded on practitioner profile, referrals.
- Laboratory technician: arrival and draft results for requested tests.
- Pharmacist: internal pharmacy worklist. Dispense button remains demo-only.
- Other staff: limited registration/profile access pending more granular privileges.

The prototype has a primary facility assignment per user (nullable for legacy accounts). A future staff-facility many-to-many model will be needed for clinicians working in multiple facilities.

## Incomplete or intentionally deferred

- No patient self-service mobile/web appointment booking yet. Patients can **request direct specialist appointments through reception** without a GP referral.
- No doctor scheduling conflict detection, duty rosters or clinical credential verification.
- No laboratory result approval, specimen lifecycle or safe clinical report release.
- No stock catalog, availability checks, contraindication checking or real pharmacy fulfillment reconciliation.
- No signature/immutable clinical note amendments, verified audit integrity or emergency fast-track bypass.
- No external email delivery until MAIL_MAILER is configured.
- The login has a bundled hospital-themed SVG illustration; it can be replaced with a licensed high-resolution hospital photograph.
- Laravel and test execution have not been verified in this repository's environment. Use synthetic data only.

## Commands

After pulling the branch and completing Laravel bootstrap:

```bash
php artisan migrate
php artisan test --filter=Hms
php artisan serve
```

To test new staff roles **locally without SMTP**:

```bash
php artisan hms:set-local-staff-password clinician@example.test
```

This command prompts for a password and refuses to operate outside local/testing environments. Never run the prototype with real patient records.