ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
d2f2c55ead
TenantAtlas/specs/138-managed-tenant-onboarding-draft-identity/research.md
ahmido 98e2b5acd9 feat: managed tenant onboarding draft identity and resume semantics (#167) 
## 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
2026-03-13 23:45:23 +00:00

2.9 KiB
Raw Blame History

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.