generated from coulomb/repo-seed
92 lines
3.4 KiB
Markdown
92 lines
3.4 KiB
Markdown
# Onboarding Journeys And Welcome Protocols
|
|
|
|
Status: implemented headless slice
|
|
Date: 2026-06-15
|
|
Related workplan: USER-WP-0013
|
|
|
|
## Purpose
|
|
|
|
This slice adds resumable onboarding journeys for newly registered or newly
|
|
entitled users. Welcome protocols are templates that can be triggered by
|
|
registration completion, prepared-account claims, invitations, access-profile
|
|
events, or explicit manual starts.
|
|
|
|
user-engine owns journey state, audit/event correlation, lifecycle gaps, and
|
|
adapter references. Notification delivery, support content, protected service
|
|
tours, and external workflow/task systems remain outside the core domain.
|
|
|
|
## Domain Model
|
|
|
|
`WelcomeProtocol` is the tenant-scoped template. It stores trigger type,
|
|
optional matching keys such as prepared journey, application, realm, service,
|
|
role, hat, factor requirements, and ordered `WelcomeProtocolStep` definitions.
|
|
|
|
`WelcomeProtocolStep` names the subsystem, task kind, optional external task
|
|
reference, optional callback reference, support reference, and whether a
|
|
subsystem callback is required.
|
|
|
|
`OnboardingJourney` is the persisted user state. It records tenant, user,
|
|
protocol, trigger type, source id/event, journey key, status, active step,
|
|
correlation id, and timestamps.
|
|
|
|
`OnboardingStep` carries step status plus optional `OnboardingTask` and
|
|
`SubsystemHandoff` references. Missing required subsystem callbacks produce
|
|
explicit lifecycle gaps such as
|
|
`subsystem-callback-missing:<subsystem>:<step>`.
|
|
|
|
## Public Facade
|
|
|
|
`UserEngineService` exposes:
|
|
|
|
- `register_welcome_protocol(...)`
|
|
- `list_welcome_protocols(...)`
|
|
- `start_onboarding_journey(...)`
|
|
- `start_onboarding_for_registration(...)`
|
|
- `start_onboarding_for_prepared_account(...)`
|
|
- `progress_onboarding_step(...)`
|
|
- `complete_onboarding_step(...)`
|
|
- `skip_onboarding_step(...)`
|
|
- `fail_onboarding_step(...)`
|
|
- `resume_onboarding_journey(...)`
|
|
- `onboarding_diagnostics(...)`
|
|
|
|
Registration completion auto-starts matching registration protocols. Prepared
|
|
account claim auto-starts matching prepared-account protocols when the claimed
|
|
package includes a matching onboarding journey key.
|
|
|
|
## Lifecycle Rules
|
|
|
|
Journey status is derived from step state:
|
|
|
|
- a missing required callback starts the journey as `blocked`;
|
|
- an active non-blocked first step starts as `in_progress`;
|
|
- failed steps fail the journey;
|
|
- all completed/skipped steps complete the journey;
|
|
- all skipped steps skip the journey.
|
|
|
|
Resuming a pending, blocked, or failed journey can attach callback references
|
|
and returns blocked/failed steps to `in_progress`.
|
|
|
|
## Adapter Boundary
|
|
|
|
The service defines ports for notification delivery, task systems, support
|
|
content, subsystem welcome callbacks, and lifecycle task linking. The current
|
|
headless slice stores adapter references but does not call external systems.
|
|
|
|
## Identity Context And Diagnostics
|
|
|
|
`identity_context` includes onboarding journeys for the resolved user/tenant.
|
|
`onboarding_diagnostics` reports protocol count, journey count, status counts,
|
|
blocked step ids, and lifecycle gaps.
|
|
|
|
Diagnostics and outbox events avoid factor values and service content. Payloads
|
|
carry ids, statuses, trigger types, source ids, active step keys, and lifecycle
|
|
gap identifiers.
|
|
|
|
## Current Limits
|
|
|
|
- No notification platform or support-content renderer is implemented.
|
|
- No protected subsystem tour is hard-coded into user-engine.
|
|
- External task and callback execution is left to adapters.
|
|
- UI surface contracts are implemented by USER-WP-0014.
|