ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
d4fb886de0
TenantAtlas/specs/133-detail-page-template/tasks.md
ahmido d4fb886de0 feat: standardize enterprise detail pages (#162) 
## Summary
- introduce a shared enterprise-detail composition layer for Filament detail pages
- migrate BackupSet, BaselineSnapshot, EntraGroup, and OperationRun detail screens to the shared summary-first layout
- add regression and unit coverage for section hierarchy, related context, degraded states, and duplicate fact/badge presentation

## Scope
- adds shared support classes under `app/Support/Ui/EnterpriseDetail`
- adds shared enterprise detail Blade partials under `resources/views/filament/infolists/entries/enterprise-detail`
- updates touched Filament resources/pages to use the shared detail shell
- includes Spec 133 artifacts under `specs/133-detail-page-template`

## Notes
- branch: `133-detail-page-template`
- base: `dev`
- commit: `fd294c7`

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

15 KiB
Raw Blame History

Tasks: View Page Template Standard for Enterprise Detail Screens

Input: Design documents from /specs/133-detail-page-template/ Prerequisites: plan.md, spec.md, research.md, data-model.md, contracts/enterprise-detail-pages.openapi.yaml

Tests: Tests are REQUIRED for this feature because it changes runtime behavior on existing Filament detail pages.

Phase 1: Setup (Shared Infrastructure)

Purpose: Create the shared implementation and test locations used by all story work.

  • T001 Create the shared enterprise-detail support namespace in app/Support/Ui/EnterpriseDetail/.gitkeep
  • T002 Create the shared enterprise-detail view partial directory in resources/views/filament/infolists/entries/enterprise-detail/.gitkeep
  • T003 Create the shared unit-test directory in tests/Unit/Support/Ui/EnterpriseDetail/.gitkeep
  • T004 Create the feature-test entry points in tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php, tests/Feature/Filament/BackupSetEnterpriseDetailPageTest.php, tests/Feature/Filament/EntraGroupEnterpriseDetailPageTest.php, and tests/Feature/Filament/EnterpriseDetailTemplateRegressionTest.php

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Build the shared enterprise-detail composition layer before refactoring any target page.

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

  • T005 Create shared page-model value objects in app/Support/Ui/EnterpriseDetail/EnterpriseDetailPageData.php, app/Support/Ui/EnterpriseDetail/SummaryHeaderData.php, app/Support/Ui/EnterpriseDetail/DetailSectionData.php, app/Support/Ui/EnterpriseDetail/SupportingCardData.php, app/Support/Ui/EnterpriseDetail/TechnicalDetailData.php, and app/Support/Ui/EnterpriseDetail/PageActionData.php
  • T006 Create the shared composition builders in app/Support/Ui/EnterpriseDetail/EnterpriseDetailBuilder.php and app/Support/Ui/EnterpriseDetail/EnterpriseDetailSectionFactory.php
  • T007 [P] Create shared summary, supporting-card, technical-detail, and empty-state partials in resources/views/filament/infolists/entries/enterprise-detail/header.blade.php, resources/views/filament/infolists/entries/enterprise-detail/supporting-card.blade.php, resources/views/filament/infolists/entries/enterprise-detail/technical-detail.blade.php, and resources/views/filament/infolists/entries/enterprise-detail/empty-state.blade.php
  • T008 [P] Add shared composition unit coverage in tests/Unit/Support/Ui/EnterpriseDetail/EnterpriseDetailBuilderTest.php and tests/Unit/Support/Ui/EnterpriseDetail/SectionVisibilityTest.php

Checkpoint: Shared enterprise-detail infrastructure is ready; user story work can now begin.

Phase 3: User Story 1 - Understand The Record Quickly (Priority: P1) 🎯 MVP

Goal: Make all target detail pages summary-first so operators can identify the record, its current state, and core context before reading raw fields.

Independent Test: Open each target detail page and confirm that title, state, and high-signal summary content render before any technical-detail section or raw metadata block.

Tests for User Story 1

  • T009 [P] [US1] Extend summary-first snapshot coverage in tests/Feature/Filament/BaselineSnapshotStructuredRenderingTest.php
  • T010 [P] [US1] Add operation-run summary hierarchy assertions in tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php
  • T011 [P] [US1] Add backup-set summary hierarchy assertions in tests/Feature/Filament/BackupSetEnterpriseDetailPageTest.php
  • T012 [P] [US1] Add EntraGroup summary hierarchy assertions in tests/Feature/Filament/EntraGroupEnterpriseDetailPageTest.php

Implementation for User Story 1

  • T013 [US1] Refactor app/Filament/Resources/OperationRunResource.php to emit shared summary-first run sections instead of a flat primary field sequence
  • T014 [US1] Refactor app/Filament/Pages/Operations/TenantlessOperationRunViewer.php to render the shared enterprise-detail shell for run detail
  • T015 [US1] Refactor app/Services/Baselines/SnapshotRendering/BaselineSnapshotPresenter.php to populate shared summary-header and primary-section data
  • T016 [US1] Refactor app/Filament/Resources/BaselineSnapshotResource/Pages/ViewBaselineSnapshot.php to render snapshot summary and content sections through the shared shell
  • T017 [US1] Refactor app/Filament/Resources/BackupSetResource.php and app/Filament/Resources/BackupSetResource/Pages/ViewBackupSet.php to replace flat field output with summary-first lifecycle sections
  • T018 [US1] Refactor app/Filament/Resources/EntraGroupResource.php and app/Filament/Resources/EntraGroupResource/Pages/ViewEntraGroup.php to promote group identity and classification ahead of raw provider data

Checkpoint: User Story 1 is complete when all four target pages are summary-first and independently testable.

Phase 4: User Story 2 - Triage And Navigate From Related Context (Priority: P2)

Goal: Give operators predictable related-context regions, supporting cards, and action placement so they can decide what to inspect next without hunting through fields.

Independent Test: Open each target detail page and verify that related context appears in a dedicated region, status and timestamps live in supporting cards, and page-level actions remain in predictable header positions.

Tests for User Story 2

  • T019 [P] [US2] Extend snapshot related-context coverage in tests/Feature/Filament/BaselineSnapshotRelatedContextTest.php
  • T020 [P] [US2] Add operation-run related-context and action-placement assertions in tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php
  • T021 [P] [US2] Extend backup-set related navigation assertions in tests/Feature/Filament/BackupSetRelatedNavigationTest.php and tests/Feature/Filament/BackupSetEnterpriseDetailPageTest.php
  • T022 [P] [US2] Add EntraGroup related-context and navigation assertions in tests/Feature/Filament/EntraGroupEnterpriseDetailPageTest.php

Implementation for User Story 2

  • T023 [US2] Update app/Support/Ui/EnterpriseDetail/EnterpriseDetailBuilder.php and app/Support/Ui/EnterpriseDetail/PageActionData.php to support supporting-card actions, related-context slots, and header action placement
  • T024 [US2] Update app/Support/Navigation/RelatedNavigationResolver.php to provide any missing permission-aware related-context entries needed by the aligned target pages
  • T025 [US2] Update app/Filament/Resources/OperationRunResource.php and app/Filament/Pages/Operations/TenantlessOperationRunViewer.php to move run actions, target scope, and related artifacts into shared header and supporting regions
  • T026 [US2] Update app/Filament/Resources/BaselineSnapshotResource.php and app/Filament/Resources/BaselineSnapshotResource/Pages/ViewBaselineSnapshot.php to surface governance context and primary related navigation in the shared layout zones
  • T027 [US2] Update app/Filament/Resources/BackupSetResource.php and app/Filament/Resources/BackupSetResource/Pages/ViewBackupSet.php to surface related operations, timestamps, and grouped header actions in the shared shell
  • T028 [US2] Update app/Filament/Resources/EntraGroupResource.php and app/Filament/Resources/EntraGroupResource/Pages/ViewEntraGroup.php to surface tenant or governance context and any canonical related navigation in the shared shell
  • T029 [US2] Update tests/Feature/Guards/ActionSurfaceContractTest.php for the changed view-header expectations in app/Filament/Resources/BaselineSnapshotResource.php, app/Filament/Resources/BackupSetResource.php, app/Filament/Resources/EntraGroupResource.php, and app/Filament/Resources/OperationRunResource.php

Checkpoint: User Story 2 is complete when all four target pages expose predictable related-context and action-placement behavior.

Phase 5: User Story 3 - Stay Oriented When Data Is Sparse Or Partial (Priority: P3)

Goal: Make the aligned detail pages degrade gracefully when related records, optional sections, or technical metadata are missing or incomplete.

Independent Test: Render each target page with sparse or incomplete data and confirm that it still shows a complete page shell, explicit empty or degraded states, and secondary technical-detail treatment.

Tests for User Story 3

  • T030 [P] [US3] Extend degraded snapshot coverage in tests/Feature/Filament/BaselineSnapshotDegradedStateTest.php
  • T031 [P] [US3] Add backup-set empty and degraded-state assertions in tests/Feature/Filament/BackupSetEnterpriseDetailPageTest.php
  • T032 [P] [US3] Add EntraGroup empty and degraded related-context assertions in tests/Feature/Filament/EntraGroupEnterpriseDetailPageTest.php
  • T033 [P] [US3] Add sparse run metadata and failure-context fallback assertions in tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php

Implementation for User Story 3

  • T034 [US3] Update app/Support/Ui/EnterpriseDetail/TechnicalDetailData.php and resources/views/filament/infolists/entries/enterprise-detail/technical-detail.blade.php to keep technical detail secondary and collapsible by default
  • T035 [US3] Update app/Support/Ui/EnterpriseDetail/EnterpriseDetailSectionFactory.php and resources/views/filament/infolists/entries/enterprise-detail/empty-state.blade.php to render explicit empty and degraded section states
  • T036 [US3] Update app/Filament/Resources/OperationRunResource.php and app/Filament/Pages/Operations/TenantlessOperationRunViewer.php to handle sparse target-scope, missing failures, and technical fallback states
  • T037 [US3] Update app/Filament/Resources/BackupSetResource.php and app/Filament/Resources/EntraGroupResource.php to keep low-signal metadata in technical sections and render intentional empty states
  • T038 [US3] Update app/Filament/Resources/BaselineSnapshotResource/Pages/ViewBaselineSnapshot.php and app/Services/Baselines/SnapshotRendering/BaselineSnapshotPresenter.php to preserve intentional fallback copy for missing snapshot context

Checkpoint: User Story 3 is complete when sparse-data and degraded-state scenarios remain readable across all aligned pages.

Phase 6: Polish & Cross-Cutting Concerns

Purpose: Lock in cross-target consistency, naming, verification, and formatting.

  • T039 [P] Add cross-target layout-regression coverage in tests/Feature/Filament/EnterpriseDetailTemplateRegressionTest.php
  • T040 Update operator-facing section titles and action labels in app/Filament/Resources/BackupSetResource.php, app/Filament/Resources/EntraGroupResource.php, app/Filament/Resources/OperationRunResource.php, and resources/views/filament/infolists/entries/enterprise-detail/header.blade.php to align UI-NAMING-001
  • T041 Run the focused validation commands documented in specs/133-detail-page-template/quickstart.md
  • T042 Run formatting on touched files with vendor/bin/sail bin pint --dirty --format agent from /Users/ahmeddarrazi/Documents/projects/TenantAtlas

Dependencies & Execution Order

Phase Dependencies

  • Setup (Phase 1): No dependencies; can start immediately.
  • Foundational (Phase 2): Depends on Setup completion; blocks all user-story implementation.
  • User Stories (Phases 3-5): Depend on Foundational completion.
  • Polish (Phase 6): Depends on the desired user stories being complete.

User Story Dependencies

  • User Story 1 (P1): Starts after Foundational and delivers the MVP by making all target pages summary-first.
  • User Story 2 (P2): Starts after Foundational and builds on US1’s shared shell to add structured related context and predictable action placement.
  • User Story 3 (P3): Starts after Foundational and builds on US1 and US2 to harden degraded-state handling and technical-detail demotion.

Within Each User Story

  • Write or update the story tests first and confirm they fail against the pre-change behavior.
  • Refactor shared builders before modifying page classes that consume them.
  • Update page-specific presenters before finalizing the corresponding view pages.
  • Finish story-level verification before moving to the next priority.

Parallel Opportunities

  • T007 and T008 can run in parallel after T005 and T006.
  • In US1, T009 through T012 can run in parallel, then T013 through T018 proceed in implementation order by target page.
  • In US2, T019 through T022 can run in parallel, then T024 can proceed before the page-specific refactors T025 through T028.
  • In US3, T030 through T033 can run in parallel, then T034 and T035 can proceed before the page-specific hardening tasks T036 through T038.
  • T039 and T040 can run in parallel once the story phases are complete.

Parallel Example: User Story 1

# Launch the summary-first page tests together:
Task: "Extend summary-first snapshot coverage in tests/Feature/Filament/BaselineSnapshotStructuredRenderingTest.php"
Task: "Add operation-run summary hierarchy assertions in tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php"
Task: "Add backup-set summary hierarchy assertions in tests/Feature/Filament/BackupSetEnterpriseDetailPageTest.php"
Task: "Add EntraGroup summary hierarchy assertions in tests/Feature/Filament/EntraGroupEnterpriseDetailPageTest.php"

Parallel Example: User Story 2

# Launch the related-context regression tests together:
Task: "Extend snapshot related-context coverage in tests/Feature/Filament/BaselineSnapshotRelatedContextTest.php"
Task: "Add operation-run related-context and action-placement assertions in tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php"
Task: "Extend backup-set related navigation assertions in tests/Feature/Filament/BackupSetRelatedNavigationTest.php and tests/Feature/Filament/BackupSetEnterpriseDetailPageTest.php"
Task: "Add EntraGroup related-context and navigation assertions in tests/Feature/Filament/EntraGroupEnterpriseDetailPageTest.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 the four target pages for summary-first structure before moving on.

Incremental Delivery

  1. Finish Setup and Foundational shared-layer work.
  2. Deliver User Story 1 to standardize the default reading path.
  3. Deliver User Story 2 to add structured navigation and contextual action placement.
  4. Deliver User Story 3 to harden sparse-data and degraded-state behavior.
  5. Finish with cross-target regression checks, quickstart validation, and formatting.

Parallel Team Strategy

  1. One contributor builds the shared enterprise-detail layer and unit tests.
  2. After foundation is ready, contributors can split by target-page refactors inside the active story phase.
  3. One contributor finalizes cross-target regression and guard coverage while another runs the focused Sail test pack and Pint.

Notes

  • [P] tasks touch different files and can be executed in parallel.
  • User-story labels map directly to the prioritized stories in spec.md.
  • All four target pages are intentionally included in each user-story phase so the standard converges across the full initial scope.
  • Tests are mandatory in this repo for every runtime change.