Feature #38
closedEpic #20: Client design adaptation
Handle onboarding definition changes and persistence failures
0%
Description
Imported from GitHub issue 285.
Source milestone: Milestone 3.
Source labels: enhancement, ready-for-agent.
Source state as of 30 October 2026: closed.
What to build¶
Make the onboarding journey recover safely as code-defined flows evolve and local progress becomes missing, stale or unreadable. Verify the user can finish multiple eligible flows with arbitrary step counts and reach the main app. This is an AFK slice; use test fixtures for additional flows rather than adding unsolicited product screens.
Acceptance criteria¶
- One-step and multi-step flows, and more than one eligible flow, execute in explicit deterministic order. Ineligible or empty flows are safely skipped, and no eligible flows leads to the main app.
- Step reordering preserves the saved stable step ID. If the saved step was removed, restart the incomplete flow at its first valid step; removed/unknown flow records do not trap startup.
- Adding/reordering steps or changing a revision does not replay a completed flow by default. Replay requires an explicit code-defined policy; tests prove both default and explicitly requested replay behaviour.
- Invalid progress is validated and safely recovered without deleting a valid independent language preference. Storage read failures present a localised retryable startup state; they do not leave an indefinite spinner or silently mark onboarding complete.
- Failed step/completion writes never report success, advance the UI or lose the current retryable state. Repeated taps and rapid actions do not produce duplicate navigation or stale writes.
- Completion and progress remain local to the device across guest/sign-in/sign-out transitions; clearing local app data resets first-run onboarding. No account sync or backend schema is added.
- Integration tests exercise changed definitions, missing/invalid progress, read/write failure and relaunch recovery through observable routing and completion behaviour.
- Document the implemented recovery/replay rules and run client tests, lint and typechecking.
Design sources and scope¶
Use only the Design and Design tokens pages in https://www.figma.com/design/yisgB7iNKYtjNZdogARGIN/Bebin-prvi-meni . Exclude the reference-app page entirely.
Approved scope: any number of code-defined onboarding flows, each with any number of screens. The initial product flows are language selection followed by a skippable app introduction. No remote flow editor, analytics, account requirement, baby profile, baby-age collection or subscription setup is introduced. Preserve existing online-required and screen-capture protection policies.