cinnabarflower/mnemo_cards
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
mnemo_cards/mnemo_cards_web_v2/workflow_state.md
Dmitry 9414005e2a stuff
2025-11-11 02:55:41 +03:00

9.9 KiB
Raw Blame History

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)

  1. ✅ Create StatisticsService with HttpRepositoryV2 integration
  2. ✅ Implement StatisticsStateManager with yx_state (loading, loaded, error states)
  3. ✅ Add StatisticsModule to UserScope DI container
  4. ✅ Create comprehensive state management with computed properties
  5. ✅ Add error handling and state refresh capabilities
  6. ✅ Write unit tests (9 tests passing for StatisticsService, state manager tests created)

Phase 3: Statistics UI Widgets ✅ COMPLETED

  1. ✅ Create main StatisticsPage with tabbed interface (Overview, Words, Activity, Achievements, Packs)
  2. ✅ Create StatisticsOverviewWidget - dashboard with key metrics and recent achievements
  3. ✅ Create WordsStatisticsWidget - word analytics with pagination, filtering, sorting
  4. ✅ Create TimelineWidget - study activity charts and period filtering
  5. ✅ Create AchievementsWidget - progress tracking and achievement unlocks
  6. ✅ Create PackProgressWidget - individual pack completion tracking
  7. ✅ Add StatisticsPage to app navigation and bottom tab bar
  8. ✅ Implement responsive Material Design UI with proper theming
  9. ✅ Add loading states, error handling, and refresh capabilities

Phase 3: Frontend Services (THEN)

  1. ⬜ Update HttpRepositoryV2 with statistics methods
  2. ⬜ Rewrite StatisticsService with real logic
  3. ⬜ Create StatisticsStateManager and related managers
  4. ⬜ Add to DI modules

Phase 4: Frontend UI (AFTER SERVICES)

  1. ⬜ Create base statistics widgets
  2. ⬜ Redesign ProfilePage
  3. ⬜ Create Settings Page
  4. ⬜ Create statistics detail pages
  5. ⬜ 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:

  1. fl_chart library will be used for all charts
  2. Frontend will cache statistics locally for performance
  3. Settings will be stored both locally (SharedPreferences) and on server
  4. Mobile app (../mnemo_cards) can be referenced for feature ideas but not architecture

Design:

  1. Animations should be smooth but not distracting
  2. Loading states should use skeleton/shimmer
  3. All pages should be responsive (mobile/tablet/desktop)
  4. 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:

  1. 🔴 24 test failures (177 passing) - low priority, mostly empty test files
  2. ⬜ Pack purchase flow incomplete (need PurchaseService & UI)
  3. ⬜ Subscription management incomplete
  4. ⬜ 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