# Phase 8 — Reports, Management Work and Cross-Cutting Authorization

## Purpose

Phase 8 closes the remaining cross-cutting authorization drift identified by the system-wide RBAC implementation plan. The phase covers dashboard access, global search, financial and loan report exports, fixed-asset reports, notifications, tasks, customer appointments, management alerts, navigation/action visibility and document exports.

Branch isolation remains a separate concern from functional authorization. Every record policy introduced here combines the relevant functional permission with `BranchAccessService` rather than replacing the existing branch model.

## Canonical permission changes

Phase 8 expands the canonical permission catalog from 95 to 109 names.

### Dashboard and search

- `dashboard.view`
- `search.use`

Both surfaces were authenticated-only before this phase. Existing effective access is preserved by granting both permissions to every ordinary default system role. Super Administrator continues to use the global Gate bypass and therefore has no explicit role permissions.

### Reports

- existing `reports.view`
- new `reports.export`

Financial and loan/branch CSV export routes no longer reuse `reports.view`.

### Fixed-asset reports

- `fixed-assets.reports.view`
- `fixed-assets.reports.export`

The fixed-asset register itself continues to use `fixed-assets.view`; report viewing and export are now independently assignable.

### Tasks

The existing `tasks.manage` permission is retained as a deprecated compatibility umbrella and replaced operationally by:

- `tasks.create`
- `tasks.update`
- `tasks.assign`
- existing `tasks.update-status`

Task status changes now use `tasks.update-status`, not `tasks.view`.

The `TaskPolicy` adds branch-aware record authorization. A user with `tasks.update-status` may update a task assigned to themselves. A user who also has `tasks.assign` may update the status of any task within their accessible branch scope. Completed and cancelled tasks remain permanently closed through domain validation.

Changing a task assignee requires `tasks.assign` in addition to task editing/creation permissions.

### Customer appointments

The existing `appointments.manage` permission is retained as a deprecated compatibility umbrella and replaced by:

- `appointments.create`
- `appointments.update`
- `appointments.manage-status`

The current UI exposes appointment creation and status management. `CustomerAppointmentPolicy::manageStatus` enforces both permission and branch scope.

### Management alerts

The existing `management-alerts.manage` permission is retained as a deprecated compatibility umbrella and replaced by:

- `management-alerts.acknowledge`
- `management-alerts.resolve`
- `management-alerts.settings`

`ManagementAlertPolicy` protects record actions. Branch users may handle only branch-owned alerts in their assigned scope. Company-level alerts remain actionable only by system-wide users. Business-wide alert thresholds and collection-task automation require the separate settings permission.

### Notifications

Existing notification permissions remain unchanged:

- `notifications.view`
- `notifications.retry`
- `notifications.manage`

Phase 8 adds `ReminderNotificationLogPolicy::retry` so retry operations require both `notifications.retry` and access to the notification branch. The controller rechecks the policy before invoking delivery retry logic.

## Effective default-role migration

`DefaultRoleMatrix` remains the reviewed historical access-parity baseline used by earlier RBAC regression tests. `EffectiveRoleMatrix` composes that baseline with the reviewed Phase 8 expansions used by `AuthorizationSeeder`.

This preserves current effective access while allowing routes to move from broad names to granular permissions:

- all ordinary default roles retain dashboard/search access;
- roles with `reports.view` also receive `reports.export`, because export was previously reachable through the view permission;
- roles with `fixed-assets.view` receive fixed-asset report view/export, matching previous behavior;
- roles with `tasks.manage` receive task create/update/assign/status permissions;
- roles with `appointments.manage` receive appointment create/update/status permissions;
- roles with `management-alerts.manage` receive alert acknowledge/resolve/settings permissions.

The deprecated broad permissions remain assigned for compatibility. They are not used by the migrated Phase 8 routes.

## Route hardening

### Dashboard

`DashboardController` exposes `permission:dashboard.view` through Laravel controller middleware and rechecks `dashboard.view` through Gate inside the controller. Management dashboard financial content still additionally depends on `reports.view`.

### Global search

`global-search.index` now requires `search.use`. `GlobalSearchService` rechecks `search.use` and continues to filter result types by the underlying object permissions and accessible branches.

### Reports

Financial and loan/branch report index routes retain `reports.view`; CSV routes now require `reports.export`.

### Tasks, appointments and alerts

Sensitive record routes use staged authorization:

1. functional `permission:*` middleware;
2. record-level `can:*` policy middleware;
3. controller/domain state checks where applicable.

### Document exports

No global document permission was introduced. Document authorization derives from the underlying business object as required by the system plan.

Examples:

- loan document review, agreement and statement: `loans.view` + `can:view,loan`;
- payment receipt: `loans.view` + `can:view,payment`;
- collateral receipt/release acknowledgement: `collateral.view` + `can:view,collateral`;
- disbursement receipt: `loans.view` + `can:view,disbursement`;
- expense voucher: `expenses.view` + `can:view,expense`.

Existing controller branch checks and document-state checks remain as defense in depth.

## UI authorization

Phase 8 aligns key navigation and action surfaces with Gate/permission checks:

- dashboard navigation;
- desktop/mobile global search;
- task create/edit/status actions;
- appointment creation;
- management alert acknowledge/resolve/settings;
- notification retry;
- fixed-asset report export.

Backend authorization remains authoritative even if a UI element is manually invoked.

## Explicit self-service boundary

Personal account security remains authenticated self-service. Phase 8 does not add business permissions to password, two-factor or recovery-code actions.

`dashboard` and `global-search.index` were removed from the authenticated-exemption registry. `document-branding.asset` remains an explicit support exemption because its controller authorizes access by verifying that the user can access a branch belonging to the requested business.

## Regression coverage

`Phase8CrossSystemAuthorizationTest` verifies:

- the 109-name canonical catalog;
- deprecated broad permission replacement mappings;
- effective default-role compatibility expansion;
- task/appointment/alert/notification branch-aware policies;
- task assignee-versus-manager status behavior;
- route permission and `can:*` middleware;
- dashboard/search service/controller rechecks;
- document export policies;
- navigation/action visibility;
- removal of dashboard/search authenticated exemptions.

`AuthorizationCatalogTest` continues to preserve the Phase 2 access fingerprint for the historical `DefaultRoleMatrix`, while catalog and seeded database counts now validate all 109 permissions.

## Out of scope / next phase

Phase 8 does not remove deprecated compatibility permissions from the database or legacy role baseline. The next authorization phase should run a full source and runtime audit for remaining direct role/permission checks, UI/backend mismatches and unused compatibility umbrellas before final cleanup and hard removal decisions.
