📖 Детальна Інструкція Користувача

1. Глобальна панель (Верхнє меню)

Головне меню дашборда дозволяє керувати системою в цілому.

• ▶ Запустити все / ⏹ Зупинити все: Дозволяє масово запускати або зупиняти всі активні віджети. Це ідеально для моменту, коли ви підготували десяток завдань і хочете увімкнути їх одночасно.
• 🔲 Розставити: Автоматично сортує віджети (Standard -> Terminal -> Compact -> Mini) та 'приклеює' їх одне до одного в щільну сітку.
• 💾 Середовища (Workspaces): Зберігає вашу поточну 'картину' екрану (всі відкриті віджети та їх координати). Ви можете створити середовище "Київські броварні", закрити все і працювати над іншим, а потім миттєво відновити попереднє.
• 🔄 Конвертер: Система зберігає кожне пиво в окремий JSON файл для швидкості. Але якщо ви бажаєте поділитися базою або імпортувати всі дані – скористайтеся конвертером, який збере всі ваші `.json` файли в один масивний файл.

2. Архітектура процесу: Збирач (Collector) та Обробник (Fetcher)

Система розділяє процес отримання даних на два незалежні етапи для максимальної швидкості та обходу блокувань:

• 📡 Збирач (Collector): Його мета — просто знайти посилання на чекіни. Він прокручує головну сторінку пива, знаходить ID кожного відгуку (наприклад, /c/123456789) і збирає їх у величезний список. Він не заходить у кожен відгук, тому працює дуже швидко.
• ⚙ Обробник (Fetcher): Його мета — завантажити деталі. Він бере готові URL з черги Збирача і повільно, імітуючи людину, відкриває кожен чекін (щоб витягти текст відгуку, оцінку, теги ароматів, локацію тощо). Саме Обробник формує кінцевий JSON-файл.

Перевага: Ви можете швидко зібрати 10 000 чекінів за кілька хвилин (працює тільки Збирач), а потім вимкнути його і залишити Обробник працювати на всю ніч, щоб він повільно (без ризику бану) завантажив усі подробиці.

3. Налаштування Віджета (Шестірня ⚙️ на кожному віконці)

Коли ви перемикаєте вкладку віджета на "Налаштування" (Settings), вам доступні наступні унікальні перемикачі:

• Headless (Фоновий): Коли вмикати? Завжди, якщо вам не потрібно своїми очима бачити сам процес браузингу сторінки. Скрипт відкриватиме Chrome невидимо. Покращує швидкодію і не заважає працювати на комп'ютері.
• Deep Scroll (Глибокий скрол): Коли вмикати? Тільки для дуже старих або рідкісних сортів пива! Untappd блокує спроби безкінечного прокручування. Якщо ви увімкнете Deep Scroll, парсер ігноруватиме ліміти, але ви ризикуєте отримати тимчасовий IP бан. Використовуйте з обережністю!
• Авто-старт при запуску сервера: Якщо галочка стоїть, то щойно ви запустите файл `start.bat` у Windows, це завдання автоматично стрибне в чергу на обробку, без вашого втручання. Ідеально для постійного моніторингу новинок.
• Авто-повтор: Якщо вам потрібно регулярно збирати статистику певного пива (хронологію зміни рейтингу), увімкніть авто-повтор і задайте, наприклад, "кожні 24 год.". Віджет нескінченно опитуватиме це пиво.
• Свій унікальний колір: Увімкніть галочку і виберіть колір, якщо хочете щоб віджет не змінював свій колір разом із темою інтерфейсу. Ідеально для маркування "Важливих" задач червоним кольором.

4. Бібліотека та Unknown Категорія

Після введення посилання, система ще не знає, якій пивоварні воно належить. Тому при збереженні (якщо пиво сканується вперше), його статус дорівнює Unknown.

Щойно завершиться перше успішне сканування, система автоматично "перенесе" його у вашу Бібліотеку під правильною назвою Броварні. Не лякайтеся, якщо спочатку ви бачите ім'я завдання як "Unknown".

5. Як обходити або знімати бани/ліміти від Untappd та Cloudflare?

Оскільки архітектура сайту дуже сильно захищена Cloudflare, "зняти" бан безпосередньо неможливо (він прив'язаний або до IP, або до сесії "підозрілості" браузера). Але ми вже заклали у віджет інструменти для запобігання та обходу. Ось найдієвіші стратегії:

• Ручний обхід (Cloudflare Captcha): Здебільшого Cloudflare блокує або ускладнює сесію, якщо бачить "незграбні" рухи мишкою. Якщо збір зупинився і сипле помилками, просто натисніть "Stop", переведіть глобальний скрапер у Віконний режим (Headful / Headless=False), після чого запустіть і коли відкриється браузер — власноруч пройдіть перевірку "I am human" або розв'яжіть капчу у вікні. Після цього Cloudflare видасть профілю playwright_profile зелений токен-куку ("cf_clearance"), і після цього автоматика знову зможе спокійно працювати навіть без вікна.
• Подовження пауз і "Людський фактор" (Burst Mode): В налаштуваннях вашого віджета ⚙️ є вкладка таймінгів. Якщо ви отримали бан IP за постійний збір, змініть пресет бота на Safe, або налаштуйте:
  • Максимальну і мінімальну паузу між зверненнями до чекінів (збільшіть до 3-6 секунд).
  • Пауза між пачками (Burst Size): Це найбільш "людська" стратегія. Налаштуйте скрипт так, щоб він збирав, скажімо, 30-50 чекінів (ніби людина переглядає), а потім робив паузу на 15 хвилин. Це не тригерить системи Rate Limiting від Cloudflare.
• Використання Проксі (IP Ban): Якщо Cloudflare повністю забанить вашу локальну IP-адресу (зазвичай це короткостроковий бан: від 1 години до доби), єдиний апаратний обхід — зміна IP. Віджет (scraper_ui.py) має підтримку proxy. Якщо ви маєте доступ до Residential Proxy IP (проксі домашніх/мобільних IP-мереж), впишіть його в налаштуваннях — Cloudflare не банить мобільні пули адрес.
• Запуск тільки з реальним Chrome: Помилка, яку ми сьогодні виправили (додавання channel="chrome"), це найпотужніший щит. Стандартний браузер від розробників Playwright моментально детектиться системою Cloudflare і відправляє його відразу до "чорного списку". Справжній системний Google Chrome, який ми зараз підключили, майже неможливо автоматично відрізнити від справжньої людини, оскільки у нього правильні відбитки (Canvas fingerprinting, відео-кодеки тощо).

Отже, якщо вас "ловлять": просто вимкніть парсинг, увімкніть браузер з вікном, "прикиньтеся" людиною, пройдіть капчу, клікніть пару раз мануально і запустіть процес з трохи більшими паузами.