Track-O — Повна документація

Вступ до Track-O

Track-O — це веб-платформа для подій зі спортивного орієнтування і не тільки. Вона дозволяє організаторам публікувати карти, а спортсменам — завантажувати GPS-треки, переглядати маршрути суперників та аналізувати результати. Все це в браузері без жодної встановленої програми.

Ключові можливості

Ролі користувачів

Роль	Можливості
Гість без реєстрації	Переглядати публічні змагання, читати карти, дивитися трeki інших. Завантажувати трек через Strava.
Спортсмен зареєстрований	Все вище + завантажувати GPX-файли та прив'язувати треки до свого профілю, переглядати особисту історію.
Організатор адмін-доступ	Все вище + створювати змагання, завантажувати карти, налаштовувати дистанції/КП, керувати всіма треками, редагувати та видаляти змагання через адмін-панель.

Акаунт та авторизація

Track-O підтримує кілька способів входу. Жоден не вимагає введення паролю вручну для звичайних користувачів.

Способи реєстрації та входу

Профіль користувача (/admin → Профіль)

• Особисті дані — ім'я, прізвище, email. Email заблоковано для редагування якщо OAuth.
• Зміна паролю — доступна для Email-акаунтів. Потрібно ввести поточний та новий пароль.
• Прив'язані акаунти — відображає статус підключення Google та Strava. Кнопки «Підключити» і «Від'язати».
• Двофакторна авторизація (2FA) — QR-код для TOTP-додатків (Google Authenticator, Authy тощо). Після увімкнення — обов'язковий 6-цифровий код при вході.
• Браузерні сесії — список активних сесій з IP-адресою та назвою браузера. Кнопка «Завершити всі інші сесії».

Прив'язка Strava до існуючого акаунту

1. Увійдіть в адмін-панель (/admin).
2. Клік на аватар у верхньому куті → «Профіль».
3. Вкладка «Прив'язані акаунти».
4. Натисніть «Підключити Strava» — Strava OAuth відкриється у тому ж вікні.
5. Після підтвердження токени збережуться автоматично й оновлюватимуться у фоні без повторної авторизації.

Тарифні плани

Кожне змагання створюється в рамках тарифного плану. Він визначає доступні функції та максимальні ліміти для конкретної події.

Параметри тарифу

Параметр	Опис
Назва	Відображається при виборі плану для нового змагання.
Вартість (кредити)	0 = безкоштовний. Ненульова вартість списується при виборі тарифу.
GPS-треки	Чи можуть учасники завантажувати GPX-треки до цього змагання.
Кілька карт	Додавання більше однієї карти до однієї події (наприклад, різні дистанції).
Малювання маршрутів	Інструмент ручного малювання маршруту на карті без GPX.
Розбивки (splits)	Таблиця проміжних часів між контрольними пунктами.
Анімація фінішу	Відтворення руху всіх учасників на карті у реальному часі.
Макс. учасників	Максимальна кількість GPS-треків для одного змагання.
Макс. дистанцій	Максимальна кількість груп/дистанцій на одній карті.

Список змагань — головна сторінка

Головна сторінка (/) — список усіх публічних змагань. Не потребує входу.

Пошук та фільтри

• Пошук за назвою — поле у верхній частині. Результати фільтруються в реальному часі без перезавантаження сторінки.
• Фільтр за типом — кнопки «Всі», «Класика», «Рогейн». Повторне натискання скидає фільтр.
• Сортування за датою — кнопки «Нові перші», «Старі перші».
• Лічильник результатів — показує скільки змагань знайдено після застосування фільтрів.

Що видно в картці змагання?

• Назва — клікабельна, веде на сторінку події.
• Тип — «Класика» (синій бейдж) або «Рогейн» (фіолетовий).
• Дата проведення — формат «дд місяць рррр» (наприклад, «15 березня 2026»).
• Кількість карт — іконка карти з числом карт.
• Кількість треків — іконка треку з числом завантажених GPS-маршрутів.
• Переглядів — лічильник відвідувань сторінки змагання.
• Статус — «Активне» (зелений) або «Відкриється через Х год» (жовтий зворотній відлік).
• Кнопка «Переглянути» — відкриває сторінку змагання.

Блок статистики платформи

Нижче списку — загальні лічильники: кількість змагань, спортсменів та треків на всій платформі.

CTA-блок «Є питання?»

Перед футером — синій банер з кнопкою «Зв'язатися з нами», що веде на сторінку контактів.

Секція «Як це працює»

За якорем #how — покрокова інструкція для нових користувачів: знайти змагання → завантажити трек → переглянути карту → порівняти маршрути.

Перегляд карти та інтерфейс події

Після відкриття змагання ви бачите інтерфейс з трьох частин: навігаційна панель зверху, бічна колонка зліва, канвас карти.

Навігаційна панель (top bar)

• Кнопка «Назад» — стрілка ліворуч, повертає на список змагань.
• Назва змагання та тип — у центрі панелі.
• Дата проведення — праворуч від назви.
• Перемикач карт — якщо прикріплено більше однієї карти, з'являється список вибору.
• Кнопка «Splits» — відкриває таблицю розбивок (якщо ввімкнено в тарифі).
• Кнопка «Анімація» — запускає відтворення (якщо ввімкнено в тарифі).
• Кнопка «Намалювати» — відкриває інструмент ручного малювання (якщо ввімкнено в тарифі).
• Кнопка «Завантажити трек» — відкриває модальне вікно завантаження.

Бічна колонка (sidebar)

• Фільтр за дистанцією — випадаючий список груп. Залишає у списку лише учасників обраної дистанції.
• Кнопки «Всі» / «Жоден» — показати або приховати всі треки одразу.
• Список учасників — кожен рядок: кольоровий кружок, ім'я учасника. Клік — вмикає/вимикає трек. Активний виділяється фоном.
• Кнопка стиснення колонки — вузька кнопка на правому краї ховає бічну панель, розширюючи карту.

Канвас карти

• Масштабування — колесо миші, або кнопки +/− у куті канвасу, або двопальцевий жест на сенсорному екрані.
• Панорамування — затиснути ліву кнопку миші та тягнути. На мобільному — один палець.
• Контрольні пункти — кола з номерами на карті (якщо задані організатором).
• Старт і фініш — спеціальні символи: трикутник (старт) і подвійне коло (фініш).
• Треки — кольорові лінії маршрутів накладені на карту.
• Панель аналізу — при наведенні на трек, знизу праворуч з'являється блок з іменем та часом учасника.
• Кнопка «На весь екран» — Fullscreen API, розгортає канвас на весь монітор.
• Кнопка скидання виду — повертає карту до вихідного масштабу та позиції.

Статуси змагань

Завантаження GPX-треку

Кнопка «Завантажити трек» на сторінці змагання відкриває модальне вікно з двома вкладками: GPX-файл і Strava.

Вкладка «GPX-файл»

1. Оберіть карту — якщо змагання має кілька карт, з'являється випадаючий список. Трек прив'язується до конкретної карти.
2. Оберіть дистанцію / групу — список заповнюється відповідно до обраної карти. Без вибору дистанції трек буде без групи.
3. Ім'я учасника — автоматично підставляється ваше ім'я з профілю. Можна змінити (макс. 100 символів).
4. Колір треку — кольорова палітра. Система автоматично призначає перший вільний колір з набору 10 стандартних. Можна змінити вручну.
5. Виберіть GPX-файл — кнопка «Оберіть файл». Формат: .gpx. Максимум: 20 МБ.
6. Натисніть «Завантажити» — трек зберігається на сервері, прив'язується до вашого акаунту та миттєво з'являється на карті.

Що відбувається після завантаження?

• Модальне вікно закривається автоматично.
• Ваш трек миттєво з'являється на карті без перезавантаження (realtime update через Alpine.js).
• У бічній колонці з'являється ваше ім'я з відповідним кольором.
• Якщо тариф включає splits — розбивки стають доступні одразу.

Автоматичне призначення кольору

Система перевіряє 10 стандартних кольорів: ■ індиго, ■ червоний, ■ зелений, ■ помаранчевий, ■ блакитний, ■ фіолетовий, ■ рожевий, ■ бірюзовий, ■ жовтий, ■ малиновий. Призначає перший незайнятий. Якщо всі зайняті — випадковий.

Strava інтеграція

Track-O дозволяє імпортувати активності зі Strava без завантаження GPX вручну — найзручніший спосіб для регулярних користувачів Strava.

Перший вхід через Strava (без акаунту)

1. Натисніть «Завантажити трек» на активному змаганні.
2. Відкрийте вкладку «Strava».
3. Натисніть помаранчеву кнопку «Підключити Strava».
4. Strava-сторінка авторизації відкриється у тому ж вікні. Підтвердьте доступ.
5. Ви будете повернені на сторінку змагання. Якщо акаунту не було — він створений автоматично з вашим іменем зі Strava.
6. Список активностей завантажується автоматично.

Вікно вибору активності зі Strava

• Список активностей — останні 20 активностей: назва, тип (Run / Ride / Hike / Walk...), відстань у км, дата.
• «Завантажити ще» — підвантажує наступні 20 записів, якщо їх більше.
• Вибір рядка — клік виділяє активність синім фоном. Повторний клік знімає вибір.
• Ім'я учасника — залишається редагованим.
• Колір — аналогічно GPX-вкладці.
• «Завантажити» — GPX-файл автоматично завантажується з Strava API і зберігається на сервері. Файл не потрібно зберігати самостійно.

Від'язка Strava

Адмін-панель → аватар → Профіль → вкладка «Прив'язані акаунти» → кнопка «Від'язати Strava». Токени видаляються з бази. При наступному Strava-імпорті система знову запросить авторизацію.

Перегляд та порівняння треків

Управління видимістю треків

• Клік по рядку учасника у бічній колонці — вмикає або вимикає показ треку на карті.
• «Всі» — зробити видимими всі треки одночасно.
• «Жоден» — приховати всі треки (зручно щоб залишити лише один для аналізу).
• Фільтр за дистанцією — показує тільки треки обраної групи.

Анімація руху учасників

Доступна якщо тариф включає функцію «Анімація фінішу»:

1. Натисніть кнопку «▶ Анімація» у навігаційній панелі.
2. Відкриється панель керування анімацією.
3. Виберіть швидкість: ×1, ×2, ×5, ×10.
4. «Play» — точки починають рухатися по треках всіх активних учасників.
5. «Пауза» — зупиняє в поточній позиції. «Скинути» — повертає на початок.
6. Лічильник часу показує «ігровий час» від умовного старту.

Розбивки (Splits)

Доступно якщо тариф включає «Splits» і організатор задав контрольні пункти:

1. Натисніть кнопку «Splits» у навігаційній панелі.
2. Відкриється модальне вікно з горизонтально прокручуваною таблицею.
3. Рядки = учасники. Колонки = КП1 → КП2 → ... → Фініш.
4. Клітинка містить проміжний час між поточним і попереднім КП у форматі хх:хх.
5. Порожня клітинка — GPS не потрапив у радіус перехоплення КП.

Ручне малювання маршруту

Якщо тариф включає «Малювання маршрутів» — доступний інструмент без GPX:

1. Кнопка «Намалювати» (олівець) у навігаційній панелі.
2. Кліком на карті додавайте точки маршруту.
3. Подвійний клік — завершення.
4. Введіть ім'я учасника та оберіть колір.
5. Збережіть — маршрут з'явиться в списку поруч з GPS-треками.

Створення змагання

Організатор створює змагання через адмін-панель (/admin): меню ліворуч → «Змагання» → кнопка «Нове змагання» (або «+ New event»).

Секція «Основна інформація»

• Назва змагання — обов'язкове. Макс. 255 символів. Відображається в списку та на сторінці події.
• Тип змагань — «Класика» (фіксований порядок КП) або «Рогейн» (довільний порядок, обмежений час). Впливає на відображення бейджа та фільтрацію на головній сторінці.
• Дата проведення — дата у форматі дд/мм/рррр. За замовчуванням — поточна дата.
• Опис — необов'язковий текст (textarea). Відображається на сторінці події. Можна вказати місце проведення, організацію, посилання на положення тощо.

Секція «Тарифний план»

Список активних тарифів у вигляді radio-buttons. Для кожного видно:

• Назву плану та вартість («Безкоштовно» або «X кредитів»).
• Максимальну кількість учасників і дистанцій.
• Іконки включених функцій: GPS / Кілька карт / Малювання / Splits / Анімація.

Секція «Видимість та доступ»

• Публічне — з'являється в загальному списку на головній. Індексується пошуковиками. Зелений значок поруч.
• Тільки за посиланням — не в списку, але доступне всім хто знає URL. Ідеально для клубних заходів.
• Приватне — бачить лише організатор. Для тестування, підготовки, або архівних подій.
• Час відкриття карти — опціональне поле дата+час. Якщо задано: завантаження треків відкрите, але карта і чужі треки недоступні до цього часу. Підказка під полем пояснює поточний режим.

Після збереження

Змагання з'являється у списку адмін-панелі. При «Публічному» доступі — одразу видно на головній сторінці. Наступний обов'язковий крок: додати карту (без карти сторінка змагання буде порожньою).

Карти та калібрування

Карта — основа кожного змагання. Після її завантаження потрібне калібрування для точного накладання GPS-треків.

Завантаження карти

1. Адмін-панель → «Змагання» → відкрийте змагання → вкладка «Карти».
2. «+ Нова карта» або «Додати карту».
3. Введіть назву карти (наприклад, «М21А», «Коротка», «День 1»).
4. Завантажте файл: .jpg, .jpeg, .png, .webp. Рекомендований розмір: до 5 МБ для швидшого завантаження.
5. Збережіть. Карта з'явиться у списку зі статусом «Не откалибровано» (сірий).

Калібрування карти

Без калібрування GPS-треки не будуть накладатися на карту. Підтримуються два методи:

Метод	Мін. точок	Точність	Коли використовувати
Affine	3	Висока для рівних карт	Більшість сканів орієнтувальних карт без деформацій.
Rubber-sheet	4+	Максимальна	Деформовані, складені або старі карти з нерівномірним масштабом.

Попередній перегляд карти

У списку карт є мініатюра файлу. Клік відкриває повне зображення для перевірки правильності завантаженого файлу.

Кілька карт (якщо тариф підтримує)

Можна додати довільну кількість карт до одного змагання. На сторінці події з'явиться перемикач карт. Типові сценарії:

• Різні дистанції з різними картами (Еліта і Масовий старт).
• Денна і нічна дистанції рогейну.
• Різні старти одного змагання.

Видалення карти

Кнопка «Видалити» у рядку карти. Перед видаленням — переконайтеся, що до цієї карти не прив'язані треки учасників (інакше вони залишаться «підвисати»). Файл зображення видаляється автоматично через Observer.

Дистанції та контрольні пункти

Дистанції (Course groups)

Дистанції — це групи учасників. Спортсмен обирає дистанцію при завантаженні треку. Глядачі можуть фільтрувати by дистанцією.

1. Адмін → «Карти» → відкрийте карту на редагування.
2. Секція «Дистанції» → «+ Додати».
3. Введіть назву (наприклад «М21А», «Ж21», «М35», «Юніори», «5 км»).
4. Збережіть. Дистанція одразу з'являється у формі завантаження треку на сторінці події.

Контрольні пункти (Controls)

КП описують розташування пунктів на карті. Використовуються двояко:

• Візуально — кола з номерами відображаються поверх карти.
• Splits — система перевіряє чи GPS-трек проходив через зону КП і записує час перетину.

1. Адмін → «Карти» → редагування → секція «Контрольні пункти».
2. «+ КП» — додати новий.
3. Задайте номер КП (1, 2, 3... або S для старту, F для фінішу).
4. Координати у пікселях карти — або введіть вручну, або клікніть на карті у редакторі.
5. Радіус зони перехоплення — у метрах. Рекомендований: 20–50м залежно від масштабу карти.
6. Збережіть. КП одразу відображається на превью карти.

Специфікація старту і фінішу

Позначення	Символ на карті
КП «S» або «0»	Трикутник — Старт
КП «F» або останній у списку	Подвійне коло — Фініш
Всі інші	Коло з номером

Видимість та управління доступом

Рівні доступу до змагання

Рівень	У списку на /	За прямим URL	Типовий сценарій
Публічне	✓ Так	✓ Так	Відкриті офіційні змагання
За посиланням	✗ Ні	✓ Так	Клубні змагання, тренування, тести
Приватне	✗ Ні	Лише організатор	Підготовка, архів, чернетки

Рівень доступу змінюється в будь-який момент через «Редагувати змагання» в адмін-панелі без втрати даних.

Час відкриття карти (Embargo / Delayed reveal)

• Порожнє — карта та треки відображаються одразу.
• Дата+час у майбутньому — спортсмени можуть завантажити трек, але не можуть побачити карту і чужі маршрути. На сторінці відображається зворотний відлік.
• Дата+час у минулому — приведе до негайного відкриття.

Поширення посилання

URL події: https://event-o.tech/event/<uuid>. Для «За посиланням» — скопіюйте URL з адресного рядка або зі сторінки «Переглянути» в адмін-панелі та поділіться у Telegram/WhatsApp групі учасників.

Управління треками учасників

Список треків в адмін-панелі

Меню → «Треки». Таблиця з усіма завантаженими треками. Фільтри:

• Пошук за іменем учасника.
• Фільтр за змаганням.
• Фільтр за дистанцією.
• Сортування за датою завантаження (за замовчуванням: нові першими).

Дані по кожному треку

Поле	Опис
Ім'я учасника	Ім'я, введене при завантаженні.
Змагання	Назва події до якої прив'язаний трек.
Карта	До якої карти належить трек.
Дистанція / група	Обрана учасником група.
Колір	Кольоровий квадрат для ідентифікації.
Завантажив	Email або ім'я акаунту. «Гість» — якщо анонімно через Strava.
Дата завантаження	Точний час (дд.мм.рррр гг:хх).

Редагування метаданих треку

«Редагувати» у рядку треку. Можна змінити: ім'я учасника, колір, дистанцію, прив'язку до карти. GPX-файл не замінюється — лише метадані.

Видалення треку

«Видалити» з підтвердженням у діалозі. GPX-файл видаляється з сервера автоматично (MapObserver відслідковує видалення). Запис не відновлюється.

Масові дії

Виберіть кілька треків чекбоксами → «Дії» → «Видалити обрані». Корисно для очищення тестових записів перед публікацією змагання.

Адмін-панель організатора

Адмін-панель на базі Filament 3 доступна за адресою /admin. Вхід — через Google OAuth або email/пароль.

Розділи меню

Розділ	Зміст
Dashboard	Огляд: лічильники змагань, треків, останні події.
Змагання	Повний список із пошуком, фільтрами, сортуванням, редагуванням, видаленням.
Карти	Всі карти з усіх змагань. Завантаження файлів, калібрування, метадані.
Треки	Всі GPS-треки з можливістю редагування та видалення.
Тарифи	Лише для суперадміна. Керування тарифними планами та їх функціями.
Користувачі	Список акаунтів. Редагування ролей, статусу, Impersonate.
Меню (Menu Builder)	Управління навігаційними меню сайту (header, footer).
Блог	Статті та публікації.
Зворотний зв'язок	Повідомлення з контактної форми з сайту.

Пошук, фільтри, сортування

• Глобальний пошук — рядок із лупою у верхньому правому куті. Шукає по назві, email, ID.
• Фільтр «Доступ» — публічне / за посиланням / приватне.
• Фільтр «Активне» — тільки активні змагання (карта відкрита).
• Сортування — клік по заголовку колонки перемикає ASC/DESC.
• Toggle-колонки — кнопка з іконкою очей в заголовку таблиці дозволяє приховати непотрібні колонки.

Дії у рядку таблиці

• Переглянути — InfoList-картка лише для читання.
• Редагувати — повна форма редагування.
• Видалити — soft-delete (дані можна відновити через адмінінструменти БД). Підтверджується у діалозі.

Imersonate (перегляд від імені користувача)

Адміністратор може перемикнутись у сесію будь-якого користувача: «Користувачі» → рядок → кнопка «Impersonate». У верхньому рядку з'являється банер «Ви переглядаєте як …» з кнопкою «Повернутися».

Сповіщення (Toast notifications)

Після будь-якої дії (збереження, видалення, від'язка Strava тощо) у правому нижньому куті з'являється кольоровий тост:

• 🟢 Зелений — успішна операція.
• 🔴 Червоний — помилка (наприклад, валідація форми).
• 🟡 Жовтий — попередження.
• 🔵 Синій — інформаційне повідомлення.

Профіль організатора та зовнішні прив'язки

Доступ до профілю

Адмін-панель → клік на аватар або ім'я у правому верхньому куті → «Профіль» (або «Мій профіль»).

Вкладки профілю

Безпека акаунту

Вихід з системи

Аватар → «Вийти». Всі токени сесії очищаються. При наступному вході потрібна повторна авторизація через Google або email.