Очередь событий вместо словаря: как спасти архитектуру

От очереди событий к стабильной архитектуре: как мы чинили _fix_headings в trend-analysis

Есть у нас проект trend-analysis — сервис, который анализирует тренды и работает с длинными асинхронными операциями. Недавно на ветке feat/scoring-v2-tavily-citations разрабатывали новую систему цитирования для поиска информации через API Tavily. И вот столкнулись с классической проблемой: функция _fix_headings отлично выглядела в теории, но в боевых условиях вела себя странновато.

Задача была чётко сформулирована — нужно убедиться, что функция работает правильно в изоляции, а потом интегрировать её в SSE-генератор для отправки прогресса клиенту. Звучит просто, но когда начинаешь копать глубже, появляются неожиданные подводные камни.

Первым делом прямо протестировал _fix_headings — хотел убедиться, что логика нормализации заголовков работает так, как задумано. Потом понял, что архитектура прогресса была криво спроектирована. Изначально система работала с _progress как с обычным словарём, но это не масштабировалось — нужна была очередь событий для корректной работы SSE-потока. Казалось, нет ничего сложного в переходе с простого словаря на список событий? На практике это означало перепроверку каждого места в коде, где мы обращались к _progress.

Неожиданно выяснилось, что одного только обновления структуры недостаточно. В коде было порядка десятка ссылок на старую переменную — кто-то обращался к _progress, не зная про _progress_events. Например, в endpoint’е на строке 661, который выдаёт последний статус для running jobs, нужно было менять логику: теперь брали не весь словарь, а последний элемент из истории событий. Это критично для получения актуального состояния операции.

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

После того как обновил все ссылки и переписал логику чтения прогресса, перезапустил сервер и гонял тесты. _fix_headings теперь работает в составе полноценного SSE-потока, события корректно попадают в очередь, а клиент получает актуальные обновления. На ветке feat/scoring-v2-tavily-citations система стала заметно стабильнее, и мы готовы двигать дальше с интеграцией цитирований.

Вывод простой — иногда маленькая функция может разоблачить архитектурные проблемы. Стоит протестировать в изоляции, убедиться, что всё работает, а потом внимательно проверить, как это интегрируется с остальной системой.