Balance/docs/DEVELOPMENT.md

Разработка (все платформы)

Сводная шпаргалка по сборке, запуску и проверке всех трёх подпроектов. Подробности — в docs/DEVELOPMENT.md каждого подпроекта.

Требования по платформам

Подпроект	Инструменты	Минимальные версии
Balance/	Xcode, Swift	Xcode 16+, iOS 17+, macOS 14+, watchOS 10+
BalanceAndroid/	Android Studio / Gradle	AGP 8.13, Kotlin 2.3.21, compileSdk 36, minSdk 26, Java 17
BalanceServer/	Go	Go 1.25.0+

Локальный запуск всей системы

Порядок, удобный для end-to-end проверки sync между платформами:

# 1. Поднять сервер
cd BalanceServer
cp .env.example .env
# задать BALANCE_JWT_SECRET (см. README.md)
go mod tidy
go run ./cmd/balance-server
# сервер слушает http://localhost:8080

# 2. Открыть Apple-проект и указать http://localhost:8080 в Settings → Server account
cd ../Balance
open Balance.xcodeproj

# 3. Собрать и запустить Android-приложение
cd ../BalanceAndroid
./gradlew assembleDebug
# на эмуляторе сервер локального хоста доступен как http://10.0.2.2:8080

Для физического iPhone/Android-устройства localhost указывает на само устройство, а не на машину разработчика — используйте сетевой адрес или HTTPS reverse proxy (см. docs/SECURITY.md).

Сборка и тесты по отдельности

Apple (Balance/)

xcodebuild -project Balance.xcodeproj -list

xcodebuild -project Balance.xcodeproj -scheme Balance \
  -destination 'generic/platform=iOS' build

xcodebuild -project Balance.xcodeproj -scheme Balance \
  -destination 'platform=iOS Simulator,name=<available iPhone>' test

Схемы: Balance (iOS), BalanceMac, BalanceWatch. Без BalanceCloudKitEnabled=YES приложение работает в local-mode (SwiftData без CloudKit) — рекомендуемый режим для разработки.

Android (BalanceAndroid/)

./gradlew clean test assembleDebug

Тесты — app/src/test/FinanceMathTest. local.properties с sdk.dir не должен попадать в Git.

Server (BalanceServer/)

go mod download
go test ./...
go test -race ./...
go vet ./...
go build ./...

Docker-путь — docker compose up -d --build (см. BalanceServer/README.md).

Что проверять при изменении общего контракта

Если PR меняет sync API, модель данных или финансовые расчёты — прогони проверки во всех трёх подпроектах, а не только в изменённом:

old iOS client   + new server
new iOS client   + server
Android client   + server
concurrent sync с двух устройств одного аккаунта
login/refresh после истечения access token
delete → pull на другом устройстве

Типовые проблемы синхронизации (одинаковый чек-лист для обеих платформ)

1. Проверь server URL в настройках клиента.
2. Проверь правило HTTPS/localhost (см. docs/SECURITY.md).
3. Проверь авторизацию/сессию (login, не истёк ли refresh).
4. Проверь дату последней синхронизации и сохранённый cursor.
5. Проверь совместимость версии клиента и BalanceServer.
6. Если данные не удаляются на другом устройстве — убедись, что удаление прошло через tombstone-путь (modelContext.deleteForSync на Apple, FinanceDao.deleteTransaction/deleteCategory/deleteBudget на Android), а не через прямой delete().