ahmido
d2f2c55ead
## Summary - add canonical onboarding lifecycle and checkpoint fields plus optimistic locking versioning for managed tenant onboarding drafts - introduce centralized onboarding lifecycle and mutation services and route wizard mutations through version-checked writes - convert Verify Access and Bootstrap into live checkpoint-driven wizard states with conditional polling and updated browser/feature/unit coverage - add Spec Kit artifacts for feature 140, including spec, plan, tasks, research, data model, quickstart, checklist, and logical contract ## Validation - branch was committed and pushed cleanly - focused tests and formatting were updated during implementation work - full validation was not re-run as part of this final git/PR step ## Notes - base branch: `dev` - feature branch: `140-onboarding-lifecycle-operation-checkpoints-concurrency-mvp` - outstanding follow-up items, if any, remain tracked in `specs/140-onboarding-lifecycle-operation-checkpoints-concurrency-mvp/tasks.md` Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #169
232 lines
15 KiB
Markdown
232 lines
15 KiB
Markdown
# Tasks: Onboarding Lifecycle, Operation Checkpoints & Concurrency MVP
|
||
|
||
**Input**: Design documents from `/specs/140-onboarding-lifecycle-operation-checkpoints-concurrency-mvp/`
|
||
**Prerequisites**: `plan.md`, `spec.md`, `research.md`, `data-model.md`, `quickstart.md`, `contracts/onboarding-lifecycle-logical-contract.openapi.yaml`
|
||
|
||
**Tests**: Tests are required for this feature. Each user story includes focused Pest feature, browser, or unit coverage.
|
||
**Operations**: This feature reuses existing `OperationRun` flows for Verify Access and Bootstrap. Tasks below preserve the canonical `OperationRun` path, Ops-UX feedback contract, canonical Monitoring links, and service-owned run lifecycle transitions.
|
||
**Organization**: Tasks are grouped by user story so each story can be implemented and validated independently after the foundational phase.
|
||
|
||
## Phase 1: Setup (Shared Infrastructure)
|
||
|
||
**Purpose**: Add the schema and support scaffolding required for canonical lifecycle and versioned mutations.
|
||
|
||
- [X] T001 Create the onboarding lifecycle migration with defaults and backfill for existing draft rows in `database/migrations/2026_03_14_000001_add_lifecycle_and_version_to_managed_tenant_onboarding_sessions.php`
|
||
- [X] T002 [P] Add controlled lifecycle and checkpoint enums in `app/Support/Onboarding/OnboardingLifecycleState.php` and `app/Support/Onboarding/OnboardingCheckpoint.php`
|
||
- [X] T003 [P] Update onboarding session factory defaults in `database/factories/TenantOnboardingSessionFactory.php`
|
||
|
||
---
|
||
|
||
## Phase 2: Foundational (Blocking Prerequisites)
|
||
|
||
**Purpose**: Centralize workflow truth and mutation safety before any user story work begins.
|
||
|
||
**⚠️ CRITICAL**: No user story work can begin until this phase is complete.
|
||
|
||
- [X] T004 Implement canonical lifecycle recalculation and readiness evaluation in `app/Services/Onboarding/OnboardingLifecycleService.php`
|
||
- [X] T005 [P] Implement version-checked draft mutation orchestration in `app/Services/Onboarding/OnboardingDraftMutationService.php`
|
||
- [X] T006 [P] Extend onboarding draft casts and helpers in `app/Models/TenantOnboardingSession.php` and `app/Support/Onboarding/OnboardingDraftStatus.php`
|
||
- [X] T007 Refactor stage resolution to consume canonical lifecycle fields in `app/Services/Onboarding/OnboardingDraftStageResolver.php`
|
||
- [X] T008 [P] Add unit coverage for lifecycle recalculation and stage resolution in `tests/Unit/Onboarding/OnboardingLifecycleServiceTest.php` and `tests/Unit/Onboarding/OnboardingDraftStageResolverTest.php`
|
||
- [ ] T009 [P] Add Ops-UX regression coverage for onboarding checkpoint starts and completions in `tests/Feature/OpsUx/QueuedToastCopyTest.php`, `tests/Feature/OperationRunServiceTest.php`, and `tests/Feature/Notifications/OperationRunNotificationTest.php`
|
||
|
||
**Checkpoint**: Schema, lifecycle service, mutation service, and supporting model semantics are ready for story implementation.
|
||
|
||
---
|
||
|
||
## Phase 3: User Story 1 - Track a trustworthy lifecycle in one wizard (Priority: P1) 🎯 MVP
|
||
|
||
**Goal**: Persist and render canonical lifecycle and checkpoint truth without changing the onboarding route structure.
|
||
|
||
**Independent Test**: Create and resume onboarding drafts across normal, blocked, active, ready, completed, and cancelled states, then confirm persisted lifecycle and checkpoint metadata drive the wizard state.
|
||
|
||
### Tests for User Story 1
|
||
|
||
- [ ] T010 [P] [US1] Expand lifecycle transition coverage in `tests/Feature/Onboarding/OnboardingDraftLifecycleTest.php`
|
||
- [ ] T011 [P] [US1] Add allow and deny lifecycle visibility assertions in `tests/Feature/Onboarding/OnboardingDraftAuthorizationTest.php`
|
||
- [X] T012 [P] [US1] Add mutation-path RBAC regression coverage for provider selection, verification, bootstrap, activation, and cancel in `tests/Feature/Rbac/OnboardingWizardUiEnforcementTest.php`
|
||
|
||
### Implementation for User Story 1
|
||
|
||
- [X] T013 [US1] Route identify and provider-selection mutations through the mutation service in `app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php`
|
||
- [X] T014 [US1] Persist provider-change invalidation, lifecycle reasons, and checkpoint metadata in `app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php` and `app/Services/Onboarding/OnboardingLifecycleService.php`
|
||
- [X] T015 [US1] Update wizard lifecycle labels, badges, and checkpoint summaries in `app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php`
|
||
- [X] T016 [US1] Align lifecycle-aware draft resume behavior in `app/Services/Onboarding/OnboardingDraftResolver.php` and `app/Services/Onboarding/OnboardingDraftStageResolver.php`
|
||
|
||
**Checkpoint**: User Story 1 delivers queryable lifecycle truth and lifecycle-driven wizard progression with focused authorization coverage.
|
||
|
||
---
|
||
|
||
## Phase 4: User Story 2 - Monitor Verify Access and Bootstrap as live checkpoints (Priority: P1)
|
||
|
||
**Goal**: Turn Step 3 and Step 4 into live, backend-truth checkpoint monitors while preserving Spec 139’s assist behavior.
|
||
|
||
**Independent Test**: Start verification and bootstrap, keep the wizard open, and confirm checkpoint state updates automatically from backend truth without losing Verify Access assist continuity.
|
||
|
||
### Tests for User Story 2
|
||
|
||
- [X] T017 [P] [US2] Add `5s` verification and bootstrap polling coverage in `tests/Browser/OnboardingDraftRefreshTest.php`
|
||
- [X] T018 [P] [US2] Add Verify Access assist compatibility coverage under active checkpoint rendering in `tests/Feature/Onboarding/OnboardingVerificationAssistTest.php` and `tests/Browser/OnboardingDraftVerificationResumeTest.php`
|
||
|
||
### Implementation for User Story 2
|
||
|
||
- [X] T019 [US2] Add conditional `5s` checkpoint polling hooks in `resources/views/filament/pages/workspaces/managed-tenant-onboarding-wizard.blade.php` and `app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php`
|
||
- [X] T020 [US2] Convert Verify Access to backend-truth checkpoint rendering in `app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php` and `resources/views/filament/forms/components/managed-tenant-onboarding-verification-report.blade.php`
|
||
- [X] T021 [US2] Convert Bootstrap to backend-truth per-run monitoring in `app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php`
|
||
- [X] T022 [US2] Preserve canonical queued and deduped feedback plus Monitoring links for checkpoint starts in `app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php`
|
||
|
||
**Checkpoint**: User Story 2 delivers live checkpoint monitoring for Verify Access and Bootstrap with Spec 139 compatibility intact.
|
||
|
||
---
|
||
|
||
## Phase 5: User Story 3 - Prevent silent overwrite across tabs and operators (Priority: P1)
|
||
|
||
**Goal**: Reject stale mutations atomically and keep the operator on the wizard with clear conflict guidance.
|
||
|
||
**Independent Test**: Open the same draft in two tabs or sessions, save in one, then submit a stale mutation in the other and confirm the stale write is rejected with visible conflict feedback.
|
||
|
||
### Tests for User Story 3
|
||
|
||
- [X] T023 [P] [US3] Expand multi-tab stale-mutation coverage in `tests/Feature/Onboarding/OnboardingDraftMultiTabTest.php`
|
||
- [ ] T024 [P] [US3] Add browser conflict-notification and wizard-continuity coverage in `tests/Browser/OnboardingDraftRefreshTest.php`
|
||
|
||
### Implementation for User Story 3
|
||
|
||
- [X] T025 [US3] Apply expected-version checks to provider selection and inline connection edits in `app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php` and `app/Services/Onboarding/OnboardingDraftMutationService.php`
|
||
- [X] T026 [US3] Apply expected-version checks to verification, bootstrap, activation, and cancel mutations in `app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php` and `app/Services/Onboarding/OnboardingDraftMutationService.php`
|
||
- [X] T027 [US3] Enforce terminal immutability and conflict-safe refresh handling in `app/Models/TenantOnboardingSession.php` and `app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php`
|
||
- [ ] T028 [US3] Add conflict audit coverage and messaging assertions in `tests/Feature/Audit/OnboardingDraftAuditTest.php` and `app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php`
|
||
- [X] T029 [US3] Add a no-takeover regression check for onboarding draft UI and services in `tests/Feature/Onboarding/OnboardingDraftMultiTabTest.php` and `app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php`
|
||
|
||
**Checkpoint**: User Story 3 delivers optimistic locking across covered draft mutations with visible conflict UX and immutable terminal drafts.
|
||
|
||
---
|
||
|
||
## Phase 6: User Story 4 - Activate only when backend truth is actually ready (Priority: P2)
|
||
|
||
**Goal**: Gate activation on canonical lifecycle and current checkpoint truth instead of stale visible state.
|
||
|
||
**Independent Test**: Bring a draft to an apparently ready state, invalidate readiness, and confirm activation refuses to complete until lifecycle truth becomes ready again.
|
||
|
||
### Tests for User Story 4
|
||
|
||
- [ ] T030 [P] [US4] Expand activation gating and terminal-state coverage in `tests/Feature/Onboarding/OnboardingActivationTest.php`
|
||
- [X] T031 [P] [US4] Add readiness-evaluation unit coverage in `tests/Unit/Onboarding/OnboardingLifecycleServiceTest.php`
|
||
|
||
### Implementation for User Story 4
|
||
|
||
- [X] T032 [US4] Rework activation readiness and override gating to use canonical lifecycle truth in `app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php` and `app/Services/Onboarding/OnboardingLifecycleService.php`
|
||
- [X] T033 [US4] Persist completed and cancelled checkpoint metadata plus terminal redirect behavior in `app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php` and `app/Models/TenantOnboardingSession.php`
|
||
|
||
**Checkpoint**: User Story 4 delivers backend-truth activation gating and preserves terminal record integrity.
|
||
|
||
---
|
||
|
||
## Phase 7: Polish & Cross-Cutting Concerns
|
||
|
||
**Purpose**: Final validation, regression safety, and code quality across all stories.
|
||
|
||
- [X] T034 [P] Run focused onboarding, browser, RBAC, Ops-UX, notification, and unit tests from `specs/140-onboarding-lifecycle-operation-checkpoints-concurrency-mvp/quickstart.md`
|
||
- [X] T035 [P] Run formatting for changed PHP files with `vendor/bin/sail bin pint --dirty --format agent`
|
||
- [X] T036 Validate the implemented flow against `specs/140-onboarding-lifecycle-operation-checkpoints-concurrency-mvp/quickstart.md` and update any missing regression coverage in `tests/Feature/Onboarding/`, `tests/Feature/Rbac/`, `tests/Feature/OpsUx/`, `tests/Feature/Notifications/`, `tests/Browser/`, and `tests/Unit/Onboarding/`
|
||
|
||
---
|
||
|
||
## Dependencies & Execution Order
|
||
|
||
### Phase Dependencies
|
||
|
||
- **Phase 1: Setup**: No dependencies. Start immediately.
|
||
- **Phase 2: Foundational**: Depends on Phase 1. Blocks all user story work.
|
||
- **Phase 3: User Story 1**: Depends on Phase 2.
|
||
- **Phase 4: User Story 2**: Depends on Phase 2 and can start after the foundational lifecycle service exists, but integrates cleanly after User Story 1 lifecycle persistence is in place.
|
||
- **Phase 5: User Story 3**: Depends on Phase 2 and shares the mutation service introduced there.
|
||
- **Phase 6: User Story 4**: Depends on Phase 2 and benefits from User Story 1 lifecycle truth plus User Story 3 mutation safety.
|
||
- **Phase 7: Polish**: Depends on completion of the desired user stories.
|
||
|
||
### User Story Dependencies
|
||
|
||
- **User Story 1 (P1)**: First MVP slice after the foundational phase. No dependency on later stories.
|
||
- **User Story 2 (P1)**: Depends on foundational lifecycle and checkpoint services; should be implemented after or alongside User Story 1 because it renders the lifecycle truth introduced there.
|
||
- **User Story 3 (P1)**: Depends on the foundational mutation service; otherwise independent of User Stories 1 and 2.
|
||
- **User Story 4 (P2)**: Depends on lifecycle truth from User Story 1 and version-safe mutation behavior from User Story 3.
|
||
|
||
### Within Each User Story
|
||
|
||
- Write or update the listed tests first and confirm they fail for the missing behavior.
|
||
- Implement shared model or service changes before page rendering updates.
|
||
- Complete the story-specific implementation before relying on it in later stories.
|
||
|
||
### Suggested Execution Order
|
||
|
||
1. Finish Phases 1 and 2.
|
||
2. Deliver User Story 1 as the MVP.
|
||
3. Deliver User Story 3 next if concurrency safety is the highest operational risk, or User Story 2 next if live checkpoint trust is the higher priority.
|
||
4. Deliver the remaining P1 story.
|
||
5. Finish User Story 4 and then run the polish phase.
|
||
|
||
---
|
||
|
||
## Parallel Opportunities
|
||
|
||
- **Setup**: `T002` and `T003` can run in parallel after `T001` defines the schema shape.
|
||
- **Foundational**: `T005`, `T006`, and `T008` can run in parallel once the lifecycle service contract from `T004` is settled.
|
||
- **User Story 1**: `T010`, `T011`, and `T012` can run in parallel.
|
||
- **User Story 2**: `T017` and `T018` can run in parallel.
|
||
- **User Story 3**: `T023` and `T024` can run in parallel.
|
||
- **User Story 4**: `T030` and `T031` can run in parallel.
|
||
- **Polish**: `T034` and `T035` can run in parallel once implementation is stable.
|
||
|
||
## Parallel Example: User Story 1
|
||
|
||
```bash
|
||
# Launch lifecycle-focused tests together:
|
||
Task: "T010 Expand lifecycle transition coverage in tests/Feature/Onboarding/OnboardingDraftLifecycleTest.php"
|
||
Task: "T011 Add allow and deny lifecycle visibility assertions in tests/Feature/Onboarding/OnboardingDraftAuthorizationTest.php"
|
||
Task: "T012 Add mutation-path RBAC regression coverage in tests/Feature/Rbac/OnboardingWizardUiEnforcementTest.php"
|
||
```
|
||
|
||
## Parallel Example: User Story 2
|
||
|
||
```bash
|
||
# Launch checkpoint-monitoring coverage together:
|
||
Task: "T017 Add verification and bootstrap polling coverage in tests/Browser/OnboardingDraftRefreshTest.php"
|
||
Task: "T018 Add Verify Access assist compatibility coverage in tests/Feature/Onboarding/OnboardingVerificationAssistTest.php and tests/Browser/OnboardingDraftVerificationResumeTest.php"
|
||
```
|
||
|
||
## Parallel Example: User Story 3
|
||
|
||
```bash
|
||
# Launch stale-mutation coverage together:
|
||
Task: "T023 Expand multi-tab stale-mutation coverage in tests/Feature/Onboarding/OnboardingDraftMultiTabTest.php"
|
||
Task: "T024 Add browser conflict-notification and wizard-continuity coverage in tests/Browser/OnboardingDraftRefreshTest.php"
|
||
```
|
||
|
||
## Parallel Example: User Story 4
|
||
|
||
```bash
|
||
# Launch activation readiness tests together:
|
||
Task: "T030 Expand activation gating and terminal-state coverage in tests/Feature/Onboarding/OnboardingActivationTest.php"
|
||
Task: "T031 Add readiness-evaluation unit coverage in tests/Unit/Onboarding/OnboardingLifecycleServiceTest.php"
|
||
```
|
||
|
||
---
|
||
|
||
## Implementation Strategy
|
||
|
||
### MVP First
|
||
|
||
Implement Phases 1 and 2, then complete User Story 1. That yields the smallest valuable slice: canonical lifecycle truth persisted on the onboarding draft and rendered by the existing wizard without route changes.
|
||
|
||
### Incremental Delivery
|
||
|
||
- Add live checkpoint monitoring with User Story 2.
|
||
- Add optimistic locking and visible conflict handling with User Story 3.
|
||
- Finish backend-truth activation gating with User Story 4.
|
||
|
||
### Validation Strategy
|
||
|
||
- Keep tests close to the story they validate.
|
||
- Reuse the focused files already present under `tests/Feature/Onboarding/`, `tests/Feature/Rbac/`, `tests/Feature/OpsUx/`, `tests/Feature/Notifications/`, `tests/Browser/`, and `tests/Unit/Onboarding/`.
|
||
- End with the quickstart validation and focused Sail test runs before broadening to any larger regression suite.
|