ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
dev
TenantAtlas/specs/136-admin-canonical-tenant/tasks.md
ahmido 45a804970e feat: complete admin canonical tenant rollout (#165) 
## Summary
- complete Spec 136 canonical admin tenant rollout across admin-visible and shared Filament surfaces
- add the shared panel-aware tenant resolver helper, persisted filter-state synchronization, and admin navigation segregation for tenant-sensitive resources
- expand regression, guard, and parity coverage for admin-path tenant resolution, stale filters, workspace-wide tenant-default surfaces, and panel split behavior

## Validation
- `vendor/bin/sail artisan test --compact tests/Feature/Guards/AdminTenantResolverGuardTest.php`
- `vendor/bin/sail artisan test --compact tests/Feature/Filament/TableStatePersistenceTest.php`
- `vendor/bin/sail artisan test --compact --filter='CanonicalAdminTenantFilterState|PolicyResource|BackupSchedule|BackupSet|FindingResource|BaselineCompareLanding|RestoreRunResource|InventoryItemResource|PolicyVersionResource|ProviderConnectionResource|TenantDiagnostics|InventoryCoverage|InventoryKpiHeader|AuditLog|EntraGroup'`
- `vendor/bin/sail bin pint --dirty --format agent`

## Notes
- Livewire v4.0+ compliance is preserved with Filament v5.
- Provider registration remains unchanged in `bootstrap/providers.php`.
- `PolicyResource` and `PolicyVersionResource` have admin global search disabled explicitly; `EntraGroupResource` keeps admin-aware scoped search with a View page.
- Destructive and governance-sensitive actions retain existing confirmation and authorization behavior while using canonical tenant parity.
- No new assets were introduced, so deployment asset strategy is unchanged and does not add new `filament:assets` work.

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #165
2026-03-13 08:09:20 +00:00

242 lines
21 KiB
Markdown
Raw Permalink Blame History

# Tasks: Admin Panel Canonical Tenant Resolution Full Rollout
**Input**: Design documents from `/specs/136-admin-canonical-tenant/`
**Prerequisites**: `plan.md`, `spec.md`, `research.md`, `data-model.md`, `contracts/admin-tenant-resolution-rollout.yaml`, `quickstart.md`
**Tests**: Tests are REQUIRED for this feature because it changes runtime behavior across existing Filament admin flows, persisted table filter state, global search parity, direct record resolution, and sensitive action safety.
## Phase 1: Setup (Shared Infrastructure)
**Purpose**: Create the implementation inventory, regression entry points, and developer-facing rollout note used by every implementation slice.
- [X] T001 Create the rollout manifest and manual tenant-switch verification note in `docs/research/admin-canonical-tenant-rollout.md`
- [X] T002 Create direct canonical tenant regression entry points in `tests/Feature/Filament/CanonicalAdminTenantFilterStateTest.php` and `tests/Feature/Filament/AdminTenantSurfaceParityTest.php`
- [X] T003 [P] Create shared-surface panel parity and guard expansion entry points in `tests/Feature/Filament/AdminSharedSurfacePanelParityTest.php` and `tests/Feature/Guards/AdminTenantResolverGuardTest.php`
---
## Phase 2: Foundational (Blocking Prerequisites)
**Purpose**: Freeze the rollout manifest, lock in the canonical admin resolver and filter-sync contract, and preserve the known-good admin reference patterns before any user-story-specific migrations begin.
**⚠️ CRITICAL**: No user story work can begin until this phase is complete.
- [X] T004 Freeze the Type A, Type B, and Type C rollout manifest plus exception inventory in `docs/research/admin-canonical-tenant-rollout.md` and `tests/Feature/Guards/AdminTenantResolverGuardTest.php`
- [X] T005 Define the shared canonical admin tenant and filter-sync contract in `app/Support/OperateHub/OperateHubShell.php` and `app/Support/Filament/CanonicalAdminTenantFilterState.php`
- [X] T006 [P] Preserve the admin-safe reference patterns in `app/Filament/Resources/AlertDeliveryResource.php`, `app/Filament/Resources/AlertDeliveryResource/Pages/ListAlertDeliveries.php`, and `app/Filament/Pages/Monitoring/AuditLog.php`
- [X] T007 [P] Extend the admin-aware search and panel-split foundation in `app/Filament/Concerns/ScopesGlobalSearchToTenant.php`
- [X] T008 [P] Add foundational resolver-precedence and filter-sync coverage in `tests/Feature/OpsUx/OperateHubShellTest.php` and `tests/Feature/Filament/CanonicalAdminTenantFilterStateTest.php`
**Checkpoint**: The rollout manifest, canonical resolver contract, filter-state contract, and shared admin reference patterns are fixed; user-story implementation can now proceed.
---
## Phase 3: User Story 1 - Trust The Active Tenant Everywhere (Priority: P1) 🎯 MVP
**Goal**: Eliminate mixed tenant sources on hard tenant-sensitive admin surfaces so header context, queries, widgets, links, and sensitive actions all resolve the same tenant.
**Independent Test**: Open representative Type A admin surfaces with an active tenant and verify that the visible tenant, list or detail data, KPIs, links, and sensitive actions all use the same tenant, with explicit safe behavior when no canonical tenant exists.
### Tests for User Story 1
- [X] T009 [P] [US1] Add hard-tenant parity coverage for policy and backup schedule flows in `tests/Feature/Filament/PolicyResourceAdminTenantParityTest.php` and `tests/Feature/BackupScheduling/BackupScheduleAdminTenantParityTest.php`
- [X] T010 [P] [US1] Add hard-tenant parity coverage for backup set, findings, and baseline compare flows in `tests/Feature/Filament/BackupSetAdminTenantParityTest.php`, `tests/Feature/Findings/FindingAdminTenantParityTest.php`, and `tests/Feature/Filament/BaselineCompareLandingAdminTenantParityTest.php`
- [X] T011 [P] [US1] Add hard-tenant parity coverage for restore, inventory, policy version, diagnostics, and page-widget alignment in `tests/Feature/Filament/RestoreRunAdminTenantParityTest.php`, `tests/Feature/Filament/InventoryCoverageAdminTenantParityTest.php`, `tests/Feature/Filament/PolicyVersionAdminTenantParityTest.php`, and `tests/Feature/TenantRBAC/TenantDiagnosticsAccessTest.php`
### Implementation for User Story 1
- [X] T012 [US1] Align admin-path query, detail, and action tenant resolution in `app/Filament/Resources/PolicyResource.php`, `app/Filament/Resources/BackupScheduleResource.php`, `app/Filament/Resources/BackupScheduleResource/Pages/ListBackupSchedules.php`, and `app/Filament/Resources/BackupScheduleResource/Pages/EditBackupSchedule.php`
- [X] T013 [US1] Eliminate mixed resolver usage in `app/Filament/Resources/BackupSetResource.php`, `app/Filament/Resources/BackupSetResource/Pages/ListBackupSets.php`, `app/Filament/Resources/BackupSetResource/Pages/ViewBackupSet.php`, `app/Filament/Resources/FindingResource.php`, `app/Filament/Resources/FindingResource/Pages/ListFindings.php`, `app/Filament/Resources/FindingResource/Pages/ViewFinding.php`, and `app/Filament/Pages/BaselineCompareLanding.php`
- [X] T014 [US1] Align shared-panel restore semantics and sensitive-action tenant parity in `app/Filament/Resources/RestoreRunResource.php`, `app/Filament/Resources/RestoreRunResource/Pages/ListRestoreRuns.php`, `app/Filament/Resources/RestoreRunResource/Pages/CreateRestoreRun.php`, and `app/Filament/Resources/RestoreRunResource/Pages/ViewRestoreRun.php`
- [X] T015 [US1] Align inventory, policy-version, diagnostics, and page-widget tenant resolution in `app/Filament/Resources/InventoryItemResource.php`, `app/Filament/Resources/InventoryItemResource/Pages/ListInventoryItems.php`, `app/Filament/Resources/InventoryItemResource/Pages/ViewInventoryItem.php`, `app/Filament/Resources/PolicyVersionResource.php`, `app/Filament/Resources/PolicyVersionResource/Pages/ListPolicyVersions.php`, `app/Filament/Resources/PolicyVersionResource/Pages/ViewPolicyVersion.php`, `app/Filament/Pages/TenantDiagnostics.php`, `app/Filament/Pages/InventoryCoverage.php`, and `app/Filament/Widgets/Inventory/InventoryKpiHeader.php`
**Checkpoint**: User Story 1 is complete when all Type A rollout surfaces use one tenant source per admin request and expose explicit safe no-tenant behavior where required.
---
## Phase 4: User Story 2 - Switch Tenants Without Stale Filters (Priority: P1)
**Goal**: Make tenant-related persisted filters reseed or clear deterministically on tenant switch while keeping workspace-wide tenant-default surfaces workspace-wide.
**Independent Test**: Persist a tenant-related filter for one tenant, switch to another tenant, reload representative Type A and Type B surfaces, and verify that stale filter state is cleared or reseeded before any tenant-sensitive data renders.
### Tests for User Story 2
- [X] T016 [P] [US2] Extend stale filter and tenant-switch coverage in `tests/Feature/Filament/TableStatePersistenceTest.php` and `tests/Feature/Filament/CanonicalAdminTenantFilterStateTest.php`
- [X] T017 [P] [US2] Add admin-path search parity or explicit disablement coverage for policy and policy version resources in `tests/Feature/Filament/PolicyResourceAdminSearchParityTest.php`, `tests/Feature/Filament/PolicyVersionAdminSearchParityTest.php`, and `tests/Feature/Filament/PolicyVersionListFiltersTest.php`
- [X] T018 [P] [US2] Add workspace-wide tenant-default coverage for provider connections and audit log in `tests/Feature/ProviderConnections/ProviderConnectionAuthorizationTest.php`, `tests/Feature/Filament/AuditLogPageTest.php`, and `tests/Feature/WorkspaceIsolation/AuditLogScopeInvariantTest.php`
- [X] T019 [P] [US2] Extend Entra group admin filter, detail, and search parity coverage in `tests/Feature/Filament/EntraGroupAdminScopeTest.php`, `tests/Feature/Filament/EntraGroupGlobalSearchScopeTest.php`, and `tests/Feature/Filament/EntraGroupEnterpriseDetailPageTest.php`
### Implementation for User Story 2
- [X] T020 [US2] Apply `CanonicalAdminTenantFilterState` across tenant-sensitive list surfaces in `app/Filament/Resources/BackupScheduleResource/Pages/ListBackupSchedules.php`, `app/Filament/Resources/BackupSetResource/Pages/ListBackupSets.php`, `app/Filament/Resources/FindingResource/Pages/ListFindings.php`, `app/Filament/Resources/InventoryItemResource/Pages/ListInventoryItems.php`, and `app/Filament/Resources/PolicyVersionResource/Pages/ListPolicyVersions.php`
- [X] T021 [US2] Align admin-path search parity or explicit disablement for policy and policy version resources in `app/Filament/Resources/PolicyResource.php`, `app/Filament/Resources/PolicyVersionResource.php`, and `app/Filament/Concerns/ScopesGlobalSearchToTenant.php`
- [X] T022 [US2] Align workspace-wide tenant-default filter behavior in `app/Filament/Resources/ProviderConnectionResource.php`, `app/Filament/Resources/ProviderConnectionResource/Pages/ListProviderConnections.php`, and `app/Filament/Pages/Monitoring/AuditLog.php`
- [X] T023 [US2] Align admin list, direct-record, search, and tenant-persisted filter behavior in `app/Filament/Resources/EntraGroupResource.php`, `app/Filament/Resources/EntraGroupResource/Pages/ListEntraGroups.php`, `app/Filament/Resources/EntraGroupResource/Pages/ViewEntraGroup.php`, and `app/Filament/Concerns/ScopesGlobalSearchToTenant.php`
**Checkpoint**: User Story 2 is complete when stale tenant filters cannot survive a tenant switch and Type B surfaces remain workspace-wide while their tenant-default context stays synchronized.
---
## Phase 5: User Story 3 - Preserve Panel-Specific Tenant Rules (Priority: P2)
**Goal**: Keep tenant-panel-native behavior intact while ensuring admin-path execution uses the canonical admin tenant rule and workspace-only surfaces stay tenant-independent.
**Independent Test**: Exercise representative shared resources in both `/admin/...` and `/admin/t/{tenant}/...` contexts and verify that admin-path behavior uses the canonical admin rule, tenant-panel behavior remains panel-native, and workspace-only surfaces do not gain hidden tenant scoping.
### Tests for User Story 3
- [X] T024 [P] [US3] Add shared-surface admin-versus-tenant panel parity coverage in `tests/Feature/Filament/AdminSharedSurfacePanelParityTest.php`, `tests/Feature/Filament/EntraGroupAdminScopeTest.php`, and `tests/Feature/Filament/RestoreRunUiEnforcementTest.php`
- [X] T025 [P] [US3] Add workspace-only non-regression coverage in `tests/Feature/Filament/WorkspaceOnlySurfaceTenantIndependenceTest.php`, `tests/Feature/Filament/Alerts/AlertRuleAccessTest.php`, `tests/Feature/Filament/BaselineProfileFoundationScopeTest.php`, `tests/Feature/Filament/BaselineSnapshotAuthorizationTest.php`, `tests/Feature/ProviderConnections/ProviderConnectionListAuthorizationTest.php`, and `tests/Feature/TenantRBAC/TenantDiagnosticsAccessTest.php`
### Implementation for User Story 3
- [X] T026 [US3] Preserve tenant-panel-native branching in `app/Filament/Resources/RestoreRunResource.php`, `app/Filament/Resources/EntraGroupResource.php`, `app/Filament/Resources/BackupSetResource.php`, and `app/Filament/Concerns/ScopesGlobalSearchToTenant.php`
- [X] T027 [US3] Keep workspace-only and workspace-wide admin surfaces free of artificial tenant enforcement in `app/Filament/Resources/AlertRuleResource.php`, `app/Filament/Resources/BaselineProfileResource.php`, `app/Filament/Resources/BaselineSnapshotResource.php`, `app/Filament/Resources/ProviderConnectionResource.php`, `app/Filament/Resources/TenantResource.php`, and `app/Filament/Pages/Monitoring/AuditLog.php`
**Checkpoint**: User Story 3 is complete when shared surfaces branch correctly by panel and workspace-only surfaces remain tenant-independent.
---
## Phase 6: User Story 4 - Catch Regressions Before Merge (Priority: P3)
**Goal**: Expand the guard and focused regression suite so new admin-path mixed-resolver drift is blocked in CI and future contributors have a clear rule to follow.
**Independent Test**: Run the guard suite and the focused regression pack and verify that any new raw admin-path `Filament::getTenant()` or `Tenant::current()` usage fails with actionable output while approved tenant-panel exceptions remain explicit.
### Tests for User Story 4
- [X] T028 [P] [US4] Expand guard manifest and persisted-filter regression coverage in `tests/Feature/Guards/AdminTenantResolverGuardTest.php` and `tests/Feature/Guards/FilamentTableStandardsGuardTest.php`
- [X] T029 [P] [US4] Add focused wrong-tenant action and record-resolution regression coverage in `tests/Feature/Filament/AdminTenantSurfaceParityTest.php`, `tests/Feature/Findings/FindingWorkflowRowActionsTest.php`, `tests/Feature/Filament/PolicyVersionRestoreToIntuneTest.php`, and `tests/Feature/RestoreRunWizardExecuteTest.php`
### Implementation for User Story 4
- [X] T030 [US4] Update the executable guard allowlist, rollout manifest notes, and exception rationale in `tests/Feature/Guards/AdminTenantResolverGuardTest.php` and `docs/research/admin-canonical-tenant-rollout.md`
- [X] T031 [US4] Document the future-surface developer rule in `docs/research/admin-canonical-tenant-rollout.md` and `specs/136-admin-canonical-tenant/quickstart.md`
**Checkpoint**: User Story 4 is complete when the guard suite reflects the full rollout manifest and future admin-path drift is blocked cheaply in CI.
---
## Phase 7: Polish & Cross-Cutting Concerns
**Purpose**: Reconcile operator-facing copy, run the focused verification pack, and format touched files.
- [X] T032 [P] Reconcile operator-facing safe-state and tenant-default copy in `app/Support/OperateHub/OperateHubShell.php`, `app/Filament/Pages/BaselineCompareLanding.php`, `app/Filament/Pages/Monitoring/AuditLog.php`, and `app/Filament/Widgets/Inventory/InventoryKpiHeader.php`
- [X] T033 Record Wave 1, Wave 2, and Wave 3 manual tenant-switch verification outcomes in `docs/research/admin-canonical-tenant-rollout.md` using the checklist in `specs/136-admin-canonical-tenant/quickstart.md`
- [X] T034 Run the focused verification commands documented in `specs/136-admin-canonical-tenant/quickstart.md`
- [X] T035 Run formatting on touched files with `vendor/bin/sail bin pint --dirty --format agent` from `/Users/ahmeddarrazi/Documents/projects/TenantAtlas`
---
## Dependencies & Execution Order
### Phase Dependencies
- **Setup (Phase 1)**: No dependencies; can start immediately.
- **Foundational (Phase 2)**: Depends on Setup completion; blocks all user-story implementation.
- **User Stories (Phases 3-6)**: Depend on Foundational completion.
- **Polish (Phase 7)**: Depends on the desired user stories being complete.
### User Story Dependencies
- **User Story 1 (P1)**: Starts after Foundational and delivers the MVP by aligning all hard tenant-sensitive surfaces.
- **User Story 2 (P1)**: Starts after Foundational and can run in parallel with US1 once the shared filter-sync contract is in place.
- **User Story 3 (P2)**: Starts after Foundational and should land before release so shared resources preserve tenant-panel semantics and workspace-only surfaces stay clean.
- **User Story 4 (P3)**: Depends on the remediation intent from US1-US3 so the final guard manifest and regression pack reflect the completed rollout set.
### Within Each User Story
- Write or update the story tests first and confirm they fail against pre-change behavior.
- Land shared resolver, filter-sync, and panel-branching logic before adjusting action or link affordances that consume it.
- Keep list, detail, deep-link, and search behavior aligned before closing the story.
- Finish story-level validation before moving to the next priority.
### Parallel Opportunities
- T003 can run in parallel with T001-T002 once the feature directory exists.
- T006-T008 can run in parallel after T004-T005.
- In US1, T009-T011 can run in parallel before T012-T015.
- In US2, T016-T019 can run in parallel before T020-T023.
- In US3, T024-T025 can run in parallel before T026-T027.
- In US4, T028-T029 can run in parallel before T030-T031.
- T032 can run in parallel with T033-T034 after the story phases are complete.
---
## Parallel Example: User Story 1
```bash
# Launch the US1 parity tests together:
Task: "Add hard-tenant parity coverage for policy and backup schedule flows in tests/Feature/Filament/PolicyResourceAdminTenantParityTest.php and tests/Feature/BackupScheduling/BackupScheduleAdminTenantParityTest.php"
Task: "Add hard-tenant parity coverage for backup set, findings, and baseline compare flows in tests/Feature/Filament/BackupSetAdminTenantParityTest.php, tests/Feature/Findings/FindingAdminTenantParityTest.php, and tests/Feature/Filament/BaselineCompareLandingAdminTenantParityTest.php"
Task: "Add hard-tenant parity coverage for restore, inventory, policy version, diagnostics, and page-widget alignment in tests/Feature/Filament/RestoreRunAdminTenantParityTest.php, tests/Feature/Filament/InventoryCoverageAdminTenantParityTest.php, tests/Feature/Filament/PolicyVersionAdminTenantParityTest.php, and tests/Feature/TenantRBAC/TenantDiagnosticsAccessTest.php"
```
---
## Parallel Example: User Story 2
```bash
# Launch the US2 filter and tenant-default tests together:
Task: "Extend stale filter and tenant-switch coverage in tests/Feature/Filament/TableStatePersistenceTest.php and tests/Feature/Filament/CanonicalAdminTenantFilterStateTest.php"
Task: "Add admin-path search parity or explicit disablement coverage for policy and policy version resources in tests/Feature/Filament/PolicyResourceAdminSearchParityTest.php, tests/Feature/Filament/PolicyVersionAdminSearchParityTest.php, and tests/Feature/Filament/PolicyVersionListFiltersTest.php"
Task: "Add workspace-wide tenant-default coverage for provider connections and audit log in tests/Feature/ProviderConnections/ProviderConnectionAuthorizationTest.php, tests/Feature/Filament/AuditLogPageTest.php, and tests/Feature/WorkspaceIsolation/AuditLogScopeInvariantTest.php"
Task: "Extend Entra group admin filter, detail, and search parity coverage in tests/Feature/Filament/EntraGroupAdminScopeTest.php, tests/Feature/Filament/EntraGroupGlobalSearchScopeTest.php, and tests/Feature/Filament/EntraGroupEnterpriseDetailPageTest.php"
```
---
## Parallel Example: User Story 3
```bash
# Launch the US3 panel-behavior tests together:
Task: "Add shared-surface admin-versus-tenant panel parity coverage in tests/Feature/Filament/AdminSharedSurfacePanelParityTest.php, tests/Feature/Filament/EntraGroupAdminScopeTest.php, and tests/Feature/Filament/RestoreRunUiEnforcementTest.php"
Task: "Add workspace-only non-regression coverage in tests/Feature/Filament/WorkspaceOnlySurfaceTenantIndependenceTest.php, tests/Feature/Filament/Alerts/AlertRuleAccessTest.php, tests/Feature/Filament/BaselineProfileFoundationScopeTest.php, tests/Feature/Filament/BaselineSnapshotAuthorizationTest.php, tests/Feature/ProviderConnections/ProviderConnectionListAuthorizationTest.php, and tests/Feature/TenantRBAC/TenantDiagnosticsAccessTest.php"
```
---
## Parallel Example: User Story 4
```bash
# Launch the US4 guard and regression work together:
Task: "Expand guard manifest and persisted-filter regression coverage in tests/Feature/Guards/AdminTenantResolverGuardTest.php and tests/Feature/Guards/FilamentTableStandardsGuardTest.php"
Task: "Add focused wrong-tenant action and record-resolution regression coverage in tests/Feature/Filament/AdminTenantSurfaceParityTest.php, tests/Feature/Findings/FindingWorkflowRowActionsTest.php, tests/Feature/Filament/PolicyVersionRestoreToIntuneTest.php, and tests/Feature/RestoreRunWizardExecuteTest.php"
```
---
## Implementation Strategy
### MVP First (User Story 1 Only)
1. Complete Phase 1: Setup.
2. Complete Phase 2: Foundational.
3. Complete Phase 3: User Story 1.
4. Validate representative Type A surfaces before moving on.
### Incremental Delivery
1. Finish Setup and Foundational shared resolver and filter-state work.
2. Deliver User Story 1 to eliminate mixed tenant sources on Type A surfaces.
3. Deliver User Story 2 to harden persisted filters, policy search parity, and workspace-wide tenant-default behavior.
4. Deliver User Story 3 to preserve tenant-panel semantics and workspace-only independence.
5. Deliver User Story 4 to lock in guard coverage and future-surface guidance.
6. Finish with copy reconciliation, manual tenant-switch verification, focused validation, and formatting.
### Parallel Team Strategy
1. One contributor handles the support-layer resolver, filter-sync contract, and rollout manifest while another prepares the new regression entry points.
2. After Foundation is ready, split US1 and US2 between hard tenant-sensitive surface parity and persisted-filter or workspace-wide tenant-default hardening.
3. Reserve one contributor for shared-surface panel behavior and the guard manifest so exception handling stays coherent while implementation lands.
---
## Notes
- `[P]` tasks touch different files and can be executed in parallel.
- User-story labels map directly to the prioritized stories in `spec.md`.
- Tests are mandatory in this repo for every runtime change in the resulting implementation.
- The suggested MVP scope is Phase 3 only after Setup and Foundational are complete.
Reference in New Issue View Git Blame Copy Permalink