mirror of
https://github.com/smmarty/friflex_flutter_starter.git
synced 2025-12-22 01:20:46 +00:00
docs(rfc): Добавить рекомендованный README для проектов с описанием структуры и инструкциями.
This commit is contained in:
PetrovY
357
README.md
357
README.md
@@ -1,95 +1,300 @@
|
||||
# Описание проекта Friflex Starter
|
||||
# 🚀 Friflex Starter - Enterprise Flutter Template
|
||||
|
||||
## Общая информация
|
||||
Friflex Starter - это стартовый шаблон для разработки Flutter-приложений, который предоставляет готовую структуру проекта, настроенные инструменты и лучшие практики разработки.
|
||||
<div align="center">
|
||||
|
||||
## Архитектура
|
||||
Проект следует принципам чистой архитектуры с разделением на три основных слоя:
|
||||
- **data** - слой данных, отвечающий за работу с API и локальным хранилищем
|
||||
- **domain** - слой бизнес-логики, содержащий основные бизнес-правила и модели
|
||||
- **presentation** - слой представления, отвечающий за UI и взаимодействие с пользователем
|
||||
|
||||
|
||||
|
||||
Каждая функциональность (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)
|
||||
</div>
|
||||
|
||||
## Структура проекта
|
||||
---
|
||||
|
||||
### Основные директории
|
||||
- `/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 <repository_url>
|
||||
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** документацию перед началом работы
|
||||
- **Следуйте** архитектурным принципам проекта
|
||||
- **Используйте** встроенные инструменты отладки
|
||||
- **Документируйте** изменения согласно стандартам
|
||||
- **Тестируйте** на всех поддерживаемых платформах
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
|
||||
**🎯 Готов к созданию enterprise-уровня Flutter приложений!**
|
||||
|
||||
*Разработано с любовью командой Friflex ❤️*
|
||||
|
||||
</div>
|
||||
|
||||
31
tools/rfc/RFC-README.md
Normal file
31
tools/rfc/RFC-README.md
Normal file
@@ -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)
|
||||
Reference in New Issue
Block a user