ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
e840007127
TenantAtlas/specs/176-backup-quality-truth/tasks.md
ahmido e840007127 feat: add backup quality truth surfaces (#211) 
## Summary
- add a shared backup-quality resolver and summary model for backup sets, backup items, policy versions, and restore selection
- surface backup-quality truth across Filament backup-set, policy-version, and restore-wizard entry points
- add focused Pest coverage and the full Spec Kit artifact set for spec 176

## Testing
- focused backup-quality verification and integrated-browser smoke coverage were completed during implementation
- degraded browser smoke path was validated with temporary seeded records and then cleaned up again
- the workspace already has a prior `vendor/bin/sail artisan test --compact` run exiting non-zero; that full-suite failure was not reworked as part of this PR

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #211
2026-04-07 11:39:40 +00:00

20 KiB
Raw Blame History

Tasks: Backup Quality Truth Surfaces

Input: Design documents from /specs/176-backup-quality-truth/ Prerequisites: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/, quickstart.md

Tests: Tests are REQUIRED for this feature. Use focused Pest coverage in existing backup, version, restore-selection, and RBAC suites, plus new backup-quality tests under tests/Feature/Filament/, tests/Feature/Rbac/, and tests/Unit/Support/BackupQuality/. Operations: This feature introduces no new OperationRun, no queued or scheduled work, and no new audit event family. Work is limited to read-first quality truth on existing backup, version, and restore-selection surfaces. RBAC: Existing tenant membership, capability-registry usage, and 404 vs 403 behavior must remain unchanged across /admin/t/{tenant}/backup-sets/..., /admin/t/{tenant}/policy-versions/..., and /admin/t/{tenant}/restore-runs/create. Users with TENANT_VIEW must see backup-quality truth on read surfaces even when restore actions remain unavailable. Operator Surfaces: Backup-set list and detail, backup-items relation rows, policy-version list and detail, and restore wizard step 1 and step 2 must show backup-quality truth before diagnostics or later restore-safety conclusions. Quality copy must remain distinct from lifecycle, restore readiness, and tenant recoverability claims. Filament UI Action Surfaces: No new primary inspect model, redundant View action, or destructive-action placement is introduced. Existing archive, restore, force-delete, remove, and bulk actions remain confirmation-gated and server-authorized. Filament UI UX-001: This feature keeps the existing Filament list, relation-manager, infolist, enterprise-detail, and wizard layouts. New quality sections must be summary-first and diagnostics-second. Badges: Snapshot completeness must continue to use centralized badge semantics through app/Support/Badges/Domains/PolicySnapshotModeBadge.php. Any additional quality wording must come from the shared backup-quality layer rather than page-local mappings.

Organization: Tasks are grouped by user story so each story can be implemented and validated as an independent increment after the shared backup-quality scaffolding is in place.

Phase 1: Setup (Shared Backup-Quality Scaffolding)

Purpose: Add the narrow derived backup-quality layer and base test scaffolding used by every story.

  • T001 Create the shared backup-quality resolver and summary types in app/Support/BackupQuality/BackupQualityResolver.php and app/Support/BackupQuality/BackupQualitySummary.php
  • T002 [P] Add unit test scaffolding for resolver rules and aggregate summaries in tests/Unit/Support/BackupQuality/BackupQualityResolverTest.php and tests/Unit/Support/BackupQuality/BackupSetQualitySummaryTest.php
  • T003 Add metadata convenience helpers for item evidence in app/Models/BackupItem.php and mirror them in app/Models/PolicyVersion.php only if resolver wiring still leaves justified duplication there
  • T004 [P] Extend metadata semantics regression coverage in tests/Unit/BackupItemTest.php and tests/Unit/AssignmentBackupServiceTest.php

Phase 2: Foundational (Blocking Shared Wiring)

Purpose: Wire the shared backup-quality contract into the existing Filament seams before any story-specific surface work begins.

⚠️ CRITICAL: No user story work should begin until this phase is complete.

  • T005 Thread shared backup-quality loading and aggregation hooks through app/Filament/Resources/BackupSetResource.php, app/Filament/Resources/PolicyVersionResource.php, and app/Filament/Resources/RestoreRunResource.php
  • T006 [P] Reuse centralized snapshot-mode and summary copy seams in app/Support/Badges/Domains/PolicySnapshotModeBadge.php and app/Support/BackupQuality/BackupQualitySummary.php
  • T007 [P] Add shared mixed-signal, integrity-warning, and unknown-quality regression coverage in tests/Unit/Support/BackupQuality/BackupQualityResolverTest.php and tests/Feature/Filament/BackupSetEnterpriseDetailPageTest.php

Checkpoint: Backup, version, and restore-selection resources can now consume one shared backup-quality contract.

Phase 3: User Story 1 - Judge Backup Sets Early (Priority: P1) 🎯 MVP

Goal: Let operators distinguish stored backup sets from degraded recovery input within one scan of the list or detail surface.

Independent Test: Load backup-set list and detail pages with full-quality, mixed-quality, and metadata-only fixtures and verify lifecycle truth stays separate from a default-visible quality summary.

Tests for User Story 1

  • T008 [P] [US1] Add backup-set list truth coverage for full, mixed, metadata-only, and archived sets in tests/Feature/Filament/BackupQualityTruthSurfaceTest.php
  • T009 [P] [US1] Extend summary-first backup-set detail assertions to cover archived parity and integrity-warning counts in tests/Feature/Filament/BackupSetEnterpriseDetailPageTest.php

Implementation for User Story 1

  • T010 [US1] Add compact backup-quality summary columns and row copy to app/Filament/Resources/BackupSetResource.php
  • T011 [US1] Add a default-visible quality summary section with integrity-warning counts, next-action guidance, and contextual related links that stay out of the header in app/Filament/Resources/BackupSetResource.php
  • T012 [US1] Ensure backup-set quality summaries use aggregated item facts without new N+1 queries in app/Support/BackupQuality/BackupQualityResolver.php and app/Filament/Resources/BackupSetResource.php
  • T013 [US1] Run the focused backup-set truth pack in tests/Feature/Filament/BackupQualityTruthSurfaceTest.php and tests/Feature/Filament/BackupSetEnterpriseDetailPageTest.php

Checkpoint: Backup-set list and detail now expose input quality early without implying restore safety.

Phase 4: User Story 2 - Inspect Item and Version Strength (Priority: P2)

Goal: Make item-level and version-level payload quality explicit instead of forcing operators to infer it from disabled actions or hidden metadata.

Independent Test: Load backup-items and policy-versions surfaces with full, metadata-only, assignment-fetch-failed, orphaned-assignment, and not-applicable fixtures and verify each surface renders explicit quality truth at scan speed.

Tests for User Story 2

  • T014 [P] [US2] Extend backup-item relation truth coverage for snapshot mode, assignment failures, orphaned assignments, non-failure capture reasons, and inspect-next-step cues in tests/Feature/Filament/BackupItemsRelationManagerFiltersTest.php
  • T015 [P] [US2] Add policy-version quality list and detail coverage for full, degraded, integrity-warning, and archived versions in tests/Feature/Filament/PolicyVersionQualityTruthSurfaceTest.php and tests/Feature/Filament/PolicyVersionTest.php
  • T016 [P] [US2] Add regression coverage that quality truth remains visible independently from restore action gating in tests/Feature/Filament/PolicyVersionRestoreViaWizardTest.php and tests/Unit/Support/BackupQuality/BackupQualityResolverTest.php

Implementation for User Story 2

  • T017 [US2] Add per-item snapshot mode, assignment-quality signals, and inspect-detail next-step cues to app/Filament/Resources/BackupSetResource/RelationManagers/BackupItemsRelationManager.php
  • T018 [US2] Add scan-speed snapshot mode, integrity-warning visibility, stronger-version or open-detail cues, and a single empty-state CTA to the table schema in app/Filament/Resources/PolicyVersionResource.php
  • T019 [US2] Add an explicit backup-quality infolist section with integrity-warning truth and non-overclaiming guidance in app/Filament/Resources/PolicyVersionResource.php
  • T020 [US2] Remove page-local quality derivation from item and version surfaces by routing them through app/Support/BackupQuality/BackupQualityResolver.php, app/Filament/Resources/BackupSetResource/RelationManagers/BackupItemsRelationManager.php, and app/Filament/Resources/PolicyVersionResource.php
  • T021 [US2] Run the focused item and version truth pack in tests/Feature/Filament/BackupItemsRelationManagerFiltersTest.php, tests/Feature/Filament/PolicyVersionQualityTruthSurfaceTest.php, tests/Feature/Filament/PolicyVersionTest.php, and tests/Feature/Filament/PolicyVersionRestoreViaWizardTest.php

Checkpoint: Backup items and policy versions now expose quality truth directly where operators inspect them.

Phase 5: User Story 3 - Select Restore Inputs With Early Warning (Priority: P3)

Goal: Show weak backup sets and items at the first restore-selection step, before later restore-safety checks or preview work begins.

Independent Test: Open the restore wizard with degraded backup-set and backup-item fixtures and verify step 1 and step 2 expose input quality before any risk-check output is shown.

Tests for User Story 3

  • T022 [P] [US3] Add step-1 degraded backup-set hint coverage in tests/Feature/Filament/RestoreSelectionQualityTruthTest.php
  • T023 [P] [US3] Extend pre-risk-check item-quality assertions in tests/Feature/Filament/RestoreItemSelectionTest.php and tests/Feature/RestoreRiskChecksWizardTest.php

Implementation for User Story 3

  • T024 [US3] Add backup-set quality summaries to step-1 option labels and helper text in app/Filament/Resources/RestoreRunResource.php
  • T025 [US3] Add item-level snapshot mode and assignment-quality descriptions to restore item option data in app/Filament/Resources/RestoreRunResource.php
  • T026 [US3] Preserve the backup-quality versus restore-safety claim boundary in app/Filament/Resources/RestoreRunResource.php and app/Filament/Resources/RestoreRunResource/Pages/CreateRestoreRun.php
  • T027 [US3] Run the focused restore-selection truth pack in tests/Feature/Filament/RestoreSelectionQualityTruthTest.php, tests/Feature/Filament/RestoreItemSelectionTest.php, and tests/Feature/RestoreRiskChecksWizardTest.php

Checkpoint: Restore selection now exposes degraded input before later restore-safety logic runs.

Phase 6: User Story 4 - Preserve Truth Under RBAC Boundaries (Priority: P4)

Goal: Keep backup-quality truth visible to read-only tenant viewers while preserving existing restore and mutation restrictions plus deny-as-not-found behavior.

Independent Test: Sign in as a tenant member with TENANT_VIEW but without restore capability and verify backup-set and policy-version surfaces still show quality truth, while non-members still receive 404 and in-scope users without mutation capability still receive 403 on execution.

Tests for User Story 4

  • T028 [P] [US4] Add tenant-view visibility coverage for backup-set, backup-item relation rows, and policy-version quality truth in tests/Feature/Rbac/BackupQualityVisibilityTest.php
  • T029 [P] [US4] Extend deny-as-not-found and missing-capability regressions for backup and restore entry points in tests/Feature/Filament/BackupSetUiEnforcementTest.php, tests/Feature/Rbac/BackupItemsRelationManagerUiEnforcementTest.php, tests/Feature/Rbac/CreateRestoreRunAuthorizationTest.php, and tests/Feature/Rbac/PolicyVersionsRestoreToIntuneUiEnforcementTest.php

Implementation for User Story 4

  • T030 [US4] Adjust quality-section visibility so read surfaces and backup-item relation rows remain available to TENANT_VIEW users in app/Filament/Resources/BackupSetResource.php, app/Filament/Resources/BackupSetResource/RelationManagers/BackupItemsRelationManager.php, and app/Filament/Resources/PolicyVersionResource.php
  • T031 [US4] Preserve 404 vs 403 semantics around restore-linked quality hints in app/Filament/Resources/RestoreRunResource.php and app/Filament/Resources/RestoreRunResource/Pages/CreateRestoreRun.php
  • T032 [US4] Run the focused RBAC truth pack in tests/Feature/Rbac/BackupQualityVisibilityTest.php, tests/Feature/Filament/BackupSetUiEnforcementTest.php, tests/Feature/Rbac/BackupItemsRelationManagerUiEnforcementTest.php, tests/Feature/Rbac/CreateRestoreRunAuthorizationTest.php, and tests/Feature/Rbac/PolicyVersionsRestoreToIntuneUiEnforcementTest.php

Checkpoint: Quality truth remains visible under read-only permissions without weakening authorization boundaries.

Phase 7: Polish & Cross-Cutting Concerns

Purpose: Final consistency, cleanup, formatting, and focused verification across all stories.

  • T033 [P] Review and align operator-facing backup-quality copy and next-action wording in app/Support/BackupQuality/BackupQualitySummary.php, app/Filament/Resources/BackupSetResource.php, app/Filament/Resources/PolicyVersionResource.php, and app/Filament/Resources/RestoreRunResource.php
  • T034 Remove dead fallback derivation and duplicate helper logic left after story implementation in app/Support/BackupQuality/BackupQualityResolver.php, app/Filament/Resources/BackupSetResource.php, app/Filament/Resources/PolicyVersionResource.php, and app/Filament/Resources/RestoreRunResource.php
  • T035 Run formatting with vendor/bin/sail bin pint --dirty --format agent for app/Support/BackupQuality/BackupQualityResolver.php, app/Filament/Resources/BackupSetResource.php, app/Filament/Resources/PolicyVersionResource.php, app/Filament/Resources/RestoreRunResource.php, and tests/Feature/Filament/BackupQualityTruthSurfaceTest.php
  • T036 Run the focused verification pack from specs/176-backup-quality-truth/quickstart.md against tests/Feature/Filament/BackupQualityTruthSurfaceTest.php, tests/Feature/Filament/BackupSetEnterpriseDetailPageTest.php, tests/Feature/Filament/BackupItemsRelationManagerFiltersTest.php, tests/Feature/Filament/BackupSetUiEnforcementTest.php, tests/Feature/Filament/PolicyVersionQualityTruthSurfaceTest.php, tests/Feature/Filament/PolicyVersionTest.php, tests/Feature/Filament/PolicyVersionRestoreViaWizardTest.php, tests/Feature/Filament/RestoreSelectionQualityTruthTest.php, tests/Feature/Filament/RestoreItemSelectionTest.php, tests/Feature/RestoreRiskChecksWizardTest.php, tests/Feature/Rbac/BackupQualityVisibilityTest.php, tests/Feature/Rbac/BackupItemsRelationManagerUiEnforcementTest.php, tests/Feature/Rbac/CreateRestoreRunAuthorizationTest.php, tests/Feature/Rbac/PolicyVersionsRestoreToIntuneUiEnforcementTest.php, tests/Unit/Support/BackupQuality/BackupQualityResolverTest.php, tests/Unit/Support/BackupQuality/BackupSetQualitySummaryTest.php, tests/Unit/AssignmentBackupServiceTest.php, and tests/Unit/BackupItemTest.php
  • T037 Run the manual validation pass in specs/176-backup-quality-truth/quickstart.md for backup-set, policy-version, restore-selection, and RBAC truth surfaces

Dependencies & Execution Order

Phase Dependencies

  • Setup (Phase 1): Starts immediately and establishes the shared backup-quality namespace and test scaffolding.
  • Foundational (Phase 2): Depends on Setup and blocks all story work until existing Filament resources consume the shared resolver and summary contract.
  • User Story 1 (Phase 3): Starts after Foundational and delivers the MVP truth surface on backup-set list and detail pages.
  • User Story 2 (Phase 4): Starts after Foundational and can proceed alongside User Story 1 once the shared resolver contract is stable.
  • User Story 3 (Phase 5): Starts after User Story 1 and User Story 2 because restore selection reuses both aggregate backup-set truth and item-level quality facts.
  • User Story 4 (Phase 6): Starts after User Story 1 and User Story 2 and should finish after User Story 3 if restore-selection RBAC visibility is included in the same pass.
  • Polish (Phase 7): Starts after the desired user stories are complete.

User Story Dependencies

  • US1: Depends only on Setup and Foundational work.
  • US2: Depends only on Setup and Foundational work and shares the same resolver contract as US1.
  • US3: Depends on US1 and US2 because step 1 and step 2 reuse the backup-set and item-level quality models introduced there.
  • US4: Depends on US1 and US2 for truth surfaces and should include US3 when restore-wizard visibility checks are part of the same test pass.

Within Each User Story

  • Tests should be added or updated before the corresponding behavior change is considered complete.
  • Shared resolver and resource wiring should land before story-specific copy cleanup for the same surface.
  • Story-level focused test runs should pass before moving to the next priority slice.

Parallel Opportunities

  • T002 and T004 can run in parallel once T001 and T003 establish the helper signatures and metadata rules.
  • T006 and T007 can run in parallel after T005 lands the shared wiring points.
  • T008 and T009 can run in parallel for US1.
  • T014, T015, and T016 can run in parallel for US2.
  • T022 and T023 can run in parallel for US3.
  • T028 and T029 can run in parallel for US4.
  • T033 and story-specific cleanup reviews can run in parallel once feature behavior is stable.

Parallel Example: User Story 1

# Story 1 tests in parallel:
Task: T008 tests/Feature/Filament/BackupQualityTruthSurfaceTest.php
Task: T009 tests/Feature/Filament/BackupSetEnterpriseDetailPageTest.php

# Story 1 implementation after assertions are set:
Task: T010 app/Filament/Resources/BackupSetResource.php
Task: T012 app/Support/BackupQuality/BackupQualityResolver.php

Parallel Example: User Story 2

# Story 2 tests in parallel:
Task: T014 tests/Feature/Filament/BackupItemsRelationManagerFiltersTest.php
Task: T015 tests/Feature/Filament/PolicyVersionQualityTruthSurfaceTest.php
Task: T016 tests/Feature/Filament/PolicyVersionRestoreViaWizardTest.php

# Story 2 implementation split after the resolver contract is fixed:
Task: T017 app/Filament/Resources/BackupSetResource/RelationManagers/BackupItemsRelationManager.php
Task: T018 app/Filament/Resources/PolicyVersionResource.php

Parallel Example: User Story 3

# Story 3 tests in parallel:
Task: T022 tests/Feature/Filament/RestoreSelectionQualityTruthTest.php
Task: T023 tests/Feature/Filament/RestoreItemSelectionTest.php

# Story 3 implementation split after the selection copy is agreed:
Task: T024 app/Filament/Resources/RestoreRunResource.php
Task: T025 app/Filament/Resources/RestoreRunResource.php

Parallel Example: User Story 4

# Story 4 tests in parallel:
Task: T028 tests/Feature/Rbac/BackupQualityVisibilityTest.php
Task: T029 tests/Feature/Rbac/CreateRestoreRunAuthorizationTest.php

# Story 4 implementation split after RBAC expectations are locked:
Task: T030 app/Filament/Resources/BackupSetResource.php
Task: T031 app/Filament/Resources/RestoreRunResource/Pages/CreateRestoreRun.php

Implementation Strategy

MVP First

  • Complete Phase 1 and Phase 2.
  • Deliver User Story 1 as the first usable increment so operators can judge backup-set quality early.
  • Validate that lifecycle truth and backup-quality truth are clearly separated on backup-set list and detail surfaces.

Incremental Delivery

  • Add User Story 2 next so item and version strength become explicit everywhere operators inspect backup inputs.
  • Add User Story 3 after that so restore selection inherits the same quality truth before risk checks.
  • Add User Story 4 last to verify RBAC-safe truth visibility across read and restore-linked surfaces.

Verification Finish

  • Run Pint on touched files.
  • Run the focused verification pack from quickstart.md.
  • Run the manual quickstart validation pass for backup-set, policy-version, restore-selection, and RBAC outcomes.
  • Offer the broader test suite only after the focused pack passes.