mnemo_cards/mnemo_cards_web_v2/FUTURE_TASKS_PLAN.md

Future Tasks Plan - mnemo_cards_web_v2

Created: October 28, 2025
Status: Active Development
Current Phase: API v2 Implementation & Feature Completion

---

📋 Overview

This document outlines the comprehensive plan for completing the mnemo_cards_web_v2 project. Tasks are organized by priority and dependency.

---

🎯 Phase 1: Complete API v2 Backend Implementation

Priority: HIGH
Estimated Time: 8-12 hours
Dependencies: None

1.1 Fix JWT Service Implementation

Status: 🔴 Critical
Time: 2-3 hours

Tasks:

• Replace placeholder HMAC-SHA256 with proper crypto library
  • Use crypto package: package:crypto/crypto.dart
  • Implement proper HMAC-SHA256 signing
  • Add secret key management (environment variable or secure storage)
• Test JWT token generation and verification
• Add token expiration handling
• Implement refresh token blacklist storage (Isar model or in-memory cache)
• Add comprehensive error handling

Acceptance Criteria:

• JWT tokens are properly signed with HMAC-SHA256
• Token verification works correctly
• Token expiration is enforced
• Refresh tokens can be invalidated

Files to Modify:

• mnemo_cards_backend/lib/api/v2/jwt_service.dart

---

1.2 Complete Authentication API v2

Status: 🟡 In Progress
Time: 2-3 hours

Tasks:

• Verify Google OAuth flow works end-to-end
• Add Telegram authentication endpoint (future)
• Test token refresh mechanism
• Add rate limiting for auth endpoints
• Add comprehensive error responses
• Write integration tests

Acceptance Criteria:

• Google OAuth flow works completely
• Token refresh works when access token expires
• Proper error messages for all failure scenarios
• Tests cover all auth flows

Files to Modify:

• mnemo_cards_backend/lib/api/v2/auth_api_v2.dart

---

1.3 Implement Packs API v2

Status: 🟡 Partial
Time: 3-4 hours

Tasks:

• Complete GET /api/v2/packs with proper pagination
  • Query params: ?page=1&limit=20&search=term&language=lang
  • Return paginated response: { items: [], total: 0, page: 1, limit: 20 }
• Implement GET /api/v2/packs/{packId}
  • Return full pack details
  • Include user's purchase status if authenticated
• Implement GET /api/v2/packs/{packId}/cards
  • Return all cards in pack
  • Support pagination if needed
• Implement GET /api/v2/packs/{packId}/cards/{cardId}/image
  • Return card image (reuse existing v1 logic)
• Implement GET /api/v2/packs/{packId}/tests
  • Return tests for pack
• Add filtering and search capabilities
• Write comprehensive tests

Acceptance Criteria:

• All pack endpoints work correctly
• Pagination works properly
• Search and filtering work
• Tests cover all endpoints

Files to Modify:

• mnemo_cards_backend/lib/api/v2/packs_api_v2.dart

---

1.4 Implement Tests API v2

Status: ⬜ Not Started
Time: 2-3 hours

Tasks:

• Implement GET /api/v2/tests/{testId}
  • Return test details
• Implement POST /api/v2/tests/{testId}/results
  • Accept test results
  • Validate results
  • Save to database
• Implement GET /api/v2/tests/{testId}/history
  • Return user's test attempt history
  • Support pagination
• Write tests

Acceptance Criteria:

• All test endpoints work correctly
• Results are properly saved
• History is correctly retrieved
• Tests cover all endpoints

Files to Create:

• mnemo_cards_backend/lib/api/v2/tests_api_v2.dart

---

1.5 Implement Games API v2

Status: ⬜ Not Started
Time: 1-2 hours

Tasks:

• Implement GET /api/v2/games
  • Return all available games
  • Include game metadata
• Implement GET /api/v2/games/{gameId}/assets
  • Return game assets URL/info
• Write tests

Acceptance Criteria:

• Games list endpoint works
• Game assets endpoint works
• Tests cover endpoints

Files to Create:

• mnemo_cards_backend/lib/api/v2/games_api_v2.dart

---

1.6 Implement Purchases API v2

Status: ⬜ Not Started
Time: 4-5 hours

Tasks:

• Implement POST /api/v2/purchases/packs/{packId}
  • Create purchase intent
  • Return purchase info
• Implement GET /api/v2/purchases/packs/{packId}/status
  • Check if pack is purchased
• Implement POST /api/v2/purchases/payments
  • Create payment (YooKassa integration)
  • Return payment URL/redirect
• Implement GET /api/v2/purchases/payments/{paymentId}/verify
  • Verify payment status
  • Update user purchases on success
• Write tests

Acceptance Criteria:

• Purchase flow works end-to-end
• Payment integration works
• Payment verification works
• User purchases are updated correctly

Files to Create:

• mnemo_cards_backend/lib/api/v2/purchases_api_v2.dart

---

1.7 Implement Subscriptions API v2

Status: ⬜ Not Started
Time: 3-4 hours

Tasks:

• Implement GET /api/v2/subscriptions/plans
  • Return available subscription plans
• Implement POST /api/v2/subscriptions
  • Create subscription (delegate to existing logic)
• Implement GET /api/v2/subscriptions/me
  • Get current user's subscription
• Implement DELETE /api/v2/subscriptions/me
  • Cancel subscription
• Write tests

Acceptance Criteria:

• All subscription endpoints work
• Subscription creation works
• Cancellation works
• Tests cover all endpoints

Files to Create:

• mnemo_cards_backend/lib/api/v2/subscriptions_api_v2.dart

---

1.8 Implement Promocodes API v2

Status: ⬜ Not Started
Time: 1-2 hours

Tasks:

• Implement GET /api/v2/promocodes
  • Return available promocodes (if public)
  • Query params: ?active=true
• Implement POST /api/v2/promocodes/{code}/apply
  • Apply promocode
  • Validate code
  • Apply discount/benefit
• Write tests

Acceptance Criteria:

• Promocode listing works
• Promocode application works
• Discounts are applied correctly
• Tests cover endpoints

Files to Create:

• mnemo_cards_backend/lib/api/v2/promocodes_api_v2.dart

---

1.9 Update Backend Routing

Status: 🟡 Partial
Time: 1 hour

Tasks:

• Mount all v2 APIs in mnemo_shelf.dart
• Verify v2 routes don't conflict with v1
• Test all v2 endpoints are accessible
• Add OpenAPI documentation for v2 endpoints

Acceptance Criteria:

• All v2 APIs are mounted correctly
• No route conflicts
• All endpoints accessible

Files to Modify:

• mnemo_cards_backend/lib/api/mnemo_shelf.dart

---

🎯 Phase 2: Migrate Web App to Use API v2

Priority: HIGH
Estimated Time: 6-8 hours
Dependencies: Phase 1 (at least backend auth must be working)

2.1 Complete HttpRepositoryV2 Implementation

Status: 🟡 Partial
Time: 2-3 hours

Tasks:

• Add missing methods to HttpRepositoryV2:
  • Purchase methods (createPackPurchase, verifyPayment, etc.)
  • Subscription methods (getSubscriptionPlans, purchaseSubscription, cancelSubscription)
  • Promocode methods (getPromocodes, applyPromocode)
  • User methods (updateUserSettings, getUserPurchases, getUserStatistics)
• Ensure all methods match API v2 endpoints
• Add proper error handling
• Write unit tests

Acceptance Criteria:

• All v2 API endpoints are accessible via HttpRepositoryV2
• Error handling is consistent
• Tests cover all methods

Files to Modify:

• mnemo_cards_web_v2/lib/domain/services/http_repository_v2.dart

---

2.2 Migrate PackManager to Use v2

Status: ⬜ Not Started
Time: 1-2 hours

Tasks:

• Update PackManager to use HttpRepositoryV2 instead of HttpRepository
• Update method calls to use v2 endpoints
• Update error handling
• Write/update tests

Acceptance Criteria:

• PackManager uses v2 API
• All pack operations work
• Tests pass

Files to Modify:

• mnemo_cards_web_v2/lib/domain/services/pack_manager.dart
• mnemo_cards_web_v2/test/domain/services/pack_manager_test.dart

---

2.3 Migrate GamesManager to Use v2

Status: 🟡 Partial
Time: 1 hour

Tasks:

• Update GamesManager to use HttpRepositoryV2
• GamesManager uses v2 API
• Games load correctly
• Tests pass

Files to Modify:

• mnemo_cards_web_v2/lib/domain/services/games_manager.dart
• mnemo_cards_web_v2/test/domain/services/games_manager_test.dart

---

2.4 Migrate TestManager to Use v2

Status: 🟡 Partial
Time: 1-2 hours

Tasks:

• Update TestManager to use HttpRepositoryV2
• TestManager uses v2 API
• Tests load and submit correctly
• Tests pass

Files to Modify:

• mnemo_cards_web_v2/lib/domain/services/test_manager.dart
• mnemo_cards_web_v2/test/domain/services/test_manager_test.dart

---

2.5 Migrate Other Services to Use v2

Status: 🟡 Partial
Time: 2-3 hours

Tasks:

• Update SubscriptionService to use HttpRepositoryV2
• Update PromocodeService to use HttpRepositoryV2
• Update StatisticsService to use v2 (if needed)
• Update PackProgressService to use v2 (if needed)
• Update tests for all services

Acceptance Criteria:

• All services use v2 API
• All functionality works
• Tests pass

Files to Modify:

• mnemo_cards_web_v2/lib/domain/services/subscription_service.dart
• mnemo_cards_web_v2/lib/domain/services/promocode_service.dart
• Related test files

---

2.6 Remove V1 Dependencies

Status: ⬜ Not Started
Time: 1 hour

Tasks:

• Remove deprecated HttpRepository from dependency injection
• Remove deprecated ApiConfig usage (or mark clearly deprecated)
• Update all references to use v2
• Clean up unused code

Acceptance Criteria:

• No v1 dependencies remain in web app
• Code is clean
• No deprecation warnings

---

🎯 Phase 3: Feature Implementation

Priority: MEDIUM
Estimated Time: 12-16 hours
Dependencies: Phase 2 complete

3.1 Pack Purchase Flow

Status: ⬜ Not Started**
Time: 6-8 hours

Tasks:

• Create PurchaseService using HttpRepositoryV2
• Implement purchase flow:
  • Check if pack is owned
  • Show "Buy Pack" button if not owned
  • Create payment via API v2
  • Handle payment redirect
  • Verify payment after return
  • Update UI to show purchased packs
• Create purchase UI:
  • Purchase confirmation dialog
  • Payment redirect handling
  • Payment status display
• Write unit tests
• Write integration tests

Acceptance Criteria:

• Users can purchase packs
• Payment flow works end-to-end
• UI updates correctly after purchase
• Tests cover purchase flow

Files to Create:

• mnemo_cards_web_v2/lib/domain/services/purchase_service.dart
• lib/presentation/pages/purchase/purchase_page.dart (if needed)
• lib/di/user_scope/modules/purchase_module.dart

Files to Modify:

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

---

3.2 Enhanced Subscription Management

Status: 🟡 Partial
Time: 4-5 hours

Tasks:

• Create subscription page UI
• Display subscription plans
• Implement subscription purchase
• Implement subscription cancellation
• Show subscription status on ProfilePage
• Add subscription benefits UI
• Write tests

Acceptance Criteria:

• Subscription page works
• Purchase flow works
• Cancellation works
• UI displays subscription status correctly

Files to Create:

• lib/presentation/pages/subscription/subscription_page.dart

Files to Modify:

• lib/presentation/pages/profile/profile_page.dart
• lib/domain/services/subscription_service.dart

---

3.3 Promocode UI

Status: ⬜ Not Started
Time: 2-3 hours

Tasks:

• Create promocode input widget
• Add promocode section to ProfilePage or PurchasePage
• Implement promocode application flow
• Show promocode benefits/status
• Handle promocode errors
• Write tests

Acceptance Criteria:

• Users can enter promocodes
• Promocodes are applied correctly
• Error handling works
• UI feedback is clear

Files to Create:

• lib/presentation/widgets/promocode_input.dart

Files to Modify:

• lib/presentation/pages/profile/profile_page.dart

---

🎯 Phase 4: Quality & Testing

Priority: MEDIUM
Estimated Time: 8-10 hours
Dependencies: Phase 2-3 complete

4.1 Comprehensive Testing

Status: ⬜ Not Started
Time: 6-8 hours

Tasks:

• Write unit tests for all v2 API endpoints (backend)
• Write unit tests for HttpRepositoryV2 (web app)
• Write integration tests for auth flow
• Write integration tests for pack browsing
• Write integration tests for purchase flow
• Write integration tests for subscription flow
• Ensure test coverage >80% for all new code

Acceptance Criteria:

• All new code has tests
• Test coverage >80%
• All tests pass

---

4.2 Fix Remaining Test Failures

Status: 🟡 In Progress
Time: 1-2 hours

Tasks:

• Fix test_page_test.dart (empty file causing compilation errors)
• Investigate other failing tests
• Fix all test failures
• Ensure all tests pass

Acceptance Criteria:

• All tests pass
• No compilation errors in tests

---

4.3 Code Quality Improvements

Status: ⬜ Not Started
Time: 2-3 hours

Tasks:

• Run flutter analyze and fix all warnings
• Fix linter errors
• Improve code documentation
• Add JSDoc comments to public APIs
• Refactor any complex code

Acceptance Criteria:

• No linter warnings
• Code is well-documented
• Code follows project patterns

---

🎯 Phase 5: Additional Features (Lower Priority)

Priority: LOW
Estimated Time: 12-16 hours
Dependencies: Phases 1-4 complete

5.1 Vocabulary/Review Page

Status: ⬜ Not Started
Time: 6-8 hours

Tasks:

• Create VocabularyPage in bottom navigation
• Fetch all learned cards across packs
• Implement filtering by pack/language
• Implement search functionality
• Create review interface
• Add export functionality
• Write tests

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

---

5.2 Settings Page

Status: ⬜ Not Started
Time: 2-3 hours

Tasks:

• Create separate SettingsPage
• Move settings from ProfilePage
• Add theme toggle
• Add language selection
• Add sound effects toggle
• Add notifications settings
• Implement settings persistence
• Write tests

Files to Create:

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

---

5.3 Telegram Authentication (Code-based)

Status: 🔴 Blocked
Time: 8-10 hours

Tasks:

• Design auth flow (code generation, validation, timeout)
• Add backend endpoints:
  • POST /api/v2/auth/telegram/request - Request auth code
  • POST /api/v2/auth/telegram/verify - Verify code and return token
• Update telegram bot with /auth command
• Implement code generation and storage in bot
• Add TelegramAuthService in web app
• Create TelegramAuthPage UI
• Integrate with existing AuthService
• Add timeout handling (codes expire after 5 min)
• Write tests

Blocker: Requires backend API endpoints and telegram bot modifications

---

🎯 Phase 6: Documentation & Deployment

Priority: LOW
Estimated Time: 4-6 hours
Dependencies: Phases 1-4 complete

6.1 API Documentation

Tasks:

• Generate OpenAPI/Swagger documentation for v2
• Document all v2 endpoints
• Add request/response examples
• Document authentication flow
• Create API migration guide

---

6.2 Deployment Preparation

Tasks:

• Update production API URLs
• Configure CORS for production
• Set up JWT secret key management
• Test deployment to staging
• Create deployment checklist

---

📊 Priority Matrix

🔴 High Priority (Complete First)

1. Fix JWT Service crypto implementation
2. Complete backend auth API v2
3. Migrate web app services to use v2
4. Implement pack purchase flow

🟡 Medium Priority (Complete Next)

1. Complete remaining backend v2 endpoints
2. Implement subscription management UI
3. Comprehensive testing
4. Fix test failures

🟢 Low Priority (Complete When Time Allows)

1. Vocabulary/Review page
2. Settings page
3. Telegram authentication
4. API documentation
5. Deployment preparation

---

📈 Estimated Timeline

Phase 1 (Backend v2): 8-12 hours
Phase 2 (Web Migration): 6-8 hours
Phase 3 (Features): 12-16 hours
Phase 4 (Quality): 8-10 hours
Phase 5 (Additional Features): 12-16 hours (optional)
Phase 6 (Documentation): 4-6 hours (optional)

Total Core Work (Phases 1-4): ~34-46 hours
Total Including Optional: ~50-68 hours

---

🎯 Success Criteria

The project will be considered complete when:

1. ✅ API v2 is fully implemented on backend
2. ✅ Web app uses API v2 exclusively
3. ✅ All core features work (auth, packs, tests, purchases, subscriptions)
4. ✅ Test coverage >80%
5. ✅ All tests pass
6. ✅ No critical bugs
7. ✅ Code follows project patterns and conventions

---

📝 Notes

• Backward Compatibility: V1 APIs should remain functional for mobile app
• Testing: Write tests as features are implemented, not after
• Documentation: Update PROGRESS.md and TODO.md after each major task
• Code Quality: Follow clean architecture, yx_scope, yx_state patterns
• Web Only: Remember this is a web app - no mobile/macOS features needed

---

Last Updated: October 28, 2025