diff --git a/README.md b/README.md index 8f4757a..2dabbb4 100644 --- a/README.md +++ b/README.md @@ -1,95 +1,300 @@ -# Описание проекта Friflex Starter +# 🚀 Friflex Starter - Enterprise Flutter Template -## Общая информация -Friflex Starter - это стартовый шаблон для разработки Flutter-приложений, который предоставляет готовую структуру проекта, настроенные инструменты и лучшие практики разработки. +
-## Архитектура -Проект следует принципам чистой архитектуры с разделением на три основных слоя: -- **data** - слой данных, отвечающий за работу с API и локальным хранилищем -- **domain** - слой бизнес-логики, содержащий основные бизнес-правила и модели -- **presentation** - слой представления, отвечающий за UI и взаимодействие с пользователем +![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) -Каждая функциональность (feature) реализуется в отдельной папке с внутренним разделением на слои, что обеспечивает модульность и масштабируемость кода. +**Корпоративный стартовый шаблон для разработки масштабируемых Flutter-приложений** -## Технологический стек +[📋 Документация](#-документация) • [🏗️ Архитектура](#️-архитектура) • [🚀 Быстрый старт](#-быстрый-старт) • [🔧 Конфигурация](#-конфигурация) -### Основные библиотеки -- **Роутинг**: [go_router](https://pub.dev/packages/go_router) -- **Управление состоянием**: [flutter_bloc](https://pub.dev/packages/flutter_bloc) -- **Внедрение зависимостей**: собственная реализация через InheritedWidget -- **Работа с ресурсами**: [flutter_gen](https://pub.dev/packages/flutter_gen) -- **Линтинг**: [friflex_lint_rules](https://pub.friflex.com/packages/friflex_lint_rules) -- **Хранение данных**: - - Защищенные данные: [flutter_secure_storage](https://pub.dev/packages/flutter_secure_storage) - - Обычные данные: [shared_preferences](https://pub.dev/packages/shared_preferences) -- **Работа с API**: [dio](https://pub.dev/packages/dio) +
-## Структура проекта +--- -### Основные директории -- `/lib` - основной код приложения - - `/app` - основные компоненты приложения - - `/features` - функциональные модули - - `/router` - настройка маршрутизации - - `/di` - настройка внедрения зависимостей - - `/l10n` - локализация - - `/gen` - сгенерированные файлы - - `/targets` - специфичные настройки для разных платформ -- `/assets` - ресурсы приложения -- `/test` - тесты -- `/tools` - инструменты и документация -- `/app_services` - сервисы приложения +## 📖 Описание проекта -### Конфигурационные файлы -- `pubspec.yaml` - зависимости и метаданные проекта -- `analysis_options.yaml` - настройки анализа кода -- `l10n.yaml` - настройки локализации +**Friflex Starter** — это готовое к использованию корпоративное решение для разработки Flutter-приложений, которое включает в себя: -## Документация для проектов -Проект содержит подробную документацию в директории `/tools/rfc/`: -- Рекомендованный README для проекта -- Инструкции по запуску проект -- Стиль написания кода -- Git-flow процесс -- Структуру проекта -- Правила ведения документации +✨ **Ключевые особенности:** -## Дополнительные особенности -- Поддержка мультиязычности (l10n) -- Шаблон для PR -- Настроенный анализ кода (analysis_options.yaml) +- 🏛️ Чистая архитектура с модульным подходом +- 🔄 Готовая система управления состоянием +- 🌐 Мультиплатформенность, разделение на сервисы +- 🛡️ Безопасное хранение данных +- 🌍 Поддержка интернационализации +- 🎨 UI Kit и система токенов дизайна +- 🔍 Инструменты отладки и мониторинга -## Начало работы -Для начала работы с проектом рекомендуется ознакомиться с документацией в директории `/tools/rfc/`, особенно с инструкциями по запуску проекта и стилем написания кода. +## 🎯 Для чего нужен стартер -## Рекомендованный Readme для проектов -#### Приложение [ProjectName] +### 🚀 Быстрый старт проектов -## Структура проекта - - проект архитектурно делится на три слоя: data, domain и presentation; - - все [features] реализуются в отдельных папках, с внутренним делением на слои; +- **Экономия времени**: Избавляет от необходимости настраивать базовую инфраструктуру с нуля +- **Унифицированный подход**: Обеспечивает единообразие всех проектов в компании +- **Проверенные решения**: Содержит только протестированные архитектурные паттерны -## Основные пакеты и реализации (обновляется при добавлении или изменении) - - управление роутингом: [go_router](https://pub.dev/packages/go_router); - - основной state manager: [flutter_bloc](https://pub.dev/packages/flutter_bloc); - - di: ручная реализация через InheritedWidget; - - работа с ресурсами: [flutter_gen](https://pub.dev/packages/flutter_gen); - - анализатор: используем [friflex_lint_rules](https://pub.friflex.com/packages/friflex_lint_rules), с правилами написания кода от компании.; - - для хранения защищенных данных - [flutter_secure_storage](https://pub.dev/packages/flutter_secure_storage); - - для хранения данных - [shared_preferences](https://pub.dev/packages/shared_preferences); - - для работы с API - [dio](https://pub.dev/packages/dio); +### 🏢 Корпоративные требования -## Инструкция по запуску проекта - - [Инструкция по запуску проекта](./tools/rfc/RFC-build.md) +- **Масштабируемость**: Поддерживает рост команды и функциональности +- **Сопровождение**: Легко поддерживается и модифицируется +- **Документированность**: Полная документация всех компонентов -## Стиль написания кода - - [Стиль написания кода](./tools/rfc/RFC-codestyle.md) +### 🛠️ Готовая инфраструктура -## Внесение изменений в код - - [Внесение изменений в код](./tools/rfc/RFC-gitflow.md) +- **DI система**: Настроенное внедрение зависимостей +- **Роутинг**: Готовая навигационная система +- **Сервисы**: Базовые сервисы для работы с API, хранилищем, логированием -## Структура проекта - - [Структура проекта](./tools/rfc/RFC-projects_structure.md) +## 🏗️ Архитектура -## Ведение документации и комментариев в проекте - - [Ведение документации и комментариев в проекте](./tools/rfc/RFC-documentation.md) +### 📐 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, // 🚀 Продакшен +} +``` + +## 🚀 Быстрый старт + +### 📋 Предварительные требования + +- Flutter 3.32.0+ +- Dart 3.8.0+ +- Xcode (для iOS) +- Android Studio (для Android) + +### 🛠️ Установка + +1. **Клонирование проекта** + +```bash +git clone +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 +``` + +### 🎯 Запуск с разными окружениями + +```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) | Правила документирования | + + +## 🎯 Особенности и нюансы + +### ✨ Преимущества + +1. **🚀 Быстрое развертывание**: Готовая к использованию инфраструктура +2. **🔧 Легкая настройка**: Минимальная конфигурация для старта +3. **📈 Масштабируемость**: Модульная архитектура поддерживает рост +4. **🛡️ Безопасность**: Встроенные механизмы защиты данных +5. **🌐 Мультиплатформенность**: Поддержка нестандартных платформ +6. **📱 Адаптивность**: Готовые решения для разных экранов + +### ⚠️ Важные нюансы + +1. **🏗️ Архитектурная дисциплина**: Требует соблюдения принципов Clean Architecture +2. **📚 Обучение команды**: Необходимо изучить корпоративные стандарты +3. **🔄 Обновления**: Регулярное обновление стартера для актуальности +4. **🎯 Кастомизация**: Некоторые решения могут потребовать адаптации под проект + +### 🔧 Рекомендации по использованию + +- **Изучите RFC** документацию перед началом работы +- **Следуйте** архитектурным принципам проекта +- **Используйте** встроенные инструменты отладки +- **Документируйте** изменения согласно стандартам +- **Тестируйте** на всех поддерживаемых платформах + +--- + +
+ +**🎯 Готов к созданию enterprise-уровня Flutter приложений!** + +*Разработано с любовью командой Friflex ❤️* + +
diff --git a/tools/rfc/RFC-README.md b/tools/rfc/RFC-README.md new file mode 100644 index 0000000..13c69ca --- /dev/null +++ b/tools/rfc/RFC-README.md @@ -0,0 +1,31 @@ +## Рекомендованный Readme для проектов +#### Приложение [ProjectName] + +## Структура проекта + - проект архитектурно делится на три слоя: data, domain и presentation; + - все [features] реализуются в отдельных папках, с внутренним делением на слои; + +## Основные пакеты и реализации (обновляется при добавлении или изменении) + - управление роутингом: [go_router](https://pub.dev/packages/go_router); + - основной state manager: [flutter_bloc](https://pub.dev/packages/flutter_bloc); + - di: ручная реализация через InheritedWidget; + - работа с ресурсами: [flutter_gen](https://pub.dev/packages/flutter_gen); + - анализатор: используем [friflex_lint_rules](https://pub.friflex.com/packages/friflex_lint_rules), с правилами написания кода от компании.; + - для хранения защищенных данных - [flutter_secure_storage](https://pub.dev/packages/flutter_secure_storage); + - для хранения данных - [shared_preferences](https://pub.dev/packages/shared_preferences); + - для работы с API - [dio](https://pub.dev/packages/dio); + +## Инструкция по запуску проекта + - [Инструкция по запуску проекта](./tools/rfc/RFC-build.md) + +## Стиль написания кода + - [Стиль написания кода](./*ools*/rfc/RFC-codestyle.md) + +## Внесение изменений в код + - [Внесение изменений в код](./tools/rfc/RFC-gitflow.md) + +## Структура проекта + - [Структура проекта](./tools/rfc/RFC-projects_structure.md) + +## Ведение документации и комментариев в проекте + - [Ведение документации и комментариев в проекте](./tools/rfc/RFC-documentation.md) \ No newline at end of file