FinApp

Кроссплатформенное приложение контроля и планирования личных финансов на Kotlin Multiplatform + Compose Multiplatform. Одна кодовая база, платформы — Windows, macOS, Linux, Android, iOS.

Импорт банковских выписок (Ozon-PDF, XLSX, OFD-чеки), дедупликация и схлопывание переводов между своими счетами, автокатегоризация по MCC/правилам/справочнику контрагентов, бюджеты с прогнозом конца месяца, аналитика с drill-down до товаров. Деньги хранятся в копейках (Long), единственный источник правды — локальная SQLite-БД.

Документы: архитектура · спецификация реализации · версионирование архитектуры.

Статус

Базовый объём v1.0.0 (майлстоуны M0–M9) реализован и заморожен (FROZEN); дальнейшая эволюция идёт инкрементами по SemVer, каждый с ADR, дельтой схемы/контрактов и критериями приёмки (см. architecture-versioning.md). Текущая версия — v1.8.0, схема БД — v5, сборка и тесты приёмки зелёные.

Базовый объём (v1.0.0, M0–M9)

• M0 — Фундамент: каркас на Windows, схема БД v1 + миграции, базовые типы, упаковка.
• M1 — Ledger + ручной ввод: счета (bank/cash/virtual), ручные операции, список с группировкой по дням, фильтры/поиск, карточка операции, быстрый ввод, ручной перевод.
• M2 — Импорт: идемпотентный импорт Ozon-PDF и XLSX-выписок, дедупликация (externalId + fingerprint), transfer-matching, refund-linker, мастер импорта с undo.
• M3 — Категории и правила: иерархия + пресет, MCC-словарь, rules-engine (≥90% автокатегоризации), инбокс «Без категории», реконсиляция с ручными.
• M4 — Splits, чеки, товары, наличные, ЖКХ: split-редактор, OFD-PDF чек → позиции, BarcodeIndex, кошелёк наличных, показания ЖКХ.
• M5 — Аналитика: donut/bar/line, drill-down до операций и товаров, экспорт CSV/XLSX.
• M6 — Бюджет и прогноз: план/факт, recurring-движок, прогноз конца месяца со светофором.
• M7 — Надёжность данных: ротация бэкапов, integrity-check, полный экспорт/импорт ZIP.
• M8 — iOS / macOS: общий KMP-парсер XLSX, Native SQLDelight-драйвер, PDFKit, FileKit, камера, адаптивный layout.
• M9 — Полировка: хоткеи desktop, onboarding, постраничный список операций, задел локализации (ru/en).

Инкременты поверх базы

Версия	Тип	Кратко	Схема
v1.0.1	UI (PATCH)	Редактор правил, форма ручного перевода, объединение двух операций в перевод постфактум	v1
v1.0.2	PATCH	Исправления парсеров XLSX/PDF, нормализации, дедупликации и категоризации по реальным данным	v1
v1.1.0	MINOR	Справочник контрагентов→категория (гибрид с правилами), выборочный экспорт/импорт справочника и правил	v1→v2
v1.1.1	PATCH	Контент-пак РФ: дерево категорий, фабричные правила и записи справочника	v2
v1.2.0	MINOR	Наличные как расход по умолчанию, СБП-телефон для авто-переводов, системная категория «Перевод между своими счетами»	v2→v3
v1.3.0	MINOR	Аналитика: фильтр по счетам, drill-down с правкой, группировка по продавцу, дашборд «частые траты»	v3
v1.4.0–v1.4.3	MINOR/PATCH	Система тем; QoL-пакеты: нормализатор контрагента, MerchantBranding (понятные имена+иконки), менеджер категорий, пользовательские бренды	v3→v4
v1.5.0	MINOR	Платформа Android (Material Design 3)	v4
v1.5.1	PATCH	Упаковка desktop для Linux: .deb, .rpm, .tar.gz, .AppImage	v4
v1.5.2	PATCH	Багфикс старта на Android (result-возвращающие PRAGMA через executeQuery)	v4
v1.6.0	MINOR	Визуальный ре-дизайн: тема «Aurora» (по умолчанию), расширенные токены, адаптивная навигация	v4→v5
v1.7.0–v1.7.3	MINOR/PATCH	UX/UI редизайн «Ledger» (макет, плотность, CategoryGlyph, герой-дашборд); палитры Aurora / Material Darker	v5
v1.8.0	MINOR	Мультифильтр операций (телефон+десктоп), поиск по имени бренда и заметкам, кликабельные «частые траты», CRUD товаров	v5

Каждый инкремент берётся в работу только после того, как предыдущий по очереди реализован и его критерии приёмки зелёные.

Модули

core/model          доменные типы: Money, YearMonth, enums, сущности
core/common         AppResult/AppError, MoneyParser, repository-интерфейсы, DI, логирование
core/database       SQLDelight: схема (v5), индексы, драйверы (JVM/Android/Native), миграции
feature/import      пайплайн импорта: парсеры (Ozon-PDF, XLSX, OFD-чек), дедуп, transfer/refund-matcher
feature/ledger      операции, splits, счета, реконсиляция, фильтры/поиск
feature/categories  категории, rules-engine, справочник контрагентов, MerchantBranding
feature/products    справочник товаров, barcode lookup, CRUD
feature/budget      бюджеты, recurring-движок, прогноз
feature/analytics   агрегаты, drill-down, дашборд «частые траты»
feature/backup      снапшоты, целостность, экспорт/импорт
ui/design-system    темы, i18n, MoneyText, TransactionRow, CategoryGlyph, charts, токены
ui/app              навигация (Decompose): корневой компонент + разделы, адаптивный layout
app/desktop         Compose for Desktop (Windows/macOS/Linux), упаковка (jpackage), хоткеи
app/android         Android-таргет (Material Design 3)
app/ios             iOS-таргет: ComposeUIViewController-хост, Native-драйвер

Таргеты: jvm (desktop — Windows/macOS/Linux), android, iosX64/iosArm64/iosSimulatorArm64. Apple-таргеты собираются на macOS; на других ОС их задачи пропускаются (общий код компилируется).

Требования

• JDK 21
• Desktop: Windows + WiX для .msi; Linux для .deb/.rpm/.AppImage (нужен imagemagick для иконки AppImage)
• Android: Android SDK (см. local.properties → sdk.dir)
• Apple: macOS + Xcode для сборки iOS/macOS-таргетов

Сборка и запуск

gradlew build                              # компиляция + все тесты
gradlew :app:desktop:run                   # запуск desktop-приложения
gradlew :app:desktop:createDistributable   # портативный образ приложения
gradlew :app:desktop:packageMsi            # установщик .msi (Windows + WiX)
gradlew :app:android:assembleDebug         # APK для Android

Передать версию пакета: -Pfinapp.version=1.8.0.

Каталог данных: %APPDATA%/FinApp (Windows), ~/Library/Application Support/FinApp (macOS), ~/.local/share/FinApp (Linux), app-каталог (Android/iOS). Файл БД: finapp.db; вложения и бэкапы — в подкаталогах attachments/, backups/.

Тесты приёмки

Каждый майлстоун и инкремент покрыт автотестами jvmTest соответствующих модулей; gradlew build гоняет их все. Примеры:

• M0–M1: MoneyTest/MoneyParserTest (Money(150099).format("RUB") == "1 500,99 ₽"), SchemaCreationTest (PRAGMA integrity_check = ok), MigrationTest, ManualTxnTest, BudgetPeriodOverrideTest, FilterSearchTest.
• M2: OzonParseTest, XlsxParseTest, IdempotentImportTest, TransferMatchTest, CashWithdrawalTest, UndoTest.
• M3–M4: AutoCategorizeCoverageTest (≥90%), RuleOrderTest, ReconcileTest, OfdPdfParseTest, SplitInvariantTest, BarcodeResolveTest.
• M5–M7: AnalyticsConsistencyTest, RefundInAnalyticsTest, ForecastTest, RolloverTest, BackupRotationTest, RestoreTest, RoundTripExportTest.
• M8–M9: KmpXlsxParserTest (общий парсер == POI), LargeDatasetPerfTest (10k операций: первая страница observe < 50 мс, donut < 100 мс).
• v1.8.0: AmountFilterTest, BrandSearchTest, pagedFilterMatchesInMemory/pagedQueryFirstPageIsFast (регресс пагинации), ProductCrudTest.

Миграции БД

Текущая версия схемы — v5 (FinAppDatabase.Schema.version); в БД дублируется в таблице schema_meta (для манифеста бэкапа). Миграции лежат в core/database/src/commonMain/sqldelight/com/finapp/core/database/migrations/<N>.sqm, где <N> — версия, из которой выполняется переход (1.sqm…4.sqm). Новые аддитивные миграции добавляются по тому же принципу.