friflex_flutter_starter/README.md

<div align="center">

# 🚀 Friflex Flutter Starter - Корпоративный шаблон

</div>
<div align="center">

![Flutter](https://img.shields.io/badge/Flutter-3.32.0+-02569B?style=for-the-badge&logo=flutter&logoColor=white)
![Dart](https://img.shields.io/badge/Dart-3.8.0+-0175C2?style=for-the-badge&logo=dart&logoColor=white)
![Version](https://img.shields.io/badge/Version-v0.0.1-green?style=for-the-badge)
![License](https://img.shields.io/badge/License-MIT-blue?style=for-the-badge)

**Корпоративный стартовый шаблон для разработки масштабируемых Flutter-приложений**

[📋 Документация](#-документация) • [🏗️ Архитектура](#️-архитектура) • [🚀 Быстрый старт](#-быстрый-старт) • [🔧 Конфигурация](#-конфигурация)

</div>

---

## 📖 Описание проекта

**Friflex Starter** — это готовое к использованию корпоративное решение для разработки Flutter-приложений, которое включает в себя:

✨ **Ключевые особенности:**

- 🏛️ Чистая архитектура с модульным подходом
- 🔄 Готовая система управления состоянием
- 🌐 Мультиплатформенность, разделение на сервисы
- 🛡️ Безопасное хранение данных
- 🌍 Поддержка интернационализации
- 🎨 UI Kit и система токенов дизайна
- 🔍 Инструменты отладки и мониторинга

## 🎯 Для чего нужен стартер

### 🚀 Быстрый старт проектов

- **Экономия времени**: Избавляет от необходимости настраивать базовую инфраструктуру с нуля
- **Унифицированный подход**: Обеспечивает единообразие всех проектов в компании
- **Проверенные решения**: Содержит только протестированные архитектурные паттерны

### 🏢 Корпоративные требования

- **Масштабируемость**: Поддерживает рост команды и функциональности
- **Сопровождение**: Легко поддерживается и модифицируется
- **Документированность**: Полная документация всех компонентов

### 🛠️ Готовая инфраструктура

- **DI система**: Настроенное внедрение зависимостей
- **Роутинг**: Готовая навигационная система
- **Сервисы**: Базовые сервисы для работы с API, хранилищем, логированием

## 🏗️ Архитектура

### 📐 Clean Architecture принципы

Проект построен на основе **Clean Architecture** с четким разделением ответственности:

```text
┌─────────────────────────────────────────┐
│              PRESENTATION               │
│  🎨 UI, Screens, Widgets           
├─────────────────────────────────────────┤
│               DOMAIN                    │
│  📋 Business Logic,BLoC, Entities, 
├─────────────────────────────────────────┤
│                DATA                     │
│  🗄️ Repositories, Data Sources, DTO   
└─────────────────────────────────────────┘
```

#### 📦 Слои архитектуры

- **🎨 Presentation** - UI компоненты, экраны
- **📋 Domain** - Бизнес-логика, сущности, интерфейсы репозиториев, BLoC/Cubit для управления состоянием
- **🗄️ Data** - Реализация репозиториев, работа с API и локальным хранилищем

### 🏗️ Feature-модульная структура

Каждая функциональность изолирована в отдельном модуле:

```text
features/
├── auth/              # 🔐 Авторизация
│   ├── data/          # API, репозитории
│   ├── domain/        # Бизнес-логика
│   └── presentation/  # UI компоненты
├── profile/           # 👤 Профиль пользователя
└── debug/             # 🐛 Инструменты отладки
```

## 🛠️ Технологический стек

### 🚀 Основные технологии

| Категория | Библиотека | Версия | Описание |
|-----------|------------|--------|----------|
| 🧭 **Навигация** | [go_router](https://pub.dev/packages/go_router) | `15.1.2` | Декларативный роутинг |
| 🔄 **State Management** | [flutter_bloc](https://pub.dev/packages/flutter_bloc) | `9.1.1` | Управление состоянием |
| 💉 **DI** | Custom InheritedWidget | - | Внедрение зависимостей |
| 🎨 **Resources** | [flutter_gen](https://pub.dev/packages/flutter_gen) | `5.10.0` | Генерация ресурсов |
| 🌐 **HTTP** | [dio](https://pub.dev/packages/dio) | `5.8.0+1` | HTTP клиент |
| 🔒 **Secure Storage** | [flutter_secure_storage](https://pub.dev/packages/flutter_secure_storage) | - | Защищенное хранилище |
| 📊 **Logging** | [talker](https://pub.dev/packages/talker_flutter) | `4.8.0` | Логирование и отладка |

### 🔧 Инструменты разработки

- **📝 Линтинг**: корпоративные правила кода
- **🏗️ Code Generation**: `build_runner` для генерации кода
- **🌍 Локализация**: `flutter_localizations` + `intl`
- **⚙️ Окружения**: `envied` для управления переменными

## 🗂️ Структура проекта

```text
friflex_starter/
├── 🎨 assets/             # Ресурсы приложения
│   ├── fonts/              # Шрифты
│   ├── icons/              # Иконки
│   ├── images/             # Изображения
│   └── lottie/             # Анимации
├── 🌐 app_services/       # Платформо-зависимые сервисы
│   ├── base/               # Базовая реализация
│   ├── aurora/             # Aurora OS реализация
│   └── i_app_services/     # Интерфейсы
├── 📂 lib/
│   ├── 🏠 app/             # Основные компоненты
│   ├── 💉 di/              # Dependency Injection
│   ├── 🧭 router/          # Навигация
│   ├── 🎯 features/        # Функциональные модули
│   ├── 🌍 l10n/            # Локализация
│   ├── ⚙️ gen/             # Сгенерированные файлы
│   └── 🎯 targets/         # Точки входа для разных окружений
├── 🧪 test/                # Тесты
└── 🛠️ tools/               # Инструменты и документация
    └── 📋 rfc/             # RFC документация
```

### 🎯 Особенности структуры

#### 🌐 Мультиплатформенные сервисы

Проект поддерживает различные платформы через абстракцию сервисов:

- **Base** - стандартная реализация для Google Services
- **Aurora** - специальная реализация для Aurora OS
- **Interfaces** - общие интерфейсы для всех платформ

#### ⚙️ Система окружений

```dart
enum AppEnv {
  dev,    // 🧪 Разработка с мок-данными
  stage,  // 🧪 Тестирование
  prod,   // 🚀 Продакшен
}
```

## 🚀 Быстрый старт

### 🛠️ Установка

1. **Клонирование проекта**

```bash
git clone https://github.com/smmarty/friflex_starter.git
cd friflex_starter
```

2. **Установка зависимостей**

```bash
flutter pub get
```

3. **Генерация файлов**

```bash
dart run build_runner build --delete-conflicting-outputs
flutter packages pub run flutter_gen
```

4. **Запуск приложения**

```bash
flutter run
```

5. **Замените название пакета на ваш**

### 🎯 Запуск с разными окружениями

```bash
# Разработка
flutter run --target lib/targets/dev.dart

# Тестирование  
flutter run --target lib/targets/stage.dart

# Продакшен
flutter run --target lib/targets/prod.dart
```

## 🔧 Конфигурация

### ⚙️ Переменные окружения

Создайте файлы окружения в папке `env/`:

- `dev.env` - для разработки
- `stage.env` - для тестирования
- `prod.env` - для продакшена

### 🎨 Генерация ресурсов

```bash
# Генерация ассетов
flutter packages pub run flutter_gen
```

```bash
# Полная перегенерация
dart run build_runner build --delete-conflicting-outputs
```

## 🧪 Отладка

### 🐛 Debug Screen

Встроенный экран отладки предоставляет:

- 📊 Информацию о текущем окружении
- 🔧 Настройки темы
- 🌍 Переключение языков
- 🎨 Просмотр UI Kit
- 🔐 Управление токенами
- 📈 Работа с логами
- 🔄 Тестирование компонентов

Доступ через `DebugScreen` или debug-меню в приложении.

### 📝 Логирование

Интегрированная система логирования Talker:

- HTTP запросы/ответы
- BLoC события и состояния
- Общие логи приложения
- Ошибки и исключения

## 📋 Документация

Полная документация проекта находится в директории `/tools/rfc/`:

| Документ | Описание |
|----------|----------|
| 📖 [RFC-README.md](./tools/rfc/RFC-README.md) | Рекомендованный Readme |
| 📋 [RFC-build.md](./tools/rfc/RFC-build.md) | Инструкции по сборке |
| 🎨 [RFC-codestyle.md](./tools/rfc/RFC-codestyle.md) | Стандарты кода |
| 🔄 [RFC-gitflow.md](./tools/rfc/RFC-gitflow.md) | Git workflow |
| 🏗️ [RFC-projects_structure.md](./tools/rfc/RFC-projects_structure.md) | Структура проекта |
| 📝 [RFC-documentation.md](./tools/rfc/RFC-documentation.md) | Правила документирования |
| 🔧 [RFC-managing_generated_files.md](./tools/rfc/RFC-managing_generated_files.md) | Рекомендации по управлению сгенерированными файлами |
| 🌐 [RFC-managing_pubspec_lock.md](./tools/rfc/RFC-managing_pubspec_lock.md) | Рекомендации по управлению pubspec.lock

## 🎯 Особенности и нюансы

### ✨ Преимущества

1. **🚀 Быстрое развертывание**: Готовая к использованию инфраструктура
2. **🔧 Легкая настройка**: Минимальная конфигурация для старта
3. **📈 Масштабируемость**: Модульная архитектура поддерживает рост
4. **🛡️ Безопасность**: Встроенные механизмы защиты данных
5. **🌐 Мультиплатформенность**: Поддержка нестандартных платформ
6. **📱 Адаптивность**: Готовые решения для разных экранов

### 🔧 Рекомендации по использованию

- **Изучите RFC** документацию перед началом работы
- **Следуйте** архитектурным принципам проекта
- **Используйте** встроенные инструменты отладки
- **Документируйте** изменения согласно стандартам
- **Тестируйте** на всех поддерживаемых платформах

---

## 📄 Лицензия

Этот проект распространяется под лицензией MIT License. Подробности смотрите в файле [LICENSE](./LICENSE).

Copyright © 2025 Friflex LLC. Все права защищены.

---


<div align="right">

*Разработано с любовью командой Friflex ❤️*

</div>