198 lines
15 KiB
Markdown
198 lines
15 KiB
Markdown
# Tasks: Structured Snapshot Rendering & Type-Agnostic Item Browser
|
|
|
|
**Input**: Design documents from `/specs/130-structured-snapshot-rendering/`
|
|
**Prerequisites**: plan.md, spec.md, research.md, data-model.md, contracts/baseline-snapshot-rendering.openapi.yaml, quickstart.md
|
|
|
|
**Tests**: Tests are REQUIRED for this feature because it changes runtime rendering, authorization-visible behavior, and centralized badge semantics.
|
|
**Operations**: No new `OperationRun`, queued workflow, or audit-log mutation flow is introduced.
|
|
**RBAC**: The feature stays on the workspace-scoped `/admin` plane. Non-member or out-of-scope access must remain 404, and protected in-scope access must remain 403 where applicable.
|
|
**Filament UI**: The feature modifies the existing `BaselineSnapshotResource` detail surface and must preserve its immutable-resource action-surface exemptions while moving the page to a summary-first infolist layout.
|
|
**Badges**: Fidelity and gap states must use centralized badge semantics through `BadgeCatalog` and `BadgeRenderer`.
|
|
|
|
## Phase 1: Setup (Shared Infrastructure)
|
|
|
|
**Purpose**: Create the test and view scaffolding used across the feature.
|
|
|
|
- [X] T001 Create feature-test scaffolds in tests/Feature/Filament/BaselineSnapshotStructuredRenderingTest.php, tests/Feature/Filament/BaselineSnapshotFallbackRenderingTest.php, tests/Feature/Filament/BaselineSnapshotAuthorizationTest.php, and tests/Feature/Filament/BaselineSnapshotDegradedStateTest.php
|
|
- [X] T002 Create unit-test scaffolds in tests/Unit/Baselines/SnapshotRendering/BaselineSnapshotPresenterTest.php, tests/Unit/Baselines/SnapshotRendering/SnapshotTypeRendererRegistryTest.php, tests/Unit/Baselines/SnapshotRendering/FallbackSnapshotTypeRendererTest.php, tests/Unit/Baselines/SnapshotRendering/IntuneRoleDefinitionSnapshotTypeRendererTest.php, tests/Unit/Baselines/SnapshotRendering/DeviceComplianceSnapshotTypeRendererTest.php, and tests/Unit/Support/Badges/BaselineSnapshotRenderingBadgeTest.php
|
|
- [X] T003 [P] Create detail-view entry stubs in resources/views/filament/infolists/entries/baseline-snapshot-summary-table.blade.php, resources/views/filament/infolists/entries/baseline-snapshot-groups.blade.php, and resources/views/filament/infolists/entries/baseline-snapshot-technical-detail.blade.php
|
|
|
|
---
|
|
|
|
## Phase 2: Foundational (Blocking Prerequisites)
|
|
|
|
**Purpose**: Build the normalized rendering primitives and registry that every story depends on.
|
|
|
|
**⚠️ CRITICAL**: No user story work should begin until this phase is complete.
|
|
|
|
- [X] T004 [P] Create normalized rendering DTOs in app/Services/Baselines/SnapshotRendering/RenderedSnapshot.php, app/Services/Baselines/SnapshotRendering/RenderedSnapshotGroup.php, app/Services/Baselines/SnapshotRendering/RenderedSnapshotItem.php, and app/Services/Baselines/SnapshotRendering/RenderedAttribute.php
|
|
- [X] T005 [P] Create rendering support value objects in app/Services/Baselines/SnapshotRendering/FidelityState.php and app/Services/Baselines/SnapshotRendering/GapSummary.php
|
|
- [X] T006 Implement the renderer contract and registry in app/Services/Baselines/SnapshotRendering/SnapshotTypeRenderer.php, app/Services/Baselines/SnapshotRendering/SnapshotTypeRendererRegistry.php, and app/Providers/AppServiceProvider.php
|
|
- [X] T007 Implement the base page presenter in app/Services/Baselines/SnapshotRendering/BaselineSnapshotPresenter.php
|
|
|
|
**Checkpoint**: The normalized rendering layer exists and user-story work can proceed.
|
|
|
|
---
|
|
|
|
## Phase 3: User Story 1 - Review captured state by policy type (Priority: P1) 🎯 MVP
|
|
|
|
**Goal**: Make the snapshot page summary-first so operators can understand captured coverage before drilling into detail.
|
|
|
|
**Independent Test**: Open a mixed-policy snapshot and verify the first meaningful content block is a structured summary with one row per captured policy type and no raw JSON as the primary experience.
|
|
|
|
### Tests for User Story 1
|
|
|
|
- [X] T008 [P] [US1] Add summary-first page assertions in tests/Feature/Filament/BaselineSnapshotStructuredRenderingTest.php
|
|
- [X] T009 [P] [US1] Add presenter summary aggregation assertions in tests/Unit/Baselines/SnapshotRendering/BaselineSnapshotPresenterTest.php
|
|
- [X] T010 [P] [US1] Update list and detail regression coverage in tests/Feature/Filament/BaselineSnapshotFidelityVisibilityTest.php and tests/Feature/Filament/BaselineSnapshotStructuredRenderingTest.php to assert summary-first output and clickable-row or linked-column inspection instead of a lone View action
|
|
|
|
### Implementation for User Story 1
|
|
|
|
- [X] T011 [US1] Implement snapshot metadata and summary-row derivation in app/Services/Baselines/SnapshotRendering/BaselineSnapshotPresenter.php and app/Services/Baselines/SnapshotRendering/RenderedSnapshot.php
|
|
- [X] T012 [US1] Replace the raw summary-primary detail section in app/Filament/Resources/BaselineSnapshotResource.php and resources/views/filament/infolists/entries/baseline-snapshot-summary-table.blade.php
|
|
- [X] T013 [US1] Update the snapshot list inspect affordance in app/Filament/Resources/BaselineSnapshotResource.php so the modified resource uses clickable rows or a primary linked column instead of a lone View row action
|
|
- [X] T014 [US1] Update the snapshot detail page composition in app/Filament/Resources/BaselineSnapshotResource/Pages/ViewBaselineSnapshot.php and app/Filament/Resources/BaselineSnapshotResource.php so metadata renders before summary and grouped content
|
|
|
|
**Checkpoint**: The snapshot detail page is summary-first and independently useful even before richer grouped rendering lands.
|
|
|
|
---
|
|
|
|
## Phase 4: User Story 2 - Drill into any captured type consistently (Priority: P1)
|
|
|
|
**Goal**: Render every captured policy type through a grouped browser with fallback visibility and first-class RBAC and compliance detail.
|
|
|
|
**Independent Test**: Open a snapshot containing `intuneRoleDefinition`, `deviceCompliancePolicy`, and an unsupported type and verify that all three appear as grouped sections with stable minimum metadata and collapsed-by-default headers.
|
|
|
|
### Tests for User Story 2
|
|
|
|
- [X] T015 [P] [US2] Add mixed-type grouped-browser feature coverage in tests/Feature/Filament/BaselineSnapshotStructuredRenderingTest.php and tests/Feature/Filament/BaselineSnapshotFallbackRenderingTest.php
|
|
- [X] T016 [P] [US2] Add fallback and registry unit coverage in tests/Unit/Baselines/SnapshotRendering/FallbackSnapshotTypeRendererTest.php and tests/Unit/Baselines/SnapshotRendering/SnapshotTypeRendererRegistryTest.php
|
|
- [X] T017 [P] [US2] Add RBAC and compliance renderer contract tests in tests/Unit/Baselines/SnapshotRendering/IntuneRoleDefinitionSnapshotTypeRendererTest.php and tests/Unit/Baselines/SnapshotRendering/DeviceComplianceSnapshotTypeRendererTest.php
|
|
|
|
### Implementation for User Story 2
|
|
|
|
- [X] T018 [US2] Implement the shared fallback renderer in app/Services/Baselines/SnapshotRendering/Renderers/FallbackSnapshotTypeRenderer.php
|
|
- [X] T019 [US2] Extract RBAC enrichment into app/Services/Baselines/SnapshotRendering/Renderers/IntuneRoleDefinitionSnapshotTypeRenderer.php and remove inline RBAC mapping from app/Filament/Resources/BaselineSnapshotResource.php
|
|
- [X] T020 [US2] Add initial compliance rendering in app/Services/Baselines/SnapshotRendering/Renderers/DeviceComplianceSnapshotTypeRenderer.php
|
|
- [X] T021 [US2] Wire renderer resolution and grouped item output into app/Services/Baselines/SnapshotRendering/BaselineSnapshotPresenter.php and app/Services/Baselines/SnapshotRendering/SnapshotTypeRendererRegistry.php
|
|
- [X] T022 [US2] Build the collapsed grouped item browser in resources/views/filament/infolists/entries/baseline-snapshot-groups.blade.php and app/Filament/Resources/BaselineSnapshotResource.php
|
|
|
|
**Checkpoint**: Every captured policy type is visible and drill-down capable, with RBAC no longer acting as the only first-class inspected type.
|
|
|
|
---
|
|
|
|
## Phase 5: User Story 3 - Understand fidelity, gaps, and degraded states safely (Priority: P2)
|
|
|
|
**Goal**: Make incomplete rendering explicit, isolate per-group failures, and keep technical payloads secondary and authorized.
|
|
|
|
**Independent Test**: Render snapshots with partial, reference-only, unsupported, empty, and per-group failure conditions and verify the page remains usable, visibly degraded where appropriate, and secondary technical detail stays collapsed.
|
|
|
|
### Tests for User Story 3
|
|
|
|
- [X] T023 [P] [US3] Add degraded-state and technical-detail feature coverage in tests/Feature/Filament/BaselineSnapshotDegradedStateTest.php
|
|
- [X] T024 [P] [US3] Add workspace authorization and route-contract coverage in tests/Feature/Filament/BaselineSnapshotAuthorizationTest.php for list and detail 403 or 404 semantics plus optional technical-detail disclosure availability
|
|
- [X] T025 [P] [US3] Add fidelity and gap badge mapping coverage in tests/Unit/Support/Badges/BaselineSnapshotRenderingBadgeTest.php
|
|
|
|
### Implementation for User Story 3
|
|
|
|
- [X] T026 [US3] Add centralized fidelity and gap badge semantics in app/Support/Badges/BadgeDomain.php, app/Support/Badges/BadgeCatalog.php, app/Support/Badges/Domains/BaselineSnapshotFidelityBadge.php, and app/Support/Badges/Domains/BaselineSnapshotGapStatusBadge.php
|
|
- [X] T027 [US3] Implement explicit fidelity and gap derivation in app/Services/Baselines/SnapshotRendering/FidelityState.php, app/Services/Baselines/SnapshotRendering/GapSummary.php, and app/Services/Baselines/SnapshotRendering/BaselineSnapshotPresenter.php
|
|
- [X] T028 [US3] Add per-group failure isolation and degraded-state rendering in app/Services/Baselines/SnapshotRendering/BaselineSnapshotPresenter.php and resources/views/filament/infolists/entries/baseline-snapshot-groups.blade.php
|
|
- [X] T029 [US3] Add the secondary technical payload disclosure in resources/views/filament/infolists/entries/baseline-snapshot-technical-detail.blade.php and app/Filament/Resources/BaselineSnapshotResource.php
|
|
- [X] T030 [US3] Preserve workspace-scoped list and detail authorization, plus optional secondary technical-detail gating, in app/Filament/Resources/BaselineSnapshotResource.php and app/Filament/Resources/BaselineSnapshotResource/Pages/ViewBaselineSnapshot.php
|
|
|
|
**Checkpoint**: The page communicates degraded evidence quality clearly, keeps failures isolated, and preserves scope-safe access semantics.
|
|
|
|
---
|
|
|
|
## Phase 6: Polish & Cross-Cutting Concerns
|
|
|
|
**Purpose**: Final verification and cleanup across all stories.
|
|
|
|
- [X] T031 [P] Run the focused Feature 130 validation commands from specs/130-structured-snapshot-rendering/quickstart.md
|
|
- [X] T032 [P] Run formatting on changed files with vendor/bin/sail bin pint --dirty --format agent
|
|
|
|
---
|
|
|
|
## Dependencies & Execution Order
|
|
|
|
### Phase Dependencies
|
|
|
|
- **Setup (Phase 1)**: No dependencies; start immediately.
|
|
- **Foundational (Phase 2)**: Depends on Setup completion; blocks all user stories.
|
|
- **User Story 1 (Phase 3)**: Depends on Foundational completion.
|
|
- **User Story 2 (Phase 4)**: Depends on Foundational completion and is safest after User Story 1 because both modify the same snapshot detail surface.
|
|
- **User Story 3 (Phase 5)**: Depends on Foundational completion and is safest after User Story 2 because degraded-state handling wraps the grouped-browser output.
|
|
- **Polish (Phase 6)**: Depends on all selected user stories being complete.
|
|
|
|
### User Story Dependencies
|
|
|
|
- **User Story 1 (P1)**: No dependency on other stories after Foundational; this is the MVP slice.
|
|
- **User Story 2 (P1)**: Functionally independent after Foundational, but recommended after US1 to avoid page-composition conflicts on the same resource.
|
|
- **User Story 3 (P2)**: Depends on the shared rendering layer and grouped browser; recommended after US2.
|
|
|
|
### Within Each User Story
|
|
|
|
- Write or update tests first and confirm they fail before implementing behavior.
|
|
- Implement presenter and renderer logic before wiring Blade or Filament view composition.
|
|
- Land Blade view changes before final authorization and regression cleanup on the shared resource.
|
|
|
|
### Parallel Opportunities
|
|
|
|
- `T003`, `T004`, and `T005` can run in parallel after setup starts.
|
|
- `T008`, `T009`, and `T010` can run in parallel inside US1.
|
|
- `T015`, `T016`, and `T017` can run in parallel inside US2.
|
|
- `T023`, `T024`, and `T025` can run in parallel inside US3.
|
|
- `T031` and `T032` can run in parallel in the polish phase.
|
|
|
|
---
|
|
|
|
## Parallel Example: User Story 1
|
|
|
|
```bash
|
|
# Launch the summary-first test updates together:
|
|
Task: "Add summary-first page assertions in tests/Feature/Filament/BaselineSnapshotStructuredRenderingTest.php"
|
|
Task: "Add presenter summary aggregation assertions in tests/Unit/Baselines/SnapshotRendering/BaselineSnapshotPresenterTest.php"
|
|
Task: "Update list and detail regression coverage in tests/Feature/Filament/BaselineSnapshotFidelityVisibilityTest.php and tests/Feature/Filament/BaselineSnapshotStructuredRenderingTest.php to assert summary-first output and clickable-row or linked-column inspection instead of a lone View action"
|
|
```
|
|
|
|
## Parallel Example: User Story 2
|
|
|
|
```bash
|
|
# Launch the renderer-contract tests together:
|
|
Task: "Add fallback and registry unit coverage in tests/Unit/Baselines/SnapshotRendering/FallbackSnapshotTypeRendererTest.php and tests/Unit/Baselines/SnapshotRendering/SnapshotTypeRendererRegistryTest.php"
|
|
Task: "Add RBAC and compliance renderer contract tests in tests/Unit/Baselines/SnapshotRendering/IntuneRoleDefinitionSnapshotTypeRendererTest.php and tests/Unit/Baselines/SnapshotRendering/DeviceComplianceSnapshotTypeRendererTest.php"
|
|
```
|
|
|
|
## Parallel Example: User Story 3
|
|
|
|
```bash
|
|
# Launch the degraded-state and authorization test work together:
|
|
Task: "Add degraded-state and technical-detail feature coverage in tests/Feature/Filament/BaselineSnapshotDegradedStateTest.php"
|
|
Task: "Add workspace authorization and route-contract coverage in tests/Feature/Filament/BaselineSnapshotAuthorizationTest.php for list and detail 403 or 404 semantics plus optional technical-detail disclosure availability"
|
|
Task: "Add fidelity and gap badge mapping coverage in tests/Unit/Support/Badges/BaselineSnapshotRenderingBadgeTest.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 that the snapshot detail page is summary-first and no longer raw-JSON-primary.
|
|
|
|
### Incremental Delivery
|
|
|
|
1. Deliver US1 to establish the normalized summary-first page shell.
|
|
2. Deliver US2 to make every policy type visible and drill-down capable through fallback plus initial enrichments.
|
|
3. Deliver US3 to make fidelity, gaps, degraded states, and technical disclosure production-safe.
|
|
|
|
### Team Strategy
|
|
|
|
1. One engineer can own the presenter and registry foundation while another prepares the feature and unit tests.
|
|
2. After Foundational completes, one engineer can implement RBAC and compliance renderers while another builds the grouped Blade view.
|
|
3. Finish with a focused pass on badge centralization, authorization regressions, and Sail-based validation.
|