# Scout C — Clinic (HIS) Permission + Role System + FE Write-Button Guard Coverage Read-only research. No code changed. Repos: - BE: `/home/moonui/moon-erp-be` - FE: `/home/moonui/public_html/moon-erp` (clinic features under `src/app/features/clinic`) --- ## 1. The `clinic.*` permission catalog **Single source of truth (seeder, not a DB-driven registry):** `Modules/Core/database/seeders/RolePermissionSeeder.php` - Class uses `Spatie\Permission\Models\Permission` (Spatie laravel-permission package) — confirmed `Modules/Core/database/seeders/RolePermissionSeeder.php:7`. - `run()` (`:11-27`) forgets the permission cache, seeds every permission string returned by `permissions()` via `Permission::firstOrCreate(['name'=>..., 'guard_name'=>'web'])` (`:17`), then calls `createRoles()` (`:20`). - All permission strings for the whole app (not just clinic) live in one big flat array returned by `private function permissions(): array` (`:46` onward). Clinic's block starts at `Modules/Core/database/seeders/RolePermissionSeeder.php:1054` (`// ── Clinic / HIS (Modules/Clinic) ────`) and runs to `:1149`. - **Current count: 85 `clinic.*` permission strings** (grown from an earlier ~81 baseline as L1/L3 work added `clinic.intents.*` / `clinic.results.external`). - **Grouping**: the array itself is grouped by inline `// P0`…`// P7`/`// L1` phase comments (not a formal data structure) mirroring the clinic build phases: - P0 foundation (`:1056-1070`): `clinic.patients.view`, `clinic.doctors.*`, `clinic.doctor-grades.*`, `clinic.rooms.*`, `clinic.departments.*` - P1 catalog & pricing (`:1072-1077`): `clinic.service.*`, `clinic.pricing.*`, `clinic.payer.*` - P2 order/money/split (`:1079-1091`): `clinic.orders.*`, `clinic.payments.*`, `clinic.cashier.*`, `clinic.ledger.view`, `clinic.split.*` - P3 scheduling & booking (`:1093-1107`): `clinic.schedule.*`, `clinic.closure.*`, `clinic.availability.view`, `clinic.appointment.*`, `clinic.queue.view`, `clinic.dashboard.view`, `clinic.visits.create` - P4 encounter & clinical (`:1109-1121`): `clinic.encounters.*`, `clinic.vitals.*`, `clinic.history.*`, `clinic.diagnosis.*` - P5 clinical orders (`:1123-1137`): `clinic.lab-orders.*`, `clinic.rad-procedures.*`, `clinic.rad-orders.*`, `clinic.rad-worklist.view`, `clinic.rad-reports.{enter,verify,release}`, `clinic.prescriptions.*` - P6 insurance & claims (`:1139-1141`): `clinic.coverage.compute`, `clinic.claim.{view,assemble}` - P7 reports/KPIs (`:1143-1144`): `clinic.reports.{view,export}` - L1 clinical intents (`:1146-1149`): `clinic.intents.{view,create,decide}`, `clinic.results.external` - **This grouping is independently re-derived (workflow order, not just phase order) in the runtime `groupOrder()`** contract — see §3, `Modules/Clinic/app/Support/ClinicPermissionDependencies.php:190-209` — used to order the (not-yet-built) roles UI by real clinic flow rather than alphabetically. - The generic permission-listing API endpoint groups purely by string prefix (`explode('.', $permission)[0]`), not by these phase/workflow groups — see §2, `RoleController::permissions()`. ## 2. Roles: creation, assignment, and the role-management UI **Package**: Spatie `laravel-permission`, wrapped by `Modules\Core\Models\Role` (extends Spatie's Role model — not separately inspected but referenced at `RolePermissionSeeder.php:6`). **BE — generic (cross-module) role CRUD:** - Controller: `Modules/Core/app/Http/Controllers/RoleController.php` - Routes: `Modules/Core/routes/api.php:69-70` — `GET permissions` → `RoleController::permissions`, `Route::apiResource('roles', RoleController::class)`. - Middleware gates: `core.roles.view` (index/show/permissions), `core.roles.create` (store), `core.roles.update` (update), `core.roles.delete` (destroy) — `RoleController.php:28-36`. - `index()`/`show()` list/return roles **tenant-scoped** via `RoleSaveService::visibleRolesQuery()` (GLOBAL roles + acting user's company roles) — `:49-75`. - `store()`/`update()` delegate to `Modules\Core\Services\RoleSaveService` (`:84-138`), which is the **single save path**: validates permission names, expands dependencies via the Core `PermissionDependencyRegistry` (see §3), persists `home_page` + `data_scope` (fail-closed `branch` default), all in one transaction (per the class's own doc comment, `RoleSaveService.php:19-`, `:257-280`). - `permissions()` (`:181-198`) — lists every seeded `Permission`, grouped **only by string prefix** (`explode('.', $p)[0]`) into `{key,label}` pairs. **Does NOT expose dependency map or presets** (contrast with LIS's dedicated endpoint, §3). - `destroy()` blocks deleting `PROTECTED_ROLES = ['owner','admin','manager','accountant','cashier','employee','super-admin']` (`:39`, `:154-158`) and blocks deleting a role that still has users (`:163-167`). - **How a role gets its permissions**: either (a) hand-picked via `store`/`update` `permissions` array (expanded through registered per-module dependency contributors, see §3), or (b) one of the seeder's hardcoded built-in roles below. **Seeded built-in roles** (`RolePermissionSeeder.php:1183-1350`, `createRoles()`): - `super-admin` (`:1189-1190`) — **zero permissions attached on purpose**; bypasses everything via `Gate::before` (per comment `:1185-1188`). - `owner` (`:1193-1195`) — `syncPermissions($allPermissions)` = **gets every clinic.\* permission** (and everything else). - `admin` (`:1198-1203`) — `core.*` + every `*.view` permission across all modules → gets **only the `.view` half** of clinic permissions (e.g. `clinic.patients.view`, `clinic.orders.view`, but not `clinic.orders.create`). - `manager` (`:1206-1243`) — explicit whitelist (`core.*` subset) + `accounting.*.view` + `inventory.*.view` + all `hrm.*` — **touches zero `clinic.*` permissions**. - `accountant` (`:1246-1258`) — `accounting.*` + a few `core.*` — **zero `clinic.*`**. - `cashier` (`:1261-1285`) — explicit whitelist, all POS/sales — **zero `clinic.*`** (this is the generic/POS cashier role, distinct from the clinic cashier workflow). - `employee` (`:1288-1306`) — basic HRM read access — **zero `clinic.*`**. - `hr_manager` (`:1309-1322`) — all `hrm.*` — **zero `clinic.*`**. - `lab_manager` (`:1325-1349`) — all `lis.*` + a few `core.*` + attachment perms — **zero `clinic.*`** (this is LIS's dedicated seeded role; there is **no equivalent seeded clinic role**). **Conclusion: no seeded role currently holds a partial, clinic-workflow-shaped permission set.** Only `owner` (all) and `admin` (all `.view`) touch `clinic.*` at all among the 9 seeded roles. Any clinic-specific role (reception, doctor, cashier, manager) must be hand-built today through the generic Roles UI, permission-by-permission, with no starting bundle — UNLESS the not-yet-wired presets in §3 are exposed. **FE — generic role-management UI (the permission matrix screen):** - Component: `src/app/features/roles/roles.component.ts` (620 lines) + `roles.component.html`. - Route: `src/app/app.routes.ts:77` — `path: 'roles'`, `data: { permissions: ['core.roles'] }`, lazy-loads `RolesComponent`. (Full path is under `/core/...` per the app's routing convention noted in CLAUDE.md, i.e. `/core/roles`.) - Fetches roles from `${environment.apiUrl}/core/roles` and permissions from `${environment.apiUrl}/core/permissions` (`roles.component.ts:69-70`). - Renders permission groups in an Accordion, one panel per prefix-group returned by the BE (`loadPermissions()`, `:214-228`). - **`permGroupToModule` map** (`:208-212`) used to hide a permission group if its owning system-module is deactivated: `accounting, sales, purchases, inventory, hrm, lis, pos, production, crm, cmms, qms, core` — **`clinic` is absent from this map**. Effect: `filteredPermissionGroups()` (`:104-121`) treats an unmapped group as `!modId → true`, so the `clinic` permission group is **always shown regardless of whether the Clinic system-module is enabled/disabled** — likely a (minor, cosmetic) gap, not a security issue since BE still gates by permission. - **No preset/dependency-auto-select UI exists in this component** — confirmed by `grep -n "preset|dependencies" roles.component.ts roles.component.html` → zero hits. Ticking a clinic permission here does not auto-tick its prerequisites in the UI (though the BE save path still silently expands them server-side per §3). ## 3. Role PRESETS **They exist in Clinic backend code already, but are NOT wired to any endpoint or FE screen — dead/unused for clinic today.** - **Registry contract**: `Modules/Core/app/Support/PermissionDependencyRegistry.php` — a module registers a "contributor" class per permission prefix at boot (`register(string $prefix, string $contributorClass)`, `:25-28`). Contract methods (doc comment `:10-17`): `expand()`, `mapFor()`, `presets()`, `groupOrder()`. - **Clinic's contributor**: `Modules/Clinic/app/Support/ClinicPermissionDependencies.php`, registered at `Modules/Clinic/app/Providers/ClinicServiceProvider.php:27` (`PermissionDependencyRegistry::register('clinic', ClinicPermissionDependencies::class)`). - `EDGES` const (`:21-86`) — explicit cross-resource prerequisite graph (e.g. `clinic.orders.create` needs `clinic.orders.view` + `clinic.patients.view` + `clinic.service.view` + `clinic.pricing.view`, `:37`). - `expand()` (`:95-119`) — transitive closure over EDGES + a generic rule (any non-`.view` action needs the matching `.view`, `:130-134`). **This IS live** — `RoleSaveService` calls `PermissionDependencyRegistry::expand('clinic', ...)` for every registered prefix on every role save (`RoleSaveService.php:262-277`), so hand-picked clinic permissions on the generic Roles screen (§2) DO get silently expanded server-side even though the FE never shows this. - `mapFor()` (`:146-157`) — permission → direct deps map, meant to drive FE auto-select ticking. - **`presets()` (`:165-181`)** — 3 ready-made role bundles already defined: - `clinic_setup` (`:168-169`, "إعداد العيادة"/"Clinic Setup") — anchors: `clinic.rooms.create`, `clinic.rooms.update`, `clinic.doctor-grades.create`, `clinic.doctors.update`. - `clinic_doctor` (`:172-174`, "طبيب العيادة"/"Clinic Doctor") — anchors: `clinic.encounters.update`, `clinic.encounters.sign`, `clinic.vitals.record`, `clinic.history.record`, `clinic.diagnosis.record`, `clinic.intents.create`, `clinic.intents.view`, `clinic.prescriptions.create`, `clinic.queue.view`. - `clinic_reception` (`:177-179`, "استقبال العيادة"/"Clinic Reception") — anchors: `clinic.visits.create`, `clinic.appointment.create`, `clinic.appointment.update`, `clinic.payments.create`, `clinic.intents.view`, `clinic.intents.decide`, `clinic.queue.view`, `clinic.dashboard.view`. - `groupOrder()` (`:190-209`) — workflow-ordered resource-group list for a future roles UI. - **The gap**: there is **no `ClinicRoleController`** (`find Modules/Clinic -iname "*Role*"` → only an unrelated `Modules/Clinic/app/Enums/PartyRole.php`), and the generic `Modules/Core/app/Http/Controllers/RoleController::permissions()` (§2) does **not** call `presets()`/`mapFor()`/`groupOrder()` for any prefix — it only returns flat `{key,label}` groups. So `ClinicPermissionDependencies::presets()` is currently **unreachable from any HTTP endpoint** and the FE has nothing to render. The 3 presets above are ready-made and load-bearing-correct (mirrors the LIS pattern's structure exactly) but sit dormant. **Closest existing, fully-wired pattern to clone: LIS.** - Contributor: `Modules/LIS/app/Support/LisPermissionDependencies.php`, registered `Modules/LIS/app/Providers/LISServiceProvider.php:26`. - **Dedicated BE controller**: `Modules/LIS/app/Http/Controllers/LabRoleController.php` — a **separate, module-scoped role screen** (not the generic Core one), gated by `lis.settings.view`/`lis.settings.manage` (`:48-54`), listing only lab-confined roles (`Modules\LIS\Support\LabRoleAssignment::isAssignable`, `:82-96`). - `catalog()` (`:102-143`) is the key endpoint: returns `{groups (ordered by groupOrder()), home_pages, data_scopes, dependencies: mapFor(...), presets: presets()}` (`:115-141`) — this is exactly the shape Clinic would need to add. - `store()`/`update()` call `RoleSaveService->create()/update()` with `lisOnly: true`, meaning **only `lis.*` permissions are touched/synced**, other module grants on the same role are preserved untouched (`:145-156`, doc comment `:17-22`). - **FE**: `src/app/features/lis/roles/lis-roles.component.ts` + `.html`, routed at `/lab/roles` (`src/app/app.routes.ts:228`, also `lis-standalone.routes.ts:406-410`). - Preset chips UI: `lis-roles.component.html:66-74` (`@if (catalog()?.presets?.length)`, `@for (ps of catalog()!.presets!; ...)`). - `applyPreset(preset: LisRolePreset)` (`lis-roles.component.ts:282-289`) — ticks the preset's anchor permissions, then (implicitly, via the dependency map) expands prerequisites, and prefills `home_page` from a `PRESET_HOME` lookup (`:278`). - **To give clinic presets/dependency-auto-select a UI, the fastest path is: (a) build a `ClinicRoleController` mirroring `LabRoleController` (catalog/index/store/update, `permission:clinic.settings.*`-style gate — note clinic has no `clinic.settings.*` perm yet, would need one or reuse another gate), (b) a `clinic-roles.component.ts` mirroring `lis-roles.component.ts`/`.html`, wired to a new `/clinic/roles` (or similar) route.** All the BE dependency-graph plumbing (`ClinicPermissionDependencies`) already exists and is registered — only the controller + FE screen are missing. ## 4. FE write-button guard coverage (`*appCan` directive) **Directive**: `src/app/shared/directives/can.directive.ts` - Selector `[appCan]`, structural directive: `