Ahmed Darrazi fd294c7b0e feat: standardize enterprise detail pages

2026-03-11 00:05:33 +01: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.

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)

Complete Phase 1: Setup.
Complete Phase 2: Foundational.
Complete Phase 3: User Story 1.
Validate the four target pages for summary-first structure before moving on.

Incremental Delivery

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

Parallel Team Strategy

One contributor builds the shared enterprise-detail layer and unit tests.
After foundation is ready, contributors can split by target-page refactors inside the active story phase.
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.

15 KiB Raw Blame History Unescape Escape