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
|
||||||
|
|
||||||
## Общая информация
|
<div align="center">
|
||||||
Friflex Starter - это стартовый шаблон для разработки Flutter-приложений, который предоставляет готовую структуру проекта, настроенные инструменты и лучшие практики разработки.
|
|
||||||
|
|
||||||
## Архитектура
|
|
||||||
Проект следует принципам чистой архитектуры с разделением на три основных слоя:
|
|
||||||
- **data** - слой данных, отвечающий за работу с API и локальным хранилищем
|
|
||||||
- **domain** - слой бизнес-логики, содержащий основные бизнес-правила и модели
|
|
||||||
- **presentation** - слой представления, отвечающий за UI и взаимодействие с пользователем
|
|
||||||
|
|
||||||
Каждая функциональность (feature) реализуется в отдельной папке с внутренним разделением на слои, что обеспечивает модульность и масштабируемость кода.
|
**Корпоративный стартовый шаблон для разработки масштабируемых Flutter-приложений**
|
||||||
|
|
||||||
## Технологический стек
|
[📋 Документация](#-документация) • [🏗️ Архитектура](#️-архитектура) • [🚀 Быстрый старт](#-быстрый-старт) • [🔧 Конфигурация](#-конфигурация)
|
||||||
|
|
||||||
### Основные библиотеки
|
</div>
|
||||||
- **Роутинг**: [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` - сервисы приложения
|
|
||||||
|
|
||||||
### Конфигурационные файлы
|
**Friflex Starter** — это готовое к использованию корпоративное решение для разработки Flutter-приложений, которое включает в себя:
|
||||||
- `pubspec.yaml` - зависимости и метаданные проекта
|
|
||||||
- `analysis_options.yaml` - настройки анализа кода
|
|
||||||
- `l10n.yaml` - настройки локализации
|
|
||||||
|
|
||||||
## Документация для проектов
|
✨ **Ключевые особенности:**
|
||||||
Проект содержит подробную документацию в директории `/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)
|
|
||||||
|
|
||||||
## Внесение изменений в код
|
- **DI система**: Настроенное внедрение зависимостей
|
||||||
- [Внесение изменений в код](./tools/rfc/RFC-gitflow.md)
|
- **Роутинг**: Готовая навигационная система
|
||||||
|
- **Сервисы**: Базовые сервисы для работы с API, хранилищем, логированием
|
||||||
|
|
||||||
## Структура проекта
|
## 🏗️ Архитектура
|
||||||
- [Структура проекта](./tools/rfc/RFC-projects_structure.md)
|
|
||||||
|
|
||||||
## Ведение документации и комментариев в проекте
|
### 📐 Clean Architecture принципы
|
||||||
- [Ведение документации и комментариев в проекте](./tools/rfc/RFC-documentation.md)
|
|
||||||
|
Проект построен на основе **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