Парсер даних вступу (abitly-parse)

Метадані

Поле	Значення
Продукт	Abitly
Тип	worker / ETL
Статус	🟢 prod
Власник	`TODO:`

Призначення

Парсить дані вступної кампанії — реєстр ЗВО, конкурсні пропозиції (offers), заяви вступників (offer_requests), спеціальності, квоти — з ЄДЕБО та допоміжних джерел і завантажує їх upsert-ами у Postgres (схема abitly) одночасно в dev і prod. Це головне джерело «сирих» вступних даних для API та симуляції.

Репозиторій та рантайм


Репо	https://github.com/abitly-org/abitly-parse
Хостинг	AWS ECS Fargate scheduled task `abitly-prod-web-parser` (EventBridge `cron(0 9,14,20 * * ? *)` — тричі на день) + ручні запуски локально
Спосіб деплою	Docker image → ECR; CMD = `python pipeline.py refresh-current --no-refresh-offers --targets dev,studsearchprod`
Публічні URL / домени	немає (batch worker)

Джерела даних

Джерело	Що дає	Клієнт
`registry.edbo.gov.ua`	реєстр ЗВО, контакти приймальних комісій	`common/registry.py` (Server Actions)
`vstup.edbo.gov.ua` (+ архівні `vstup{year}`)	offers, заяви вступників; live-портал 2026 — RSA+AES-шифрований API	`common/vstup_current.py`, `common/edbo_crypto.py`
`abit-poisk.org.ua`	ПІБ вступників, fallback-рейтинги коли ЄДЕБО лежить	`common/abitpoisk.py`
`vstup.osvita.ua`	квоти (`max_quota1`/`max_quota2`)	`common/osvita.py` (scrapling)

Пайплайн

Стадії per-таблиця: fetch → build → link → load (FK-порядок: universities → faculties → specialities → offers → offer_requests). Сирі відповіді кешуються у файли (cache/**/*.jsonl.gz, на Fargate — EFS abitly-prod-web-parser-cache). Load — ідемпотентний INSERT … ON CONFLICT DO UPDATE; прохідні бали — fill-only (COALESCE), квоти — sticky-zero. Колонки score_map, prediction_status, explanation парсер не заповнює — їх пишуть API (POST /offers/admitted-scores/populate) і симуляція.

Gates перед записом: FK-preflight, blocked-build при нерозпізнаних назвах/спеціальностях, fewer-entries safeguard для fallback, table_metadata.last_updated як freshness-маркер.

Залежності

Залежить від: зовнішніх порталів ЄДЕБО/abit-poisk/osvita, Postgres (dev і prod через SSM-тунелі), Claude CLI (LLM-enrich назв факультетів/ЗВО)
Від нього залежать: API, vstup-simulation, аналітика вступу

Env-змінні

Лише назви. Повний індекс: environments.

Змінна	Призначення	Де зберігається
`DB_NAME` / `DB_USER` / `DB_PASSWORD` / `DB_SSLMODE`	підключення до цільових БД	SSM `/abitly/prod/web-parser/DB__DEV`, `DB__STUDSEARCHPROD`
`SSM_INSTANCE_ID[_DEV/_PROD]`	тунельні інстанси для локальних запусків	локальний `.env`
`ABITPOISK_VERIFY`	вимкнення SSL-перевірки abit-poisk	локальний `.env`
`CLAUDE_BIN`	шлях до `claude` CLI для enrich	локальний `.env`

Ключові команди

python pipeline.py fetch                    # повний sweep усіх джерел
python pipeline.py refresh-current \
  --no-refresh-offers --targets dev,studsearchprod   # live-цикл кампанії (те, що крутиться в проді)
python pipeline.py admissions --year 2026   # build offers + requests + link + passing

Типові проблеми

Інкрементальний fetch (--no-refresh-offers) не бачить нові КП у вже закешованих ЗВО → періодично потрібен повний --refresh.
SSM-тунель відвалюється на довгих load (~28 хв) → chunked-транзакції вже вбудовані, але ручні запуски можуть падати.
Fallback на abit-poisk лишає content-keyed ids у БД → після відновлення ЄДЕБО потрібен offer_requests cleanup --load (маркер cache/vstup/current/fallback_usage.json).
Дані «зникли/протухли» на сайті → перевір abitly.table_metadata.last_updated і runbook Typesense.
ЄДЕБО блокує/капчить: жорсткий бан (403/429) → retry+backoff → SystemExit, БД лишається stale-but-intact; «тихий» блок (200 + порожнє тіло) приймається як валідні дані — ризик регресії каталогу. Проксі не підтримується, алертів на фейл таски немає — деталі й план у data-архітектурі (слабке місце №14).

Повна картина потоків даних → data-архітектура.