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:**
- [x] 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:**
- [x] 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:**
- [x] Update `SubscriptionService` to use `HttpRepositoryV2`
- [x] 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