284 lines
18 KiB
Markdown
284 lines
18 KiB
Markdown
# Tasks: Monitoring Page-State Contract
|
|
|
|
**Input**: Design documents from `/specs/198-monitoring-page-state/`
|
|
**Prerequisites**: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/
|
|
|
|
**Tests**: For runtime behavior changes in this repo, tests are REQUIRED (Pest).
|
|
**Operations**: This feature does not create or reuse a new `OperationRun`; existing Monitoring and governance writes keep their current run, audit, and confirmation behavior.
|
|
**RBAC**: Authorization semantics remain unchanged, but tasks include negative-path coverage where requested query or selected-record state becomes unauthorized or invalid.
|
|
**UI Naming**: Operator-facing labels and helper copy must stay aligned with the spec's canonical vocabulary (`Operations`, `Audit log`, `Finding exceptions queue`, `Evidence overview`, `Baseline compare matrix`, `Inspect event`, `Approve exception`, `Reject exception`, `Apply filters`, `Reset filters`).
|
|
**Operator Surfaces**: Each changed page keeps the spec's declared surface role and single inspect/open model.
|
|
**Filament UI Action Surfaces**: All changed pages must preserve one primary inspect model, keep destructive-like actions confirmation-gated, and avoid introducing new page-local status or action frameworks.
|
|
**Proportionality / Anti-Bloat**: Keep the implementation surface-first and page-local; do not introduce a global page-state engine or new persistence.
|
|
|
|
**Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story.
|
|
|
|
## Phase 1: Setup (Shared Infrastructure)
|
|
|
|
**Purpose**: Prepare shared verification scaffolding for Spec 198 without changing runtime behavior yet.
|
|
|
|
- [X] T001 [P] Create the cross-surface contract test scaffold in `apps/platform/tests/Feature/Monitoring/MonitoringPageStateContractTest.php`
|
|
- [X] T002 [P] Create the Spec 198 browser smoke scaffold in `apps/platform/tests/Browser/Spec198MonitoringPageStateSmokeTest.php`
|
|
- [X] T003 [P] Extend the shared state-persistence harness in `apps/platform/tests/Feature/Filament/TableStatePersistenceTest.php`
|
|
|
|
---
|
|
|
|
## Phase 2: Foundational (Blocking Prerequisites)
|
|
|
|
**Purpose**: Establish the shared page-state contract structure and helper touchpoints before any surface-specific work begins.
|
|
|
|
**⚠️ CRITICAL**: No user story work can begin until this phase is complete.
|
|
|
|
- [X] T004 [P] Add explicit page-state contract declarations to `apps/platform/app/Filament/Pages/Monitoring/Operations.php`, `apps/platform/app/Filament/Pages/Monitoring/AuditLog.php`, `apps/platform/app/Filament/Pages/Monitoring/FindingExceptionsQueue.php`, and `apps/platform/app/Filament/Pages/Monitoring/EvidenceOverview.php`
|
|
- [X] T005 [P] Add explicit page-state contract declarations to `apps/platform/app/Filament/Pages/BaselineCompareLanding.php` and `apps/platform/app/Filament/Pages/BaselineCompareMatrix.php`
|
|
- [X] T006 [P] Align shared query/session/navigation normalization touchpoints in `apps/platform/app/Support/Filament/CanonicalAdminTenantFilterState.php` and `apps/platform/app/Support/Navigation/CanonicalNavigationContext.php`
|
|
- [X] T007 Update cross-surface state-class, query-role, invalid-fallback, and shared inspect-vocabulary assertions in `apps/platform/tests/Feature/Monitoring/MonitoringPageStateContractTest.php`
|
|
- [X] T008 Update tenant-sensitive persistence and restore-boundary assertions in `apps/platform/tests/Feature/Filament/TableStatePersistenceTest.php`
|
|
|
|
**Checkpoint**: Foundation ready. All user stories can now proceed independently.
|
|
|
|
---
|
|
|
|
## Phase 3: User Story 1 - Enter Operations Without Tab Drift (Priority: P1) 🎯 MVP
|
|
|
|
**Goal**: Make Operations use one deterministic contract for requested dashboard state, tenant prefilter, tabs, and persisted table state.
|
|
|
|
**Independent Test**: Open Operations directly and from KPI/drillthrough context, change tabs and filters, and confirm refresh or reopen behavior restores only the documented shareable state.
|
|
|
|
### Tests for User Story 1 ⚠️
|
|
|
|
> **NOTE**: Write these tests first, ensure they fail before implementation.
|
|
|
|
- [X] T009 [P] [US1] Extend deeplink, dashboard-prefilter, and unauthorized requested-tenant fallback coverage in `apps/platform/tests/Feature/Monitoring/OperationsDashboardDrillthroughTest.php` and `apps/platform/tests/Feature/Rbac/ActionSurfaceRbacSemanticsTest.php`
|
|
- [X] T010 [P] [US1] Extend Operations restorable tab/filter coverage in `apps/platform/tests/Feature/Filament/TableStatePersistenceTest.php`
|
|
|
|
### Implementation for User Story 1
|
|
|
|
- [X] T011 [US1] Align requested tenant, requested dashboard prefilter, and `activeTab` precedence in `apps/platform/app/Filament/Pages/Monitoring/Operations.php`
|
|
- [X] T012 [US1] Update explicit shareable/restorable tab and filter cues in `apps/platform/resources/views/filament/pages/monitoring/operations.blade.php`
|
|
|
|
**Checkpoint**: Operations behaves as a predictable simple monitoring surface and is testable independently.
|
|
|
|
---
|
|
|
|
## Phase 4: User Story 2 - Inspect Audit Events Through One Model (Priority: P1)
|
|
|
|
**Goal**: Make Audit Log use one selected-event inspect contract for action-based inspect, deeplink entry, close detail, and refresh.
|
|
|
|
**Independent Test**: Open Audit Log with and without a selected event, inspect an event, then refresh and back-navigate to confirm there is only one selected-event model.
|
|
|
|
### Tests for User Story 2 ⚠️
|
|
|
|
- [X] T013 [P] [US2] Extend selected-event hydration, invalid or unauthorized event fallback, and close-detail restoration coverage in `apps/platform/tests/Feature/Monitoring/AuditLogInspectFlowTest.php` and `apps/platform/tests/Feature/Rbac/ActionSurfaceRbacSemanticsTest.php`
|
|
- [X] T014 [P] [US2] Extend persisted filter and selected-event clear-state coverage in `apps/platform/tests/Feature/Filament/TableStatePersistenceTest.php`
|
|
|
|
### Implementation for User Story 2
|
|
|
|
- [X] T015 [US2] Make `selectedAuditLogId` the single inspect source in `apps/platform/app/Filament/Pages/Monitoring/AuditLog.php`
|
|
- [X] T016 [US2] Align inline event-detail rendering and close-detail controls in `apps/platform/resources/views/filament/pages/monitoring/audit-log.blade.php` and `apps/platform/resources/views/filament/pages/monitoring/partials/audit-log-inspect-event.blade.php`
|
|
|
|
**Checkpoint**: Audit Log is independently testable with one selected-event inspect model.
|
|
|
|
---
|
|
|
|
## Phase 5: User Story 3 - Review Finding Exceptions Through One Workbench State (Priority: P1)
|
|
|
|
**Goal**: Make Finding Exceptions Queue use one selected-exception workbench model for inspect, summary, decision actions, and refresh.
|
|
|
|
**Independent Test**: Open the queue with and without a selected exception and verify that summary, decision actions, and refresh behavior all derive from the same selected-exception state.
|
|
|
|
### Tests for User Story 3 ⚠️
|
|
|
|
- [X] T017 [P] [US3] Extend selected-exception hydration, invalid or unauthorized fallback, and selection-clearing coverage in `apps/platform/tests/Feature/Monitoring/FindingExceptionsQueueHierarchyTest.php` and `apps/platform/tests/Feature/Rbac/ActionSurfaceRbacSemanticsTest.php`
|
|
- [X] T018 [P] [US3] Extend calm-queue vs decision-ready state coverage in `apps/platform/tests/Feature/Monitoring/FindingExceptionsQueueTest.php`
|
|
|
|
### Implementation for User Story 3
|
|
|
|
- [X] T019 [US3] Make `selectedFindingExceptionId` the sole inspect/review state in `apps/platform/app/Filament/Pages/Monitoring/FindingExceptionsQueue.php`
|
|
- [X] T020 [US3] Align selected-exception summary and decision-lane rendering in `apps/platform/resources/views/filament/pages/monitoring/finding-exceptions-queue.blade.php`
|
|
|
|
**Checkpoint**: Finding Exceptions Queue is independently testable as one selected-exception workbench flow.
|
|
|
|
---
|
|
|
|
## Phase 6: User Story 4 - Keep Compare Matrix Explicitly Special (Priority: P1)
|
|
|
|
**Goal**: Preserve Baseline Compare Matrix as an explicit draft/apply special case while making launch-context, applied state, and focus state predictable.
|
|
|
|
**Independent Test**: Launch the matrix from the landing page, change draft filters without applying them, apply the new state, focus a subject, and verify what refresh, back, and a shared link restore.
|
|
|
|
### Tests for User Story 4 ⚠️
|
|
|
|
- [X] T021 [P] [US4] Extend launch-context hydration and focus handoff coverage in `apps/platform/tests/Feature/Filament/BaselineCompareLandingStartSurfaceTest.php`
|
|
- [X] T022 [P] [US4] Extend draft/apply, focus restoration, and draft discard coverage in `apps/platform/tests/Feature/Filament/BaselineCompareMatrixPageTest.php`
|
|
- [X] T023 [P] [US4] Extend invalid and unauthorized compare-context fallback coverage in `apps/platform/tests/Feature/Rbac/BaselineCompareMatrixAuthorizationTest.php`
|
|
|
|
### Implementation for User Story 4
|
|
|
|
- [X] T024 [US4] Treat compare landing context as initialization-only state in `apps/platform/app/Filament/Pages/BaselineCompareLanding.php` and `apps/platform/resources/views/filament/pages/baseline-compare-landing.blade.php`
|
|
- [X] T025 [US4] Separate draft, applied, focus, and shareable slices in `apps/platform/app/Filament/Pages/BaselineCompareMatrix.php`
|
|
- [X] T026 [US4] Surface draft/apply/focus semantics in `apps/platform/resources/views/filament/pages/baseline-compare-matrix.blade.php`
|
|
|
|
**Checkpoint**: Compare Matrix remains powerful but independently testable with explicit launch, draft/apply, and focus semantics.
|
|
|
|
---
|
|
|
|
## Phase 7: User Story 5 - Preserve Simple Monitoring Pages Without One-Off Protocols (Priority: P2)
|
|
|
|
**Goal**: Align Evidence Overview with the shared simple monitoring contract for query hydration, clear filters, and restorable filter behavior.
|
|
|
|
**Independent Test**: Enter Evidence Overview with prefilter state, clear filters, reopen or refresh the page, and confirm the page behaves like a simple monitoring surface without hidden local exceptions.
|
|
|
|
### Tests for User Story 5 ⚠️
|
|
|
|
- [X] T027 [P] [US5] Extend tenant/search hydration, clear-filter, and refresh coverage in `apps/platform/tests/Feature/Evidence/EvidenceOverviewPageTest.php`
|
|
|
|
### Implementation for User Story 5
|
|
|
|
- [X] T028 [US5] Align query hydration, session persistence, and simple-monitoring filter semantics in `apps/platform/app/Filament/Pages/Monitoring/EvidenceOverview.php`
|
|
- [X] T029 [US5] Update empty-state and clear-filter rendering for the simple monitoring contract in `apps/platform/resources/views/filament/pages/monitoring/evidence-overview.blade.php`
|
|
|
|
**Checkpoint**: Evidence Overview is independently testable as a simple monitoring surface.
|
|
|
|
---
|
|
|
|
## Phase 8: Polish & Cross-Cutting Concerns
|
|
|
|
**Purpose**: Final verification, browser coverage, closure documentation, and formatting across all stories.
|
|
|
|
- [X] T030 [P] Add cross-surface deeplink, refresh, back, and share smoke coverage in `apps/platform/tests/Browser/Spec198MonitoringPageStateSmokeTest.php`
|
|
- [X] T031 [P] Extend no-regression browser flows in `apps/platform/tests/Browser/Spec190BaselineCompareMatrixSmokeTest.php` and `apps/platform/tests/Browser/Spec194GovernanceFrictionSmokeTest.php`
|
|
- [X] T032 Run the focused Sail feature-test pack for `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/Monitoring/FindingExceptionsQueueTest.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/ActionSurfaceRbacSemanticsTest.php`, and `apps/platform/tests/Feature/Rbac/BaselineCompareMatrixAuthorizationTest.php`
|
|
- [X] T033 Execute the manual smoke checklist in `specs/198-monitoring-page-state/quickstart.md` against `/admin/operations`, `/admin/audit-log`, `/admin/finding-exceptions/queue`, `/admin/evidence/overview`, and the Baseline Compare routes
|
|
- [X] T034 [P] Update closure documentation in `specs/198-monitoring-page-state/spec.md` and `specs/198-monitoring-page-state/quickstart.md` with the final shareable/restorable-state mapping and any Spec 199 handoff notes
|
|
- [X] T035 Run `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent` over touched files under `apps/platform/app/Filament/Pages/`, `apps/platform/app/Support/`, `apps/platform/resources/views/filament/pages/`, and `apps/platform/tests/`
|
|
|
|
---
|
|
|
|
## Dependencies & Execution Order
|
|
|
|
### Phase Dependencies
|
|
|
|
- **Setup (Phase 1)**: No dependencies. Can start immediately.
|
|
- **Foundational (Phase 2)**: Depends on Setup completion. Blocks all user stories.
|
|
- **User Stories (Phases 3-7)**: All depend on Foundational completion.
|
|
- User Stories 1-4 are all Priority P1 and can proceed in parallel after Phase 2.
|
|
- User Story 5 is Priority P2 and can also proceed after Phase 2, but it is lower delivery priority.
|
|
- **Polish (Phase 8)**: Depends on all desired user stories being complete.
|
|
|
|
### User Story Dependencies
|
|
|
|
- **User Story 1 (P1)**: Can start after Foundational. No dependency on other stories.
|
|
- **User Story 2 (P1)**: Can start after Foundational. No dependency on other stories.
|
|
- **User Story 3 (P1)**: Can start after Foundational. No dependency on other stories.
|
|
- **User Story 4 (P1)**: Can start after Foundational. No dependency on other stories; landing and matrix work stay inside the same story.
|
|
- **User Story 5 (P2)**: Can start after Foundational. No dependency on other stories.
|
|
|
|
### Within Each User Story
|
|
|
|
- Tests MUST be written and fail before implementation.
|
|
- Page class state logic before Blade rendering updates.
|
|
- Query/session precedence before browser smoke validation.
|
|
- Story-specific verification before moving on to another story.
|
|
|
|
### Parallel Opportunities
|
|
|
|
- All Setup tasks marked `[P]` can run in parallel.
|
|
- Foundational tasks `T004`, `T005`, and `T006` can run in parallel.
|
|
- Once Foundational is complete, the test tasks for US1-US5 can run in parallel.
|
|
- User Stories 1-4 can be implemented in parallel by different developers after Phase 2.
|
|
- Browser smoke additions `T030` and `T031` can run in parallel once story behavior is stable.
|
|
|
|
---
|
|
|
|
## Parallel Example: User Story 1
|
|
|
|
```bash
|
|
# Launch both Operations test tracks together:
|
|
Task T009 - Extend deeplink and dashboard-prefilter hydration coverage in apps/platform/tests/Feature/Monitoring/OperationsDashboardDrillthroughTest.php
|
|
Task T010 - Extend Operations restorable tab/filter coverage in apps/platform/tests/Feature/Filament/TableStatePersistenceTest.php
|
|
```
|
|
|
|
---
|
|
|
|
## Parallel Example: User Story 2
|
|
|
|
```bash
|
|
# Launch both Audit Log test tracks together:
|
|
Task T013 - Extend selected-event hydration, invalid event fallback, and close-detail restoration coverage in apps/platform/tests/Feature/Monitoring/AuditLogInspectFlowTest.php
|
|
Task T014 - Extend persisted filter and selected-event clear-state coverage in apps/platform/tests/Feature/Filament/TableStatePersistenceTest.php
|
|
```
|
|
|
|
---
|
|
|
|
## Parallel Example: User Story 3
|
|
|
|
```bash
|
|
# Launch both Finding Exceptions Queue test tracks together:
|
|
Task T017 - Extend selected-exception hydration, invalid fallback, and selection-clearing coverage in apps/platform/tests/Feature/Monitoring/FindingExceptionsQueueHierarchyTest.php
|
|
Task T018 - Extend calm-queue vs decision-ready state coverage in apps/platform/tests/Feature/Monitoring/FindingExceptionsQueueTest.php
|
|
```
|
|
|
|
---
|
|
|
|
## Parallel Example: User Story 4
|
|
|
|
```bash
|
|
# Launch all Compare Matrix verification tasks together:
|
|
Task T021 - Extend launch-context hydration and focus handoff coverage in apps/platform/tests/Feature/Filament/BaselineCompareLandingStartSurfaceTest.php
|
|
Task T022 - Extend draft/apply, focus restoration, and draft discard coverage in apps/platform/tests/Feature/Filament/BaselineCompareMatrixPageTest.php
|
|
Task T023 - Extend invalid and unauthorized compare-context fallback coverage in apps/platform/tests/Feature/Rbac/BaselineCompareMatrixAuthorizationTest.php
|
|
```
|
|
|
|
---
|
|
|
|
## Parallel Example: User Story 5
|
|
|
|
```bash
|
|
# Evidence Overview can start alongside any P1 story once Phase 2 is complete:
|
|
Task T027 - Extend tenant/search hydration, clear-filter, and refresh coverage in apps/platform/tests/Feature/Evidence/EvidenceOverviewPageTest.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. **STOP and VALIDATE**: Test User Story 1 independently.
|
|
5. Demo or ship the Operations state contract before moving to additional surfaces.
|
|
|
|
### Incremental Delivery
|
|
|
|
1. Complete Setup + Foundational → foundation ready.
|
|
2. Add User Story 1 → test independently → deploy/demo.
|
|
3. Add User Story 2 → test independently → deploy/demo.
|
|
4. Add User Story 3 → test independently → deploy/demo.
|
|
5. Add User Story 4 → test independently → deploy/demo.
|
|
6. Add User Story 5 → test independently → deploy/demo.
|
|
|
|
### Parallel Team Strategy
|
|
|
|
With multiple developers:
|
|
|
|
1. Team completes Setup + Foundational together.
|
|
2. Once Foundational is done:
|
|
- Developer A: User Story 1
|
|
- Developer B: User Story 2
|
|
- Developer C: User Story 3
|
|
- Developer D: User Story 4
|
|
- Developer E: User Story 5
|
|
3. Finish with the shared browser, documentation, and verification tasks in Phase 8.
|
|
|
|
---
|
|
|
|
## Notes
|
|
|
|
- `[P]` tasks touch different files and have no direct dependency on incomplete tasks.
|
|
- `[US#]` labels map tasks back to the five user stories in `spec.md`.
|
|
- Every story remains independently completable and testable after Phase 2.
|
|
- Verify tests fail before implementing each story.
|
|
- Avoid adding a new global page-state framework, shell-level context layer, or new persistence while implementing these tasks. |