ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
3c38192405
TenantAtlas/specs/198-monitoring-page-state/quickstart.md
ahmido e02799b383 feat: implement spec 198 monitoring page state contract (#238) 
## Summary
- implement Spec 198 monitoring page-state contracts across Operations, Audit Log, Finding Exceptions Queue, Evidence Overview, Baseline Compare Landing, and Baseline Compare Matrix
- align selected-record and draft/apply behavior with query/session restoration semantics, including canonical navigation and tenant-filter normalization helpers
- add Spec 198 feature and browser coverage, update closure/spec artifacts, and refresh affected regression tests that asserted pre-contract behavior

## Verification
- focused Spec 198 feature pack passed through Sail
- Spec 198 browser smoke passed through Sail
- existing Spec 190 and Spec 194 browser smokes passed through Sail
- targeted fallout tests were updated and rerun during full-suite triage

## Notes
- Livewire v4 / Filament v5 compliant only; no legacy API reintroduction
- no provider registration changes; Laravel 11+ provider registration remains in `bootstrap/providers.php`
- no global-search behavior changed for any resource
- destructive queue decision actions remain confirmation-gated and authorization-backed
- no new Filament assets were added; existing deploy step for `php artisan filament:assets` remains unchanged

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #238
2026-04-15 21:59:42 +00:00

117 lines
8.8 KiB
Markdown
Raw Blame History

# Quickstart: Monitoring Page-State Contract
## Goal
Bring the in-scope monitoring and governance pages under one bounded page-state contract so operators can predict how deeplinks, tabs, filters, selected-record detail, draft/apply behavior, refresh, back, and shared links behave.
## Implementation Sequence
1. Declare the contract on the in-scope pages.
- Make contextual prefilter, active, draft, inspect, and shareable/restorable state explicit on Operations, Audit Log, Finding Exceptions Queue, Evidence Overview, Baseline Compare Landing, and Baseline Compare Matrix.
- Define the invalid-state fallback for each page.
2. Standardize the simple monitoring pages.
- Align Operations query/session precedence for requested dashboard context, tenant prefilter, active tab, and persisted table state.
- Align Evidence Overview query hydration, filter clearing, and restorable filter behavior.
3. Unify the selected-record inspect pages.
- Ensure Audit Log uses one selected-event inspect model for action-based inspect, deeplink entry, close detail, and refresh.
- Ensure Finding Exceptions Queue uses one selected-exception workbench model for inspect, summary, decision actions, close detail, and refresh.
4. Keep Compare Matrix explicitly special.
- Treat Baseline Compare Landing as launch context only.
- Keep Baseline Compare Matrix split into draft state, applied state, and focus state.
- Ensure unapplied draft state never becomes shareable or restorable.
5. Add regression protection.
- Add one narrow cross-surface contract test.
- Extend the existing Operations, Audit Log, Finding Exceptions Queue, Evidence Overview, Baseline Compare Landing, Baseline Compare Matrix, and table-persistence suites.
- Add one focused browser smoke suite for state restoration and navigation behavior.
## Suggested Source Files
- `apps/platform/app/Filament/Pages/Monitoring/Operations.php`
- `apps/platform/app/Filament/Pages/Monitoring/AuditLog.php`
- `apps/platform/app/Filament/Pages/Monitoring/FindingExceptionsQueue.php`
- `apps/platform/app/Filament/Pages/Monitoring/EvidenceOverview.php`
- `apps/platform/app/Filament/Pages/BaselineCompareLanding.php`
- `apps/platform/app/Filament/Pages/BaselineCompareMatrix.php`
- `apps/platform/app/Support/Filament/CanonicalAdminTenantFilterState.php`
- `apps/platform/app/Support/Navigation/CanonicalNavigationContext.php`
- `apps/platform/resources/views/filament/pages/monitoring/operations.blade.php`
- `apps/platform/resources/views/filament/pages/monitoring/audit-log.blade.php`
- `apps/platform/resources/views/filament/pages/monitoring/partials/audit-log-inspect-event.blade.php`
- `apps/platform/resources/views/filament/pages/monitoring/finding-exceptions-queue.blade.php`
- `apps/platform/resources/views/filament/pages/monitoring/evidence-overview.blade.php`
- `apps/platform/resources/views/filament/pages/baseline-compare-landing.blade.php`
- `apps/platform/resources/views/filament/pages/baseline-compare-matrix.blade.php`
## Suggested Test Files
- `apps/platform/tests/Feature/Monitoring/MonitoringPageStateContractTest.php`
- `apps/platform/tests/Feature/Monitoring/OperationsDashboardDrillthroughTest.php`
- `apps/platform/tests/Feature/Monitoring/AuditLogInspectFlowTest.php`
- `apps/platform/tests/Feature/Monitoring/FindingExceptionsQueueHierarchyTest.php`
- `apps/platform/tests/Feature/Evidence/EvidenceOverviewPageTest.php`
- `apps/platform/tests/Feature/Filament/BaselineCompareLandingStartSurfaceTest.php`
- `apps/platform/tests/Feature/Filament/BaselineCompareMatrixPageTest.php`
- `apps/platform/tests/Feature/Filament/TableStatePersistenceTest.php`
- `apps/platform/tests/Feature/Rbac/BaselineCompareMatrixAuthorizationTest.php`
- `apps/platform/tests/Browser/Spec198MonitoringPageStateSmokeTest.php`
## Minimum Verification Commands
Run all commands through Sail from `apps/platform`.
```bash
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Monitoring/MonitoringPageStateContractTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Monitoring/OperationsDashboardDrillthroughTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Monitoring/AuditLogInspectFlowTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Monitoring/FindingExceptionsQueueHierarchyTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Evidence/EvidenceOverviewPageTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/BaselineCompareLandingStartSurfaceTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/BaselineCompareMatrixPageTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/TableStatePersistenceTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/Spec198MonitoringPageStateSmokeTest.php
cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent
```
## Manual Acceptance Checklist
1. Open Operations directly and from a KPI or drillthrough link, change tabs and filters, and confirm refresh and reopen behavior matches the documented contract.
2. Open Audit Log with and without a selected event and confirm inspect action, selected-event deeplink, close detail, and refresh all use the same selected-event model.
3. Open Finding Exceptions Queue with and without a selected exception and confirm summary, decision actions, close detail, and refresh all use the same selected-exception model.
4. Open Evidence Overview with prefilter state, clear filters, and confirm refresh or reopen behavior stays predictable and simple.
5. Open Baseline Compare Landing and launch the matrix with subject context, then confirm the matrix owns applied compare state after hydration.
6. On Baseline Compare Matrix, change draft filters without applying them, confirm applied results do not move, then apply and verify the new results and focused subject restore correctly.
7. Use browser back on the in-scope pages and confirm selected detail, active filters, and shareable state match the documented restore or discard behavior.
## Deployment Notes
- No migration is expected.
- No provider registration change is expected; Laravel 11+ provider registration remains in `bootstrap/providers.php`.
- No new asset registration is expected. Existing deployment handling of `cd apps/platform && php artisan filament:assets` remains sufficient.
## Final Implemented State Mapping
1. Operations restores the entitled `tenant_id`, the selected `activeTab`, and compatible table filters/search. It does not keep a competing same-page inspect state.
2. Audit Log restores filters/search and the `event` query parameter only while the selected event is still visible and authorized; otherwise it falls back to the unselected history view.
3. Finding Exceptions Queue restores queue filters and the `exception` query parameter only while the selected request is still visible and authorized; otherwise it falls back to quiet monitoring mode.
4. Evidence Overview keeps only the simple monitoring filter/search contract. Clearing filters redirects back to the canonical overview route without hidden residual state.
5. Baseline Compare Landing is launch-context only. It can hand valid context into the matrix, but it never owns applied compare state.
6. Baseline Compare Matrix restores applied compare filters, presentation mode, and focused subject through the URL. Unapplied draft filters remain local and are discarded on reopen or refresh.
## Verification Results
The contract was verified with the following passing commands run through Sail:
```bash
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Monitoring/MonitoringPageStateContractTest.php tests/Feature/Monitoring/OperationsDashboardDrillthroughTest.php tests/Feature/Monitoring/AuditLogInspectFlowTest.php tests/Feature/Monitoring/FindingExceptionsQueueHierarchyTest.php tests/Feature/Monitoring/FindingExceptionsQueueTest.php tests/Feature/Evidence/EvidenceOverviewPageTest.php tests/Feature/Filament/BaselineCompareLandingStartSurfaceTest.php tests/Feature/Filament/BaselineCompareMatrixPageTest.php tests/Feature/Filament/TableStatePersistenceTest.php tests/Feature/Rbac/ActionSurfaceRbacSemanticsTest.php tests/Feature/Rbac/BaselineCompareMatrixAuthorizationTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/Spec198MonitoringPageStateSmokeTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/Spec190BaselineCompareMatrixSmokeTest.php tests/Browser/Spec194GovernanceFrictionSmokeTest.php
cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent
```
## Spec 199 Boundary
This spec normalizes page-owned state only. Global shell behavior, remembered workspace or tenant context before page hydration, and any future cross-shell state contract remain a Spec 199 concern.
Reference in New Issue View Git Blame Copy Permalink