Симуляція широкого конкурсу (vstup-simulation)

Метадані

Поле	Значення
Продукт	Abitly
Тип	worker / обчислювальний рушій
Статус	🟢 prod (ручні запуски)
Власник	`TODO:`

Призначення

Реалізує алгоритм розподілу бюджетних місць (Додаток 6, Наказ МОН №373): deferred acceptance по субконкурсах А/Б/ББ/В + широкий конкурс із суперобсягами. На вході — живий зріз abitly.offers + abitly.offer_requests; на виході — прохідні бали і прогноз статусу кожної заяви. Живить сторінки КП («хто куди проходить») і фічу симуляції вступу.

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


Репо	https://github.com/abitly-org/vstup-simulation
Хостинг	ніде не хоститься — запускається вручну з машини оператора (скіл `/wide-run` у репо); шляхи `.env` захардкожені на Windows-машину оркестратора
Спосіб деплою	немає (git pull + node)
Публічні URL / домени	немає

Потік даних

Зріз: одна REPEATABLE READ транзакція читає abitly.offers + abitly.offer_requests за рік (scripts/ingest/build-snapshot-db.mjs).
Статичні входи з репо: data/<рік>/wide-competitions.json (реєстр широких конкурсів і суперобсяги), offer-specializations.csv, min-score-lookup.json.
Симуляція: placement/run.mjs → етапи А/Б/В бюджету + контракт; детермінований tie-break (FNV-1a від abitly_id); незалежний fairness-верифікатор.
Запис (одна транзакція): схема wide_competition — runs (draft/active/archived, unique active per year), groups, lanes, applications, offer_cutoffs; при --activate додатково оновлюється abitly.offer_requests.prediction_status/explanation (⚠️ без run_id, перезаписується безповоротно).

Оркестрація (скіл `/wide-run`)

preflight (перевірка env/DDL/файлів, identity-assert БД) → dry-run (import-wide-run.mjs) → перегляд report.json → явна згода людини → --activate → verify-wide-run.mjs. Активація блокується при fairness-порушеннях чи fatal-інваріантах. Тунель до БД (порти 55432 dev / 55433 prod) піднімає людина.

Залежності

Залежить від: Postgres (читає abitly, пише wide_competition), даних abitly-parse, Redis (purge кешу після activate, fail-safe)
Від нього залежать: API (WideCompetitionController, OfferApplicantsController, live cutoffs у симуляції), сторінки КП на вебі

Env-змінні

Змінна	Призначення	Де зберігається
`DB_HOST` / `DB_PORT` / `DB_NAME` / `DB_USERNAME` / `DB_PASSWORD`	ціль запису (dev/prod)	локальні `.env` / `.env.prod` оператора
`REDIS_HOST` / `REDIS_PORT` / `REDIS_PASSWORD`	purge кешу applicants	там само
`MIN_SCORE_YEAR`	рік порогів допуску	виставляється з `--year`

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

Прогнози не версіоновані: попередній prediction_status втрачається при кожному activate; відкат = re-activate старого рану (може бути pruned у БД, лишається у локальному архіві data/archive/wide-runs/).
Суперобсяги 2026 частково carryover-2025 (до МОН-розкладки) — прохідні ~37 груп орієнтовні; Б14д/Б29д стабільно занижені (кластер C1).
Якщо Redis недоступний під час activate — кеш /offer-applicants/* (TTL 1 год) показує старі прогнози до години.
min_obsyag=0 у всіх КП → етап Б (анулювання недоборів) фактично не спрацьовує.

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