Ta375/onboarding integration

[3TTemi]

Summary

This PR implements a complete 13-step user onboarding flow with backend integration for persistent completion tracking. New users are guided through the app's key features (Challenges, Journeys, Gameplay, Profile, Leaderboard), and onboarding status persists across sessions.

Onboarding Flow Implementation:

• Implemented all 13 onboarding steps guiding users through key app features
• Created BearMascotMessage widget with responsive positioning and SVG assets
• Added full-screen dimmed overlays and interactive highlights for UI elements
• Implemented auto-navigation between steps with tap-anywhere dismissal
• Added OnboardingModel for state management across pages using ChangeNotifier pattern
• Integrated showcaseview package for widget highlighting with custom styling

Backend Integration:

• Connected OnboardingModel to backend via WebSocket to check hasCompletedOnboarding status
• Added loading state to prevent onboarding flash on login for returning users
• Implemented auto-reset logic when new users log in (handles multiple users in same session)
• Step 13 saves completion to backend database permanently
• Added CASL permission for hasCompletedOnboarding field to fix data filtering issue
• Merged backend branch as4288/onboarding-backend for database schema and API endpoints

Main Files Modified:

• game/lib/widgets/bear_mascot_message.dart - Custom onboarding widget (new file)
• game/lib/model/onboarding_model.dart - State management + backend integration (new file)
• game/lib/main.dart - Integrated OnboardingModel
• game/lib/navigation_page/bottom_navbar.dart - Steps 0, 3, 11, 12, 13 of onboarding
• game/lib/navigation_page/home_navbar.dart - Step 2
• game/lib/challenges/challenges_page.dart - Step 1
• game/lib/journeys/journeys_page.dart - Step 4
• game/lib/gameplay/gameplay_page.dart - Steps 5, 6
• game/lib/gameplay/gameplay_map.dart - Steps 7, 8, 9, 10
• game/lib/api/* - Auto-generated from backend DTOs
• server/src/casl/casl-ability.factory.ts - Added hasCompletedOnboarding to User read permissions
• Bear mascot SVG assets added to game/assets/images/

Remaining TODOs:

• Run database migration on Heroku production
• Monitor production for backend integration issues

Depends on: Backend branch as4288/onboarding-backend (already merged)

Test Plan

Onboarding Flow:

• All 13 steps functional and guide users through app features
• Make sure this works on different screen sizes
• Test backend secnarios of reloading app, logging in and logging out, deleting and recreating users

Production Testing Plan:

1. Backup production database
2. Fix duplicate usernames:
3. Run migration
4. Test onboarding with new user on production
5. Verify returning users don't see onboarding again

Notes

Important Implementation Details:

• OnboardingModel uses non-lazy initialization to ensure stream listeners are registered before backend events
• _isLoadingFromBackend flag prevents onboarding flash on login
• CASL permission fix was critical - without it, hasCompletedOnboarding was filtered out by backend
• Each page manages its own showcase scope and interacts with the onboarding model

Breaking Changes / Blockers

• Migration required for Database schema change: Merged backend branch includes new hasCompletedOnboarding Boolean field in User table
• Production database has duplicate usernames preventing 20250922023823_add_user_fields migration
  • Resolution: Run deduplication SQL before migration

[dti-github-bot]

[diff-counting] Significant lines: 2153. This diff might be too big! Developer leads are invited to review the code.