mnemo_cards/mnemo_cards_web_v2/workflow_state.md

# Workflow State - mnemo_cards_web_v2

**Last Updated:** 2025-11-08

---

## PLAN - 🔥 STATISTICS SYSTEM UPGRADE

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

**Plan Documents:**
- Main Plan: `STATISTICS_UPGRADE_PLAN.md` (111-144 hours total)
- Backend Tasks: `../mnemo_cards_backend/STATISTICS_TASKS.md` (35-47 hours)
- Frontend Tasks: `STATISTICS_TASKS.md` (93-119 hours)

**Status:** 🟡 PLANNING COMPLETE - READY TO START

---

## CURRENT STATUS

### Completed:
- ✅ Pack cover images
- ✅ Tests functionality
- ✅ Telegram/js_util compilation
- ✅ Card images (fully implemented)
- ✅ Card flipping (fully implemented)
- ✅ API v2 foundation (Auth, Packs, Tests, Games, Purchases)
- ✅ Statistics upgrade planning (detailed plan created)

### In Progress:
- 🟡 Statistics system implementation (planning complete, ready to code)

### Not Started:
- ⬜ Pack purchase flow
- ⬜ Subscription management
- ⬜ Vocabulary/Review page
- ⬜ Promocode UI

### Known Issues:
- 🔴 24 test failures (177 passing) - low priority, mostly empty test files

---

## NEXT_ACTIONS

### Phase 1: HttpRepositoryV2 Statistics Methods ✅ COMPLETED (4 hours)
1. ✅ Add API endpoint constants to ApiConfigV2 (/statistics/detailed, /packs, /words, /timeline, /sessions, /achievements)
2. ✅ Implement 6 new repository methods in HttpRepositoryV2 with proper error handling
3. ✅ Create response DTOs (WordsStatisticsResponse, TimelineStatisticsResponse, StudySessionResponse)
4. ✅ Add query parameter support (pagination, filtering, sorting, date ranges)
5. ✅ Write smoke tests for all new methods (6 tests, all passing)

### Phase 2: Statistics Service & State Manager ✅ COMPLETED (3 hours)
6. ✅ Create StatisticsService with HttpRepositoryV2 integration
7. ✅ Implement StatisticsStateManager with yx_state (loading, loaded, error states)
8. ✅ Add StatisticsModule to UserScope DI container
9. ✅ Create comprehensive state management with computed properties
10. ✅ Add error handling and state refresh capabilities
11. ✅ Write unit tests (9 tests passing for StatisticsService, state manager tests created)

### Phase 3: Statistics UI Widgets ✅ COMPLETED
12. ✅ Create main StatisticsPage with tabbed interface (Overview, Words, Activity, Achievements, Packs)
13. ✅ Create StatisticsOverviewWidget - dashboard with key metrics and recent achievements
14. ✅ Create WordsStatisticsWidget - word analytics with pagination, filtering, sorting
15. ✅ Create TimelineWidget - study activity charts and period filtering
16. ✅ Create AchievementsWidget - progress tracking and achievement unlocks
17. ✅ Create PackProgressWidget - individual pack completion tracking
18. ✅ Add StatisticsPage to app navigation and bottom tab bar
19. ✅ Implement responsive Material Design UI with proper theming
20. ✅ Add loading states, error handling, and refresh capabilities

### Phase 3: Frontend Services (THEN)
11. ⬜ Update HttpRepositoryV2 with statistics methods
12. ⬜ Rewrite StatisticsService with real logic
13. ⬜ Create StatisticsStateManager and related managers
14. ⬜ Add to DI modules

### Phase 4: Frontend UI (AFTER SERVICES)
15. ⬜ Create base statistics widgets
16. ⬜ Redesign ProfilePage
17. ⬜ Create Settings Page
18. ⬜ Create statistics detail pages
19. ⬜ Add animations and polish

---

## ASSUMPTIONS

### Technical:
1. Backend Isar database can be extended without breaking existing data
2. API v2 endpoints are preferred over v1 for new features
3. mnemo_cards_common package is shared between backend and frontend
4. Statistics should be calculated server-side and cached
5. Session tracking will use middleware on backend
6. Achievements will be checked asynchronously after user actions

### Frontend:
7. fl_chart library will be used for all charts
8. Frontend will cache statistics locally for performance
9. Settings will be stored both locally (SharedPreferences) and on server
10. Mobile app (../mnemo_cards) can be referenced for feature ideas but not architecture

### Design:
11. Animations should be smooth but not distracting
12. Loading states should use skeleton/shimmer
13. All pages should be responsive (mobile/tablet/desktop)
14. Achievement unlocks should have celebration animations

---

## PROGRESS_LOG

### 2025-11-08: Statistics Upgrade - Planning Phase Complete ✅

**Analysis:**
- Reviewed current backend statistics (UserDataModel, WordStatisticsDto, TestStatisticsDto)
- Reviewed frontend ProfilePage (mocked statistics, basic UI)
- Identified gaps: no pack progress, no achievements, no session tracking, no difficulty scoring

**Planning:**
- Created STATISTICS_UPGRADE_PLAN.md with 10 sections, 6 phases
- Created backend task breakdown (35-47 hours, 5 phases)
- Created frontend task breakdown (93-119 hours, 8 phases)
- Updated TODO.md with STAT-1 feature entry
- Prioritized tasks into High/Medium/Low

**Key Features Planned:**
1. Extended statistics: streaks, study time, accuracy, pack progress
2. Detailed word statistics with difficulty scoring
3. Achievement system with 8+ achievement types
4. Study session tracking
5. Beautiful profile page redesign
6. Statistics detail pages (words, packs, achievements)
7. Enhanced settings page (appearance, learning, privacy, account)
8. Timeline charts and activity heatmaps
9. Animations (counters, confetti, shimmer)
10. Comprehensive testing

**Estimates:**
- Backend: 35-47 hours
- Frontend: 93-119 hours
- Total: 111-144 hours

**Next Step:** Start Phase 1.1 - Create new DTOs in mnemo_cards_common

---

### Previous Progress:

#### 2025-11-08: Pack Details UX Polish
- ✅ Added shuffle animation with AnimatedSwitcher
- ✅ Rotating control feedback
- ✅ Card movement wrappers
- ✅ Widget and unit tests
- ✅ CardViewer responsive UI
- ✅ CardFlipper responsive layout refactor

#### 2025-11-08: Ads Reward Flow
- ✅ Implemented AdsRewardService
- ✅ Created state manager
- ✅ Added user scope module
- ✅ Unit tests

#### 2025-10-29: API v2 - Authentication
- ✅ Fixed JWT Service with proper HMAC-SHA256
- ✅ Created RefreshTokenModel for token storage
- ✅ Implemented token blacklisting
- ✅ 15 JwtService tests passing
- ✅ 12 AuthApiV2 integration tests passing

#### 2025-10-29: API v2 - Packs
- ✅ Implemented all 5 Packs API v2 endpoints
- ✅ Pagination, search, filtering
- ✅ Purchase status check
- ✅ Card image endpoint
- ✅ 17 tests passing

#### 2025-10-29: API v2 - Tests
- ✅ Implemented all 3 Tests API v2 endpoints
- ✅ Submit results, get history
- ✅ Pagination for history
- ✅ 17 tests passing

#### 2025-10-29: API v2 - Games
- ✅ Implemented all 2 Games API v2 endpoints
- ✅ Get games list and assets
- ✅ 6 tests passing

#### 2025-10-29: API v2 - Purchases
- ✅ Implemented all 4 Purchases API v2 endpoints
- ✅ Pack purchase flow
- ✅ Payment creation and verification
- ✅ 13 tests passing

---

## OPEN_ISSUES

### Statistics Feature (New):
1. ⬜ Define achievement icons/images (need design)
2. ⬜ Choose color scheme for activity heatmaps
3. ⬜ Determine difficulty scoring algorithm for words
4. ⬜ Plan database migration strategy for new Isar models
5. ⬜ Consider performance impact of streak calculations
6. ⬜ Handle timezone issues for daily streaks
7. ⬜ Define session timeout duration (15 min? 30 min?)
8. ⬜ Plan caching strategy for statistics (Redis? In-memory?)
9. ⬜ Set pagination limits for words/packs lists
10. ⬜ Test with large datasets (1000+ words)
11. ⬜ Consider rate limiting for statistics API endpoints
12. ⬜ Plan GDPR compliance (data export/deletion)

### Existing Issues:
13. 🔴 24 test failures (177 passing) - low priority, mostly empty test files
14. ⬜ Pack purchase flow incomplete (need PurchaseService & UI)
15. ⬜ Subscription management incomplete
16. ⬜ Promocode UI not implemented

---

## RECENT ACCOMPLISHMENTS

✅ **API v2 Backend (Complete):**
- Authentication (Google OAuth, JWT, refresh tokens)
- Packs (list, details, cards, images, tests)
- Tests (details, submit results, history)
- Games (list, assets)
- Purchases (create, verify payments)

✅ **Frontend Features:**
- Card images and flipping (fully working)
- Pack details with responsive UI
- Card viewer with study flow
- Shuffle animations
- Ads reward flow preparation

✅ **Planning:**
- Comprehensive statistics upgrade plan (111-144 hours)
- Detailed task breakdowns for backend and frontend
- Clear priorities and dependencies

---

## WORK STRATEGY

### Development Approach:
1. **Start Small:** Begin with backend models and DTOs
2. **Test Early:** Write tests alongside implementation
3. **Iterate:** Complete one phase before moving to next
4. **Verify:** Test endpoints and UI after each phase
5. **Document:** Update PROGRESS.md and TODO.md regularly

### Quality Gates:
- All new code has unit tests
- Integration tests for all API endpoints
- Widget tests for all new UI components
- Linter passes
- No critical bugs

### Communication:
- Update workflow_state.md after each work session
- Keep progress log concise (≤100 tokens per entry)
- Mark tasks complete in TODO.md
- Update PROGRESS.md with completed features

---

## FILES TO MAINTAIN

**Planning:**
- `STATISTICS_UPGRADE_PLAN.md` - Main feature plan
- `STATISTICS_TASKS.md` - Frontend task breakdown
- `../mnemo_cards_backend/STATISTICS_TASKS.md` - Backend tasks

**Tracking:**
- `TODO.md` - High-level task list
- `workflow_state.md` - This file (current state)
- `PROGRESS.md` - Completed work log

**Documentation:**
- `README.md` - Project overview
- Future: `STATISTICS_API.md` - API documentation
- Future: `STATISTICS_UI_GUIDE.md` - UI component guide

---

**Status:** Ready to begin implementation  
**Next Action:** Create new DTOs in mnemo_cards_common  
**Estimated Time for Next Phase:** 4-6 hours