mnemo_cards/mnemo_cards_web_v2/TODO.md
2025-11-11 02:55:41 +03:00

26 KiB
Raw Blame History

TODO - mnemo_cards_web_v2

Status: Active Development

Last Updated: November 8, 2025


🔥 Bug Fixes & Maintenance

PURCHASE-1: Purchase Page Loading Issue - FIXED

Priority: HIGH Status: COMPLETED Time Spent: 2 hours Date Fixed: November 8, 2025

Issue: Purchase page (/purchase/5) was not loading due to JSON deserialization problems.

Root Cause:

  • Constructor CardPackBuyDto incorrectly marked nullable fields as required
  • UI method _buildItem used item.toString() which doesn't work for polymorphic Item subclasses

Solution Applied:

  • Fixed CardPackBuyDto constructor to properly handle nullable fields
  • Implemented type-safe rendering for different Item types (TextItem, SpacerItem, ButtonItem)
  • Added proper spacing and visual elements for each item type

Result: Purchase page now loads correctly and displays pack information properly.


🔥 New Features

TASKS-1: Tasks System Implementation - PHASE 1 COMPLETE

Priority: HIGH Status: Phase 1 Complete, Ready for Phase 2 Estimated Time: 40-60 hours total

Plan Document: TASKS_PLAN.md

Goal: Реализовать механику заданий для mnemo_cards_web_v2 - систему заданий, которые пользователь выполняет как в приложении, так и в реальном мире.

Current Phase: Phase 1 (Frontend Infrastructure) - Complete

Completed in Phase 1:

  • Created comprehensive task data models (Task, TaskProgress, TaskReward, enums)
  • Implemented TasksRepository with mock data for development
  • Created TasksStateManager with full state management using yx_state
  • Added TasksModule to UserScope with proper dependency injection
  • Built TaskCard widget with rewards display and action buttons
  • Implemented TasksPage with filtering, tabs, and search functionality
  • Added navigation route /tasks and updated bottom navigation
  • Updated MainShell to include "Задания" tab
  • Integrated with existing yx_scope/yx_state architecture
  • Created unit tests for all components

Next Actions:

  • Phase 2: Backend Integration (API endpoints, real data) - 12-16 hours
  • Phase 3: Advanced Features (task creation, admin panel) - 8-12 hours
  • Phase 4: Polish & Analytics (animations, tracking) - 8-12 hours
  • Phase 5: Testing & Deployment (integration tests, production) - 8-12 hours

See TASKS_PLAN.md for complete breakdown.


CHAT-1: Chat Module Implementation - MODULARIZATION COMPLETE

Priority: HIGH Status: Modularization Complete, Ready for Phase 2 Estimated Time: 60-80 hours total

Plan Document: CHAT_PLAN.md

Goal: Реализовать функциональность чата для общения пользователя с LLM через сервер, поддерживая текст и аудио сообщения.

Current Phase: Phase 1 (Infrastructure) - Complete

Completed:

  • Modularization: Created separate mnemo_cards_chat Flutter package
  • Architecture: Clean architecture with ChatRepository interface for loose coupling
  • Models: Comprehensive data models (ChatMessage, AudioMessage, ChatSession, ChatParticipant)
  • Services: ChatService with business logic and ChatRepository abstraction
  • State Management: Simplified ChatStateManager with manual state classes
  • DI Integration: ChatModule for yx_scope integration in main application
  • Code Generation: All freezed/json_serializable generation working
  • Compilation: Module compiles successfully and integrates cleanly

Next Actions:

  • Phase 2: UI Components (MessageBubble, ChatInput, AudioRecorder, ChatPage) - 16-20 hours
  • Phase 3: Audio Functionality (recording, playback, Web Audio API) - 12-16 hours
  • Phase 4: Integration & Polish (navigation, error handling, theming) - 8-12 hours
  • Phase 5: Backend Integration & Testing (API endpoints, LLM integration) - 8-12 hours

See CHAT_PLAN.md for complete breakdown.

GT-1: Game Tests Implementation - PLANNING COMPLETE

Priority: HIGH Status: 🟡 Planning Complete, Ready to Start Estimated Time: 40-60 hours total

Plan Document: GAME_TESTS_IMPLEMENTATION_PLAN.md

Goal: Реализовать систему игровых тестов в mnemo_cards_web_v2, начиная с простых тестов с выбором 1 варианта из нескольких, с соблюдением архитектуры yx_scope/yx_state.

Current Phase: Planning Complete

Current Phase: Phase 4 Complete - UX Improvements FINISHED Status: GAME SYSTEM WITH ENHANCED UX READY

Successfully Implemented:

  • Phase 1: Basic Infrastructure
  • Phase 2: Multiple Choice Tests
  • Phase 4: UX Improvements (animations, sounds, theming)
  • Phase 5: Advanced Question Types

Question Types Available:

  • Multiple Choice - Fully implemented and working
  • Input Letters - Fully implemented and working
  • Match - UI ready, waiting for backend support
  • Matrix - UI ready, waiting for backend support

UX Enhancements Added:

  • Sound Effects - Complete audio feedback system
  • Animations - Smooth transitions and visual feedback
  • Dark Theme - Full compatibility with light/dark themes
  • Performance - Optimized animations and resource usage

Remaining Phases (Optional):

  • Phase 3: Statistics & Analytics (results submission) - 4-6 hours

Game System is Production Ready! 🎮

See GAME_TESTS_IMPLEMENTATION_PLAN.md for complete breakdown.


STAT-1: Statistics System Upgrade - PLANNING COMPLETE

Priority: HIGH
Status: 🟡 Planning Complete, Ready to Start
Estimated Time: 111-144 hours total

Plan Document: STATISTICS_UPGRADE_PLAN.md

Goal: Расширить систему сбора и отображения статистики пользователя для создания детализированной страницы профиля с красивым UI и настройками приложения.

Current Phase: Phase 1 - Backend Models and DTOs

Next Actions:

  • Phase 1.1: Расширить модели данных (4-6 hours)
  • Phase 1.2: Создать новые API endpoints (8-10 hours)
  • Phase 2.2: Переписать StatisticsService (4-5 hours)
  • Phase 3.1: Редизайн ProfilePage (12-15 hours)
  • Phase 4.1: Создать Settings Page (10-12 hours)

See STATISTICS_UPGRADE_PLAN.md for complete breakdown.


🔴 Critical Issues

CI-1: Fix Telegram Package Compilation Errors COMPLETE

Priority: HIGH
Status: Complete

Problem: telegram_web_app-0.3.3 package has compilation errors with JSExportedDartFunction type Impact: Tests cannot run, app may not compile Solution: Either update package version, remove dependency, or add conditional compilation


CI-2: Card Images Not Displaying COMPLETE

Priority: HIGH
Status: Complete
Date Fixed: December 19, 2024

Problem: Card word images not showing in packs Impact: Users cannot see card images in pack lists, details, or card viewer Root Cause: Frontend using deprecated ApiConfig generating wrong v1 API URLs instead of v2 Solution:

  • Updated all frontend widgets to use ApiConfigV2.getCardImageUrl()
  • Modified backend to allow public image access for enabled packs
  • Added proper validation (pack exists, enabled, card belongs to pack)
  • Enhanced error handling in backend endpoint

Files Fixed:

  • lib/presentation/widgets/pack_card_item.dart
  • lib/presentation/widgets/card_flipper/card_flipper.dart
  • lib/presentation/widgets/card_viewer.dart
  • lib/presentation/pages/pack_details/pack_details_page.dart
  • mnemo_cards_backend/lib/api/v2/packs_api_v2.dart

Tests Added:

  • mnemo_cards_backend/test/api/v2/packs_api_v2_test.dart (6 new tests)

CI-3: Fix Failing Tests (24 failures)

Priority: MEDIUM
Status: 🟡 In Progress

Problem: 24 tests are failing (177 passing) Impact: Mostly empty test files causing compilation errors Action: Fix test_page_test.dart empty file, investigate other failures Notes: Lower priority - most failures are from empty test files


🟡 Backend Integration Tasks

BI-0: API v2 Backend Implementation PHASE 1.2 COMPLETE

Priority: HIGH
Status: Phase 1.2 Complete (Auth API)
Latest Update: October 29, 2025

Phase 1.1 - JWT Service COMPLETE:

  • Fixed JWT crypto implementation with proper HMAC-SHA256
  • Created RefreshTokenModel Isar model for token storage
  • Implemented token storage, blacklisting, and cleanup methods
  • Written comprehensive unit tests (15 tests, all passing)

Phase 1.2 - Authentication API v2 COMPLETE:

  • Google OAuth flow implemented and tested
  • Token refresh mechanism implemented and tested
  • Logout endpoint with refresh token blacklisting
  • Get current user endpoint
  • Comprehensive integration tests (12 tests, all passing)
  • Improved error handling and error responses
  • Updated HttpRepositoryV2 logout to send refresh token

Next Steps (Phase 1.3):

  • Implement Packs API v2 with pagination and filtering
  • Implement Tests API v2
  • Implement remaining v2 APIs (Games, Purchases, Subscriptions, Promocodes)

Files Created/Modified:

  • mnemo_cards_backend/lib/api/v2/auth_api_v2.dart
  • mnemo_cards_backend/lib/api/v2/jwt_service.dart
  • mnemo_cards_backend/test/api/v2/auth_api_v2_test.dart (12 tests)
  • mnemo_cards_backend/test/api/v2/jwt_service_test.dart (15 tests)
  • mnemo_cards_web_v2/lib/domain/services/http_repository_v2.dart

BI-1: Card Flipping Functionality COMPLETE

Priority: MEDIUM
Status: Complete
Estimated Time: 0 hours (already implemented)

Description: Card flipping functionality is already fully implemented

Verification:

  • CardFlipper widget exists and works
  • Card flip UI with animations implemented
  • Progress tracking implemented
  • Integration with PackDetailsPage complete

Files Verified:

  • lib/presentation/widgets/card_flipper/card_flipper.dart
  • lib/domain/services/card_flipper_service.dart
  • lib/di/user_scope/modules/card_flipper_module.dart

BI-2: Pack Purchase Functionality COMPLETE

Priority: MEDIUM
Status: Complete
Date Completed: November 8, 2025
Time Spent: 5 hours

Description: Implement pack purchase flow with payment integration

  • Progress:
  • Implemented API v2 client helpers and PurchasesService with DI wiring
  • Added unit tests validating service → repository delegation
  • Created PurchaseStateManager with freezed states
  • Created PurchasePage with YooKassa payment integration
  • Added purchase module to DI
  • Added purchase route to app_router
  • Wrote comprehensive unit tests for state manager

Features Implemented:

  • Purchase page UI with pack preview
  • YooKassa payment integration
  • Payment URL launching
  • Payment verification dialog
  • Success/error states handling
  • Purchase state management with yx_state
  • Purchase module with DI wiring

API Endpoints Used:

  • GET /api/v2/packs/{packId}/buy - Get purchase page info
  • POST /api/v2/purchases/packs/{packId} - Create pack purchase intent
  • POST /api/v2/purchases/payments - Create YooKassa payment
  • GET /api/v2/purchases/payments/{paymentId}/verify - Verify payment status

Files Created/Updated:

  • lib/domain/models/purchase_models.dart
  • lib/domain/services/http_repository_v2.dart
  • lib/domain/services/purchases_service.dart
  • lib/domain/state/purchase_state_manager.dart (NEW)
  • lib/di/user_scope/modules/purchase_module.dart (NEW)
  • lib/di/user_scope/modules/purchases_module.dart
  • lib/di/user_scope/user_scope.dart
  • lib/di/user_scope/user_scope_container.dart
  • lib/presentation/pages/purchase/purchase_page.dart (NEW)
  • lib/presentation/router/app_router.dart
  • test/domain/services/purchases_service_test.dart
  • test/domain/state/purchase_state_manager_test.dart (NEW)

BI-2B: Pack Purchase Status Check COMPLETE

Priority: HIGH Status: Complete Date Completed: November 8, 2025 Time Spent: 2 hours

Description: Modify PackDetailsPage to check pack purchase status and redirect to purchase page if pack is not purchased.

Features Implemented:

  • Updated PackDetailsPage to use GetCardPackResponse union type
  • Added purchase status check in _loadPack() method
  • Implemented automatic redirect to /purchase/:packId for unpurchased packs
  • Maintained proper loading and error states
  • Updated all methods to handle CardPackDto type casting
  • Verified app compiles successfully with new logic

Technical Implementation:

  • Response type checking: packResponse.responseType == GetCardPackResponseType.buy
  • Automatic redirect: context.push('/purchase/${widget.packId}'); for unpurchased packs
  • Type safety: Proper as CardPackDto casting after purchase verification
  • Backward compatibility: All existing functionality preserved for purchased packs

User Experience:

  • Unpurchased packs: Direct redirect to purchase page (no details shown)
  • Purchased packs: Full pack details page with all features
  • Error states: Proper error handling for network issues
  • Loading states: Smooth loading experience maintained

Files Modified:

  • lib/presentation/pages/pack_details/pack_details_page.dart

BI-2A: Ads Reward Unlock Flow COMPLETE

Priority: HIGH Status: Complete - Real Adsgram Integration Date Completed: November 8, 2025 Time Spent: 6 hours

Description: Allow users to unlock specific packs/products on the web by watching a rewarded ad, similar to the mobile experience.

Progress:

  • Implemented AdsRewardService, AdsRewardStateManager, and user scope module with unit tests
  • Added animated shuffle transitions for pack card grid/list views
  • Created AdsRewardButton widget with state management integration
  • Integrated AdsRewardButton into pack_details_page.dart
  • Added Adsgram SDK integration for rewarded ads
  • Added loading, success, and error states to UI
  • Wrote widget tests for AdsRewardButton

Features Implemented:

  • Detect packs eligible for ad unlock and surface CTA in UI
  • Integrate Adsgram rewarded ad web SDK with proper lifecycle handling
  • Track ad playback state, completion, and failure
  • Call /ads/product/acquire/<key> upon rewarded completion and refresh user entitlements
  • Provide user feedback (loading, success, retry prompts)
  • Emit analytics events for impressions, completions, failures
  • Added Adsgram block ID configuration (16505)
  • Implemented reward callback endpoint /adsgram/reward?userId=[userId]
  • JavaScript interop with bidirectional callbacks
  • Real Adsgram SDK integration (no simulation)
  • Enhanced web/foos.js with callback system

API Endpoints Used:

  • POST /ads/product/acquire/<key> - Grant product after rewarded ad
  • GET /api/v2/packs/{packId}/buy - Check ad availability
  • GET /api/v2/adsgram/reward?userId={userId} - Adsgram reward callback

Files Created/Updated:

  • lib/presentation/widgets/ads_reward_button.dart (NEW)
  • lib/domain/config/api_config_v2.dart (ads config)
  • lib/presentation/pages/pack_details/pack_details_page.dart (integration)
  • pubspec.yaml (adsgram dependency)
  • test/presentation/widgets/ads_reward_button_test.dart (NEW)

BI-3: Subscription Management

Priority: MEDIUM
Status: 🟡 Partial (SubscriptionService exists)
Estimated Time: 4-6 hours

Description: Complete subscription purchase and management

Features Needed:

  • Subscription page UI
  • View available subscription plans
  • Purchase subscription
  • Cancel subscription
  • Show subscription status on ProfilePage

API Endpoints:

  • GET /subscription/page - Get subscription info (implemented)
  • POST /subscription/add - Purchase subscription (implemented)
  • POST /subscription/delete/<id> - Cancel subscription

Files to Create:

  • lib/presentation/pages/subscription/subscription_page.dart
  • Update subscription_service.dart with cancel method
  • Add route to app_router.dart

BI-4: Vocabulary/Review Page

Priority: LOW
Status: Not Started
Estimated Time: 6-8 hours

Description: Create vocabulary page to review all learned words across packs

Features Needed:

  • VocabularyPage in bottom navigation
  • Display all learned cards
  • Filter by pack, language
  • Search functionality
  • Review cards
  • Export vocabulary

API Endpoints:

  • GET /cards - Fetch all cards
  • GET /user/data - Get user's learning progress

Files to Create:

  • lib/presentation/pages/vocabulary/vocabulary_page.dart
  • lib/domain/services/vocabulary_service.dart
  • lib/domain/state/vocabulary_state_manager.dart
  • lib/di/user_scope/modules/vocabulary_module.dart

BI-5: Promocode Functionality

Priority: LOW
Status: 🟡 Partial (Service migrated; awaiting UI)
Estimated Time: 3-4 hours

Description: UI for entering and applying promocodes

Features Needed:

  • Promocode input field on ProfilePage or PurchasePage
  • Apply promocode
  • Show promocode benefits
  • Validate promocode

API Endpoints:

  • POST /user/promocode - Apply promocode (implemented)
  • GET /promocode/list - List available promocodes (implemented)

Files to Create:

  • lib/presentation/widgets/promocode_input.dart
  • Update promocode_service.dart UI integration

BI-6: Settings Page

Priority: LOW
Status: Not Started
Estimated Time: 2-3 hours

Description: Separate settings page (currently settings are in ProfilePage)

Features Needed:

  • Separate SettingsPage
  • Theme toggle
  • Language selection
  • Sound effects toggle
  • Notifications settings
  • Account settings

API Endpoints:

  • POST /user/settings - Update user settings

Files to Create:

  • lib/presentation/pages/settings/settings_page.dart
  • lib/domain/state/settings_state_manager.dart

BI-7: Card Images Display COMPLETE

Priority: HIGH
Status: Complete
Estimated Time: 0 hours (already implemented)

Description: Display card images in PackDetailsPage and CardFlipper

Features Needed:

  • Fetch card images from backend (using Image.network with ApiConfig.getCardImageUrl)
  • Display in card list (PackDetailsPage._buildCardImage)
  • Display in card viewer (CardViewer._buildImage)
  • Display in card flipper (CardFlipper._buildImage)

Notes: Card images are already fully implemented using Image.network. Flutter handles caching automatically. No additional work needed.


BI-8: Card Flipper Responsive Layout COMPLETE

Priority: MEDIUM
Status: Complete
Estimated Time: 2 hours

Description: Align web CardFlipper experience with mobile adaptive behavior by introducing responsive layouts while preserving existing state and animations.

Features Delivered:

  • Breakpoint resolver (compact / medium / expanded) via LayoutBuilder
  • Adaptive card sizing that respects viewport height and width
  • Responsive progress indicator and control clusters per breakpoint
  • Optional stateManagerOverride parameter for isolated widget testing
  • Widget tests covering compact, tablet, wide desktop, and tall desktop scenarios

Notes: No backend changes required. Verify new widget tests in card_flipper_responsive_test.dart during CI.


BI-9: Card Viewer Study Flow COMPLETE

Priority: MEDIUM
Status: Complete
Estimated Time: 2 hours

Description: Launch fullscreen study mode directly from pack card taps, mirroring mobile UX without redundant controls.

Features Delivered:

  • Removed dedicated “Изучение” CTA from pack controls
  • Routed taps through CardViewer with ordered card lists (shuffle + favorites aware)
  • Started study at tapped card index with consistent navigation
  • Added widget tests covering initial index, swiping order, and flip interaction

Notes: Learning progress marking remains handled externally via _markCardLearned. Future enhancements can add per-card callbacks if needed.


BI-10: Pack Details Shuffle Animation COMPLETE

Priority: LOW
Status: Complete
Estimated Time: 1 hour

Description: Make pack card shuffling feel responsive and delightful with animated transitions and control feedback.

Features Delivered:

  • Added reusable ShuffleAnimatedSwitcher for fade + scale transitions across grid/list shuffles
  • Highlighted shuffle control with active state styling and AnimatedRotation feedback
  • Animated card reordering with movement-aware wrappers plus widget/unit coverage

Notes: Animation is triggered whenever shuffle/favorites state changes via _shuffleAnimationKey. Scroll position resets intentionally to showcase rearranged cards.


🟢 Quality & Testing Tasks

QT-1: Increase Test Coverage

Priority: MEDIUM
Status: 🔴 In Progress
Progress: ~70% coverage

Areas Needing Tests:

  • pack_progress_service_test.dart
  • promocode_service_test.dart (partial)
  • subscription_service_test.dart (partial)
  • card_flipper_service_test.dart
  • All new pages

QT-2: Fix Linter Issues

Priority: LOW
Status: Not Started

Action: Run flutter analyze and fix all warnings


QT-3: Integration Tests

Priority: LOW
Status: Not Started

Tests Needed:

  • Full auth flow
  • Pack browsing and purchase
  • Test taking flow
  • Card learning flow

🚫 Blocked/Deferred Tasks

BD-1: Telegram Authentication COMPLETE

Priority: MEDIUM
Status: Complete
Completion Date: November 8, 2025

Outcome: Web-initiated Telegram login bridge with 5-minute codes, bot claims, and improved web UI.

Highlights:

  • Implemented backend /auth/telegram/web-code, /claim-code, and /code-status/{code} endpoints
  • Updated Telegram bot to accept login_<code> payloads and keep /code fallback
  • Added web login UI for code generation, bot deep-link, status polling, and auto-login
  • Created unit tests for auth service helpers and code status parsing

UI-1: PackTip Support Implementation COMPLETE

Priority: MEDIUM Status: Complete Estimated Time: 3 hours Actual Time: 5 hours

Description: Add support for CardPackPreviewDto.tip field to display small icons or badges in corners or right side of pack cards, adapting PackTip functionality from mobile app to web version for both horizontal and vertical card layouts.

Completed Tasks:

  • Created PackTipExt extension for PackTip.build() method
  • Implemented support for all PackTipType variants (asset, base64, text, unknown)
  • Added _buildPackTip() method to PackCard widget (horizontal layout)
  • Added _buildPackTip() method to PackCardVertical widget (vertical layout)
  • Implemented support for all PackTipPosition values (topRight, bottomRight, fullRight)
  • Adapted fullRight positioning: right side for horizontal, bottom banner for vertical cards
  • Refactored both card layouts to use Stack for tip overlays
  • Added proper theming and error handling
  • Verified build success and code quality

Files Created/Modified:

  • lib/utils/pack_tip_extension.dart - PackTipExt extension
  • lib/presentation/widgets/pack_card.dart - PackTip integration for horizontal cards
  • lib/presentation/widgets/pack_card_vertical.dart - PackTip integration for vertical cards

Technical Details:

  • Extension pattern for clean PackTip rendering
  • Stack-based overlay system for tip positioning on both card types
  • Adaptive positioning logic for horizontal vs vertical layouts
  • Full compatibility with mobile PackTip system
  • Type-safe implementation with proper error handling

Next Steps:

  • Test with real backend PackTip data
  • Monitor performance with multiple tips
  • Consider animation enhancements

BD-2: API v2 Implementation 🔄 IN PROGRESS

Priority: HIGH
Status: 🟡 In Progress
Estimated Time: 34-46 hours for core work

Description: Implement API v2 with OAuth2/JWT, RESTful patterns, and versioning

Current Status:

  • Backend: AuthApiV2, JwtService, authorizeV2 middleware created
  • Web: ApiConfigV2, HttpRepositoryV2 created
  • AuthService migrated to use v2
  • ⚠️ Backend: JWT crypto needs proper implementation
  • ⚠️ Backend: Remaining v2 endpoints need implementation
  • ⚠️ Web: Remaining services need migration to v2

See: FUTURE_TASKS_PLAN.md for detailed breakdown


📊 Progress Summary

Total Tasks: 18 Completed: 1 In Progress: 2 Not Started: 13 Blocked/Deferred: 2

Priority Breakdown:

  • 🔴 HIGH: 5 tasks
  • 🟡 MEDIUM: 7 tasks
  • 🟢 LOW: 5 tasks

Immediate Priority (Phase 1 - Backend v2)

  1. Fix JWT Service - Use proper crypto library for HMAC-SHA256
  2. Complete Auth API v2 - Test and verify Google OAuth flow
  3. Implement Packs API v2 - Complete all pack endpoints
  4. Implement Tests API v2 - Complete test endpoints
  5. Implement remaining v2 APIs - Games, Purchases, Subscriptions, Promocodes

Next Priority (Phase 2 - Web Migration)

  1. Complete HttpRepositoryV2 - Add all missing methods
  2. Migrate PackManager - Update to use v2
  3. Migrate remaining services - GamesManager, TestManager, etc.
  4. Remove v1 dependencies - Clean up deprecated code

After Migration (Phase 3 - Features)

  1. Pack Purchase Flow - Implement purchase UI and flow
  2. Subscription Management - Complete subscription UI
  3. Promocode UI - Add promocode input and application

For complete detailed plan, see: FUTURE_TASKS_PLAN.md


Note: Tasks are prioritized based on:

  • User impact
  • Technical dependencies
  • Development effort
  • Backend availability