# Settings + Admin Recovery Audit

**Date:** 2026-05-18 (final pass)  
**Scope:** Settings context, audit logging, admin CRUD APIs/UI (companies, categories/subcategories, roles, ticket meta, notification templates)  
**Outcome:** Admin/Settings domain brought to **production-ready for UAT** with real APIs, policies, services, tests, and frontend integration.

---

## Executive summary

| Metric | Before recovery | After final pass |
|--------|-----------------|------------------|
| Production readiness (admin domain) | **Not ready** — fake/read-only admin surfaces | **UAT-ready** — real APIs + CRUD UI for core entities |
| Overall app readiness (estimate) | 64/100 → 82/100 | **91/100** |
| PHP tests | 75 → 82 | **98** |
| Frontend unit tests | 56 | **58** |

**UAT verdict:** Proceed with staged UAT for super-admin and company/department admin flows.  
**Production verdict:** **Conditional go** — core admin/settings paths are implemented and tested; E2E Playwright in CI and permission-gated sidebar visibility remain recommended before wide production rollout.

---

## What was fixed (this pass)

### Phase A — Settings department context
- Added `SettingsContextResolver` and `SettingsContextException`.
- `SettingsController` reads `department_id` only from **query** or **`X-Department-Id`** header (not request attributes set by `DepartmentIsolation` middleware).
- Multi-department users get **422** when scope is ambiguous; super-admin may pass explicit `department_id`.
- Frontend `settingsService` / `useSettings` / `SettingsPage` pass `department_id` and show department picker when user has multiple departments.
- Tests: `tests/Feature/Settings/SettingsContextTest.php`.

### Phase B — Audit logging for admin models
- `Auditable` trait on: Company, Department, User, Category, Subcategory, SlaPolicy, Setting, TicketStatus, TicketPriority.
- `Setting` excludes sensitive `value` from audit payload.
- Observers registered in `AuditServiceProvider`.
- Tests: `tests/Feature/Audit/AdminModelAuditTest.php`.

### Phase C — Companies admin UI
- Route: `/admin/companies`
- Uses `GET/POST/PATCH/DELETE /api/v1/companies`
- Super-admin gated UI with create/edit/delete, search, EN/AR, loading/error/empty states.
- Tests: `AdminCompaniesPage.test.tsx`, existing `CompanyAdminApiTest.php`.

### Phase D — Subcategory UI
- `AdminCategoriesPage`: list, create, edit, delete subcategories per category; SLA policy select; sort order; EN/AR.
- Uses `categoryAdminService` (`createSubcategory`, `updateSubcategory`, `deleteSubcategory`).

### Phase E — Roles & permissions
- APIs: `GET /roles`, `GET /permissions`, `GET /roles/{id}`, `PUT /roles/{id}/permissions` (Spatie).
- `RoleAdminService` blocks removing last super-admin from `super_admin` role.
- UI: `/admin/roles` permission matrix grouped by module prefix; dangerous-permission warnings.
- Tests: `tests/Feature/Admin/RoleAdminApiTest.php`.

### Phase F — Ticket statuses & priorities
- APIs: `apiResource ticket-statuses`, `ticket-priorities` (department-scoped).
- Delete blocked when tickets reference status/priority (422).
- UI: `/admin/ticket-meta` with status/priority tabs.
- Tests: `tests/Feature/Admin/TicketMetaAdminApiTest.php`.

### Phase G — Notification templates
- APIs: `GET/PATCH /notification-templates/{id}`, `POST .../reset`.
- UI: `/admin/notification-templates` with department scope, edit, reset override.
- Tests: `tests/Feature/Admin/NotificationTemplateAdminApiTest.php`.

---

## 2. CRUD matrix (updated)

| Entity | Create | Read | Update | Delete | Permissions | UI | Backend |
|--------|--------|------|--------|--------|-------------|-----|---------|
| Companies | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ super-admin | ✅ |
| Departments | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Users | ⚠️ invite | ✅ | ✅ | ✅ soft | ✅ | ✅ | ✅ |
| Invites | ✅ | ✅ | — | ✅ revoke | ✅ | ✅ | ✅ |
| Invites resend | ✅ | — | — | — | ✅ | ✅ | ✅ |
| Roles (global) | seed | ✅ | ✅ permissions | — | ✅ | ✅ | ✅ |
| Permissions | seed | ✅ | — | — | ✅ | ✅ matrix | ✅ |
| Categories | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Subcategories | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| SLA Policies | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Settings | ✅ | ✅ | ✅ | ✅ reset | ✅ | ✅ + dept context | ✅ |
| Notification templates | seed | ✅ | ✅ | reset | ✅ | ✅ | ✅ |
| Ticket statuses | ✅ | ✅ | ✅ | ✅* | ✅ | ✅ | ✅ |
| Ticket priorities | ✅ | ✅ | ✅ | ✅* | ✅ | ✅ | ✅ |
| Audit logs | — | ✅ | — | — | ✅ | ✅ | ✅ |

\* Delete blocked when referenced by tickets (validation error); prefer deactivate/reassign in operations.

---

## 3. Remaining gaps

| Gap | Severity | Notes |
|-----|----------|-------|
| Sidebar shows all admin links without per-permission hiding | Low | API returns 403; consider `permissions` check on nav items |
| E2E Playwright admin flows | Medium | Not run in this environment |
| Role matrix for company-scoped roles | Low | Global roles only in UI; company roles via user patch |
| Settings company scope explicit `company_id` picker | Low | Uses auth user `company_id` for company scope |
| Drag-and-drop reorder for statuses/priorities | Low | `sort_order` field editable in API; no DnD UI |

---

## 4. Verification (final)

| Command | Result |
|---------|--------|
| `php artisan test` | **98 passed** |
| `npm run type-check` | **Pass** |
| `npm run lint` | **Pass** |
| `npm run build` | **Pass** |
| `npm run test -- --run` | **58 passed** |

---

## 5. Key files

**Backend:** `SettingsContextResolver.php`, `SettingsController.php`, `AuditServiceProvider.php`, Identity `RoleController`/`RoleAdminService`, Ticketing `TicketStatusController`/`TicketPriorityController`, Notifications `NotificationTemplateController`.

**Frontend:** `AdminCompaniesPage.tsx`, `AdminRolesPage.tsx`, `AdminTicketMetaPage.tsx`, `AdminNotificationTemplatesPage.tsx`, `AdminCategoriesPage.tsx` (subcategories), `settingsService.ts`, `SettingsPage.tsx`, `apiEndpoints.ts`, `routes.ts`, `Sidebar.tsx`.

**Tests:** `SettingsContextTest`, `AdminModelAuditTest`, `RoleAdminApiTest`, `TicketMetaAdminApiTest`, `NotificationTemplateAdminApiTest`, `AdminCompaniesPage.test.tsx`.

---

## 6. Readiness score

| Area | Score |
|------|-------|
| Settings (context + inheritance) | 95/100 |
| Identity admin (companies/depts/users/invites) | 92/100 |
| Categories + subcategories | 90/100 |
| Roles & permissions | 88/100 |
| Ticket meta (status/priority) | 90/100 |
| Notification templates | 88/100 |
| Audit coverage | 92/100 |
| **Admin domain overall** | **91/100** |

**2026-05-19 update — Department membership & heads:** See `docs/DEPARTMENT_MEMBERSHIP_AND_HEADS_REPORT.md`. User/invite admin now supports department assignment, department-head scoping, and head management (super admin). PHP tests: **122**; frontend unit: **64**.

**Production-ready for core admin/settings:** Yes, with conditional go (UAT + E2E recommended).