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
88 lines
4.4 KiB
Markdown
88 lines
4.4 KiB
Markdown
# Quickstart: Onboarding Lifecycle, Operation Checkpoints & Concurrency MVP
|
|
|
|
## Goal
|
|
|
|
Validate the lifecycle, checkpoint-monitoring, and optimistic-locking design on the existing managed tenant onboarding wizard without adding routes or replacing the current flow.
|
|
|
|
## Prerequisites
|
|
|
|
1. Start the local stack with `vendor/bin/sail up -d`.
|
|
2. Ensure the database is migrated after implementation with `vendor/bin/sail artisan migrate --no-interaction`.
|
|
3. Use a workspace member with onboarding permissions and, for activation scenarios, an owner-capable actor.
|
|
|
|
## Manual Validation Flow
|
|
|
|
### Scenario 1: New draft lifecycle foundation
|
|
|
|
1. Open `/admin/onboarding`.
|
|
2. Create or resume a draft.
|
|
3. Confirm the persisted draft starts in `draft` and `current_checkpoint` reflects the current wizard step.
|
|
|
|
### Scenario 2: Verify Access as a live checkpoint
|
|
|
|
1. Select a provider connection.
|
|
2. Start Verify Access from Step 3.
|
|
3. Confirm the draft moves to `verifying` and the step shows live checkpoint messaging.
|
|
4. Keep the page open until the run becomes terminal.
|
|
5. Confirm the step updates within the active `5s` polling cadence without manual refresh and the lifecycle transitions to either `ready_for_activation` or `action_required`.
|
|
6. Confirm the Spec 139 required-permissions assist still works when verification is blocked or needs attention.
|
|
|
|
### Scenario 3: Bootstrap as an optional live checkpoint
|
|
|
|
1. Select one or more bootstrap actions in Step 4.
|
|
2. Start bootstrap.
|
|
3. Confirm the draft moves to `bootstrapping`.
|
|
4. Keep the page open until selected runs become terminal.
|
|
5. Confirm the step renders per-run status within the active `5s` polling cadence and stops polling when no relevant runs remain active.
|
|
|
|
### Scenario 4: Activation gating
|
|
|
|
1. Reach a state that appears ready for activation.
|
|
2. Invalidate readiness by changing the provider connection or by forcing a relevant blocking condition in another session.
|
|
3. Attempt activation.
|
|
4. Confirm activation rechecks backend truth and refuses to complete until readiness is restored.
|
|
|
|
### Scenario 5: Optimistic locking conflict
|
|
|
|
1. Open the same onboarding draft in two tabs.
|
|
2. Save a draft mutation in Tab A.
|
|
3. Submit a stale mutation in Tab B.
|
|
4. Confirm Tab B sees a clear conflict notification, remains on the wizard, and does not show a false success state.
|
|
|
|
## Focused Test Targets
|
|
|
|
- `tests/Feature/Onboarding/OnboardingDraftLifecycleTest.php`
|
|
- `tests/Feature/Onboarding/OnboardingDraftMultiTabTest.php`
|
|
- `tests/Feature/Onboarding/OnboardingActivationTest.php`
|
|
- `tests/Feature/Onboarding/OnboardingVerificationAssistTest.php`
|
|
- `tests/Feature/Onboarding/OnboardingDraftAuthorizationTest.php`
|
|
- `tests/Feature/Rbac/OnboardingWizardUiEnforcementTest.php`
|
|
- `tests/Feature/OpsUx/QueuedToastCopyTest.php`
|
|
- `tests/Feature/OperationRunServiceTest.php`
|
|
- `tests/Browser/OnboardingDraftRefreshTest.php`
|
|
- `tests/Browser/OnboardingDraftVerificationResumeTest.php`
|
|
- `tests/Unit/Onboarding/OnboardingLifecycleServiceTest.php`
|
|
- `tests/Unit/Onboarding/OnboardingDraftStageResolverTest.php`
|
|
|
|
## Suggested Verification Commands
|
|
|
|
1. `vendor/bin/sail artisan test --compact tests/Feature/Onboarding/OnboardingDraftLifecycleTest.php`
|
|
2. `vendor/bin/sail artisan test --compact tests/Feature/Onboarding/OnboardingDraftMultiTabTest.php`
|
|
3. `vendor/bin/sail artisan test --compact tests/Feature/Onboarding/OnboardingActivationTest.php`
|
|
4. `vendor/bin/sail artisan test --compact tests/Feature/Onboarding/OnboardingVerificationAssistTest.php`
|
|
5. `vendor/bin/sail artisan test --compact tests/Feature/Onboarding/OnboardingDraftAuthorizationTest.php`
|
|
6. `vendor/bin/sail artisan test --compact tests/Feature/Rbac/OnboardingWizardUiEnforcementTest.php`
|
|
7. `vendor/bin/sail artisan test --compact tests/Feature/OpsUx/QueuedToastCopyTest.php`
|
|
8. `vendor/bin/sail artisan test --compact tests/Feature/OperationRunServiceTest.php`
|
|
9. `vendor/bin/sail artisan test --compact tests/Browser/OnboardingDraftRefreshTest.php`
|
|
10. `vendor/bin/sail artisan test --compact tests/Browser/OnboardingDraftVerificationResumeTest.php`
|
|
11. `vendor/bin/sail artisan test --compact tests/Unit/Onboarding/OnboardingLifecycleServiceTest.php`
|
|
|
|
## Expected Outcome
|
|
|
|
- No new onboarding routes are needed.
|
|
- Verify Access and Bootstrap behave as operation-backed checkpoints.
|
|
- Lifecycle truth is queryable from top-level draft fields.
|
|
- Terminal drafts remain immutable.
|
|
- Stale mutations fail safely with visible conflict guidance.
|