trainings-sync: жаттығулар мен денсаулық деректерін Garmin, Strava және жергілікті мұрағат арасында синхрондау

trainings-sync — бұл жаттығулар мен денсаулық деректерін Garmin Connect, Strava және компьютердегі жергілікті қалта арасында синхрондайтын команда жолы құралы (FIT/GPX/TCX форматтары). Бір командамен барлық деректеріңіздің толық жеке мұрағатын дискіңізде аласыз — әрі бір платформаға тәуелді болмайсыз.

Не үшін қажет

• Өз дерек мұрағатыңыз. Барлық жаттығулар мен денсаулық көрсеткіштері жергілікті, ашық форматтарда сақталады — оларды ешкім алып қоймайды.
• Сервистер арасындағы еркіндік. Активтерді Garmin мен Strava арасында тасымалдаңыз, екеуінде де әрі дискіде сақтаңыз.
• AI-жаттықтырушыға отын. Жергілікті жаттығу және денсаулық файлдары — деректеріңізді талдайтын жеке AI-жаттықтырушы үшін тамаша кіріс (AI-жаттықтырушы туралы бөлек мақаланы қараңыз).
• Сенімділік. Үзілген синхрондау тоқтаған жерінен жалғасады; қажетсіз қайта жүктеу жоқ.

Не істей алады (қысқаша)

• Жаттығуларды Garmin, Strava және жергілікті қалта арасында синхрондау (FIT/GPX/TCX).
• Денсаулық деректерін синхрондау (ұйқы, пульс, HRV, стресс, салмақ және т.б.).
• Параллель өңдеу — үлкен мұрағаттарда да жылдам.
• Секреттерді файлда немесе KeePass базасында сақтау.
• Ақылды кэш және қайта жүктеу, API лимиттерімен ұқыпты жұмыс.
• Фото мен бейне синхрондау — ұқсас құралдарда сирек кездесетін мүмкіндік.
• Кеңейтілгіштік: өз коннекторларыңыз бен секрет қоймаларыңызды қосуға болады.

Коннекторлар және кеңейтілгіштік

Қораптан үш дереккөз/қабылдағыш қолдау табады: Garmin Connect, Strava және жергілікті қалта. Бірақ ең бастысы — жүйе модульді: коннекторлар бірыңғай интерфейсті (ServiceConnector) іске асырады, сондықтан кез келген сервиске өз коннекторыңызды жазуға болады (басқа платформа, корпоративтік трекер, бұлттық файл қоймасы) — ол ортақ синхрондау конвейеріне қосылады. Қолдау Strava, Garmin және жергілікті қалтамен шектелмейді — бұл тек дайын іске асырулар.

Бір іске қосуда әртүрлі бағыттағы бірнеше синхрондау тобын сипаттауға болады, мысалы:

1. Strava → Garmin Connect (Strava активтерін Garmin-ге жүктеу);
2. Garmin + Strava → жергілікті қалта (дискіге сақтау, басымдық Garmin-де).

Денсаулық (wellness) деректерін синхрондау

Жаттығулардан бөлек құрал денсаулық көрсеткіштерінің үлкен жиынтығын шығарады — әдепкіде әр іске қосуда (--skip-wellness жалаушасымен өшіріледі). Garmin Connect-тен, атап айтқанда:

Strava-дан athlete_stats және athlete_zones снимоктары шығарылады. Деректер wellness/ қалтасында күндер бойынша JSON-да сақталады. Кейбір типтер (салмақ, дене құрамы, қысым, гидратация) жазуды да қолдайды — коннекторлар толық оқу/жазу интерфейсін іске асырады.

Активтердің фото және бейнесін синхрондау

Құрал жаттығулардың өзін ғана емес, оларға тіркелген фотосуреттер мен бейнелерді де тасымалдайды: медианы активпен бірге жүктеп алады және қабылдағыш қолдаса, оларды кері жүктейді (мысалы, Garmin Connect фото жүктеуді қолдайды). Ұқсас синхрондаушыларда мұндай мүмкіндік сирек — әдетте олар тек трактарды ғана тасымалдайды.

Жылдамдық: параллель өңдеу

Синхрондау асинхронды ядрода жазылған: дереккөздер параллель жүктеледі, ал денсаулық көрсеткіштері воркерлер пулымен алынады (10-ға дейін бір мезгілдегі тапсырма), сондықтан көп жылдық мұрағат та жылдам өңделеді. Сонымен қатар құрал API лимиттерін бақылайды (әсіресе Strava-да): ағымдағы шығынды логқа басып, лимит терезесі қалпына келгенше синхрондауды автоматты тоқтатып, кейін жалғастырады.

Секреттерді сақтау

Логин мен парольдерді екі тәсілмен сақтауға болады:

• Тіркелгі деректері бар JSON-файл (--creds-json).
• KeePass базасы (.kdbx, --creds-keepass) — мастер-пароль KEEPASS_PASSWORD орта айнымалысынан оқылады немесе консольде сұралады.

Секрет қоймалары да кеңейтілгіш: олардың артында бірыңғай абстрактілі интерфейс тұр, сондықтан жаңа қойма түрін (мысалы, жүйелік keychain немесе корпоративтік секрет-менеджер) қалған кодты өзгертпей қосуға болады.

Сенімділік: кэш және қайта жүктеу

Жүктелген активтер мен көрсеткіштер кэштеледі (конфигтегі cache_dir). Қайта іске қосу тек жоқ нәрсені ғана тартып алады — бұл жұмысты жылдамдатады әрі синхрондауды еркін үзіп, жалғастыруға мүмкіндік береді. --force жалаушасы бәрін мәжбүрлеп қайта жүктейді.

Орнату (қысқаша)

Git, Python 3.14 және Poetry қажет.

# 1) Python 3.14 мен Poetry орнатыңыз
# macOS:
brew install git python@3.14 pipx && pipx ensurepath && pipx install poetry
# Linux (Ubuntu/Debian):
sudo add-apt-repository ppa:deadsnakes/ppa && sudo apt update && sudo apt install python3.14 python3.14-venv
pip3 install pipx && pipx ensurepath && pipx install poetry
# Windows (PowerShell): Git пен Python 3.14 орнатыңыз, содан соң: pip install pipx; pipx ensurepath; pipx install poetry

# 2) Клондап, тәуелділіктерді орнатыңыз
git clone https://github.com/dchernykh1984/trainings_sync.git
cd trainings_sync
poetry config virtualenvs.in-project true
poetry install --no-root

# 3) Конфиг шаблондарын көшіріп, өзіңізге бейімдеңіз
mkdir -p config && cp config_templates/*.json config/

Іске қосу мысалдары

# Garmin -> жергілікті қалта (тіркелгі деректері JSON-да)
poetry run trainings-sync --config config/config.garmin-to-local.json --creds-json config/creds.json

# Сол, бірақ секреттер KeePass-та
poetry run trainings-sync --config config/config.garmin-to-local.json --creds-keepass /path/to/keepass.kdbx

# Strava + Garmin (толық схема: Strava->Garmin және Garmin+Strava->қалта)
poetry run trainings-sync --config config/config.strava-and-garmin.json --creds-json config/creds.strava-source.json

Пайдалы опциялар: --start/--end (күндер аралығы), --force (бәрін қайта жүктеу), --skip-wellness (денсаулық деректерінсіз).

Жоспарда

Қазір trainings-sync — команда жолы құралы. Пайдаланушылар тарапынан қызығушылық болса, CLI-ге қосымша графикалық интерфейс (GUI) жоспарда; оны Finish Protocol Generator жобасында қолданылатын дәл сол PySide6 (Qt) құралымен жасау көзделген.

Кеңейту мүмкіндігі

• Жаңа коннекторлар басқа сервистерге/трекерлерге — бірыңғай ServiceConnector интерфейсі арқылы (және оның wellness нұсқасы).
• Жаңа секрет қойма түрлері — абстрактілі тіркелгі интерфейсі арқылы.
• Жаңа файл форматтары — FIT/GPX/TCX парсерлері біркелкі, тағы біреуін қосу оңай.

Репозиторий

Бастапқы код, конфиг шаблондары және толық құжаттама: https://github.com/dchernykh1984/trainings_sync

*Сипаттама жобаның бастапқы коды негізінде, 2026 жылдың маусымы бойынша жасалды. Нақты орнату қадамдары, конфиг форматы және синхрондалатын деректердің өзекті тізімін репозиторий README-сінен қараңыз.*