doc(readme): README.md update

2025-10-16 14:22:23 +03:00
parent fa3cf297a3
commit 4db5dda3ce
1 changed files with 445 additions and 10 deletions
--- a/README.md
+++ b/README.md
@@ -1,14 +1,449 @@
-# eatvio_app
+# Eatvio - Nutrition & Diet Management Application

+## Project Overview

---
+Eatvio is a comprehensive mobile application connecting users with nutrition consultants, providing diet planning tools, recipes, food diary tracking, and professional consultation services. The application is specifically designed for Russian-speaking users interested in nutrition and healthy eating.
+
+### Core Features
+- **Blog Posts**: Educational nutrition content and articles
+- **Nutrition Consultation**: Professional consultation services with certified nutritionists
+- **Recipes**: User-generated and professional recipes with nutritional information
+- **Diets**: Structured diet plans with daily schedules
+- **Nutrition Plans**: Long-term nutrition planning and tracking
+
+### Target Audience
+- **Primary**: Russian-speaking users interested in nutrition and healthy eating
+- **Secondary**: Certified nutrition consultants offering professional services
+- **Market**: Russian Federation and Russian-speaking countries
+
+### Business Model
+- Paid consultations with nutritionists
+- Content marketplace for premium diets and plans
+- Subscription-based features for consultants
+
+### Platform Information
+- **Mobile**: iOS and Android (including Huawei devices)
+- **Language**: Russian (ru)
+- **Current Version**: 1.3.0+79 (build 79)
+
+## Prerequisites
+
+### Flutter & Dart Versions
+- **Flutter**: SDK 3.8.0+
+- **Dart**: Language version >=3.8.0 <4.0.0
+
+### Platform-Specific Requirements
+
+#### Android
+- **NDK Version**: 27.0.12077973
+- **Huawei HMS Dependencies**:
+  - Huawei Push (6.12.0.300)
+  - Huawei Analytics (6.12.0.300)
+- **Google Play Services**
+- **ProGuard** for code obfuscation
+- **Compile SDK**: Flutter default
+- **Min SDK**: Flutter default
+- **Target SDK**: Flutter default
+
+#### iOS
+- **APNs** for push notifications
+- **Deep linking** configuration
+- **Xcode** version compatible with Flutter requirements
+
+#### General IDE Requirements
+- **VS Code** with Flutter/Dart extensions
+- **Android Studio** with Flutter plugin
+- **Visual Studio Code** recommended for development
+
+## Environment Configuration
+
+### .env Setup Process
+
+1. Copy the environment template:
+   ```bash
+   cp env.example .env
+   ```
+
+2. Edit the `.env` file with your configuration values
+
+### Required Environment Variables
+
+#### API URLs
+- `BASE_URL` - основной URL API (по умолчанию: https://eatvio.ru)
+- `DEV_BASE_URL` - URL API для разработки (по умолчанию: https://dev2.eatvio.com)
+
+#### Sentry Configuration
+- `SENTRY_DSN` - DSN для Sentry мониторинга
+
+#### Firebase Configuration
+- `FIREBASE_PROJECT_ID` - ID проекта Firebase
+- `FIREBASE_DATABASE_URL` - URL базы данных Firebase
+- `FIREBASE_STORAGE_BUCKET` - bucket для хранения файлов
+- `FIREBASE_MESSAGING_SENDER_ID` - ID отправителя сообщений
+
+#### Firebase Android Configuration
+- `FIREBASE_ANDROID_API_KEY` - API ключ для Android
+- `FIREBASE_ANDROID_APP_ID` - ID приложения для Android
+
+#### Firebase iOS Configuration
+- `FIREBASE_IOS_API_KEY` - API ключ для iOS
+- `FIREBASE_IOS_APP_ID` - ID приложения для iOS
+- `FIREBASE_IOS_BUNDLE_ID` - Bundle ID для iOS
+
+#### App Store URLs
+- `APP_STORE_URL` - URL App Store
+- `RUSTORE_URL` - URL RuStore
+
+#### Support URLs
+- `TELEGRAM_SUPPORT_URL` - URL поддержки в Telegram
+- `SUPPORT_EMAIL` - email для поддержки
+
+#### Test Credentials (только для разработки)
+- `TEST_EMAIL` - тестовый email
+- `TEST_PASSWORD` - тестовый пароль
+
+#### Email Validation API
+- `EMAIL_VALIDATION_API_URL` - URL API для валидации email
+
+#### Connection Check URLs
+- `GOOGLE_CHECK_URL` - URL для проверки соединения (Google)
+- `YANDEX_CHECK_URL` - URL для проверки соединения (Yandex)
+
+#### VK ID Configuration
+- `VK_CLIENT_ID` - ID приложения VK (числовой)
+- **Примечание**: VK_CLIENT_ID - это числовой "ID приложения" из консоли VK ID, НЕ "Защищённый ключ" или "Сервисный ключ доступа"
+
+#### Yandex ID Configuration
+- `YANDEX_CLIENT_ID` - ID приложения Yandex OAuth
+- `YANDEX_CLIENT_SECRET` - секретный ключ приложения Yandex OAuth
+- `YANDEX_REDIRECT_URI` - URI для перенаправления (должен совпадать с настройками в Yandex OAuth приложении)
+
+## Technology Stack
+
+### Core Framework
+- **Flutter**: SDK 3.8.0+
+- **Dart**: Language version >=3.8.0 <4.0.0
+- **Version**: 1.3.0+79 (build 79)
+
+### State Management
+- **flutter_bloc**: ^9.1.1 - BLoC pattern implementation
+- **equatable**: ^2.0.7 - Value equality for state objects
+
+### Data Management
+- **freezed**: ^3.2.0 - Immutable data classes
+- **freezed_annotation**: ^3.1.0 - Code generation annotations
+- **json_annotation**: ^4.9.0 - JSON serialization
+- **json_serializable**: ^6.10.0 - JSON code generation
+
+### Networking
+- **dio**: ^5.9.0 - HTTP client
+- **retrofit**: ^4.7.1 - Type-safe REST client
+- **retrofit_generator**: ^10.0.2 - Retrofit code generation
+- **http**: ^1.5.0 - Additional HTTP support
+- **http_parser**: ^4.1.2 - HTTP parsing utilities
+
+### Real-time Communication
+- **dart_pusher_channels**: ^1.2.3 - WebSocket support via Pusher
+- **connectivity_plus**: ^6.1.5 - Network connectivity monitoring
+
+### Navigation & Routing
+- **go_router**: ^16.1.0 - Declarative routing
+- Deep linking support for content
+
+### UI Components
+- **cached_network_image**: ^3.4.1 - Image caching
+- **flutter_svg**: ^2.2.0 - SVG rendering
+- **google_fonts**: ^6.3.0 - Mulish font family
+- **carousel_slider_plus**: ^7.1.1 - Carousel widgets
+- **photo_view**: ^0.15.0 - Image viewer
+- **dismissible_page**: ^1.0.2 - Swipe to dismiss
+- **badges**: ^3.1.2 - Notification badges
+- **lottie**: ^3.3.1 - Animation support
+- **flutter_portal**: ^1.1.4 - Overlay widgets
+- **dotted_border**: ^3.1.0 - Dotted borders
+- **flutter_rating_bar**: ^4.0.1 - Rating widgets
+
+### Forms & Input
+- **flutter_form_builder**: ^10.2.0 - Form management
+- **validators**: ^3.0.0 - Input validation
+- **flutter_typeahead**: ^5.2.0 - Autocomplete
+- **keyboard_dismisser**: ^3.0.0 - Keyboard management
+- **flutter_keyboard_visibility**: ^6.0.0 - Keyboard state
+- **mask_text_input_formatter**: ^2.9.0 - Input masking
+
+### Media & Files
+- **image_picker**: ^1.2.0 - Image selection
+- **flutter_image_compress**: ^2.4.0 - Image compression
+- **image**: ^4.5.4 - Image manipulation
+- **file_picker**: ^10.3.1 - File selection
+- **audioplayers**: ^6.5.0 - Audio playback
+- **qr_code_scanner_plus**: ^2.0.10+1 - QR code scanning
+
+### Data Visualization
+- **syncfusion_flutter_charts**: ^30.2.5 - Chart widgets
+- **syncfusion_flutter_gauges**: ^30.2.5 - Gauge widgets
+- **table_calendar**: ^3.2.0 - Calendar widget
+
+### Storage & Persistence
+- **shared_preferences**: ^2.5.3 - Local key-value storage
+- **path_provider**: ^2.1.5 - File system paths
+- **path**: ^1.9.1 - Path manipulation
+
+### Firebase
+- **firebase_core**: ^4.0.0 - Firebase initialization
+- **firebase_messaging**: ^16.0.0 - Push notifications
+
+### Analytics & Monitoring
+- **sentry_flutter**: ^9.6.0 - Error tracking
+- **appmetrica_plugin**: ^3.3.0 - Analytics (Russian market)
+
+### Authentication
+- **vk_id**: ^1.0.3 - VK social login
+- **flutter_login_yandex**: ^0.0.5 - Yandex ID login
+- OAuth support for OK and Mail.ru
+
+### Utilities
+- **url_launcher**: ^6.3.2 - URL handling
+- **easy_debounce**: ^2.0.3 - Debouncing
+- **share_plus**: ^11.1.0 - Content sharing
+- **flutter_html**: ^3.0.0 - HTML rendering
+- **webview_flutter**: ^4.13.0 - WebView
+- **intl**: ^0.20.2 - Internationalization
+- **collection**: ^1.19.1 - Collection utilities
+- **uuid**: ^4.5.1 - UUID generation
+- **visibility_detector**: ^0.4.0+2 - Visibility tracking
+- **fluttertoast**: ^8.2.12 - Toast messages
+- **version**: ^3.0.2 - Version management
+- **package_info_plus**: ^8.3.1 - Package info
+- **device_info_plus**: ^11.5.0 - Device information
+- **permission_handler**: ^12.0.1 - Permissions
+
+## Development Workflow
+
+### Code Generation
+- Run `flutter pub run build_runner build` for code generation
+- Run `flutter pub run build_runner build --delete-conflicting-outputs` for clean generation
+- Use `flutter pub run build_runner watch` for watch mode
+
+### Environment Setup
+- Configure `.env` file with all required variables
+- Set up Firebase for both Android and iOS platforms
+- Configure social authentication providers (VK, Yandex, etc.)
+
+### Testing
+- Unit tests with `flutter_test`
+- Integration tests with `integration_test`
+- Mocking with `mockito`
+
+## Build Commands
+
+### Development Builds
 ```bash
-# apt install linux-oem-24.04
-# sudo apt-get install --install-recommends linux-lowlatency-hwe-24.04
+# Run on connected device
+flutter run
+
+# Run on specific Android device
+flutter run -d emulator-5554
+
+# Run on specific iOS simulator
+flutter run -d iPhone\ 15
 ```

---
-ubuntu switch to hwe [kernel](https://canonical-kernel-docs.readthedocs-hosted.com/latest/reference/hwe-kernels/#installing-a-hwe-kernel)
+### Production Builds

---
-ubuntu instal intel iRIS gpu [drivers](https://dgpu-docs.intel.com/driver/client/overview.html#ubuntu-latest)
+#### Android
+```bash
+# Build APK (split by ABI)
+flutter build apk --release --split-per-abi
+
+# Build App Bundle
+flutter build appbundle --release
+
+# Huawei-specific build (with HMS)
+flutter build apk --release --flavor production --target-platform android-arm64
+```
+
+#### iOS
+```bash
+# Build IPA for TestFlight
+flutter build ipa --export-options-plist=ExportOptions.plist
+
+# Build for specific device architecture
+flutter build ipa --export-options-plist=ExportOptions.plist --no-codesign
+```
+
+## Optimization Techniques
+
+### Android Build Optimization
+1. **ProGuard Rules**:
+   - Configure rules in [`android/app/proguard-rules.pro`](android/app/proguard-rules.pro:1)
+   - Essential rules for Flutter:
+     ```
+     -keep class io.flutter.app.** { *; }
+     -keep class io.flutter.plugin.**  { *; }
+     -keep class io.flutter.util.**  { *; }
+     -keep class io.flutter.view.**  { *; }
+     ```
+
+2. **Resource Shrinking**:
+   - Enabled in `android/app/build.gradle`:
+     ```gradle
+     buildTypes {
+         release {
+             shrinkResources true
+             minifyEnabled true
+         }
+     }
+     ```
+
+3. **Code Obfuscation**:
+   - Use `--obfuscate` flag with build commands
+   - Verify with `flutter build apk --release --obfuscate --split-debug-info=debug-info/`
+
+4. **Image Compression Workflow**:
+   - Automatic compression via [`flutter_image_compress`](lib/features/create_diet/models/create_diet_model.dart:1)
+   - Configuration in image upload flows:
+     ```dart
+     final compressedFile = await FlutterImageCompress.compressWithFile(
+       file.path,
+       quality: 85,
+       minWidth: 1024,
+       minHeight: 1024,
+     );
+     ```
+
+## Troubleshooting
+
+### Common Issues
+
+#### Missing .env Variables
+- **Symptom**: Application crashes on startup with "Missing environment variable" error
+- **Solution**: 
+  1. Verify `.env` file exists in project root
+  2. Check [`ENV_SETUP.md`](ENV_SETUP.md) for required variables
+  3. Regenerate configuration with `flutter clean && flutter pub get`
+
+#### Firebase Configuration Errors
+- **Android**:
+  - Missing `google-services.json` in `android/app/`
+  - Missing `agconnect-services.json` for Huawei devices
+  - Verify SHA-1 fingerprints match Firebase console
+- **iOS**:
+  - Missing `GoogleService-Info.plist` in `ios/Runner`
+  - Check bundle identifier matches Firebase project
+
+#### WebSocket Connection Failures
+- **Symptoms**: Chat messages not delivering, real-time updates not working
+- **Solutions**:
+  1. Verify Pusher configuration in [`lib/core/websockets/ws_manager.dart`](lib/core/websockets/ws_manager.dart:1)
+  2. Check network connectivity with `connectivity_plus` package
+  3. Ensure proper authentication token is sent with WebSocket connection
+
+#### Platform-Specific Build Errors
+- **Huawei vs Google Services**:
+  - For Huawei devices, ensure `agconnect-services.json` is present
+  - Use `--flavor` flag to specify build variant:
+    ```bash
+    flutter build apk --release --flavor hms
+    ```
+  - Check for conflicting dependencies between HMS and GMS
+
+- **iOS Code Signing Issues**:
+  - Verify `ExportOptions.plist` contains correct provisioning profiles
+  - Update signing certificates in Xcode
+  - Clean build folder: `flutter clean && rm -rf ios/Pods ios/Podfile.lock`
+
+## Key Implementation Details
+
+### Content View Tracking
+- `ViewsCubit` handles visibility detection
+- `VisibilityDetector` widget tracks on-screen time
+- Views sent to backend when 50%+ visible for 2+ seconds
+- Debounced to prevent excessive API calls
+
+### Image Handling
+- `ImagePicker` for selection
+- `FlutterImageCompress` for compression
+- MultiPart form data upload via Dio
+- Preview via `CachedNetworkImage`
+
+### Search Implementation
+- Debounced search with 500ms delay
+- Min query length: 3 characters
+- Applied to: Feed, Recipes, Diets, Plans, Consultants
+- Tag-based filtering for recipes
+
+### Pagination Pattern
+- Page-based pagination
+- Scroll detection for next page load
+- Loading state during fetch
+- Meta data tracking (current page, last page)
+
+## Security Considerations
+
+### Authentication
+- Bearer token authentication
+- Secure token storage
+- Automatic session management
+- OAuth 2.0 for social login
+
+### Data Protection
+- HTTPS only communication
+- Token encryption in storage
+- Secure WebSocket connections
+- Privacy policy compliance
+
+## Key Files Reference
+
+### Entry Point
+- `lib/main.dart` - App initialization
+
+### Core Infrastructure
+- `lib/core/app_initializer.dart` - Startup sequence
+- `lib/core/locator_service.dart` - DI container
+- `lib/core/app_config.dart` - App configuration
+- `lib/core/app_router.dart` - Routing setup
+
+### WebSocket
+- `lib/core/websockets/ws_manager.dart` - Connection management
+- `lib/core/websockets/ws_service.dart` - API service
+
+### Authentication
+- `lib/features/auth/sdk/social_auth_facade.dart` - Social auth
+- `lib/core/token_storage.dart` - Token persistence
+- `lib/core/interceptors/token_interceptor.dart` - Auth interceptor
+
+### Environment
+- `lib/core/env_config.dart` - Environment variables
+- `.env` - Environment file (not in repo)
+
+## Key Success Metrics
+
+- User engagement with food diary
+- Consultation bookings and completion rates
+- Content creation by consultants
+- User retention and progress tracking
+
+## Documentation Standards
+
+- **Last Updated**: 2025-10-16
+- All paths are relative to `/home/apoloz/dev/eatvio_app`
+- Russian market focus maintained throughout documentation
+- Version compatibility matrix:
+  | Component | Version | Notes |
+  |-----------|---------|-------|
+  | Flutter | 3.8.0+ | Required |
+  | Dart | 3.8.0-3.9.9 | Required |
+  | Android SDK | 34 | Target SDK |
+  | iOS Deployment | 14.0 | Minimum |
+
+## Ubuntu Development PC Optimization
+ ```bash
+-# apt install linux-oem-24.04
+-# sudo apt-get install --install-recommends linux-lowlatency-hwe-24.04
+```
+----
+- ubuntu switch to hwe [kernel](https://canonical-kernel-docs.readthedocs-hosted.com/latest/reference/hwe-kernels/#installing-a-hwe-kernel)
+----
+- ubuntu instal intel iRIS gpu [drivers](https://dgpu-docs.intel.com/driver/client/overview.html#ubuntu-latest)
+```