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. |