generated from coulomb/repo-seed
146 lines
4.4 KiB
Markdown
146 lines
4.4 KiB
Markdown
---
|
|
id: USER-WP-0013
|
|
type: workplan
|
|
title: "Onboarding Journeys And Welcome Protocols"
|
|
domain: netkingdom
|
|
repo: user-engine
|
|
status: finished
|
|
owner: codex
|
|
topic_slug: netkingdom
|
|
planning_priority: medium
|
|
planning_order: 13
|
|
created: "2026-06-15"
|
|
updated: "2026-06-15"
|
|
depends_on:
|
|
- USER-WP-0011
|
|
- USER-WP-0012
|
|
state_hub_workstream_id: "1dc82dfd-be68-4585-b6c9-6d24aebd3e27"
|
|
---
|
|
|
|
# USER-WP-0013 - Onboarding Journeys And Welcome Protocols
|
|
|
|
## Goal
|
|
|
|
Create a journey layer that helps newly registered or newly entitled users
|
|
enter the right NetKingdom subsystems. Welcome protocols should be driven by
|
|
registration, prepared-account, invitation, role, profile, and access events.
|
|
|
|
## Scope Direction
|
|
|
|
user-engine owns journey state, task references, event correlation, and user
|
|
context. Delivery systems, protected services, help content, notification
|
|
channels, and external task systems remain adapters or downstream systems.
|
|
|
|
## Non-Goals
|
|
|
|
- Do not build a notification platform.
|
|
- Do not embed service-specific tours or support content in core domain code.
|
|
- Do not replace external workflow/task systems.
|
|
- Do not build the UI in this workplan.
|
|
|
|
## Tasks
|
|
|
|
```task
|
|
id: USER-WP-0013-T1
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "30ef8507-eebc-4b96-8aa6-c530bef05739"
|
|
```
|
|
|
|
Define onboarding journey, welcome protocol, journey step, task, and subsystem
|
|
handoff models.
|
|
|
|
```task
|
|
id: USER-WP-0013-T2
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "7c6e53d4-ff96-4036-a413-f04b4b73d266"
|
|
```
|
|
|
|
Add journey templates keyed by registration outcome, prepared entitlement,
|
|
tenant, realm, service, application, role, hat, and factor requirements.
|
|
|
|
```task
|
|
id: USER-WP-0013-T3
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "d9c2983a-45d1-4b1b-a416-63e180ca74b3"
|
|
```
|
|
|
|
Implement journey start, progress, complete, skip, fail, and resume operations
|
|
with authorization, audit, and outbox behavior.
|
|
|
|
```task
|
|
id: USER-WP-0013-T4
|
|
status: done
|
|
priority: medium
|
|
state_hub_task_id: "7155c2eb-4e32-46f0-ad33-961784cb9a03"
|
|
```
|
|
|
|
Add adapter ports for notifications, task systems, support content, subsystem
|
|
welcome callbacks, and lifecycle task linking.
|
|
|
|
```task
|
|
id: USER-WP-0013-T5
|
|
status: done
|
|
priority: medium
|
|
state_hub_task_id: "c5e42dd6-207a-4b1e-a0d8-35701e9f71bc"
|
|
```
|
|
|
|
Expose onboarding status through identity context, diagnostics, and optional UI
|
|
contracts.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- Registration or prepared-account claim can start an onboarding journey.
|
|
- Journey state is resumable, auditable, and correlated with outbox events.
|
|
- Subsystem welcome steps are adapter-driven, not hard-coded into core
|
|
registration logic.
|
|
- Users and admins can inspect pending onboarding work and blocked steps.
|
|
- Missing subsystem callbacks produce explicit lifecycle gaps.
|
|
|
|
## Expected Outputs
|
|
|
|
- Onboarding journey domain model.
|
|
- Welcome protocol service facade.
|
|
- Adapter ports for notifications and subsystem handoff.
|
|
- Scenario tests for successful, blocked, and resumed onboarding.
|
|
|
|
## Implementation Notes
|
|
|
|
Implemented on 2026-06-15:
|
|
|
|
- Added `OnboardingTriggerType`, `OnboardingJourneyStatus`,
|
|
`OnboardingStepStatus`, `WelcomeProtocol`, `WelcomeProtocolStep`,
|
|
`OnboardingJourney`, `OnboardingStep`, `OnboardingTask`, and
|
|
`SubsystemHandoff` domain models.
|
|
- Added welcome-protocol and onboarding-journey persistence to
|
|
`UserEngineStore` and `InMemoryUserEngineStore`, including transaction
|
|
snapshots and record counts.
|
|
- Added adapter ports for onboarding notifications, task links, support
|
|
content, subsystem welcome callbacks, and lifecycle task linking.
|
|
- Added `UserEngineService` onboarding facade methods:
|
|
`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`, and
|
|
`onboarding_diagnostics`.
|
|
- Added auto-start hooks for matching registration-completion protocols and
|
|
prepared-account claim protocols.
|
|
- Extended `identity_context` with onboarding journeys for the resolved
|
|
user/tenant.
|
|
- Added lifecycle-gap handling for missing subsystem callbacks and resumable
|
|
blocked/failed journey state.
|
|
- Added `docs/onboarding-journeys-and-welcome-protocols.md`, public contract
|
|
updates, and tests for registration-triggered, prepared-claim-triggered,
|
|
blocked, resumed, progressed, skipped, and failed onboarding.
|
|
|
|
Verification:
|
|
|
|
```text
|
|
make test
|
|
Ran 66 tests in 0.620s
|
|
OK
|
|
```
|