Сборщики событий «По душе»: спецификация для инженера

0. Как читать и где источники правды

Правило чтения: перед правкой любого файла из ingestion/ открыть его докстринг. В этом проекте докстринг объясняет причину, а комментарий рядом с кодом называет инцидент («раньше здесь было X, и происходило Y»). Это стиль, который надо воспроизводить, а не ломать.

Правило источника правды: если этот документ расходится с кодом или с docs/internal/*, прав код, затем docs/internal, затем этот документ — и расхождение надо починить в документе.

1. Продукт: что считается ценным событием

«По душе» — афиша живых офлайн-встреч, второй продукт платформы (первый — знакомства «По любви»). Каталог не может стартовать пустым, поэтому его наполняют сборщики. Из чата владельца от 24.07.2026 и решений проекта следует шкала ценности:

1. Событие с точными координатами и малого формата — главная цель. Лекции, мастер-классы, разговорные и книжные клубы, беседы, йога в парке, прогулки, квизы, настолки, дегустации, волонтёрские выезды. Именно ради них строится продукт (в чате: «события на 8–15 человек»).
2. Событие с адресом без координат — годится: каталог догеокодирует по своему справочнику OSM (ingestion/geo/*), статус до тех пор needs_geo.
3. Массовое зрелище (стадион, репертуарный театр, фестиваль) — в каталог берём, но помечаем format=mass: в ленту оно идёт через премодерацию и квоту (FEED_MASS_QUOTA=1), в районную ленту — нет. «Массовая афиша на карте районов — шум, который убивает гиперлокальность» (чат 24.07).
4. Онлайн — по умолчанию не берём (у онлайна нет места на карте). Берём только по явному флагу прогона там, где площадка смешивает форматы.
5. Прошедшее — не берём никогда; отсев на стороне сборщика.

Решения владельца, которые действуют на всю работу:

• Юридическую чистоту источников не оцениваем — владелец договаривается с площадками сам. Но технические правила проекта, которые из этого выросли, обязательны: ссылка на источник у каждой карточки (иначе карточка не отдаётся стенду), авторство фото там, где площадка его даёт, ретенция сырья 90 дней, erase по запросу.
• Указание источника в карточке = копирайт и обмен трафиком, поэтому берём широко — «от афиш концертов до простых локальных прогулок, читательских клубов, православных бесед, йоги в парках».
• Тир 4 (Timeleft, Sea Soul, Globi, Invitor, Luma, Partiful) не собираем — это конкурентная разведка, не источник контента.
• Билетные операторы (тир 3 в чате) уже собраны парсерами — решение о партнёрских фидах остаётся за владельцем (см. §18).

География: Москва — приоритет проверки качества, но справочник знает 91 город (ingestion/collectors/cities.py), и каждый сборщик объявляет, какие из них умеет. Пригороды складываются в большой город (ADR 0002).

2. Что уже сделано

2.1. 27 боевых источников (состояние на 07.09.2026)

Все зарегистрированы в orchestrator/registry.py, описаны в domain.SOURCE_CATALOG, входят в ночную и дневную волну (CRON_SOURCES). auto — политика стенда DEFAULT_POLICIES в events/catalog_import.py (True — карточка публикуется сразу, False — публикует оператор).

Итого в каталоге на стенде после ночной волны 04.09.2026 (для масштаба): moibiz 1309 событий / 482 площадки, leader_id 1061 / 322. Тестов в репозитории — 1131 (pytest --collect-only, 07.09.2026), все зелёные на 03.09.2026 (982 на тот момент).

2.2. Карточки беклога в «Заблокировано» (5) — с пробой 07.09.2026

2.3. Решения «не делать» (чтобы не завести карточку заново)

2.4. Что сделано частично (важно не принять за «готово»)

• SRC-LECTORIA закрыта, но реализован только ВШЭ (hse). МГУ (whitelist факультетских календарей), РАНХиГС (ДОД + научный календарь) — не сделаны; в карточке есть разведка 18.08.2026.
• SRC-CONGRESS — ЦМТ, Школа Сколково, events.sk.ru. «Технопарк» так и не выбран (technopark.ru — магазин техники; кандидаты: Технополис Москва, Техноград ВДНХ, кластер «Ломоносов»).
• SRC-BIZASSOC — только Опора МСК; на 03.09.2026 у неё ноль предстоящих очных событий. Самый бедный источник проекта.
• SRC-HABRVC — только Хабр; VC не делать.
• timepad — механизм пропуска неизменившихся деталей не заведён (страница события ~2,5 с; окупится сильнее всех) — см. tests/test_skip_rollout.py.
• leader_id — ⚠️ номера городов Тулы и Ярославля расходятся между двумя слитыми реализациями (1227359/1265352 против 1283537/1299162); параметр placeIds[] у events/search не проверен.

3. Реестр площадок к сбору

Полный список из чата 24.07.2026, разложенный по разделам чата. Колонки: Статус — Готово (код) / Частично / Заблокировано / Отказ / Не начато; Проба 07.09 — что ответил сайт с сервера salam0nn.ru (код HTTP, движок, признаки машинной разметки: jsonld — есть JSON-LD, EVENT-LD — в нём есть @type: Event, ics/rss — есть ссылки на календарь или ленту, timepad-widget — на странице встроен виджет Timepad, ANTIBOT — капча/челлендж, 000 — соединения нет). ⚠️ Проба с сервера ≠ проба с ноутбука: mbm.mos.ru с сервера закрыт по IP, с ноутбука открыт. Всё с 000, 401, 403, ANTIBOT перепроверить с ноутбука.

Приоритет — предложение автора документа по шкале «плотность малых офлайн-событий × гео-полнота × простота»; утверждает владелец.

3.1. Универсальные афиши и агрегаторы (чат, раздел 1)

3.2. Деловые, образовательные, IT (раздел 2)

3.3. Лектории и просвещение (раздел 3) — не начато

Здесь много площадок продают билеты через Timepad или публикуются в KudaGo — перед адаптером проверить, не течёт ли площадка через уже собранные источники (§13, шаг 2). Проба показала виджет Timepad у РГБ и Мосспорта.

3.4. Культурные площадки и парки (раздел 4) — не начато, кроме справочника

3.5. Музыка, вечеринки, клубы (раздел 5)

Концерты и стендап уже в большом объёме приходят из kassir, mtslive, radario, qtickets, afisha, yandex_afisha, ticketland. Прямые календари площадок нужны только там, где они дают то, чего нет у операторов (бесплатные, камерные).

3.6. Спорт и активности на воздухе (раздел 6)

3.7. Экскурсии, прогулки, краеведение (раздел 7)

3.8. Книжные клубы, разговорные форматы, настолки (раздел 8)

3.9. Религиозные и духовные сообщества (раздел 9)

3.10. Гастрономия и напитки (раздел 10) — не начато

Дегустации (SimpleWine, Invisible, винные школы), каппинги (Скуратов, Camera Obscura, ЛЕС), гастромаркеты (Депо, Вокруг света, StrEAT), кулинарные школы (CulinaryOn, Novikov School), social dining. Ни одна площадка не пробована. Ожидаемо: анонсы в TG и через Timepad/Qtickets. Приоритет средний; разведку начать с проверки пересечений (§13 шаг 2), потом Tilda/HTML-адаптеры.

3.11. Творчество и хобби (раздел 11) — не начато

Гончарные и художественные студии, Paint&Wine (ArtVino, «Холст и бокал»), швейные/столярные коворкинги (Rubankov), фотопрогулки (Photoplay), флористика, керамика, театральные студии, импров (BIT). Ни одна не пробована. Это «студийные расписания»: у большинства расписание — форма записи без дат-событий. Брать только площадки с календарём конкретных мастер-классов. Приоритет средний.

3.12. Маркеты, фестивали, сезонные (раздел 12)

3.13. Знакомства и социальные форматы (раздел 13)

3.14. Волонтёрство и социальные события (раздел 14)

3.15. Соцсети и мессенджеры (раздел 15) — главный слой микро-событий

3.16. Региональное расширение (раздел 16)

Дешёвое региональное расширение без новых парсеров: у kudago, opendata_mkrf, qtickets, kassir, radario, nethouse, gorodzovet, russpass, hse списки городов короче, чем умеет площадка. Расширение supported_cities — это правка справочника + живая сверка идентификаторов (§13 шаг 6), а не новый код.

4. Очередность работ (волны 6–9)

Предложение автора документа. Принцип из чата 24.07: сначала то, что даёт плотность малых офлайн-событий на карте Москвы, потом регионы, потом самый дорогой слой — соцсети. Внутри волны — от площадок с машинной разметкой (JSON-LD/ICS/RSS/WP REST) к чистому HTML, от бесплатных к платным. Каждый пункт — отдельная карточка SRC-* в беклоге и отдельный коммит.

Волна 6 — «Лектории, парки, культурные центры Москвы» (гео-плотность)

Волна 7 — «Клубные форматы малого размера»

Волна 8 — «Регионы»

Волна 9 — «Соцсети и мессенджеры»

Перепроверки заблокированного — по одной пробе в квартал: 2do2go, Runet-ID, Политех, Мосгорпарк, dancetime, bistrosvidania, РазДельный сбор (все 000).

5. Архитектура в одну страницу

collectors/<code>/        адаптер одной площадки: HTTP → CatalogUpsert   (ШЛЮЗ 1: сбор)
        ↓ CollectResult(items, venues, stats, errors)
orchestrator/runner.py    прогон: advisory-лок на источник, города в потоках,
                          heartbeat, промежуточная запись, статусы, парковка
        ↓ по одной строке
orchestrator/persist.py   слияние в каталог: дедуп, полевая политика, статус (ШЛЮЗ 2)
        ↓
db/models.py              Postgres #1: events / event_sessions / venues / organizers /
                          event_media / event_source_links / raw_payloads / collection_runs
        ↓ GET /api/export/events (X-Auth-Token)
ui/export.py::_build_card проекция в плоскую карточку, fail-closed по атрибуции,
                          интересы, feed_ready                                (ШЛЮЗ 3)
        ↓ HTTP
стенд events/catalog_import.py  политика источника, замки оператора, уборка   (ШЛЮЗ 4)
        ↓
витрина Nuxt · свайп-лента Android/iOS · консоль оператора

Три вещи, которые важнее всего помнить:

1. Ingestion — отдельный сервис со своей базой. Стенд ходит к нему только по HTTP. Сборщик ничего не знает про базу; оркестратор ничего не знает про сайт. Договор между ними — датаклассы collectors/protocol.py.
2. Событие проходит четыре независимых шлюза и может провалиться на любом. «Собрал» ≠ «в ленте». Проверка нового источника заканчивается на карточке экспорта и на строке в стенде, а не на stats.normalized.
3. feed_eligible — не «видно в ленте». Настоящий предикат на стенде: is_active И is_published И окно дат И (feed_eligible ИЛИ пустой external_id).

Что где отсеивается (чтобы понимать, почему «событие есть, а в приложении нет»):

6. Договор сборщика

6.1. Каталог файлов

ingestion/collectors/<code>/
  __init__.py       экспорт класса XxxCollector
  collector.py      класс: параметры прогона, обход, статистика, отсев, flush/heartbeat
  http_client.py    транспорт: базовый URL, темп, пагинация, обход анти-бота
  normalize.py      сырой объект → CatalogUpsert; NormalizeError; is_past
  parse_list.py / parse_detail.py   только у HTML-скраперов
  <адаптеры>.py     у семейств: один файл на сайт (wtc.py, skolkovo.py, opora_msk.py)

Эталон для чтения — kudago (198 строк, всё по правилам). Эталон семейства — venue_cals (три сайта, общий нормализатор) и bizassoc (адаптеры + общие помощники из collect_util: parse_subset, moscow_address, mentions_other_city, https_url).

6.2. Класс сборщика

class XxxCollector:
    source_code = "xxx"          # постоянный ключ каталога; переименовать нельзя
    source_name = "Название"
    auth_type = "none"           # none | bearer | api_key | token
    supported_cities = tuple(city_ids_for("xxx"))   # нет атрибута → только msk
    default_max_pages = DEFAULT_MAX_PAGES           # None = дамп, обходить целиком
    # default_city_workers = 12  # ТОЛЬКО если города — разные хосты
    def collect(self, ctx: CollectContext) -> CollectResult: ...
    def configuration_error(self) -> str | None: ...  # опционально: почему не может работать

CollectContext даёт сборщику: city_code (код продукта), run_key, params (словарь параметров прогона), should_stop() (кооперативная отмена), heartbeat(dict) (признак жизни), flush(items) -> int (сдать собранное в каталог сейчас), known_digests(keys) -> dict (что каталог помнит про отпечатки анонсов). Любой из колбэков может быть None — сборщик обязан работать и без них (прогон из теста или скрипта).

CollectResult: items: list[CatalogUpsert], venues: list[VenueUpsert] (только для справочников площадок, событий из них оркестратор не делает), stats: dict, errors: list[str].

6.3. CatalogUpsert — одна карточка

6.4. Точки регистрации — что править, добавляя источник

Порядок значим только там, где написано.

6.5. Параметры прогона (ctx.params)

Общие имена, которые понимает CLI/UI/волна, и их надо уважать:

Неизвестный/неприменимый параметр не роняет прогон: он попадает в stats.ignored_params (так сделано у timepad).

Читать параметры только через params.param_bool / param_int: "false" и "0" — это False, а 0 — валидное число (int_or_default).

6.6. Статистика прогона (stats)

Обязательные ключи: source, pages, raw_events, normalized, skipped, filtered, filter_reasons (словарь причина → число), needs_geo, mass. Флаги: config_error, cancelled, source_unavailable, transport_error, parse_error, blocked. Диагностика: field_coverage/fields_missing (дрейф контракта), http_requests/http_wait_sec (цена прогона), details_skipped, digest_keys_asked/matched, skipped_samples (образцы отсева, до 5), ignored_params, api_total_by_city.

Правило слияния по городам (runner._merge): bool — ИЛИ, число — сумма, словарь — покомпонентная сумма. Значит, счётчики — числа, признаки — bool, разбивки — словари; строки в stats не сливаются.

errors — только сбои сборщика (сеть, разбор, баги). Брак карточки площадки — это отсев: filter_reasons + skipped_samples, не errors. Иначе волна вечно partial, а тревога дежурному орёт каждые 12 часов (инцидент moibiz 04.09.2026).

6.7. Коды выхода python -m ingestion run

7. Правила поведения сборщика

Нумерация постоянная — на неё можно ссылаться в ревью и карточках. «Обязан» — без этого код не принимается; «должен» — отступление требует причины в докстринге.

Обход и бюджеты

• R-1. Сборщик обязан уважать max_pages и объявлять ABSOLUTE_MAX_PAGES — предохранитель на --full: у площадок next не кончается, а обход в ?archive=y или в карточки, похожие на списки, длился часами (moibiz: 129 334 страницы ради 6436 событий).
• R-2. default_max_pages = None только у дампов, где страницы — не «ещё того же», а части одного набора (data.mos резался с 5529 до 5000).
• R-3. Страница списка — это сам путь списка максимум с /page/N; ссылка «Подробнее »» — не пагинация.
• R-4. Если у площадки есть серверный фильтр по дате — обязан использоваться (leader_id: без dateFrom бюджет уходил в многомесячные программы, начатые давно).
• R-5. Обход останавливается на первой странице без будущих анонсов, если лента упорядочена по дате.

Живость и промежуточные результаты

• R-6. ctx.flush(items) после каждой страницы. Без этого оператор видит работающий сбор и ноль в каталоге, а обрыв теряет всё.
• R-7. ctx.heartbeat({...}) на каждой странице и на каждой долгой фазе (индекс площадок у kassir). Иначе часовой reaper закроет живой прогон.
• R-8. should_stop() проверяется между страницами и перед каждым ожиданием (interruptible_sleep, gated_wait). Отмена прекращает сбор, а не запись.
• R-9. Обход страниц оборачивается в collect_util.drain_event_pages: мягкий сбой (SourceUnavailableError, httpx.HTTPError, ValueError) не теряет уже собранные страницы, ставит флаг в stats и заканчивает честно.

Сбои и отсев

• R-10. Брак одной карточки — NormalizeError → filter_reasons[<причина>] и образец в skipped_samples; страница продолжается.
• R-11. Неожиданное исключение при разборе одной карточки — stats.bugs += 1, строка в errors, страница продолжается (kudago, except Exception).
• R-12. Три таймаута подряд → SourceUnavailableError, не долбить дальше. У opendata_mkrf это норма, а не поломка.
• R-13. Блокировка по IP/гео (403 geoblocked, «restricted access from your IP») — не JS-челлендж: браузер не поможет. Сборщик поднимает свою ошибку → stats.blocked = True, оркестратор паркует источник на 20 часов (config.network_blocked в sources), run выходит с кодом 3. Парковка живёт в базе, не в памяти процесса: cron запускает каждый источник отдельным процессом.
• R-14. Сетевой сбой (DNS, таймаут) парковкой не считается.
• R-15. Нет ключа → configuration_error() возвращает текст; сид паркует источник (needs_credentials) и сам оживляет, когда ключ появится. Сетевых проб из configuration_error не делать (сид держит открытую сессию базы; проба из сида снята 03.09.2026).
• R-16. 404 у детали — PageGoneError: страницу сняли, это не ошибка разбора и не сбой площадки.

Что отсеивается на стороне сборщика

• R-17. Прошедшее — всегда (is_past, future_only=True). Карточка без времени живёт до конца дня.
• R-18. Онлайн — по умолчанию отсев (filter_reasons.online), берётся только по include_online. «Очное участие и ВКС» — очное.
• R-19. Событие с явным маркером другого города/региона у московского источника — отсев out_of_town (collect_util.moscow_address, mentions_other_city), а не «Москва, г. Сочи».
• R-20. Закрытые/внутренние записи (защиты диссертаций у ВШЭ, «запишись в ЛК» без даты у «Моего бизнеса», курсы вместо событий у edtech) — отсев с именованной причиной.
• R-21. Услуга без даты (экскурсия «по запросу», квест, мастер-класс по записи) — не событие; не брать.

Город

• R-22. Код города продукта → идентификатор площадки только через cities.city_ids_for(code); неизвестный город — ValueError со списком известных, не молчаливая Москва.
• R-23. city_code у карточки — код обхода. Пригороды складываются в большой город, адрес и координаты остаются настоящими (ADR 0002). Значение в справочнике может быть кортежем идентификаторов — сборщик обходит все.
• R-24. Ширину default_city_workers выше 4 поднимать только там, где города — разные хосты. Один хост от этого быстрее не станет: темп задаёт общий шлюз.

Даты и время

• R-25. Сеанс хранится с часовым поясом площадки/города (SessionSpec.timezone), сравнение «прошло/будущее» — по aware-датам.
• R-26. Год у даты без года — не «текущий» по умолчанию. Диапазон — от конца (timepad); лента, убывающая по дате, — год от предыдущей карточки (bizassoc). Пометка extras.year_guessed, чтобы оператор видел.
• R-27. «15.10.2026» — не время 15:10; «взнос 12.90» — не время; голое «до 12:00» — срок, не начало. Значения вне суток отбрасываются, не роняют прогон.
• R-28. Серия (один объект на слот, еженедельный старт) — один Event с многими Session; ключ сеанса стабильный.

Место

• R-29. Координаты в сборщике не выдумываются и не геокодируются; это делает каталог (geo backfill по справочнику OSM). Если площадка даёт координаты — отбросить 0,0 и вне диапазона.
• R-30. У площадки с известным адресом (свой офис, парк, кампус) — фиксированные координаты и source_place_id в коде адаптера, не геокод каждой карточки.
• R-31. Адрес московского источника получает «Москва, » первым словом только если в нём нет маркера другого города (moscow_address).
• R-32. Уровень точности геокода не подделывается: extras.geo_source пишет каталог.

Цена, места, формат

• R-33. is_free — только по явному признаку площадки («бесплатно», price is null там, где это документированная семантика). Пустая цена ≠ бесплатно.
• R-34. capacity — места; аудитория сообщества — extras.members_count. format — только classify_format.
• R-35. Форумы, выставки, стадионы, репертуар — format=mass (через категорию-зрелище или large источника), но в каталог — да.

Медиа и тексты

• R-36. Обложка — абсолютный https, с CDN площадки; favicon, логотип площадки, заглушки «изображение отсутствует» не пишутся (all_events.is_placeholder_image, favicon Timepad 196×196).
• R-37. Обложку, которой нет в списке, можно добрать с детали/og:image, но только с allowlist-хостов (защита от SSRF).
• R-38. Описание — как даёт площадка (plain и/или html); заголовок не «улучшать»; чистка только от мусора вёрстки.

Экономия: не ходить за тем, что не менялось

• R-39. Если деталь — отдельный запрос на карточку, сборщик переводится на пропуск неизменившихся деталей целиком: preview_digest по полям списка, known_digests_for(ctx, keys) разом на страницу, пропуск только у анонса с датой, карточка при пропуске всё равно эмитится (last_seen живёт), счётчик details_skipped заведён и растёт, refresh_all = param_bool(...) привязан. Половина механизма опаснее его отсутствия — сторожит test_skip_rollout.
• R-40. Стойкий кэш на диске (detail_cache.py у leader_id/moibiz) — допустимая альтернатива, но с TTL, путём через переменную окружения и выключателем в conftest.

Транспорт и анти-бот

• R-41. Один темп на хост в процессе: любой транспорт (httpx, curl, Playwright, GraphQL) ходит через http_util.host_gate/gated_wait или ThrottledJsonClient/fetch_text. Свой цикл запросов не писать (третья копия уже удалялась в ревью).
• R-42. Браузер — один на прогон, не на запрос; закрывать в finally. Playwright — только когда httpx и системный curl не проходят (лестница afisha), и только с PLAYWRIGHT_BROWSERS_PATH в cron-окружении.
• R-43. Системный curl — законная ступень (Cloudflare режет JA3 CPython), но allowlist хостов обязателен.
• R-44. verify=False — только для конкретного хоста с битым TLS (events.sk.ru), никогда глобально.
• R-45. Браузерный User-Agent + Referer там, где без них soft-block (Хабр отдаёт HTML вместо JSON).

Семейства

• R-46. Несколько сайтов одного рода (ассоциации, центры, парки, библиотеки) — один source_code с адаптерами внутри (Источник-семейство, CONTEXT.md): код нельзя переименовать без потери связей, а сайты приходят и уходят. source_object_id с префиксом адаптера.
• R-47. Разные по природе площадки, которые лишь делят парсер, семейством не делаются.

Стиль

• R-48. Докстринг модуля объясняет «зачем так», комментарий у кода называет инцидент; русский в комментариях, английский в именах; числа — измерения, не оценки. Того, чего нет, не изображать («антифрода нет»).
• R-49. Python 3.12+ (PEP 695 в persist.py). Секреты — только через secrets.resolve_secret; в params прогона не класть (они вырезаются, но не надо и пытаться).

8. Требования к карточке события

Что стенд и лента ждут от карточки, и почему. Всё это проверяется на выходе ui/export.py::_build_card и на стенде; сборщик отвечает за вход.

9. Вежливость и сеть

Лимит принадлежит хосту, а не сборщику и не городу.

Сетевые особенности стенда, о которых надо знать до первого «у меня не открывается»: DNS в контейнерах прибит к 8.8.8.8/1.1.1.1; IPv6 выключен (иначе сайты с AAAA висят 20 с); MTU 1360 на машине разработчика (VPN); подсеть 172.28.0.0/16. Подробности — docs/internal/07 и 11.

Разница адресов: сервер и ноутбук владельца видят разные площадки (mbm.mos.ru закрыт для сервера по IP). Сборщики крутятся на ноутбуке (стек posobytiyam_ingestion_*), salam0nn.ru только пересылает. Любую пробу доступа повторять с обеих машин.

10. Дедупликация: что обязан знать сборщик

Дедуп делает каталог (orchestrator/persist.py::_find_merge_event), но его качество зависит от того, что пришло из сборщика.

Идентичность события: title_norm + city_code + место, сеансы выбирают близнеца. «То же место» = та же строка площадки или та же гео-ячейка (~110×55 м) и то же нормализованное имя площадки. Обе карточки с координатами в разных ячейках — два события, как бы ни совпадали часы. Два разных известных организатора — никогда одно событие.

Что из этого следует для сборщика:

1. source_object_id стабилен между прогонами — иначе каждый прогон заводит новый объект, а старый уходит в архив.
2. venue.source_place_id стабилен и не пустой: без id — ключ из нормализованного адреса. Площадка «Место будет объявлено позднее» с координатами центра города — не площадка (не давать ей координат).
3. organizer.source_org_id — только если это действительно организатор, а не «сайт-источник»: ложный организатор блокирует склейку с другими площадками.
4. Заголовок — как у площадки: «улучшение» заголовка разводит дубли.
5. Серию отдавать одним объектом с сеансами, а не десятком объектов с одинаковым названием (каталог их всё равно склеит, но это лишняя работа и лишние raw_payloads).
6. is_ongoing (постоянная экспозиция, «идёт сейчас») — в extras и в volatile_extras: заявка живёт по объекту источника и отзывается, когда объект перестаёт её присылать.
7. Полевая политика слияния: title — первый непустой; описание — длиннее выигрывает; категории/теги — объединение; цены/capacity — первый ненулевой; координаты/площадка/организатор — правит только первичный источник. Значит, сборщик не должен присылать «пустое, чтобы затереть».

После каждой волны крутится maintenance dedup тем же предикатом; след каждой склейки — event_merge_log. Если новый источник породил волну ложных склеек — смотреть туда, а не в events.

11. Стенд: что нужно дописать, чтобы событие дошло до ленты

Перенос в стенд идёт курсорно до 100 страниц × 200 карточек; события новых площадок имеют самые большие events.id и лежат в хвосте — при «переносе всех» хвост может не доехать (stats.truncated=True). Известная общая проблема; обход — точечный перенос import_catalog(sources=['<code>']). При приёмке нового источника проверять именно это.

Проверка «доехало»: сквозной тест tests/test_wave5_catalog_e2e.py — образец для каждого нового источника (сборщик → run_collector → каталог → _build_card → feed_ready, интересы, площадка с адресом, сеанс, обложка).

12. Тесты

12.1. Что обязательно для нового источника

12.2. Правила

• Никакой сети в тестах. Фикстуры — реальные ответы площадки, снятые один раз в tests/fixtures/<code>_*.json|html, обезличенные, не больше необходимого (одна страница списка + одна-две детали).
• Даты в фикстурах сдвигаются в будущее в тесте (_page() у KudaGo): прибитые даты красят тест через месяц без единой правки кода.
• Тестовая база: имя обязано заканчиваться на _test (TEST_DATABASE_URL=postgresql+psycopg://podushe:podushe@127.0.0.1:5433/podushe_ingestion_test); фикстуры делают alembic downgrade base и TRUNCATE.
• Стойкие кэши и сетевые пробы выключаются в tests/conftest.py (*_DETAIL_CACHE_PATH="", INGESTION_SKIP_PROBES=1).
• Сторожа, которые обязаны остаться зелёными: test_cron_sources_parity, test_city_directory_parity, test_skip_rollout, test_export_sources, tests_dating_tz/test_api_contract.py (стенд), test_live_window_matches_the_feed, test_a_fast_neighbour_cannot_speed_up_a_cautious_host.
• Весь прогон: .venv/bin/python -m pytest -q (1131 тест на 07.09.2026). Перед коммитом — весь, не «свой файл».

12.3. Живой smoke

python -m ingestion run --source <code> --city msk --max-pages 1, затем --city all --max-pages 1 (если городов много), затем docker/verify.sh <code> на стенде. Считать: сколько собрано, сколько отсеяно и почему, сколько needs_geo, есть ли обложки, сколько mass, сколько запросов и секунд ожидания. Эти числа идут в карточку и в docs/internal/03.

13. Разведка площадки: протокол

Разведка — половина работы и отдельный результат: карточка беклога с «паспортом площадки» (приложение Б), даже если вывод — «не делать». Разведка предшествует любому коду.

1. Проверить, что этого ещё нет. Беклог events (все колонки), docs/internal/03, git status рабочей копии на ноутбуке владельца (/home/joda/Projects/ПоСобытиям/plibvi): 03.09.2026 две карточки из трёх оказались уже сделаны в незакоммиченной копии.
2. Проверить пересечение с уже собранным. Название площадки/организатора поискать в каталоге (organizers, venues, консоль → каталог) и на Timepad/KudaGo/Leader-ID/Qtickets. Если ≥ 80 % событий площадки уже приходят оттуда — адаптер не нужен, нужен whitelist (VK) или ничего.
3. Снять поверхность. Для домена: robots.txt, sitemap.xml, RSS/Atom, .ics, JSON-LD (@type: Event — лучший случай), WP REST (/wp-json/wp/v2/, плагины календарей), Bitrix (PAGEN_N, ajax), Tilda (данные в tildacdn/встроенный Timepad), Nuxt/Next (__NUXT__, __NEXT_DATA__, внутренний API из network tab), GraphQL. Вкладка Network браузера при листании и фильтрации даёт больше, чем HTML.
4. Проба доступа с двух адресов: сервер и ноутбук. Коды 403/401/000, DDoS-Guard, QRATOR, Variti, Cloudflare — записать. JS-челлендж и блок по IP — разные вещи: первый обходится браузером, второй — нет.
5. Померить данные на 1–3 страницах: всего записей, доля предстоящих, доля очных, доля с адресом, доля с координатами, доля с картинкой, доля с ценой, есть ли id объекта, стабилен ли URL, формат дат (год есть?), пояс, пагинация (offset/курсор/страница; сортировка по дате?), фильтр по дате на сервере, лимиты (заголовки Retry-After, X-RateLimit-*).
6. Города. Как площадка называет города (слаг, id, поддомен), совпадают ли с нашим справочником, какие есть у неё и нет у нас. Идентификаторы сверять живьём (у KudaGo официальный справочник даёт 5 городов, работают 13; у Leader-ID номера двух городов до сих пор под вопросом).
7. Категории. Полный список рубрик площадки (обходом разделов, если нет иначе) — он целиком пойдёт в CATEGORY_MAP.
8. Оценить объём и цену: событий/неделю предстоящих очных; запросов на полный обход; секунд при вежливом темпе; нужен ли браузер; нужен ли пропуск деталей (деталь = отдельный запрос?).
9. Вывод: делать / не делать / отложить, чем (API/HTML/ICS/RSS/браузер), в какое семейство, какой приоритет, какие решения нужны от владельца. Всё — в карточку, с датой пробы и адресами, с которых пробовали.

Инструменты: curl -sIL, curl -A "Mozilla/5.0 …", Playwright (.venv/bin/playwright install chromium; на сервере бинарь лежит в ~/.cache/ms-playwright/chromium-*/chrome-linux64/chrome), jq, Wayback для мёртвых сайтов (только чтобы понять, что было; не как источник данных).

14. Процесс: от карточки до отчёта

1. Карточка. Одна площадка или одно семейство — одна карточка SRC-* в беклоге events (шаблон — приложение А). Карточка живёт в «В работе» с момента разведки.
2. Разведка (§13) → паспорт в карточке. Если нужны решения владельца (новый город, пригород, семейство или отдельный код, публиковать сразу или оператором, брать ли онлайн, лимит), — вопрос задаётся до кода, списком, с вариантами и рекомендацией. Решение с последствиями на годы (география, идентичность) — ADR в docs/adr/ (формат: Статус, Контекст, Решение, Последствия).
3. Реализация по §6–7, начиная с normalize.py и фикстур: сначала тест на нормализацию, потом клиент, потом сборщик.
4. Регистрация по чек-листу §6.4 (все 17 строк, отмечать в карточке).
5. Тесты §12: весь прогон зелёный, живой smoke по одному городу и по всем.
6. Самопроверка по правилам R-1…R-49 и по «Граблям» (§17). Ревью 03.09.2026 нашло 33 находки за четыре прохода на двух площадках — это норма, не позор; лучше найти самому.
7. Документация: раздел площадки в docs/internal/03 (транспорт, ключи, особенности, измеренные числа, что решено не брать и почему), число источников в 02, строка в ingestion/README.md, запись в docs/CHANGELOG.md, термины в CONTEXT.md.
8. Коммит: один источник — один коммит (правки по ревью — отдельными), сообщение в стиле репозитория: feat(<code>): «Название» — семейство, адаптер X (SRC-XXX), fix(<code>): …, perf(<code>): …, test(<code>): …, docs(…): …. Заголовок по-русски, называет что и почему. Пуш требует проброшенного ssh-агента (SSH_AUTH_SOCK).
9. Выкат на стенд: пересборка образа сборщиков на ноутбуке (./docker/build.sh, код запекается в образ), sources seed, docker/verify.sh <code>, точечный перенос в стенд (import_catalog(sources=['<code>'])), проверка политики источника и карточек в консоли оператора.
10. Наблюдение: дождаться ночной волны (00:17 МСК) и дневной (12:17), прочитать collect_cron.log и collect_status.json: длительность источника (и его место в CRON_SOURCES), errors vs filter_reasons, число записанных, truncated у переноса.
11. Отчёт в карточку и перевод в «Готово»: измеренные числа (собрано / отсеяно по причинам / needs_geo / обложки / mass / длительность / запросов), что не сделано и почему, что решено не брать.

Definition of Done — приложение В.

Что не делать без явного решения владельца: переименовывать source_code; менять общие модули (protocol, runner, persist, http_util, cities) ради одной площадки без ADR/обсуждения; заводить второй путь сбора «на всякий случай» (у Timepad прямо запрещено); подключать платные API и партнёрские фиды; менять политику публикации источника на стенде.

15. Слой Telegram/VK с извлечением через LLM

В чате 24.07 это «самый дорогой в обработке, но безальтернативный источник йоги в парке и православных бесед». Сегодня в проекте есть только vk (события сообществ, без извлечения из текста). Ниже — требования к слою, чтобы разведка и ADR шли по одному списку. До решений владельца по пунктам 1, 2, 7 код не пишется.

1. Реестр каналов — данные, не код. Таблица channel_registry (или JSON в репозитории на первом шаге): канал/паблик, город, район, тематика, кто добавил, дата, активен ли. 200–400 записей по оценке чата. Пополнение — операторская задача, не релиз.
2. Доступ к Telegram. Telethon требует пользовательской сессии (номер, код, 2FA) — как у VK/Добро (.secrets, keepalive). Кто владелец аккаунта, где живёт сессия, что при бане — решение владельца.
3. Извлечение. На каждый пост с признаками даты — запрос к модели со строгой JSON-схемой: title, starts_at (с поясом; год из контекста поста и даты публикации), ends_at, address, venue_name, is_online, price_text, is_free (только по явному слову), organizer, registration_url, confidence. Поля, которых нет в тексте, — null, не догадка. Промпт и схема — в репозитории, с версией; изменение промпта = перепрогон оценочного набора.
4. Оценочный набор: 100–200 размеченных вручную постов (события / не события / поля) в tests/fixtures/tg_eval/; порог приёмки — точность даты и адреса ≥ 90 %, ложных событий ≤ 5 %. Ниже порога — слой не выкатывается.
5. Экономия: извлекать только посты с датой-кандидатом (регулярка), один раз на post_id (кэш по хешу текста), не перечитывать правки без изменения текста; лимит стоимости на волну.
6. Что становится карточкой: source_object_id = "<channel>:<post_id>", source_url — ссылка на пост (t.me/<channel>/<id>), обложка — фото поста (свой CDN-хост в allowlist), raw_payload — текст поста без служебных полей. ПДн: телефоны, личные контакты организаторов из текста в карточку не переносить; сырьё под ретенцией 90 дней; erase по запросу.
7. Публикация: auto_publish=False — каждую карточку смотрит оператор, пока оценочный набор не докажет качество; в карточке extras.llm_extracted с версией промпта и confidence.
8. Дедуп: тот же механизм каталога; ожидается, что половина постов — репосты событий, уже собранных с Timepad/KudaGo; проверять долю склеек.
9. Модель: у проекта уже есть шлюз к модели (раздел «SEO» ходит к Claude через панель на salam0nn.ru); переиспользовать его или завести отдельный ключ — решение владельца. Рестарт панели рвёт и генерацию статей.
10. Наблюдение: в stats — постов прочитано / с датой / отправлено в модель / извлечено / отброшено по confidence / стоимость.

Для VK тот же путь дешевле: wall.get по whitelist пабликов + то же извлечение. Но сначала — расширение whitelist сообществ-событий (карточка 9.1), это без LLM.

16. Операционка и наблюдение

Бюджет длительности нового источника: он не должен становиться самым долгим без причины. Ориентиры медианы (02–04.09.2026): moibiz 6,5 ч (до починки), ticketland 2,5 ч, russpass ~1,7 ч; большинство — минуты. Если полный обход площадки дольше часа — сначала серверный фильтр по дате, пропуск деталей и ABSOLUTE_MAX_PAGES, потом ширина потоков.

17. Известные грабли (короткий список)

Полный свод — docs/internal/11-gotchas.md. Здесь то, на что новый источник наступает чаще всего.

1. page= без _num у Хабра отдаёт архив 2023 года — параметры пагинации сверять с network tab, а не с документацией.
2. У opendata.mkrf данные в нумерованной версии, $last → 404; свежая версия не обязательно непустая.
3. Длинный заголовок переполнял dedup_signature varchar(512) и терял событие целиком — лечится в каталоге, но длину полей помнить (source_org_id 128).
4. Пустая цена ≠ is_free; capacity=0 ≠ «мест нет».
5. Ключ площадки без id — из адреса, не из имени.
6. «Москва, г. Сочи» — маркер чужого города проверять до дописывания города.
7. Год без года: текущий — неверно почти всегда (Опора: 15 призраков из 76).
8. Карточка события, похожая на страницу списка, зацикливает обход (moibiz: 129 334 страницы).
9. Брак карточки в errors красит волну навсегда — только filter_reasons.
10. Проба доступа из configuration_error под открытой сессией базы — нельзя.
11. Парковка в памяти процесса не работает под cron — только в базе.
12. bool в stats складывается как число при слиянии городов — признаки только bool, счётчики только числа.
13. Стойкий кэш деталей ломает изоляцию тестов — выключать в conftest.
14. Обложка площадки не в _IMG_HOST_SUFFIXES — консоль слепа.
15. Категории источника не в CATEGORY_MAP — feed_ready=False навсегда.
16. Перенос в стенд обрезается на 20 000 карточках — новый источник в хвосте.
17. Playwright в cron без PLAYWRIGHT_BROWSERS_PATH — «Executable doesn't exist».
18. curl — жёсткая зависимость образа (JA3), не удобство отладки.
19. Сессия SQLAlchemy не потокобезопасна — свои сессии на поток города делает оркестратор; в сборщике базы нет вообще.
20. verify=False глобально — никогда.

18. Открытые вопросы к владельцу

1. Партнёрские фиды билетных операторов (Ticketscloud, Qtickets, Radario): парсеры уже есть; нужен ли партнёрский API ради комиссии (фаза 3 в чате 24.07)? Если да — карточка SRC-TICKETSCLOUD оживает как интеграция, а не парсер.
2. PRO.Культура.РФ: партнёрский ключ с обязательством выгружать все события региона за 2 суток — брать или остаёмся на открытых данных МКРФ?
3. Telegram-слой: аккаунт для Telethon, модель и бюджет на извлечение, кто ведёт реестр каналов (§15, пункты 1, 2, 7, 9).
4. Московское долголетие (55+): расширять ли возрастной сегмент.
5. Онлайн-события: сейчас отсев везде; нужен ли отдельный раздел «онлайн» на витрине (тогда include_online по умолчанию у части источников).
6. Leader-ID: номера Тулы и Ярославля (1227359/1265352 против 1283537/1299162) — сверить живьём и оставить один; placeIds[].
7. Перенос в стенд: чинить обрезку курсора (общая проблема) до подключения новых источников или продолжать точечные переносы.
8. Порядок волн 6–9 (§4) — утвердить или переставить.
9. Регионы: какие города продукт открывает первыми после Москвы (это определяет, где расширять supported_cities).
10. Незакоммиченные правки от 04.09.2026 (порядок CRON_SOURCES, default_city_workers) — закоммитить до начала работы сотрудника.

19. Приложения

А. Шаблон карточки беклога SRC-*

Заголовок: Collector: <Площадка> (<домен>)
Приоритет: high | normal | low
Why (одной фразой): что даёт продукту и почему сейчас.

## Цель
Что собираем (тип событий, города), чего не собираем.

## Разведка <дата>, с <сервер | ноутбук>
Таблица: поверхность | факт (код, движок, разметка, пагинация, лимит, id, даты, гео, картинки).
Пересечения с уже собранным (что и какая доля).
Категории площадки (полный список).

## Как парсить
Транспорт, адаптер/семейство, source_object_id, source_url, площадка и гео,
пропуск деталей, ABSOLUTE_MAX_PAGES, темп.

## Фильтры
Что отсеиваем и под каким именем в filter_reasons.

## Риски
Анти-бот, нестабильность, дубли, ПДн.

## Решения владельца
Список вопросов → ответ, дата.

## Приёмка
- [ ] чек-лист §6.4 (17 пунктов)
- [ ] тесты §12
- [ ] smoke msk / all
- [ ] docs/internal/03, README, CHANGELOG
- [ ] стенд: политика, интересы, CDN, перенос
- [ ] волна: длительность, errors=0, отчёт числами

Б. Паспорт площадки (заполняется при разведке)

В. Definition of Done для источника

• [ ] Карточка с разведкой и решениями; ADR, если решение на годы.
• [ ] Код по §6–7; докстринги с «зачем»; никаких вторых путей.
• [ ] Все 17 точек регистрации §6.4.
• [ ] Тесты §12.1, фикстуры без сети, даты сдвигаются; весь прогон зелёный.
• [ ] Smoke по одному городу и по всем; числа записаны.
• [ ] Стенд: политика источника, интересы для всех категорий, CDN в allowlist, точечный перенос, карточка видна в консоли с обложкой и адресом.
• [ ] Прошла хотя бы одна ночная и одна дневная волна: errors пусты или объяснены, длительность известна, место в CRON_SOURCES по времени.
• [ ] docs/internal/03, 02, README, CHANGELOG, CONTEXT.md.
• [ ] Коммит(ы) с сообщением по стилю; карточка в «Готово» с отчётом.

Г. Команды

# окружение
.venv/bin/pip install -r requirements.txt
.venv/bin/playwright install chromium
.venv/bin/alembic upgrade head
.venv/bin/python -m ingestion sources seed

# сбор
python -m ingestion run --source <code> --city msk --max-pages 1
python -m ingestion run --source <code> --city all --max-pages 1
python -m ingestion run --source <code> --city msk --full --refresh-all
python -m ingestion status
python -m ingestion ui            # http://127.0.0.1:8765/

# тесты
TEST_DATABASE_URL=postgresql+psycopg://podushe:podushe@127.0.0.1:5433/podushe_ingestion_test \
  .venv/bin/python -m pytest -q
.venv/bin/python -m pytest -q tests/test_<code>_collector.py tests/test_cron_sources_parity.py tests/test_skip_rollout.py

# стенд (ноутбук владельца)
./docker/build.sh
docker compose exec app /app/docker/verify.sh <code>
docker compose exec app /app/docker/collect-all.sh --dry-run
docker compose exec app cat /app/state/collect_status.json
tail -f logs/collect_cron.log

Д. Откуда взят реестр площадок

Чат владельца от 24.07.2026 «Сервис мероприятий» — два ответа: тиры 1–4 с правовыми и архитектурными требованиями, затем полный реестр из 16 разделов по просьбе «максимально полный список, от афиш концертов до простых локальных прогулок». Разделы 3.1–3.16 этого документа повторяют структуру реестра один к одному; ни одна площадка из чата не пропущена, к каждой добавлен статус на 07.09.2026 и результат пробы с сервера.