ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
d2f2c55ead
TenantAtlas/specs/140-onboarding-lifecycle-operation-checkpoints-concurrency-mvp/quickstart.md
ahmido d2f2c55ead feat: add onboarding lifecycle checkpoints and locking (#169) 
## 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
2026-03-14 11:02:29 +00:00

4.4 KiB
Raw Blame History

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.