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

• 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

• 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
  • Card Images Storage: Stop storing base64 in DB; always store path/file name and serve via image endpoints (фикс 500 на картинках)
  • Card Voices Storage: Stop storing base64 in DB; store voice file name and serve via /api/v2/voice/<id> (voices list returns direct url)
  • Tests Images (Admin API): Stop returning base64 in /api/v2/admin/tests/<id>; always return image links and heal legacy base64 on read
  • Generated Tests Cleanup: Fix orphan generated tests and add TTL purge (cron/DB cleanup)

Features

• 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
• 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
• 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
• 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
• 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
• 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
• 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 19, 2025