Ahmed Darrazi 0ae7f91a6d feat: complete admin canonical tenant rollout

2026-03-12 23:26:32 +01:00

21 KiB

Raw 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.

T001 Create the rollout manifest and manual tenant-switch verification note in docs/research/admin-canonical-tenant-rollout.md
T002 Create direct canonical tenant regression entry points in tests/Feature/Filament/CanonicalAdminTenantFilterStateTest.php and tests/Feature/Filament/AdminTenantSurfaceParityTest.php
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.

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
T005 Define the shared canonical admin tenant and filter-sync contract in app/Support/OperateHub/OperateHubShell.php and app/Support/Filament/CanonicalAdminTenantFilterState.php
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
T007 [P] Extend the admin-aware search and panel-split foundation in app/Filament/Concerns/ScopesGlobalSearchToTenant.php
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

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
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
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

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
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
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
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

T016 [P] [US2] Extend stale filter and tenant-switch coverage in tests/Feature/Filament/TableStatePersistenceTest.php and tests/Feature/Filament/CanonicalAdminTenantFilterStateTest.php
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
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
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

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
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
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
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

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
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

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
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

T028 [P] [US4] Expand guard manifest and persisted-filter regression coverage in tests/Feature/Guards/AdminTenantResolverGuardTest.php and tests/Feature/Guards/FilamentTableStandardsGuardTest.php
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

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
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.

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
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
T034 Run the focused verification commands documented in specs/136-admin-canonical-tenant/quickstart.md
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

# 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

# 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

# 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

# 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)

Complete Phase 1: Setup.
Complete Phase 2: Foundational.
Complete Phase 3: User Story 1.
Validate representative Type A surfaces before moving on.

Incremental Delivery

Finish Setup and Foundational shared resolver and filter-state work.
Deliver User Story 1 to eliminate mixed tenant sources on Type A surfaces.
Deliver User Story 2 to harden persisted filters, policy search parity, and workspace-wide tenant-default behavior.
Deliver User Story 3 to preserve tenant-panel semantics and workspace-only independence.
Deliver User Story 4 to lock in guard coverage and future-surface guidance.
Finish with copy reconciliation, manual tenant-switch verification, focused validation, and formatting.

Parallel Team Strategy

One contributor handles the support-layer resolver, filter-sync contract, and rollout manifest while another prepares the new regression entry points.
After Foundation is ready, split US1 and US2 between hard tenant-sensitive surface parity and persisted-filter or workspace-wide tenant-default hardening.
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.

21 KiB Raw Blame History