# Permission-per-Role Matrix — Metro Cashless System (MCS)

This document lists every permission in the MCS authorization catalog and shows which
roles hold it. It is generated from the single source of truth,
`app/Authorization/Permissions.php` (the `all()` catalog and `roleMap()` mapping), which
both the seeder and the provisioning migration use to configure the system.

- **Guard:** all permissions and roles are registered under the single `web` guard.
- **Legend:** ✅ = permission granted to the role · — = not granted.
- **Roles (6):** `super-admin`, `site-supervisor`, `finance`, `admin`, `cxo`, `customer`.
- **Permissions (24).**

## Matrix

| # | Permission | super-admin | site-supervisor | finance | admin | cxo | customer |
|---|------------|:-----------:|:---------------:|:-------:|:-----:|:---:|:--------:|
| 1 | access-admin-panel | ✅ | ✅ | — | — | — | — |
| 2 | view-dashboard | ✅ | ✅ | — | — | ✅ | — |
| 3 | manage-users | ✅ | ✅ | — | — | — | — |
| 4 | manage-roles | ✅ | — | — | — | — | — |
| 5 | manage-permissions | ✅ | — | — | — | — | — |
| 6 | manage-customers | ✅ | ✅ | — | — | — | — |
| 7 | manage-cards | ✅ | ✅ | — | — | — | — |
| 8 | manage-seasons | ✅ | ✅ | — | — | — | — |
| 9 | manage-deposits | ✅ | ✅ | — | — | — | — |
| 10 | manage-sites | ✅ | ✅ | — | — | — | — |
| 11 | manage-parking | ✅ | ✅ | — | — | — | — |
| 12 | view-reports | ✅ | ✅ | ✅ | — | ✅ | — |
| 13 | manage-credit-debit-note | ✅ | ✅ | — | — | — | — |
| 14 | edit-credit-debit-note | ✅ | ✅ | ✅ | — | — | — |
| 15 | delete-credit-debit-note | ✅ | ✅ | — | — | — | — |
| 16 | approve-credit-debit-note | ✅ | ✅ | ✅ | — | — | — |
| 17 | manage-requests | ✅ | ✅ | — | — | — | — |
| 18 | manage-settings | ✅ | ✅ | — | — | — | — |
| 19 | view-audit-trail | ✅ | ✅ | — | — | — | — |
| 20 | delete-payment-item | ✅ | ✅ | — | — | — | — |
| 21 | create-users | ✅ | ✅ | — | — | — | — |
| 22 | read-users | ✅ | ✅ | — | — | — | — |
| 23 | update-users | ✅ | ✅ | — | ✅ | — | — |
| 24 | delete-users | ✅ | ✅ | — | ✅ | — | — |
| | **Total granted** | **24** | **22** | **3** | **2** | **2** | **0** |

## Role summaries

- **super-admin** — Holds the entire catalog (all 24 permissions). In addition, a
  `Gate::before` bypass grants super-admin every ability at runtime, so `can()` checks
  always pass regardless of explicit assignment.
- **site-supervisor** — Full administrative access: every permission **except**
  `manage-roles` and `manage-permissions`, which remain exclusive to super-admin.
- **finance** — Credit/Debit Note approval (`approve-credit-debit-note`), note editing
  (`edit-credit-debit-note`, since the approval decision is made on the note's edit page)
  and reporting (`view-reports`). Does **not** have `access-admin-panel`; lands on the
  Credit/Debit Note area after login.
- **admin** — User update/delete only (`update-users`, `delete-users`). Does **not** have
  `access-admin-panel`.
- **cxo** — Read-oriented reporting: `view-dashboard` and `view-reports`. Does **not**
  have `access-admin-panel`, so it does not open the admin area.
- **customer** — No administrative permissions.

## Enforcement

Every permission in this matrix is now **actively enforced** at both the route and menu
level. Admin modules use a two-layer model:

1. The outer gate `permission:access-admin-panel` admits a user into the admin area.
2. Each module additionally requires its own permission (layered on top), so a user must
   hold **both** `access-admin-panel` and the module permission to reach that module.

| Module (routes) | Required permission (in addition to `access-admin-panel`) |
|---|---|
| Dashboard | `view-dashboard` |
| User management (`user.*`, `account.*`) | `manage-users` |
| Roles (`roles.*`) | `manage-roles` |
| Permissions (`permissions.*`) | `manage-permissions` |
| Customers + payments (`customer.*`, `payment.*`, `payment-item.*`) | `manage-customers` |
| Cards (`card.*`) | `manage-cards` |
| Seasons (`season.*`) | `manage-seasons` |
| Deposits (`deposit.*`) | `manage-deposits` |
| Sites (`sites.*`) | `manage-sites` |
| Parking + rates (`parking.*`, `seasonType.*`, `seasonRate.*`, `casualRate.*`, `vehicleType.*`) | `manage-parking` |
| Settings + reference data (`admin.settings.*`, `states.*`) | `manage-settings` |
| Requests (`admin.request.*`) | `manage-requests` |
| Audit trail (`activities.*`) | `view-audit-trail` |
| Reports + invoicing (`report.*`, `admin.invoices.*`) | `view-reports` |
| Credit/Debit Note create/update/delete (`adjustment.*` admin actions) | `manage-credit-debit-note` |
| Credit/Debit Note review/approval (`adjustment.show`, edit, approve) | `approve-credit-debit-note` (or site-supervisor/super-admin) |

The sidebar menu mirrors this: each menu group and sensitive submenu item is wrapped in a
matching `@can`/`@canany` directive, so users only see the modules they can actually open.
Because `site-supervisor` lacks `manage-roles`/`manage-permissions`, the "Manage Role" and
"Manage Permission" links are hidden from site supervisors (previously they were visible but
returned 403).

## Notes for reviewers

- **Super-admin-only capabilities:** `manage-roles` and `manage-permissions` are granted to
  super-admin exclusively. These gate the roles and permissions management screens.
- **Admin area entry:** `access-admin-panel` is the master gate for the admin panel
  (routes, sidebar, and the `isAdmin()` check). Only `super-admin` and `site-supervisor`
  hold it.
- **Super-admin bypass:** because of the `Gate::before` hook, super-admin effectively
  satisfies every permission check even beyond the explicit grants shown above.
- **Source of truth:** if roles or permissions change, update
  `app/Authorization/Permissions.php`; both the seeder and the migration read from it, and
  this document should be regenerated to match.

_Generated from `app/Authorization/Permissions.php`._