🛠 Довідка Модератора v2.6

1. Архітектура файлів

Untappd_flavors/
├── tasks/
│   ├── tasks.json              ← стан ВСІХ задач (статус, pending_urls, прогрес)
│   ├── {tid}_proc.json         ← "оброблено назавжди" — Set всіх готових URL
│   ├── {tid}_log.txt           ← текстовий лог виконання
│   └── engine_settings.json    ← глобальні налаштування рушія
│
└── beer_data/
    ├── beer_index.json         ← індекс: URL пива → файл + назва + пивоварня
    └── untappd/
        └── beer_{id}.json      ← зібрані чекіни (рейтинг, коментар, флейвори)
    

2. Відстеження оброблених URL

3. Потік даних: від сторінки до файлу

  [Сторінка пива на Untappd]
          │
          ▼  Collector (щогодини або при запуску)
  [Скрапінг посилань на чекіни зі сторінки пива]
          │
          ▼  Фільтр: url NOT IN proc_set AND url NOT IN pending_urls
  [Нові URL → t.pending_urls → tasks.json]
          │
          ▼  Fetcher (постійно, пакетами)
  [Відкриває кожну сторінку чекіна окремо]
          │
          ▼  JS evaluate: user, rating, comment, flavors, date
  [beer_data/untappd/beer_{id}.json] ← злиття за ключем URL
          │
          ▼  URL → proc_set → {tid}_proc.json
    

Злиття в beer_{id}.json: нові чекіни додаються, вже відомі — оновлюються (перезаписуються за URL-ключем). Дублювань немає.

4. Один URL vs Кілька URL у задачі

Задача може містити будь-яку кількість URL пива. Логіка роботи відрізняється:

Порівняння режимів створення з бібліотеки

5. Пріоритети (1–10)

Пріоритет — це вага в черзі колектора, а не в fetcher'і. Важливо розуміти, що саме він впливає на:

Як реально працює пріоритет:

Колектор (_collector_loop) перебирає активні задачі в порядку як вони з'явились в store.all() — тобто за часом створення, не за пріоритетом. Пріоритет наразі впливає тільки на позицію в fetcher черзі через Round-Robin.

Рекомендація: використовуйте пріоритет 8–10 для свіжих важливих пивоварень, 5 для поточної бази, 1–2 для архівних або давно зупинених.

6. Deep Scroll

Deep Scroll — режим, при якому колектор не зупиняється автоматично після того, як знаходить підряд 10 вже відомих чекінів.

Стандартний режим (Deep Scroll = OFF):

  Прокрутка сторінки вниз (до coll_max_clicks разів)
      ↓ перевіряє останні 10 чекінів
      → якщо всі 10 вже в proc_set → СТОП (вважає, що решта — теж відомі)
    

Deep Scroll = ON:

  Прокрутка сторінки вниз (до coll_max_clicks разів)
      ↓ ігнорує перевірку "10 відомих підряд"
      → завжди прокручує до максимальної глибини (coll_max_clicks)
    

7. Поведінка бота (Bot Preset)

Пресет — множник затримок між запитами. Є глобальний (Налаштування → Обробник) і поперетинковий (у кожному віджеті окремо).

Як множник застосовується:

Ієрархія пресетів:

  Задача має пресет "Системна"?
      ↓ ТАК → використовується глобальний пресет з Налаштувань
      ↓ НІ  → використовується пресет задачі (ігнорує глобальний)
    

8. Таймінги, паузи та їх взаємодія з пресетами

Параметри колектора (Налаштування → Збирач):

Параметри fetcher'а (Налаштування → Обробник):

Повна схема затримок за один цикл чекіна:

  1. Відкрити нову вкладку браузера
  2. goto(url)  ← показує індикатор "Завантаження... Xс"
  3. fetch_pause_min × mult ... fetch_pause_max × mult  ← рандомна пауза
         (якщо затримка ≥ 0.5с → показується тимчасовий індикатор; якщо ≥ log_threshold → записується в лог)
  4. JS evaluate → зібрати дані
  5. Закрити вкладку
  6. [якщо burst_count % burst_size == 0] → burst_pause_m секунд
         (індикатор "Burst-пауза: XXс..." щосекунди)
    

Приклад: "Обережний" з довгими паузами

Налаштування "Логувати паузи довше N сек" (окремо для кожної задачі)

• За замовч. 0 = паузи між чекінами не пишуться в лог (лише тимчасовий індикатор)
• Якщо встановити, наприклад, 3.0 — будь-яка пауза ≥ 3 с запишеться у постійний лог як ⏸ Пауза: 3.7с
• Це не змінює саму тривалість паузи — тільки її видимість в лозі

9. Round-Robin, parallel_tabs та Burst-пауза

Що таке "слот" і як семафор ділить роботу

Fetcher пускає всі активні задачі через один asyncio.Semaphore(parallel_tabs). Один слот = одна корутина _fetch_burst(tid), яка послідовно відкриває вкладки для свого батчу.

Алгоритм для різних конфігурацій

Поки задача чекає семафора — у її терміналі з'являється: «Очікую черги Round-Robin... 00хв 03с»

Burst-пауза та її взаємодія з parallel_tabs

Burst-пауза відбувається всередині _fetch_burst(tid) — поки задача спить, вона продовжує тримати свій слот семафора.

  _fetch_burst(A, sem):
      acquire(sem)  ← захоплює слот
      try:
          for cu in batch:
              ...обробка чекінів...
              якщо burst_count % burst_size == 0:
                  sleep(300с)  ← ПАУЗА ТУТ, слот ВСЕ ЩЕ УТРИМУЄТЬСЯ
      finally:
          sem.release()  ← звільняє тільки тут

Матриця: що реально відбувається під час burst-паузи задачі A

Практичні рекомендації

Burst-лічильники — деталі

• Кожна задача має окремий лічильник self._burst_counters[tid]
• Накопичується між усіма батчами — не скидається між RR-ітераціями
• Скидається лише при натисканні ▶ (повторний запуск задачі)
• Burst задачі A не скидає і не впливає на лічильник B

10. WebSocket та REST API

[~~]-логи: не зберігаються у {tid}_log.txt, не з'являються в глобальному журналі. Замінюють попередній тимчасовий рядок у терміналі.

12. Колектор і Обробник — механіка роботи

Рушій — це один процес з двома незалежними паралельними корутинами. Кожна може бути вимкнена окремо.

┌──────────────────────────────────────────────────────────┐
│                     ENGINE PROCESS                       │
│                                                          │
│  _collector_loop()            _fetcher_loop()            │
│  ═════════════════            ══════════════             │
│  1 вкладка, послідовно        N вкладок, паралельно      │
│                                                          │
│  beer URL → checkin URLs      checkin URL → смаки/оцінка │
└──────────────────────────────────────────────────────────┘

Колектор

Відвідує сторінку пива (/b/brewery-beer/ID) і збирає URL чекінів кліками "Load More".

task.urls = ["https://untappd.com/b/varvar-brew-black-bean/3548624"]
                        ↓  колектор
task.pending_urls = [checkin_1, checkin_2, ... checkin_269]  ← черга для обробника

Обробник

Відвідує кожну сторінку чекіна (/c/user/id) і зберігає: смаки, оцінку, дату, фото.

Round-Robin детально

Задачі: [A, B, C]    parallel_tabs=3    batch_size=5

Цикл 1 → gather одночасно:
  A: обробляє checkins 1–5   [вкладка 1]
  B: обробляє checkins 1–5   [вкладка 2]
  C: обробляє checkins 1–5   [вкладка 3]

Цикл 2 (зміщення на 1) → gather одночасно:
  B: обробляє checkins 6–10  [вкладка 1]
  C: обробляє checkins 6–10  [вкладка 2]
  A: обробляє checkins 6–10  [вкладка 3]

► Задача з 1000 чекінів не блокує задачу з 50.
► Кожна задача просувається рівномірно.

Семафор і вкладки

parallel_tabs = 3  →  Semaphore(3)

  [вкладка 1] - A batch  ┐
  [вкладка 2] - B batch  ├─ одночасно
  [вкладка 3] - C batch  ┘

Якщо parallel_tabs = 1:
  [вкладка 1] - A batch → чекає → B batch → чекає → C batch   (послідовно)

Поки всі слоти зайняті, задача показує: [~~] Очікую черги Round-Robin... 00хв 12с

Паузи — де і коли

КОЛЕКТОР:
  page.goto()           → [coll_timeout_ms, макс 60с]
  перед кліком          → [coll_pause_min × 0.5 .. coll_pause_min]
  після кожного кліку   → [coll_pause_min .. coll_pause_max]

ОБРОБНИК:
  між кожним чекіном    → [fetch_pause_min .. fetch_pause_max]
  кожні burst_size чек. → [burst_pause_m × 60 секунд]
  page.goto()           → [fetch_timeout_ms, макс 30с]

Ключова різниця

13. Статуси віджетів

Кожен віджет має статус, який відображається кольоровим бейджем у лівому нижньому куті. Ось повна таблиця з умовами переходу:

Діаграма переходів статусів

              ┌──────────────[Старт сервера: running→]──────────────┐
              ↓                                                      │
    [IDLE] ──▶──── ▶ натиснуто ────→ [QUEUED] ──────────────────→ [PAUSED]
      ↑                                   │                          │
      │ ✕ cancel                          │ Колектор взяв задачу     │ ▶ відновлено
      │                                   ↓                          │
    [DONE] ←────────────────────── [RUNNING] ←───────────────────────┘
      │         pending=[] AND             │
      │         collect_done=True          │ ⏸ пауза / auth lost
      │                                    ↓
      └─── [розклад увімкнено] ─────→ [QUEUED]        [PAUSED]

Статус-бар у нижній частині віджета (RUNNING)

З'являється коли задача RUNNING. Будується з кількох компонентів:

В черзі: 177 · Оброблено: 4 · 1.2/хв · ~145хв · збір ✓ ⚠️ 21хв без активності
─────────────────────────────────────────────────────────────────
    [1]           [2]        [3]         [4]      [5]       [6]

Попередження у статус-барі

Статус-бар у стані DONE

+45 · Всього: 1247 · Наступний: 2:34:17

Статус-бар у стані IDLE / PAUSED

IDLE:   "3 URLs"        ← скільки URL в задачі
PAUSED: "PAUSED"        ← просто текст статусу

14. Порядок збереження чекінів

Чи зберігаються чекіни в хронологічному порядку?

Як формується порядок

Колектор обходить сторінку пива зверху вниз (від нових до старих — Untappd відображає чекіни від найновіших):

Untappd сторінка пива (зверху → вниз):
  [checkin_newest]     ← колектор збирає першим
  [checkin_2nd]
  [checkin_3rd]
  ...
  [checkin_oldest]     ← колектор збирає останнім

Отже pending_urls = список від нових до старих. Обробник обробляє їх у тому ж порядку (FIFO).

Злиття при повторному запуску

При кожному наступному запуску задачі, _save_beer зливає нові чекіни зі старими за ключем URL:

ex = {c["url"]: c for c in existing_checkins}   ← dict від старих
for r in new_results: ex[r["url"]] = r           ← update/overwrite
results = list(ex.values())                       ← результат: dict.values() порядок

Практичні наслідки