mnemo_cards/TODO.md

- Подготовить Dockerfile и CI/CD для Dart backend под Coolify.
- Подготовить Dockerfile и CI/CD для веб/админки (статический билд + nginx/caddy).
- Завести сервисы и домены в Coolify (api/web/admin) с Traefik/LE.
- Переключить трафик, остановить legacy nginx/systemd после проверки.
# Mnemo Cards TODO List

## High Priority

### Infrastructure & Deployment
- [x] **Admin Panel Deployment**: Fixed automated CI/CD pipeline for admin panel
  - Fixed directory navigation issue in `tools/deploy/admin/deploy.sh`
  - Modified `check_project_root()` function to automatically navigate to `mnemo_cards_admin/web`
  - **Enhanced portability**: Script can now be run from any directory within the project
  - Added intelligent project root detection that searches upwards from script location
  - **SSL Certificate Fix**: Resolved HTTPS certificate issue for admin.mnemo-cards.online
    - Created automated SSL certificate renewal script (`tools/ssl/renew_admin_ssl.sh`)
    - Obtained Let's Encrypt certificate for admin.mnemo-cards.online
    - Updated nginx configuration to use HTTPS with proper SSL certificates
    - Added automatic certificate renewal via cron job
  - **Admin API Configuration Fix**: Fixed admin authentication API URL routing
    - Created separate `adminApiClient` that always uses production backend (`https://api.mnemo-cards.online`)
    - Admin authentication now correctly routes to production server instead of localhost:8000
    - Prevents authentication failures during local development
  - Admin panel deployment now works correctly from CI/CD pipeline and any project directory with valid HTTPS

- [x] **Telegram Bot Deployment**: Created automated CI/CD pipeline for telegram bot
  - Created `deploy_bot.yaml` workflow for automated bot deployment
  - Triggers on changes to `mnemo_cards_telegram_bot/**`, `mnemo_cards_common/**`, `mnemo_cards_common_backend/**`
  - Compiles Dart executable and updates systemd service
  - Includes proper error handling and service verification

- [ ] **Monitoring Setup**: Implement comprehensive monitoring for all services
  - Application performance monitoring (APM)
  - Server resource monitoring
  - Service health checks
  - Alerting system

- [ ] **Backup Automation**: Automated backup procedures
  - Database backups
  - Configuration backups
  - User data backups
  - Recovery testing

- [ ] **Load Testing**: Performance testing under load
  - Identify bottlenecks
  - Optimize resource usage
  - Scalability testing

### Testing
- [ ] **Unit Test Coverage**: Expand unit test coverage
  - Backend services: Target 80% coverage
  - Frontend components: Target 70% coverage
  - Common libraries: Target 90% coverage
  - ✅ **MinIO Backend Tests**: Added unit tests for MinioService and MediaApiV2
    - Created `test/storage/minio_service_test.dart` for MinioService configuration and logic tests
    - Created `test/api/v2/media_api_v2_test.dart` for MediaApiV2 endpoint tests with mocked MinioService
    - Tests cover admin access control, bucket validation, presigned URL generation, and file deletion
  - ✅ **Admin Panel MinIO Integration**: Updated all file upload components for MinIO
    - Created Media API client (`src/api/media.ts`) for file uploads
    - Updated ImageUpload component: uploads via Media API, saves objectId, previews via presigned URLs
    - Updated AudioUpload component: uploads via Media API, saves objectId
    - Updated BulkCardUpload: batch uploads via Media API with progress indicators
    - Updated preview logic: uses presigned URLs from backend when available
    - All components maintain backward compatibility with legacy base64/URL formats
  - ✅ **Web App MinIO Integration**: Updated all widgets for MinIO presigned URLs
    - Updated DTOs in mnemo_cards_common: added imageUrl/imageBackUrl/presignedUrl to test question DTOs
    - Updated backend test_manager: adds imageUrl while keeping image (objectId) for questions and buttons
    - Updated all card display widgets: card_viewer, card_flipper, pack_details_page, pack_card_item
    - Updated test widgets: matrix_widget, answer_options, question_display
    - Updated tests_state_manager: converts DTOs to use presigned URLs when available
    - All widgets maintain backward compatibility with fallback to ApiConfigV2 URL building
  - ✅ Added unit test for version display on auth page
  - ✅ Admin: fixed `BulkCardEditor` pack loading TypeScript error (TS2352) + unit test; added JSDOM polyfills for Radix Select
  - ✅ Web: CardViewer navigation controls are constrained under the card on wide screens (widget test added)
  - ✅ Web: CardViewer header controls — voice left + favorite right (heart is part of the card), while the title stays centered (widget test added)
  - ✅ Web: Pack details "Перемешать" button has no active (pressed) state (widget test updated)
  - ✅ Web: Pack details cards — removed "view" (eye) icon; moved favorite (heart) to top-right corner (widget test updated)
  - ✅ **User Telegram Field Tests**: Added comprehensive unit tests for telegram field
    - Created `test/models/user_model_telegram_test.dart` with 6 test cases
    - Created `test/user_dto_telegram_test.dart` with 7 test cases
    - Tests cover serialization, deserialization, null handling, and copyWith functionality
  - ✅ Refactored authentication components - need to add unit tests for SignInWithGoogleButton and SignInWithTelegram
  - ✅ Added comprehensive unit tests for ThemeToggleWidget (7 test cases covering all functionality)
  - ✅ Game/Test flow cleanup: removed traditional test entry, themed game page, added widget coverage for question card surfaces, exit control, and interactive-only notice; timer/progress pulled from live session state
  - ✅ Web: fixed game navigation actions (Exit/Finish/Back) by using push to `/game/:id` and adding deep-link fallback + widget tests
  - ✅ Game Tests package: created `games/packages/game_tests`, added `GameTestSettings`, integrated into `mnemo_cards_web_v2` settings and state manager
  - ✅ **Test Page Code Quality Fix**: Fixed critical code duplication in `test_page.dart`
    - Removed 700+ lines of duplicate code
    - Added missing state variables and TestResult class
    - Fixed deprecated method calls and compilation issues
    - Restored full test functionality
  - ✅ **PackDetailsHeader Code Fix**: Fixed critical structural issues in pack details header widget
    - Resolved broken method structure with hanging code blocks
    - Created missing `_buildTitleSection` method
    - Removed undefined `cachedImage` variable usage
    - Cleaned up unused imports
    - Fixed all linter errors and compilation issues
  - ✅ **Pack Details Controls**: Control buttons (Сетка/Карточки, Перемешать, Избранные) now adaptively hide text when there's insufficient space
    - Implemented LayoutBuilder + TextPainter to measure text width
    - Buttons maintain full width expansion while showing only icons when text doesn't fit
    - Added comprehensive widget tests for both wide and narrow layouts
  - ✅ Backend: Added regression test ensuring generated tests are linked to packs
  - ✅ **Loading Screens Enhancement**: Replaced basic loading screens with themed images
    - Removed CircularProgressIndicator from both initialization and app loading screens
    - Added sun image (el_sol.png) for light theme and moon image (la_luna.png) for dark theme
    - Created theme-aware loading screen components using StateBuilder
    - Added assets/images/ to pubspec.yaml and updated app.dart with new loading UI
  - ✅ **Test Images Fix**: Fixed missing images in game tests (matrix questions)
    - Fixed matrix question generation: now uses card.image instead of card.id for button images
    - Unified MinIO bucket structure: all images (cards and tests) now use single cardImagesBucket
    - Removed testImagesBucket bucket - simplified architecture to single bucket for all images
    - Fixed image conversion to keep image as objectId and add imageUrl as presigned URL (no overwrite)
    - Updated all API endpoints (MediaApiV2, AdminTestsApiV2, TestManager) to use unified bucket
    - Updated all tests (media_api_v2_test, minio_service_test) to reflect single bucket structure
    - Added comprehensive unit tests in test_manager_image_conversion_test.dart with 3 test cases

- [ ] **Integration Tests**: Implement comprehensive integration testing
  - API endpoint testing
  - Database operations
  - Service interactions

- [ ] **E2E Tests**: End-to-end testing suite
  - User journey testing
  - Cross-browser compatibility
  - Mobile device testing

## Medium Priority

### Security
- [ ] **Security Audit**: Comprehensive security review
  - Code security analysis
  - Infrastructure security
  - Data protection compliance

- [ ] **Advanced Security**: Enhanced security measures
  - Rate limiting implementation
  - Advanced firewall rules
  - Intrusion detection
  - Security headers optimization

### Performance
- [ ] **Frontend Optimization**: Web application performance
  - Bundle size optimization
  - Lazy loading implementation
  - Caching strategies

- [ ] **Backend Optimization**: API performance improvements
  - Database query optimization
  - Caching layer implementation
  - Response time optimization
  - [x] **Card Images Storage**: Stop storing base64 in DB; always store path/file name and serve via image endpoints (фикс 500 на картинках)
  - [x] **Card Voices Storage**: Stop storing base64 in DB; store voice file name and serve via `/api/v2/voice/<id>` (voices list returns direct `url`)
  - [x] **Tests Images (Admin API)**: Stop returning base64 in `/api/v2/admin/tests/<id>`; always return image links and heal legacy base64 on read
  - [x] **Generated Tests Cleanup**: Fix orphan generated tests and add TTL purge (cron/DB cleanup)

### Features
- [x] **Card Voices**: Audio metadata & playback
  - Isar collection for voices linked to cards
  - API for voices list and mp3 delivery
  - Web UI playback with error handling and tests
  - Fix web playback 401: fetch voice bytes via authenticated API and play from memory
  - UI: move voice play icon into a `Stack` overlay on card so it doesn't take an extra row
- [x] **Admin Card Voices**: Upload voice on card Create/Update
  - Added voice uploader to card editor (upload on Save)
  - Added unit tests for upsert+voice flow
- [x] **Admin Packs: Color Palette Picker**: Add palette-based pack color selection
  - Replace free-text hex input with native picker (palette)
  - Remove hardcoded default swatch colors (keep only palette)
  - Add unit tests for the picker component
- [x] **Admin Tests: Link to Packs**: Add pack selection in test editor and sync test↔pack links on Save
  - Add unit test coverage for pack-linking UI
- [x] **Admin Tests: Color Picker + Pack Color Sync**: Use palette picker for test color and sync from selected pack
  - Replace free-text test color input with `ColorPaletteInput`
  - Auto-update test color when selecting/changing a pack in test editor
- [x] **Matrix Test (image selection)**: Add matrix question type end-to-end (backend + web + admin)
  - Auto-generate matrix images from pack card pool (generator framework)
  - Web: multi-stage single question (shake on wrong, flip+reveal translation on correct, then disappear)
  - Admin: matrix size configuration + JSON (de)serialization + tests
- [x] **Matrix Question Types**: Added support for different matrix question types
  - Created MatrixQuestionType enum with 5 types (original_translation, original_images, translation_originals, audio_images, audio_translation)
  - Backend generates stages array with all target words/audio upfront
  - MatrixCardDto adaptively fills only needed fields based on question type
  - Web UI supports stages navigation, audio playback, and adaptive card display
  - Need to add unit tests for generator and all question types
- [x] **CardViewer Carousel Looping**: Implement infinite carousel scrolling for card viewer
  - Cards loop seamlessly: last card → first card and first card → last card
  - Works for both swipe gestures and navigation buttons
  - Added comprehensive unit tests for looping functionality
- [ ] **User Experience**: Enhanced user experience features
  - Offline mode support
  - Progressive Web App (PWA)
  - Advanced statistics and analytics

## Low Priority

### Infrastructure
- [ ] **CDN Integration**: Content delivery network
  - Static asset delivery
  - Global performance improvement
  - Cost optimization

- [ ] **Containerization**: Docker containerization
  - Development environment standardization
  - Deployment consistency
  - Scaling capabilities

### Documentation
- [ ] **API Documentation**: Comprehensive API docs
  - OpenAPI/Swagger documentation
  - Developer guides
  - Integration examples

- [ ] **User Documentation**: User-facing documentation
  - User guides
  - FAQ section
  - Video tutorials

### Analytics
- [ ] **Usage Analytics**: User behavior analysis
  - Feature usage tracking
  - Performance metrics
  - User engagement analysis

---

## Development Guidelines

### Code Quality
- Follow established coding standards
- Implement proper error handling
- Use TypeScript/Flow for type safety
- Regular code reviews

### Testing Strategy
- Write tests before implementing features (TDD)
- Maintain test coverage above established thresholds
- Regular integration testing
- Performance regression testing

### Deployment Process
- Automated deployment pipeline
- Rollback capabilities
- Environment parity
- Zero-downtime deployments

---

*Last updated: December 20, 2025*