# Patient Journey Tracking

## Purpose

The optional `patient_journey_tracking` module lets authorized staff follow appointment, examination, and reporting progress. Staff with approval permission can issue time-limited public access to a patient, guardian, representative, or primary team member.

## Enable or disable

Open **Administration > Settings > Modules** and enable **Patient journey tracking**. The module is disabled by default. Disabling it immediately hides navigation and returns `404` for both staff and public tracking routes without deleting grants or audit history.

## Staff workflow

1. Open **Patient Journey** from the sidebar.
2. Search for the patient or accession number.
3. Select the patient's examinations and approved recipient.
4. Record the approval reason and validity period.
5. Enable final-report/PDF sharing only when clinically and legally approved.
6. Copy the generated reference and access code immediately. Only the code hash is stored, so the code cannot be recovered later.
7. Revoke a grant immediately when access is no longer appropriate.

## Public workflow

The approved recipient opens `/track` and enters the reference, access code, and patient date of birth. A verified session lasts 20 minutes. Five failed attempts lock the grant for 15 minutes.

Public views expose operational milestones only. Preliminary or draft diagnostic content is never displayed. A finalized report is available only when report access was explicitly approved for both the grant and examination; PDF access requires its own approval.

## Permissions

- `view_patient_tracking`: view authorized internal journeys.
- `manage_tracking_grants`: view all grants and patient journeys.
- `approve_public_tracking`: issue access grants.
- `revoke_tracking_access`: revoke active grants.
- `view_tracking_audit`: reserved for audit review access.
- `share_final_reports`: approve finalized report and PDF sharing.

All verification, viewing, download, creation, and revocation activity is written to append-only tracking access events.
