🏗️ Clean Architecture Flutter Framework

Готовый каркас Flutter приложения с Clean Architecture, настроенными инструментами разработки и современным стеком технологий для быстрого старта новых проектов.

⚡ Быстрый старт

🚀 Запуск приложения

# Основное приложение с Device Preview
flutter run -d windows

# Или на любой другой платформе
flutter run -d chrome
flutter run -d android  # при наличии эмулятора

📚 Запуск Widgetbook (каталог компонентов)

# Для разработки UI компонентов изолированно
flutter run widgetbook/main.dart -d windows

🧪 Запуск тестов

# Все тесты
flutter test

# Только unit тесты
flutter test test/features/presentation/cubit/theme_cubit_test.dart

# С покрытием
flutter test --coverage

🛠️ Генерация кода (после изменений)

# Одноразово
dart run build_runner build --delete-conflicting-outputs

# С отслеживанием изменений
dart run build_runner watch

💡 Как пользоваться

1. Device Preview - переключайте устройства прямо в приложении (справа в панели)
2. Widgetbook - разрабатывайте компоненты изолированно, тестируйте разные состояния
3. Настройки темы - в приложении Settings → Theme (Light/Dark/System)
4. Добавление фич - следуйте структуре Clean Architecture в папке features/

---

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

📋 Предварительные требования

• Flutter SDK 3.27.0 или выше
• Dart 3.0.0 или выше
• Visual Studio (для Windows)
• Android Studio (опционально)

💻 Как запустить

1. Клонируйте репозиторий и установите зависимости:

git clone <repository-url>
cd clean_architecture_application_framework
flutter pub get

2. Генерация кода:

dart run build_runner build --delete-conflicting-outputs

3. Запуск основного приложения:

# На Windows
flutter run -d windows

# На Android (при наличии эмулятора)
flutter run -d android

# На Web
flutter run -d chrome

4. Запуск Widgetbook для разработки компонентов:

flutter run widgetbook/main.dart -d windows

🧪 Тестирование

Widget Testing через Widgetbook

Widgetbook позволяет изолированно разрабатывать и тестировать UI компоненты:

1. Запустите Widgetbook:

flutter run widgetbook/main.dart -d windows

2. В интерфейсе Widgetbook:
   • Выберите компонент в левой панели
   • Тестируйте разные состояния и параметры
   • Переключайтесь между темами (Light/Dark)
   • Эмулируйте разные устройства

Device Preview

Приложение включает Device Preview для тестирования на разных устройствах:

• 📱 iPhone SE, iPhone 13
• 📱 Samsung Galaxy S20
• 📱 Различные Android устройства

Переключайтесь между устройствами прямо в приложении!

Автотесты

Запуск всех тестов:

flutter test

Запуск с покрытием:

flutter test --coverage

🏛️ Архитектура проекта

Проект следует принципам Clean Architecture с разделением на 3 основных слоя:

📁 Структура папок

lib/
├── 🎯 features/           # Бизнес-функциональность
│   ├── 📊 data/          # Слой данных
│   │   ├── datasources/  # Источники данных (API, Local)
│   │   ├── models/       # Модели данных
│   │   └── repositories/ # Реализация репозиториев
│   ├── 💼 domain/        # Бизнес-логика
│   │   ├── entities/     # Сущности предметной области
│   │   ├── repositories/ # Контракты репозиториев
│   │   └── usecases/     # Варианты использования
│   └── 🎨 presentation/  # UI слой
│       ├── cubit/        # Управление состоянием
│       └── screens/      # Экраны приложения
├── ⚙️ core/              # Общие компоненты
│   ├── di/               # Dependency Injection
│   ├── router/           # Навигация
│   └── usecases/         # Базовые UseCase
└── 📱 main.dart          # Точка входа

widgetbook/               # 📚 Каталог компонентов
test/                     # 🧪 Тесты

🛠️ Используемые технологии

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

• Clean Architecture - Разделение ответственности
• BLoC (Cubit) - Управление состоянием
• GetIt + Injectable - Dependency Injection

🚦 Навигация и UI

• Auto Route - Декларативная маршрутизация
• Material 3 - Современный дизайн
• Device Preview - Эмуляция устройств

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

• Widgetbook - Каталог UI компонентов
• Freezed - Immutable классы
• Build Runner - Генерация кода

🌐 Сеть и данные

• Dio - HTTP клиент
• Shared Preferences - Локальное хранение
• JSON Serialization - Сериализация данных

📖 Как добавить новую фичу

1. Создание Domain слоя

// lib/features/domain/entities/my_entity.dart
@freezed
class MyEntity with _$MyEntity {
  const factory MyEntity({
    required String id,
    required String name,
  }) = _MyEntity;
}

// lib/features/domain/repositories/my_repository.dart
abstract class MyRepository {
  Future<List<MyEntity>> getItems();
}

// lib/features/domain/usecases/get_items_usecase.dart
@injectable
class GetItemsUseCase implements UseCase<List<MyEntity>, NoParams> {
  final MyRepository _repository;
  GetItemsUseCase(this._repository);

  @override
  Future<List<MyEntity>> call(NoParams params) async {
    return await _repository.getItems();
  }
}

2. Создание Data слоя

// lib/features/data/models/my_model.dart
@freezed
class MyModel with _$MyModel {
  const factory MyModel({
    required String id,
    required String name,
  }) = _MyModel;

  factory MyModel.fromJson(Map<String, dynamic> json) =>
      _$MyModelFromJson(json);
}

// Добавьте extension методы для конвертации между Entity и Model

3. Создание Presentation слоя

// lib/features/presentation/cubit/my_cubit.dart
@injectable
class MyCubit extends Cubit<MyState> {
  final GetItemsUseCase _getItemsUseCase;
  
  MyCubit(this._getItemsUseCase) : super(const MyState.initial());

  Future<void> loadItems() async {
    emit(const MyState.loading());
    try {
      final items = await _getItemsUseCase(NoParams());
      emit(MyState.loaded(items));
    } catch (e) {
      emit(MyState.error(e.toString()));
    }
  }
}

// lib/features/presentation/screens/my_screen.dart
@RoutePage()
class MyScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return BlocProvider(
      create: (context) => getIt<MyCubit>()..loadItems(),
      child: Scaffold(
        appBar: AppBar(title: const Text('My Screen')),
        body: BlocBuilder<MyCubit, MyState>(
          builder: (context, state) {
            return state.when(
              initial: () => const SizedBox(),
              loading: () => const CircularProgressIndicator(),
              loaded: (items) => ListView.builder(
                itemCount: items.length,
                itemBuilder: (context, index) {
                  return ListTile(title: Text(items[index].name));
                },
              ),
              error: (message) => Text('Error: $message'),
            );
          },
        ),
      ),
    );
  }
}

4. Добавление в навигацию

// lib/core/router/app_router.dart
@AutoRouterConfig(replaceInRouteName: 'Screen,Route')
class AppRouter extends _$AppRouter {
  @override
  List<AutoRoute> get routes => [
    // ... существующие маршруты
    AutoRoute(
      page: MyRoute.page,
      path: '/my-screen',
    ),
  ];
}

5. Генерация кода

dart run build_runner build --delete-conflicting-outputs

🧪 Добавление в Widgetbook

// widgetbook/main.dart
WidgetbookComponent(
  name: 'MyScreen',
  useCases: [
    WidgetbookUseCase(
      name: 'Default',
      builder: (context) => const MyScreen(),
    ),
    WidgetbookUseCase(
      name: 'Loading State',
      builder: (context) => const MyScreenLoading(),
    ),
  ],
),

🔄 Команды разработки

Генерация кода

# Одноразовая генерация
dart run build_runner build --delete-conflicting-outputs

# Отслеживание изменений
dart run build_runner watch --delete-conflicting-outputs

Тестирование

# Все тесты
flutter test

# Тесты с покрытием
flutter test --coverage

# Специфический тест
flutter test test/widget_test.dart

Анализ кода

# Анализ кода
flutter analyze

# Форматирование
dart format lib/ test/ widgetbook/

🎨 Кастомизация темы

Темы настраиваются в lib/main.dart:

theme: ThemeData(
  useMaterial3: true,
  colorScheme: ColorScheme.fromSeed(
    seedColor: Colors.blue, // Измените основной цвет
  ),
),

Переключение темы доступно в настройках приложения.

📚 Полезные ресурсы

• Clean Architecture
• BLoC Documentation
• Auto Route Guide
• Widgetbook Documentation
• Device Preview

🤝 Вклад в проект

1. Форкните репозиторий
2. Создайте feature branch (git checkout -b feature/amazing-feature)
3. Зафиксируйте изменения (git commit -m 'Add amazing feature')
4. Отправьте в branch (git push origin feature/amazing-feature)
5. Откройте Pull Request

📄 Лицензия

Этот проект распространяется под лицензией MIT. См. файл LICENSE для подробностей.

---

Готов к использованию! 🚀 Этот каркас предоставляет все необходимое для быстрого старта разработки Flutter приложений с современной архитектурой и инструментами.