ahmido
98e2b5acd9
## Summary - add canonical managed-tenant onboarding draft routing with explicit draft identity and landing vs concrete draft behavior - implement draft lifecycle, authorization, attribution, picker UX, resume-stage resolution, and auditable cancel or completion semantics - add focused feature, unit, and browser coverage plus Spec 138 artifacts for the onboarding draft resume flow ## Validation - `vendor/bin/sail artisan test --compact tests/Feature/ManagedTenantOnboardingWizardTest.php tests/Feature/Audit/OnboardingDraftAuditTest.php tests/Feature/Onboarding/OnboardingDraftAccessTest.php tests/Feature/Onboarding/OnboardingDraftAuthorizationTest.php tests/Feature/Onboarding/OnboardingDraftLifecycleTest.php tests/Feature/Onboarding/OnboardingDraftMultiTabTest.php tests/Feature/Onboarding/OnboardingDraftPickerTest.php tests/Feature/Onboarding/OnboardingDraftRoutingTest.php tests/Feature/Onboarding/OnboardingRbacSemanticsTest.php tests/Feature/Onboarding/OnboardingVerificationClustersTest.php tests/Feature/Onboarding/OnboardingVerificationTest.php tests/Feature/Onboarding/OnboardingVerificationV1_5UxTest.php tests/Feature/Verification/VerificationReportViewerDbOnlyTest.php tests/Unit/Onboarding tests/Unit/VerificationReportSanitizerEvidenceKindsTest.php tests/Browser/OnboardingDraftRefreshTest.php tests/Browser/OnboardingDraftVerificationResumeTest.php` - passed: 69 tests, 251 assertions Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #167
44 lines
2.9 KiB
Markdown
44 lines
2.9 KiB
Markdown
# Research: Managed Tenant Onboarding Draft Identity & Resume Semantics
|
|
|
|
## Decision 1: Use explicit draft identity in the URL
|
|
|
|
- **Decision**: Use a hybrid model with `/admin/onboarding` as a landing route and `/admin/onboarding/{onboardingDraft}` as the canonical route for an active draft.
|
|
- **Rationale**: This gives operators a concrete mental model, makes refresh deterministic, and removes silent wizard-state heuristics as the primary resume mechanism.
|
|
- **Alternatives considered**:
|
|
- Keep landing-only heuristic resume: rejected because it is ambiguous and not bookmarkable.
|
|
- Query parameter only: acceptable technically, but rejected as the primary enterprise representation because the path route is clearer and easier to reason about.
|
|
|
|
## Decision 2: Resume stage comes from persisted state, not only `current_step`
|
|
|
|
- **Decision**: Derive the resumed wizard step from persisted confirmed data completeness plus verification and bootstrap state.
|
|
- **Rationale**: Persisted data is more trustworthy than a stale step marker and tolerates partial inconsistencies better.
|
|
- **Alternatives considered**:
|
|
- Resume purely from `current_step`: rejected because it can lie when required state is missing.
|
|
|
|
## Decision 3: Keep unsaved edits transient
|
|
|
|
- **Decision**: Persist only at explicit step-confirmation boundaries. Unsaved current-step edits may be lost on refresh.
|
|
- **Rationale**: This keeps the model understandable, avoids partial write complexity, and matches the enterprise requirement that confirmed work be durable without implying autosave.
|
|
- **Alternatives considered**:
|
|
- Autosave every input: rejected as out of scope and higher risk for misleading partial persistence semantics.
|
|
|
|
## Decision 4: Use workspace-shared draft visibility for continuity
|
|
|
|
- **Decision**: Authorized onboarding operators in the current workspace may see resumable drafts, regardless of creator.
|
|
- **Rationale**: Enterprise admin workflows require continuity across operators and should not become fragile when one user is unavailable.
|
|
- **Alternatives considered**:
|
|
- Creator-only visibility: rejected because it harms operational continuity and creates unnecessary support burden.
|
|
|
|
## Decision 5: Completed and cancelled drafts are non-resumable
|
|
|
|
- **Decision**: Completed and cancelled drafts remain historical or summary records and do not reopen in edit mode.
|
|
- **Rationale**: This avoids unsafe reopening and preserves operator trust around lifecycle meaning.
|
|
- **Alternatives considered**:
|
|
- Allow reopening completed drafts: rejected because it blurs activation completion semantics.
|
|
|
|
## Decision 6: Browser-level validation is mandatory
|
|
|
|
- **Decision**: Add browser tests for hard refresh on the canonical draft route.
|
|
- **Rationale**: The main trust defect is visible only in real reload behavior, not just unit or Livewire state transitions.
|
|
- **Alternatives considered**:
|
|
- Feature tests only: rejected because they do not prove real browser reload semantics. |