TenantAtlas/specs/180-tenant-backup-health/quickstart.md

Quickstart: Tenant Backup Health Signals

Goal

Validate that the tenant dashboard now answers the operator's backup question within seconds, that backup-health warnings drill into confirming surfaces, and that positive backup-health wording only appears when the available evidence genuinely supports it.

Prerequisites

1. Start Sail if it is not already running.
2. Ensure the workspace has representative tenant fixtures for:
   • no usable completed backup basis
   • one latest completed backup basis that is older than the backup-health freshness window
   • one latest completed backup basis that is recent but degraded under existing backup-quality truth
   • one latest completed backup basis that is recent and not materially degraded
   • one enabled backup schedule whose next_run_at is overdue or whose last_run_at indicates missing or failed execution
   • for a deterministic local/testing fixture that reproduces the established-member dashboard-visible but backup-drillthrough-403 case, run vendor/bin/sail artisan tenantpilot:backup-health:seed-browser-fixture --no-interaction, then open /admin/local/backup-health-browser-fixture-login when the integrated browser cannot complete Microsoft SSO for the seeded local user
3. Ensure the acting users are valid workspace and tenant members.
4. Ensure at least one tenant-scoped user exists for positive summary visibility and one non-member or wrong-tenant case exists for tenant-scope isolation checks.

Focused Automated Verification

Run the smallest existing dashboard and backup pack first:

vendor/bin/sail artisan test --compact tests/Feature/Filament/DashboardKpisWidgetTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/NeedsAttentionWidgetTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/TenantDashboardTruthAlignmentTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/TenantDashboardTenantScopeTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/TenantDashboardDbOnlyTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/BackupSetEnterpriseDetailPageTest.php
vendor/bin/sail artisan test --compact tests/Feature/BackupScheduling/BackupScheduleLifecycleTest.php

Expected new or expanded spec-scoped coverage:

vendor/bin/sail artisan test --compact tests/Unit/Support/BackupHealth/TenantBackupHealthResolverTest.php
vendor/bin/sail artisan test --compact --filter=backup tests/Feature/Filament/DashboardKpisWidgetTest.php tests/Feature/Filament/NeedsAttentionWidgetTest.php tests/Feature/Filament/TenantDashboardTruthAlignmentTest.php
vendor/bin/sail artisan test --compact --filter=backup tests/Feature/Filament/BackupSetListContinuityTest.php tests/Feature/Filament/BackupSetEnterpriseDetailPageTest.php tests/Feature/BackupScheduling/BackupScheduleLifecycleTest.php

Use --filter for smaller iteration passes while implementing specific scenarios.

The tenant-scope pack must include one established-member scenario where the dashboard still renders truthful summary state with a disabled or downgraded backup-health action target while the protected downstream route returns 403.

Manual Validation Pass

1. Verify no-backup posture

Open /admin/t/{tenant} for a tenant without a usable completed backup basis and confirm:

• the tenant dashboard explicitly shows a backup-health warning rather than a calm omission
• NeedsAttention includes a no-backup item or equivalent primary backup warning
• the drillthrough opens the backup-set list, which confirms that no usable completed basis exists

2. Verify stale latest-backup posture

Open /admin/t/{tenant} for a tenant whose latest relevant completed backup basis is older than the configured freshness window and confirm:

• the dashboard does not show Backups are recent and healthy
• the stale reason is visible on a primary summary surface
• the drillthrough opens the latest relevant backup set and its recency confirms the stale posture immediately
• if the latest relevant backup basis is both stale and degraded, the dashboard still leads with stale posture while the destination preserves degradation as supporting detail

3. Verify degraded latest-backup posture

Open /admin/t/{tenant} for a tenant whose latest relevant completed backup basis is recent but degraded and confirm:

• the dashboard shows degraded backup posture rather than a stale or healthy fallback
• the drillthrough opens the latest relevant backup set
• the destination confirms degradation through existing backup-quality summary without implying restore safety

4. Verify healthy backup posture

Open /admin/t/{tenant} for a tenant with a recent, non-degraded latest relevant completed backup basis and confirm:

• the dashboard may show a positive backup-health check
• no backup-health attention item, including schedule_follow_up, is present
• the healthy wording remains bounded to backup posture and does not imply recoverability or restore success

5. Verify schedule-follow-up posture

Open /admin/t/{tenant} for a tenant with an enabled schedule that looks overdue or never-successful and confirm:

• schedule follow-up appears as a backup-health attention reason when appropriate
• a never-successful schedule triggers follow-up only when it is old enough that it should already have produced success evidence
• if the latest backup basis is otherwise fresh and non-degraded, the basis posture may remain healthy, but schedule_follow_up stays the active reason and no positive healthy backup check appears
• schedule presence alone does not make the dashboard healthy and suppresses any positive healthy backup check while the follow-up remains active
• the drillthrough opens the backup-schedules list and the destination makes the overdue or missed-execution condition scan-fast

6. Verify tenant-scope and RBAC consistency

Repeat the dashboard checks as:

• an entitled tenant member, to confirm backup-health summary truth is visible
• an entitled tenant member who can load the dashboard but cannot open one backup destination, to confirm the summary still renders, the affordance degrades safely, and the blocked downstream route fails with 403; the deterministic local/testing fixture command above seeds exactly this case for smoke-requester+180@tenantpilot.local, and /admin/local/backup-health-browser-fixture-login starts the local/testing browser session for that user
• a non-member or wrong-tenant actor, to confirm tenant dashboard and drillthrough routes remain deny-as-not-found

Non-Regression Checks

Confirm the feature did not change:

• current backup-set and backup-schedule route identity
• existing destructive action confirmation behavior on backup resources
• existing backup-quality semantics owned by BackupQualityResolver
• existing OperationRun behavior and operations widgets
• current global asset registration and deployment requirements

Formatting And Final Verification

Before finalizing implementation work:

vendor/bin/sail bin pint --dirty --format agent

Then rerun the smallest affected test set and offer the full suite only after the focused backup-health pack passes.

Close the feature only after manual validation confirms:

• an operator can identify absent, stale, degraded, or healthy backup posture within 10 seconds on the tenant dashboard
• warning drillthroughs land on surfaces that confirm the same problem class
• positive backup-health wording appears only when the evidence truly supports it