Бюджет — Android-приложение (Kotlin, MVP)

Нативное Android-приложение личного бюджета по логике Google-таблицы. Минимальный рабочий скоуп, без эмодзи, тёмная тема Material 3.

Первая сборка на новой машине

1. Проект использует Gradle Wrapper (8.9) — файлы gradlew, gradlew.bat, gradle/wrapper/* обязательны, версия закреплена и совместима с AGP 8.5.2 (системный Gradle 9.x НЕ подходит).
2. local.properties в git/архив не входит (машино-зависимый): Android Studio создаёт его сам при первом открытии/синхронизации проекта. Вручную: sdk.dir=C\:\\Users\\<имя>\\AppData\\Local\\Android\\Sdk (двойные бэкслеши), либо переменная окружения ANDROID_HOME.
3. Сборка из терминала: gradlew.bat assembleDebug (Windows) / ./gradlew assembleDebug (Linux/macOS).

Скоуп MVP

• Экран «Сегодня»: дельта (свободные деньги накопительно), конверты месяца (доступно / потрачено / перенос далее), бюджет на день, последние операции.
• Экран «Бюджет»: конвертный бюджет по категориям (план-факт), тап по категории — изменение плана месяца.
• Добавление операции (кнопка «+»): сумма → тип (расход/доход) → категория → дата → заметка. Тап по операции в списке — редактирование/удаление.
• Навигация по месяцам со стрелок у заголовка.
• Экспорт в Excel: кнопка со стрелкой вниз в шапке — все операции выгружаются в .xlsx в папку «Загрузки» (Дата / Тип / Категория / Сумма / Заметка). Без Apache POI — собственный минимальный OOXML-генератор export/XlsxWriter.kt (перенесён из TheSleepTracker). На Android 10+ запись через MediaStore без разрешений.
• Самообновление через GitHub: при запуске и по кнопке в шапке приложение проверяет version.json в репозитории, скачивает APK системным DownloadManager и открывает установщик (с обработкой разрешения «неизвестные источники» на Android 8+). Механизм перенесён из TheSleepTracker (модули update/UpdateChecker.kt, update/ApkDownloader.kt).

Ключевая логика (конверты с переносом)

available(m) = plan(m) + carryIn(m)      // доступно = план + перенос с прошлого месяца
left(m)      = available(m) − spent(m)   // остаток; уходит в следующий месяц (со знаком)
carryIn(m)   = left(m−1)                 // перерасход уменьшает следующий месяц
delta(m)     = income(m) − expense(m)    // накопительно за год с переносом

Планы по умолчанию (аренда 4000, продукты 10000, кофе 1000 и т.д.) засеиваются при первом запуске на месяцы с текущего до конца года.

Требования

• Android Studio Koala (2024.1.1) или новее
• JDK 17 (входит в поставку Android Studio)
• minSdk 26 (Android 8.0), target/compile SDK 34

Сборка

1. Открыть папку BudgetApp в Android Studio: File → Open.
2. Дождаться Gradle Sync (Gradle 8.9 скачается сам по gradle-wrapper.properties; если Studio спросит про недостающий wrapper — согласиться на исправление, либо выполнить в терминале gradle wrapper --gradle-version 8.9).
3. Run ▶ на эмуляторе или устройстве.

CLI: ./gradlew assembleDebug → app/build/outputs/apk/debug/app-debug.apk.

Стек

Слой	Решение
UI	Jetpack Compose + Material 3 (тёмная тема, dynamic color не используется)
Архитектура	MVVM: AppViewModel + StateFlow<AppState>
БД	Room (таблицы transactions, plans), KSP
Расчёты	BudgetEngine — чистый Kotlin без Android-зависимостей (тестируется юнит-тестами)
Экспорт	XlsxWriter — .xlsx без внешних зависимостей; запись в Downloads через MediaStore
Обновления	version.json в репозитории + DownloadManager + FileProvider

Как выпустить обновление (чек-лист)

Приложение обновляет само себя с GitHub. Ссылки заданы в app/build.gradle.kts (VERSION_URL, APK_URL) — сейчас указывают на maks-march/BudgetApp, поправьте под свой репозиторий.

1. Поднять versionCode (на 1) и versionName в app/build.gradle.kts.
2. Собрать: ./gradlew assembleRelease → app/build/outputs/apk/release/app-release.apk.
3. Положить APK в репозиторий как apk/Budget.apk (заменить файл).
4. Обновить version.json в корне репозитория: { "versionCode": <тот же, что в gradle>, "versionName": "...", "notes": "что нового" }.
5. Закоммитить и запушить — у всех установленных приложений при следующем запуске появится диалог «Доступна версия …».

Почему это работает (уроки TheSleepTracker из ОБНОВЛЕНИЕ.md):

• подпись: debug и release подписаны одним постоянным ключом keystore/budget.jks (пароль по умолчанию budgetapp, выносится в keystore.properties) — иначе обновление не встанет поверх (INSTALL_FAILED_UPDATE_INCOMPATIBLE);
• versionCode в version.json должен быть строго больше установленного, сравнение 4 > 4 = «обновлений нет»;
• на Android 8+ один раз нужно разрешить «Установка неизвестных приложений» — приложение само открывает нужный экран настроек.

Структура

app/src/main/java/ru/budget/app/
├── MainActivity.kt            — точка входа
├── data/
│   ├── Model.kt               — категории (справочник) и группы потоков
│   └── Db.kt                  — Room: сущности, DAO, база
├── domain/
│   └── BudgetEngine.kt        — конверты, переносы, дельта, итоги месяца
├── export/
│   ├── XlsxWriter.kt          — минимальный генератор .xlsx без зависимостей
│   └── BudgetExporter.kt      — выгрузка операций в «Загрузки» (MediaStore)
├── update/
│   ├── UpdateChecker.kt       — проверка version.json в репозитории
│   └── ApkDownloader.kt       — DownloadManager + установщик + разрешения
└── ui/
    ├── Theme.kt               — цвета и тема
    ├── Common.kt              — формат денег, даты, GroupDot
    ├── AppViewModel.kt        — состояние + действия (+ экспорт)
    ├── AppRoot.kt             — scaffold, шапка (экспорт/обновления), диалоги
    ├── TodayScreen.kt         — дашборд
    ├── BudgetScreen.kt        — план-факт + диалог плана
    └── AddSheet.kt            — шторка добавления/редактирования

Дорожная карта (не вошло в MVP)

1. Накопления: счета, переносы «в накопления», цели 10/20% от дохода.
2. Калькулятор распределения дохода (50/30/20 и свои проценты).
3. Кастомные категории (сейчас — фиксированный справочник).
4. Копирование плана месяца на весь год.
5. Второй лист в экспорте: сводка конвертов по месяцам (как лист 1 таблицы).
6. Импорт из CSV/JSON, синхронизация с Google Sheets.
7. Юнит-тесты BudgetEngine (формулы переносов — ключевой сценарий).