HabitTracker — социальный трекер привычек

Отмечай привычки в одиночку или с друзьями, создавай групповые привычки и устраивай челленджи. Напоминания, офлайн-поддержка, синхронизация через Firestore и удобный современный UI на Jetpack Compose.

---

Содержание

• О проекте
• Основные возможности
• Скриншоты
• Стек технологий
• Архитектура и структура
• Документация в репозитории
• Быстрый старт
• Тестирование
• Безопасность и приватность
• Производительность
• Как контрибьютить
• Лицензия
• Благодарности

О проекте

HabitTracker — мобильное приложение для Android, которое помогает формировать и отслеживать привычки как индивидуально, так и в группах с друзьями. Делайте прогресс вместе: приглашайте друзей, получайте напоминания, отмечайте выполнение и смотрите общую статистику.

Проект построен с упором на:

• современный UI/UX (Jetpack Compose, Material 3, анимации);
• надежную офлайн-поддержку (Room) и синхронизацию (Outbox → Firestore);
• социальные функции (друзья, приглашения, групповые привычки);
• уведомления (локальные напоминания и push через FCM).

Основные возможности

• Личные и групповые привычки (поддержка участников, лимитов, invite-code, публичные/приватные группы).
• Приглашения в привычки: отправка, принятие/отклонение, присоединение по коду.
• Напоминания о привычках: WorkManager + корректная работа с разрешением уведомлений (Android 13+).
• Система друзей: поиск, заявки, принятие/отклонение, список друзей.
• Push-уведомления (FCM): приглашения, события групповых привычек, активности друзей.
• Челленджи между друзьями:
  • создание на основе привычки (в т.ч. групповой);
  • инвайты участникам и принятие/отклонение;
  • авто-вступление в групповую привычку при принятии инвайта (если пользователь еще не участник);
  • защита от переполнения группы: если групповая привычка заполнена, новые внешние участники не добавляются в челлендж, а создатель получает понятное предупреждение;
  • автоматическое завершение по дате и определение победителя + уведомления участникам.
• Офлайн-режим: Room-кэш, оптимистичные апдейты, Outbox-синхронизация с Firestore.
• Аналитика и мониторинг: Firebase Analytics, Crashlytics и Performance Monitoring.
• Аутентификация Google (Credential Manager API).
• Улучшенный UX: валидация формы в реальном времени, Snackbar, UNDO после удаления, плавные анимации.

Статус модулей:

• Челленджи: реализовано (core-функциональность + уведомления).
• Геймификация (очки, уровни, достижения): реализованы базовые достижения (UserAchievements) with synchronization.

Скриншоты

Файлы лежат в art/screenshots/.

Splash

Основные экраны

Экран	Светлая тема	Тёмная тема
Мои привычки
Детали групповой привычки
Создание/редактирование
Друзья
Статистика
Достижения
Публичные привычки

Стек технологий

• Язык: Kotlin, Coroutines + Flow
• UI: Jetpack Compose (Material 3), Navigation Compose
• DI: Hilt
• Данные: Room (локально), Firebase Firestore (облако)
• Синхронизация: Outbox-паттерн + WorkManager (экспедированная OneTimeWork)
• Уведомления: WorkManager (локальные), Firebase Cloud Messaging (push)
• Аналитика: Firebase Analytics, Crashlytics, Performance Monitoring
• Логирование: Timber
• Аутентификация: Firebase Auth + Google Sign-In (Credential Manager)
• Изображения: Coil (аватарки и кэширование)

Архитектура и структура

Следуем Clean Architecture и MVVM.

Слои:

• Presentation — экраны Compose, ViewModel, навигация
• Domain — use cases, модели, интерфейсы репозиториев
• Data — реализации репозиториев, источники данных (Room/Firestore)

Пакеты (сокращенно):

com.habittracker/
├── presentation/
│   ├── ui/
│   │   ├── habits/
│   │   ├── social/
│   │   ├── challenges/
│   │   ├── profile/
│   │   └── auth/
│   ├── viewmodel/
│   └── navigation/
├── domain/
│   ├── model/
│   ├── repository/
│   └── usecase/
├── data/
│   ├── local/ (Room)
│   ├── remote/ (API/Firestore/FCM)
│   └── repository/
└── di/

Ключевые решения:

• Room-first + Outbox: все операции сначала в локальную БД, затем — фоновая синхронизация с Firestore.
• Оптимистичные апдейты в UI, last-write-wins стратегия конфликтов по updatedAtMillis.
• Soft-delete для habit/challenge: удаление доставляется через tombstones (deletedAtMillis), а не hard delete.
• Multi-device FCM: users.fcmTokens[] обновляется атомарно через outbox ARRAY_UNION/ARRAY_REMOVE.
• Разрешения на уведомления (Android 13+) запрашиваются корректно и контекстно.

Документация в репозитории

• sync_architecture.md — актуальный принцип синхронизации Room ↔ Firestore (Outbox, pending-guards, merge/LWW ограничения)
• sync_gaps.md — текущие риски/гепы синхронизации и план закрытия
• ANALYTICS_GUIDE.md — руководство по использованию аналитики, мониторингу ошибок и работе с Firebase Console
• FCM_SETUP_INSTRUCTIONS.md — инструкция по настройке Cloud Messaging

Синхронизация (коротко)

• Запись (Room-first): UI всегда читает из Room. При create/update/delete репозиторий обновляет Room и кладёт операцию в outbox.
• Доставка в Firestore: SyncWorker вызывает SyncManager.drainPending(). Для пользовательских действий дополнительно делается экспедит: scheduleOneTimeSync() + неблокирующий drainPending().
• Realtime (Firestore → Room): слушатели по ключевым коллекциям мержат данные в Room с pending-guard и LWW по updatedAtMillis.

Где смотреть логи:

• SyncWorker: старт/завершение дренажа.
• SyncManager: enqueue / pushUpsert / pushDelete / retry.

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

Требования:

• Android Studio Koala или новее
• JDK 17
• Android SDK 26+

Шаги:

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

   git clone https://github.com/Cha1000000/HabitTracker.git
   cd HabitTracker

2. Firebase:

   • Создайте проект Firebase и добавьте Android-приложение (используйте applicationId из HabitTracker/build.gradle.kts).
   • Скачайте google-services.json и поместите в HabitTracker/.
   • Включите Authentication (Google), Firestore и Cloud Messaging.
   • Добавьте SHA-1/SH A-256 отпечатки для корректного Google Sign-In.

3. FCM Server Key:

   • Не храните ключ в репозитории. Следуйте FCM_SETUP_INSTRUCTIONS.md для безопасной настройки (через local.properties/переменные окружения и BuildConfig).

4. Сборка и запуск:

   • Откройте проект в Android Studio и запустите на устройстве/эмуляторе;
   • либо используйте Gradle:

   Сборка:

   ./gradlew installDebug

Очистка и сборка:

./gradlew clean build --info

Сборка с глубоким тестированием:

./gradlew lint test

Проверка работоспособности приложения:

./gradlew assembleDebug

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

./gradlew installDebug && adb shell am start -n com.habittracker/.MainActivity

Sync

./gradlew --refresh-dependencies

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

• Unit-тесты:

  ./gradlew test

• Быстрый запуск unit-тестов только модуля приложения:

  ./gradlew :HabitTracker:testDebugUnitTest

• UI-тесты (на подключенном устройстве/эмуляторе):

  ./gradlew connectedDebugAndroidTest

Примечание: в HabitTracker/build.gradle.kts настроены packagingOptions для исключения дубликатов META-INF. Часть UI-тестов стабилизирована с помощью MockK.

Безопасность и приватность

• Не коммитьте секреты (FCM Server Key, приватные ключи, реальные google-services.json).
• Валидируйте входные данные, не логируйте чувствительное.
• Для локального хранения чувствительных данных используйте безопасные решения (шифрование/EncryptedSharedPreferences/Room с шифрованием по необходимости).

Производительность

• Используются LazyColumn/LazyVerticalGrid для списков.
• Coil с кэшированием изображений.
• Минимизация recomposition в Compose.
• Пагинация для истории выполнений (по мере необходимости).

Как контрибьютить

1. Форкните репозиторий и создайте ветку из main.
2. Следуйте принятым стилям (Kotlin style, Compose best practices, SOLID/DRY).
3. Пишите чистые коммиты и описательные PR (что сделано, почему, скриншоты/видео при UI-изменениях).
4. Покрывайте критические изменения тестами.

Лицензия

Проект распространяется под лицензией Apache License 2.0.

Благодарности

• Jetpack Compose и AndroidX команда
• Firebase (Auth, Firestore, FCM)
• Сообщество Kotlin/Android за примеры и лучшие практики

---

Если у вас есть идеи или вы нашли проблему — создайте Issue или отправьте PR. Приятного использования HabitTracker!