ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
136-admin-canonical-tenant
TenantAtlas/specs/130-structured-snapshot-rendering/tasks.md
ahmido 3c445709af feat: add structured baseline snapshot rendering (#158) 
## Summary
- replace the baseline snapshot detail page with a structured summary-first rendering flow
- add a presenter plus renderer registry with RBAC, compliance, and fallback renderers
- add grouped policy-type browsing, fidelity and gap badges, and workspace authorization coverage
- add Feature 130 spec, plan, contract, research, quickstart, and completed task artifacts

## Testing
- focused Pest coverage was added for structured rendering, fallback behavior, degraded states, authorization, presenter logic, renderer resolution, and badge mapping
- I did not rerun the full validation suite in this final PR step

## Notes
- base branch: `dev`
- feature branch: `130-structured-snapshot-rendering`

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #158
2026-03-10 08:28:06 +00:00

15 KiB
Raw Permalink Blame History

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.

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

  • 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
  • T005 [P] Create rendering support value objects in app/Services/Baselines/SnapshotRendering/FidelityState.php and app/Services/Baselines/SnapshotRendering/GapSummary.php
  • 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
  • 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

  • T008 [P] [US1] Add summary-first page assertions in tests/Feature/Filament/BaselineSnapshotStructuredRenderingTest.php
  • T009 [P] [US1] Add presenter summary aggregation assertions in tests/Unit/Baselines/SnapshotRendering/BaselineSnapshotPresenterTest.php
  • 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

  • T011 [US1] Implement snapshot metadata and summary-row derivation in app/Services/Baselines/SnapshotRendering/BaselineSnapshotPresenter.php and app/Services/Baselines/SnapshotRendering/RenderedSnapshot.php
  • 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
  • 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
  • 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

  • T015 [P] [US2] Add mixed-type grouped-browser feature coverage in tests/Feature/Filament/BaselineSnapshotStructuredRenderingTest.php and tests/Feature/Filament/BaselineSnapshotFallbackRenderingTest.php
  • T016 [P] [US2] Add fallback and registry unit coverage in tests/Unit/Baselines/SnapshotRendering/FallbackSnapshotTypeRendererTest.php and tests/Unit/Baselines/SnapshotRendering/SnapshotTypeRendererRegistryTest.php
  • 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

  • T018 [US2] Implement the shared fallback renderer in app/Services/Baselines/SnapshotRendering/Renderers/FallbackSnapshotTypeRenderer.php
  • T019 [US2] Extract RBAC enrichment into app/Services/Baselines/SnapshotRendering/Renderers/IntuneRoleDefinitionSnapshotTypeRenderer.php and remove inline RBAC mapping from app/Filament/Resources/BaselineSnapshotResource.php
  • T020 [US2] Add initial compliance rendering in app/Services/Baselines/SnapshotRendering/Renderers/DeviceComplianceSnapshotTypeRenderer.php
  • T021 [US2] Wire renderer resolution and grouped item output into app/Services/Baselines/SnapshotRendering/BaselineSnapshotPresenter.php and app/Services/Baselines/SnapshotRendering/SnapshotTypeRendererRegistry.php
  • 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

  • T023 [P] [US3] Add degraded-state and technical-detail feature coverage in tests/Feature/Filament/BaselineSnapshotDegradedStateTest.php
  • 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
  • T025 [P] [US3] Add fidelity and gap badge mapping coverage in tests/Unit/Support/Badges/BaselineSnapshotRenderingBadgeTest.php

Implementation for User Story 3

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

  • T031 [P] Run the focused Feature 130 validation commands from specs/130-structured-snapshot-rendering/quickstart.md
  • 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

# 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

# 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

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