250 lines
20 KiB
Markdown
250 lines
20 KiB
Markdown
# 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.
|
|
|
|
- [X] T001 Create the shared backup-quality resolver and summary types in `app/Support/BackupQuality/BackupQualityResolver.php` and `app/Support/BackupQuality/BackupQualitySummary.php`
|
|
- [X] 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`
|
|
- [X] 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
|
|
- [X] 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.
|
|
|
|
- [X] 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`
|
|
- [X] T006 [P] Reuse centralized snapshot-mode and summary copy seams in `app/Support/Badges/Domains/PolicySnapshotModeBadge.php` and `app/Support/BackupQuality/BackupQualitySummary.php`
|
|
- [X] 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
|
|
|
|
- [X] T008 [P] [US1] Add backup-set list truth coverage for full, mixed, metadata-only, and archived sets in `tests/Feature/Filament/BackupQualityTruthSurfaceTest.php`
|
|
- [X] 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
|
|
|
|
- [X] T010 [US1] Add compact backup-quality summary columns and row copy to `app/Filament/Resources/BackupSetResource.php`
|
|
- [X] 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`
|
|
- [X] 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`
|
|
- [X] 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
|
|
|
|
- [X] 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`
|
|
- [X] 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`
|
|
- [X] 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
|
|
|
|
- [X] T017 [US2] Add per-item snapshot mode, assignment-quality signals, and inspect-detail next-step cues to `app/Filament/Resources/BackupSetResource/RelationManagers/BackupItemsRelationManager.php`
|
|
- [X] 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`
|
|
- [X] T019 [US2] Add an explicit backup-quality infolist section with integrity-warning truth and non-overclaiming guidance in `app/Filament/Resources/PolicyVersionResource.php`
|
|
- [X] 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`
|
|
- [X] 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
|
|
|
|
- [X] T022 [P] [US3] Add step-1 degraded backup-set hint coverage in `tests/Feature/Filament/RestoreSelectionQualityTruthTest.php`
|
|
- [X] 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
|
|
|
|
- [X] T024 [US3] Add backup-set quality summaries to step-1 option labels and helper text in `app/Filament/Resources/RestoreRunResource.php`
|
|
- [X] T025 [US3] Add item-level snapshot mode and assignment-quality descriptions to restore item option data in `app/Filament/Resources/RestoreRunResource.php`
|
|
- [X] 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`
|
|
- [X] 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
|
|
|
|
- [X] 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`
|
|
- [X] 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
|
|
|
|
- [X] 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`
|
|
- [X] 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`
|
|
- [X] 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.
|
|
|
|
- [X] 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`
|
|
- [X] 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`
|
|
- [X] 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`
|
|
- [X] 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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.
|