traccar-client-android/README.md

# traccar-client-android (форк)

Android-приложение Traccar Client — GPS-трекер, который снимает координаты устройства и отправляет их на сервер Traccar по протоколу OsmAnd (HTTP GET с параметрами). Работает фоновой службой, накапливает точки в локальной SQLite-очереди и досылает их при появлении сети.

Форк сделан как резервная копия официального репозитория [traccar/traccar-client-android](https://github.com/traccar/traccar-client-android) (автор — Anton Tananaev) в самохостовом Gitea: приложение используется вместе со своим сервером Traccar, и наличие независимой копии исходников гарантирует возможность пересобрать APK даже без доступа к GitHub.

Документация оригинала (ссылки на Google Play/F-Droid, команда, лицензия Apache 2.0) сохранена в [README.upstream.md](README.upstream.md).

## Отличия от оригинала

Изменений нет. Все 438 коммитов принадлежат авторам оригинала (386 + 19 — Anton Tananaev, остальные — внешние контрибьюторы через pull request'ы). Собственных правок владельца форка в истории нет. Форк взят как резервная копия.

## Стек

- Kotlin 1.8.0, Android SDK (compileSdk/targetSdk 33, minSdk 16)
- Gradle 7.5.1 + Android Gradle Plugin 7.4.1
- AndroidX: `core-ktx` 1.9.0, `preference-ktx` 1.2.0, `multidex` 2.0.1, Material Components 1.6.1
- `com.github.judemanutd:autostarter` 1.1.0 и `dev.doubledot.doki` — обход агрессивного энергосбережения вендоров (DKMA)
- Flavor `google`: Firebase BOM 28.2.1 (Analytics, Crashlytics), Play Services Location 21.0.1, Play Core
- SQLite (`SQLiteOpenHelper`) — буфер непереданных позиций
- Тесты: JUnit 4.13.2, Robolectric 4.7.3
- Локализация: Transifex (48 каталогов `values-*`)

## Структура

| Путь | Назначение |
|---|---|
| `app/src/main/java/org/traccar/client/MainActivity.kt`, `MainFragment.kt` | Экран настроек (PreferenceFragment), запуск/остановка трекинга, запрос разрешений на геолокацию и отключение энергосбережения |
| `app/src/main/java/org/traccar/client/TrackingService.kt`, `TrackingController.kt` | Foreground-служба и логика цикла: получить позицию → записать в БД → отправить → удалить |
| `app/src/main/java/org/traccar/client/PositionProvider.kt`, `AndroidPositionProvider.kt` | Источник координат на системном `LocationManager` |
| `app/src/{regular,google,hidden}/java/.../PositionProviderFactory.kt` | Выбор источника позиций по flavor: системный или Google Fused Location |
| `app/src/main/java/org/traccar/client/ProtocolFormatter.kt` | Формирование URL запроса к серверу (протокол OsmAnd) |
| `app/src/main/java/org/traccar/client/RequestManager.kt`, `NetworkManager.kt` | HTTP-отправка и отслеживание состояния сети |
| `app/src/main/java/org/traccar/client/DatabaseHelper.kt` | SQLite-очередь позиций |
| `app/src/main/java/org/traccar/client/AutostartReceiver.kt`, `BatteryOptimizationHelper.kt`, `WakefulBroadcastReceiver.kt` | Автозапуск после перезагрузки, wake lock, борьба с убийством процесса |
| `app/src/main/java/org/traccar/client/ShortcutActivity.kt`, `DialLaunchReceiver.kt` | Ярлыки старт/стоп и запуск по набору кода в звонилке |
| `app/src/main/java/org/traccar/client/StatusActivity.kt` | Журнал событий приложения |
| `app/src/main/res/xml/preferences.xml` | Описание всех пользовательских настроек |
| `app/src/main/res/xml/network_security_config.xml` | Разрешён HTTP-трафик, доверие пользовательским CA (для HTTPS-прокси) |
| `app/src/test/java/...` | Unit-тесты форматтера URL, БД и отправки запросов |
| `translate.py` | Выгрузка переводов из Transifex (проект `traccar`, ресурс `client`) в `res/values-*` |
| `.github/` | Только CONTRIBUTING, FUNDING и шаблоны issue. CI-workflow в репозитории нет |

## Как собрать/запустить

```bash
./gradlew assembleRegularDebug      # сборка без сервисов Google
./gradlew assembleRegularRelease
./gradlew assembleGoogleRelease     # вариант с Firebase и Fused Location
./gradlew assembleHiddenRelease     # скрытый вариант (applicationId org.traccar.client.hidden)
./gradlew test                      # unit-тесты (JUnit + Robolectric)
```

Три product flavor'а: `regular` (по умолчанию), `google`, `hidden`. Для сборки `google`-варианта задача `copyJson` копирует `google-services.json` из внешнего каталога `../../environment/google-services/traccar-client-android.json` — этого каталога в репозитории нет, для своей сборки нужен собственный файл Firebase либо использование flavor `regular`.

Обновление переводов: `./translate.py -t <transifex_token>` (требуется пакет `transifex-python`).

## Конфигурация

Настройки задаются в самом приложении и хранятся в SharedPreferences (`app/src/main/res/xml/preferences.xml`):

| Ключ | Назначение |
|---|---|
| `status` | Переключатель «служба запущена» |
| `id` | Идентификатор устройства; генерируется автоматически при первом запуске, должен совпадать с идентификатором в Traccar |
| `url` | Адрес сервера, куда шлются позиции (http:// или https://) |
| `accuracy` | Точность: high / medium / low |
| `interval` | Период опроса, секунды (по умолчанию 300) |
| `distance` | Минимальное смещение для отправки, метры (0 — выключено) |
| `angle` | Минимальное изменение курса, градусы (0 — выключено) |
| `buffer` | Буферизация точек при отсутствии сети |
| `wakelock` | Удержание процессора |

Сборочные параметры: `applicationId org.traccar.client` (у flavor `hidden` — `org.traccar.client.hidden`), `versionCode 81`, `versionName 7.0`, `gradle.properties` содержит только `android.useAndroidX=true`.

Секретов в репозитории нет: ключи Firebase и токен Transifex в коде отсутствуют и подставляются извне.

## Состояние

Рабочий, но копия устаревшая: 438 коммитов, последний — 05.04.2023 (Anton Tananaev, «Non nullable fields»), версия приложения 7.0 (versionCode 81). Оригинальный проект с тех пор развивается дальше, форк с ним не синхронизировали. Собственных коммитов владельца форка нет, поэтому дата последней своей правки отсутствует.

## Что не доделано

Меток TODO/FIXME и заглушек в коде нет — это релизная версия официального приложения. Применительно к самому форку не хватает только синхронизации с upstream: копия отстаёт от оригинала более чем на три года.