# 08 — Permissions & Roles Expansion (Phase 6–13)

Same enforcement mechanism as `03-permissions-and-roles.md`: **100% Spatie `laravel-permission`**,
guard `admin`, flat dot-string keys added to `database/seeders/RolePermissionSeeder.php` via
`Permission::findOrCreate($name, 'admin')`, plus matching Arabic labels in
`arabicPermissionSegments()`. Do not build on `group_name`/`Roles`/`Permissions` — those remain
vestigial/display-only, exactly as already documented.

The **field-level restriction** established in `03-permissions-and-roles.md` §4 (precise medical
detail — diagnosis, prescription, history, allergies — is for Doctor and Patient only, never
Clinic Admin/Receptionist, and not even Super Admin without explicit override) **extends
unchanged** to every new clinical table below (`clinic_encounters`, `clinic_vitals`,
`clinic_diagnoses`, the three specialty tables, `clinic_prescriptions`). Enforce it the same way:
never `select()`/`with()` those fields/relations in any `Admin\Clinic\*` controller, service, or
view.

## New permission keys — add to the same seeder block

```
clinic.encounters.view                 (Doctor guard only, per the field-level rule above)
clinic.encounters.manage                (Doctor guard only — create/edit)
clinic.vitals.manage                    (Doctor guard, or a future nurse role — see note)
clinic.diagnoses.manage                 (Doctor guard only)
clinic.specialty_records.view           (Doctor guard only — diabetes screening / bariatric assessment / nutrition plan, read)
clinic.specialty_records.manage         (Doctor guard only — same, write)
clinic.prescriptions.view               (Doctor + Patient — patient reads their own via Site\Clinic)
clinic.prescriptions.manage             (Doctor guard only)
clinic.medications.view                 (admin — drug catalog is not sensitive, Clinic Admin can view for reference)
clinic.medications.manage               (Super Admin/Clinic Admin — maintain the drug catalog)
clinic.lab_catalog.manage               (Super Admin — maintain the test catalog)
clinic.lab_orders.view                  (Doctor guard only)
clinic.lab_orders.manage                (Doctor guard only)
clinic.lab_results.view                 (Doctor + Patient)
clinic.lab_results.manage               (Doctor guard only — result entry)
clinic.surgery.view
clinic.surgery.schedule
clinic.surgery.manage                   (edit case, record pre-op assessment — Doctor/surgeon scope)
clinic.invoices.view
clinic.invoices.create
clinic.invoices.post                    (triggers the Finance posting — restrict tightly, mirrors how Sales gates invoice posting)
clinic.reports.diabetes_control.view
clinic.reports.bariatric_outcomes.view
clinic.reports.surgery_volume.view
clinic.reports.revenue_by_specialty.view
```

> **Note on a future "nurse" role**: this expansion does not introduce a new guard/role for
> nurses — `clinic.vitals.manage` is granted to the `Doctor` guard for now (a doctor or the doctor
> account itself records vitals). If clinical staffing later needs a lighter "record vitals only"
> account, that's a new role decision to make explicitly with the user first, following the same
> pattern used for Clinic Admin/Receptionist in `03-permissions-and-roles.md` — not assumed here.

## Role assignments — additions to existing `givePermissionTo()` calls

`Super Admin` gets the full new `clinic.*` set added, same as every other module, **except**
`clinic.encounters.view` / `clinic.prescriptions.manage` / `clinic.diagnoses.manage` /
`clinic.specialty_records.*` / `clinic.lab_results.manage` / `clinic.vitals.manage` — these stay
excluded from Super Admin by default per the existing field-level medical-privacy rule, exactly as
`clinic.medical_records.view` already is.

`Clinic Admin` and `Receptionist` (existing roles) get only the **operational, non-clinical**
subset added to their existing lists:

```php
// Clinic Admin — additions
'clinic.medications.view', 'clinic.medications.manage',
'clinic.lab_catalog.manage',
'clinic.surgery.view', 'clinic.surgery.schedule',
'clinic.invoices.view', 'clinic.invoices.create', 'clinic.invoices.post',
'clinic.reports.diabetes_control.view', 'clinic.reports.bariatric_outcomes.view',
'clinic.reports.surgery_volume.view', 'clinic.reports.revenue_by_specialty.view',

// Receptionist — additions
'clinic.invoices.view', 'clinic.invoices.create',
'clinic.surgery.view',
```

No new role is created for the `doctor` guard's own permission set — the `Doctor` model uses its
own guard, not Spatie roles today (per `00-overview.md`'s guard summary); access within the doctor
portal is enforced by the existing `auth:doctor` + `doctor.active` middleware and
ownership checks (a doctor only ever sees their own patients' encounters/prescriptions/lab
orders), not by a Spatie permission list. This expansion doesn't change that model — it only adds
new controllers under `app/Http/Controllers/Doctor/` that follow the same ownership-check pattern
`Doctor\VisitController` already uses.

## Branch scoping — unchanged, extends automatically

The `BelongsToClinicBranch` trait / `ClinicBranchScope` (see `03-permissions-and-roles.md` §Branch
scoping) is applied to any new branch-owned model the same way it's applied to `Booking`/`Offer`
today. `clinic_invoices`, `clinic_surgery_cases`, and `clinic_lab_orders` all carry a `branch_id`
(directly or via their linked `Booking`/`Encounter`) and get the same scope — a Clinic Admin only
ever sees invoices/surgeries/lab orders for their own branch, Super Admin sees all.