ahmido
671abbed53
## Summary - retrofit the tenant detail recent-operations and verification surfaces to keep one clear primary inspect path per state - keep onboarding workflow actions on the wizard step while moving previous-run and advanced monitoring links into diagnostics-only technical details - add focused spec 172 design artifacts, feature coverage, and a dedicated browser smoke test for the deferred operator surface retrofit ## Testing - `vendor/bin/sail artisan test --compact tests/Browser/Spec172DeferredOperatorSurfacesSmokeTest.php tests/Browser/OnboardingDraftRefreshTest.php tests/Browser/OnboardingDraftVerificationResumeTest.php` ## Notes - base branch: `dev` - branch head: `172-deferred-operator-surfaces-retrofit` - browser smoke pack passed locally after the final changes Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #203
191 lines
12 KiB
Markdown
191 lines
12 KiB
Markdown
# Tasks: Deferred Operator Surfaces Retrofit
|
|
|
|
**Input**: Design documents from `specs/172-deferred-operator-surfaces-retrofit/`
|
|
**Prerequisites**: `plan.md`, `spec.md`, `research.md`, `data-model.md`, `contracts/embedded-operation-surface-contract.yaml`, `quickstart.md`
|
|
|
|
**Tests**: Required. Update the focused Pest coverage listed in `specs/172-deferred-operator-surfaces-retrofit/quickstart.md`.
|
|
**Operations**: Reuse the existing `OperationRun` lifecycle and canonical `/admin/operations` routes; this feature must not add new run semantics.
|
|
**RBAC**: Authorization planes and 404/403 behavior stay unchanged; covered surfaces still need access-aware advanced links.
|
|
|
|
## Phase 1: Setup (Shared Context)
|
|
|
|
**Purpose**: Confirm the retrofit boundary, affected surfaces, and focused verification targets before implementation starts.
|
|
|
|
- [X] T001 Review the implementation boundary in `specs/172-deferred-operator-surfaces-retrofit/spec.md`, `specs/172-deferred-operator-surfaces-retrofit/plan.md`, `specs/172-deferred-operator-surfaces-retrofit/research.md`, and `specs/172-deferred-operator-surfaces-retrofit/contracts/embedded-operation-surface-contract.yaml`
|
|
- [X] T002 Baseline the current tenant-detail and onboarding behavior in `app/Filament/Resources/TenantResource/Pages/ViewTenant.php`, `app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php`, `tests/Feature/Filament/RecentOperationsSummaryWidgetTest.php`, and `tests/Feature/Onboarding/OnboardingVerificationTest.php`
|
|
|
|
---
|
|
|
|
## Phase 2: Foundational (Blocking Prerequisites)
|
|
|
|
**Purpose**: Put the shared route and CTA handoff in place before changing individual surfaces.
|
|
|
|
**⚠️ CRITICAL**: No user story work should start until this phase is complete.
|
|
|
|
- [X] T003 Update shared destination metadata in `app/Support/OperationRunLinks.php` so retrofitted surfaces can keep canonical collection/detail routes while making any broader admin scope explicit
|
|
- [X] T004 Establish page-level workflow-action ownership in `app/Filament/Resources/TenantResource/Pages/ViewTenant.php` and `app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php` so embedded surfaces consume inspect-oriented inputs instead of deciding workflow CTAs themselves
|
|
|
|
**Checkpoint**: Shared helpers and page-level state handoff are ready, so story work can proceed safely.
|
|
|
|
---
|
|
|
|
## Phase 3: User Story 1 - Tenant Detail Drill-Ins Preserve Tenant Context (Priority: P1) 🎯 MVP
|
|
|
|
**Goal**: Make the tenant-detail recent-operations and verification widgets expose one clear primary CTA per state without silently broadening scope.
|
|
|
|
**Independent Test**: Render the tenant-detail widgets and verify that row-level or current-run inspection stays primary, any collection drill-in is clearly secondary, and the visible scope remains truthful before navigation.
|
|
|
|
### Tests for User Story 1
|
|
|
|
- [X] T005 [P] [US1] Update `tests/Feature/Filament/RecentOperationsSummaryWidgetTest.php` to assert row-level `Open operation` links stay primary and any collection drill-in is secondary and scope-explicit
|
|
- [X] T006 [P] [US1] Update `tests/Feature/Filament/TenantVerificationReportWidgetTest.php` to assert `Start verification` and `Open operation` never appear as competing peer CTAs on the widget
|
|
|
|
### Implementation for User Story 1
|
|
|
|
- [X] T007 [US1] Refine state assembly in `app/Filament/Widgets/Tenant/RecentOperationsSummary.php` and `app/Filament/Widgets/Tenant/TenantVerificationReport.php` so each tenant-detail surface emits one primary CTA contract per state
|
|
- [X] T008 [P] [US1] Update `resources/views/filament/widgets/tenant/recent-operations-summary.blade.php` to demote any collection affordance and make broader admin scope explicit before navigation
|
|
- [X] T009 [P] [US1] Update `resources/views/filament/widgets/tenant/tenant-verification-report.blade.php` to render one primary CTA per state and rely on the tenant-detail header action for reruns
|
|
|
|
**Checkpoint**: Tenant-detail embedded operation surfaces are independently testable and preserve tenant context truth.
|
|
|
|
---
|
|
|
|
## Phase 4: User Story 2 - Onboarding And Verification Surfaces Expose One Clear Operation Path (Priority: P1)
|
|
|
|
**Goal**: Keep onboarding verification workflow controls authoritative while report and technical-details surfaces expose one primary inspect path plus diagnostics-secondary links only.
|
|
|
|
**Independent Test**: Render onboarding verification surfaces in no-run, active-run, and completed-run states and verify that each state exposes exactly one primary CTA while previous-run or advanced monitoring links remain secondary and access-aware.
|
|
|
|
### Tests for User Story 2
|
|
|
|
- [X] T010 [P] [US2] Update `tests/Feature/Onboarding/OnboardingVerificationTest.php` to assert one primary verification CTA per onboarding state
|
|
- [X] T011 [P] [US2] Update `tests/Feature/Onboarding/OnboardingVerificationClustersTest.php` and `tests/Feature/Onboarding/OnboardingVerificationV1_5UxTest.php` to assert previous-run and advanced monitoring links stay diagnostics-secondary and access-aware
|
|
|
|
### Implementation for User Story 2
|
|
|
|
- [X] T012 [US2] Refine onboarding verification report payload assembly in `app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php` so current-run, previous-run, and advanced-link data reach the embedded surfaces without introducing inline workflow CTAs
|
|
- [X] T013 [P] [US2] Update `resources/views/filament/forms/components/managed-tenant-onboarding-verification-report.blade.php` to show exactly one primary current-run inspect CTA when a run exists and otherwise render explanatory empty-state content without inline workflow CTAs
|
|
- [X] T014 [P] [US2] Update `resources/views/filament/modals/onboarding-verification-technical-details.blade.php` to keep previous-run and advanced monitoring links secondary, explicitly labeled, and diagnostics-only
|
|
|
|
**Checkpoint**: Onboarding verification surfaces are independently testable and expose a single clear operator path per state.
|
|
|
|
---
|
|
|
|
## Phase 5: User Story 3 - Retrofitted Deferred Surfaces Gain Explicit Governance (Priority: P2)
|
|
|
|
**Goal**: Replace blanket deferred-surface treatment for the retrofitted operation-bearing surfaces with explicit governance and representative automated coverage.
|
|
|
|
**Independent Test**: Run the guard suite and confirm that tenant-detail and onboarding verification surfaces are covered explicitly, while unrelated deferred surfaces remain intentional non-goals.
|
|
|
|
### Tests for User Story 3
|
|
|
|
- [X] T015 [P] [US3] Update `tests/Feature/Guards/ActionSurfaceContractTest.php` to assert tenant-detail and onboarding verification surfaces are covered explicitly rather than by blanket deferred exemptions
|
|
|
|
### Implementation for User Story 3
|
|
|
|
- [X] T016 [US3] Narrow retrofit governance in `app/Support/Ui/ActionSurface/ActionSurfaceExemptions.php` so only true non-goal deferred surfaces remain exempt and dedicated coverage is documented for `ManagedTenantOnboardingWizard`
|
|
|
|
**Checkpoint**: Governance now protects the retrofitted surfaces without sweeping unrelated deferred pages into scope.
|
|
|
|
---
|
|
|
|
## Phase 6: Polish & Cross-Cutting Concerns
|
|
|
|
**Purpose**: Run the focused regression and cleanup steps needed to ship the retrofit safely.
|
|
|
|
- [X] T017 Run the focused regression suite in `tests/Feature/Filament/RecentOperationsSummaryWidgetTest.php`, `tests/Feature/Filament/TenantVerificationReportWidgetTest.php`, `tests/Feature/Onboarding/OnboardingVerificationTest.php`, `tests/Feature/Onboarding/OnboardingVerificationClustersTest.php`, `tests/Feature/Onboarding/OnboardingVerificationV1_5UxTest.php`, and `tests/Feature/Guards/ActionSurfaceContractTest.php`
|
|
- [X] T018 Run formatting for `app/Support/OperationRunLinks.php`, `app/Filament/Resources/TenantResource/Pages/ViewTenant.php`, `app/Filament/Widgets/Tenant/RecentOperationsSummary.php`, `app/Filament/Widgets/Tenant/TenantVerificationReport.php`, `app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php`, and `app/Support/Ui/ActionSurface/ActionSurfaceExemptions.php`
|
|
- [X] T019 Execute the manual validation checklist in `specs/172-deferred-operator-surfaces-retrofit/quickstart.md` against `resources/views/filament/widgets/tenant/recent-operations-summary.blade.php`, `resources/views/filament/widgets/tenant/tenant-verification-report.blade.php`, `resources/views/filament/forms/components/managed-tenant-onboarding-verification-report.blade.php`, and `resources/views/filament/modals/onboarding-verification-technical-details.blade.php`
|
|
- [X] T020 Verify render-path constraints in `app/Filament/Widgets/Tenant/RecentOperationsSummary.php`, `app/Filament/Widgets/Tenant/TenantVerificationReport.php`, `app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php`, and `app/Support/OperationRunLinks.php` so the retrofit stays DB-only at render time, adds no remote calls or queued work, does not alter polling cadence, and does not broaden query fan-out
|
|
|
|
---
|
|
|
|
## Dependencies & Execution Order
|
|
|
|
### Phase Dependencies
|
|
|
|
- **Phase 1: Setup** has no dependencies and starts immediately.
|
|
- **Phase 2: Foundational** depends on Phase 1 and blocks all story work.
|
|
- **Phase 3: User Story 1** depends on Phase 2.
|
|
- **Phase 4: User Story 2** depends on Phase 2.
|
|
- **Phase 5: User Story 3** depends on the relevant US1 and US2 implementation and test coverage being in place.
|
|
- **Phase 6: Polish** depends on the desired story phases being complete.
|
|
|
|
### User Story Dependencies
|
|
|
|
- **US1** can start as soon as T003-T004 are complete.
|
|
- **US2** can start as soon as T003-T004 are complete.
|
|
- **US3** should start after US1 and US2 have landed their representative surface behavior, because the governance guard needs the final retrofit boundary.
|
|
|
|
### Parallel Opportunities
|
|
|
|
- **US1**: T005 and T006 can run in parallel; after T007, T008 and T009 can run in parallel.
|
|
- **US2**: T010 and T011 can run in parallel; after T012, T013 and T014 can run in parallel.
|
|
- **US3**: Parallelism is intentionally limited; create the failing guard in T015 first, then narrow the exemption set in T016.
|
|
|
|
---
|
|
|
|
## Parallel Example: User Story 1
|
|
|
|
```bash
|
|
# Run the tenant-detail widget tests together:
|
|
Task: "T005 [US1] Update tests/Feature/Filament/RecentOperationsSummaryWidgetTest.php"
|
|
Task: "T006 [US1] Update tests/Feature/Filament/TenantVerificationReportWidgetTest.php"
|
|
|
|
# After widget state assembly is updated, align both Blade views together:
|
|
Task: "T008 [US1] Update resources/views/filament/widgets/tenant/recent-operations-summary.blade.php"
|
|
Task: "T009 [US1] Update resources/views/filament/widgets/tenant/tenant-verification-report.blade.php"
|
|
```
|
|
|
|
## Parallel Example: User Story 2
|
|
|
|
```bash
|
|
# Update onboarding coverage together:
|
|
Task: "T010 [US2] Update tests/Feature/Onboarding/OnboardingVerificationTest.php"
|
|
Task: "T011 [US2] Update tests/Feature/Onboarding/OnboardingVerificationClustersTest.php and tests/Feature/Onboarding/OnboardingVerificationV1_5UxTest.php"
|
|
|
|
# After the wizard state contract is ready, update both onboarding views together:
|
|
Task: "T013 [US2] Update resources/views/filament/forms/components/managed-tenant-onboarding-verification-report.blade.php"
|
|
Task: "T014 [US2] Update resources/views/filament/modals/onboarding-verification-technical-details.blade.php"
|
|
```
|
|
|
|
## Parallel Example: User Story 3
|
|
|
|
```bash
|
|
# No safe implementation pair is recommended here; land the failing guard first, then narrow the exemption baseline:
|
|
Task: "T015 [US3] Update tests/Feature/Guards/ActionSurfaceContractTest.php"
|
|
Task: "T016 [US3] Update app/Support/Ui/ActionSurface/ActionSurfaceExemptions.php"
|
|
```
|
|
|
|
---
|
|
|
|
## Implementation Strategy
|
|
|
|
### MVP First (User Story 1 Only)
|
|
|
|
1. Complete T001-T004.
|
|
2. Complete T005-T009.
|
|
3. Validate tenant-detail behavior with the focused US1 tests before moving on.
|
|
|
|
### Incremental Delivery
|
|
|
|
1. Complete Setup and Foundational work to lock the shared route and CTA contract.
|
|
2. Deliver US1 and validate tenant-detail scope truth.
|
|
3. Deliver US2 and validate onboarding CTA hierarchy.
|
|
4. Deliver US3 to replace blanket exemptions with explicit governance.
|
|
5. Finish with T017-T020.
|
|
|
|
### Parallel Team Strategy
|
|
|
|
1. One developer completes T001-T004.
|
|
2. After Phase 2, one developer can take US1 while another takes US2.
|
|
3. Once both surfaces are stable, finish US3 governance and the shared regression pass.
|
|
|
|
---
|
|
|
|
## Notes
|
|
|
|
- `[P]` tasks touch different files and can run in parallel.
|
|
- User story labels map directly to the priorities and acceptance criteria in `specs/172-deferred-operator-surfaces-retrofit/spec.md`.
|
|
- Keep the implementation narrow: no new routes, persistence, capabilities, assets, or `OperationRun` lifecycle changes.
|