2026-03-20 — Выделение оркестратора и onboarding-подсказки

20 марта стало самым крупным днём внутреннего рефакторинга со времён перехода на архитектуру v2 — и при этом дало результаты, видимые операторам. К концу дня runtime получил выделенный bridge orchestrator, lifecycle state machine, device registry и слой config validation. Поверх этого операторы получили onboarding-чеклист, recovery assistant и переработанную поверхность диагностики. Двадцать семь RC-релизов и два стабильных тега прошли через pipeline.

Что было сделано

Выделение bridge orchestrator

Ключевая логика координации, ранее живущая внутри sendspin_client.py, была выделена в отдельный модуль bridge_orchestrator.py. Это стало кульминацией разделения модулей services/, которое также отделило device registry, lifecycle state, status snapshot и event publishing.

Выделение было важным, потому что монолитный client-класс разросся за разумные рамки для одного модуля. С оркестратором, владеющим последовательностью запуска, переходами lifecycle устройств и координацией между устройствами, оставшийся SendspinClient стал per-device обёрткой подпроцесса с гораздо более узкой поверхностью.

Lifecycle state machine и device registry

Каждое устройство теперь проходит через явные lifecycle-состояния вместо того, чтобы полагаться на ad-hoc флаги статуса. Device registry отслеживает все известные устройства и их текущие lifecycle-позиции, позволяя другим модулям — диагностике, onboarding, recovery — запрашивать состояние устройства, не проникая в internals подпроцессов.

Это также сделало status snapshot’ы надёжнее. Вместо копирования мутабельных dict’ов в произвольные моменты, snapshot’ы теперь строятся из стабильного представления каждого устройства в registry.

Endpoint валидации конфигурации

Новый слой валидации проверяет payload’ы конфигурации до их сохранения. Это ловит типичные ошибки операторов — дублирование портов, невалидный формат MAC, отсутствующие обязательные поля — до того, как bridge перезапустится с поломанным конфигом. Endpoint валидации используется flow сохранения веб-интерфейса и может также вызываться напрямую из скриптов или автоматизаций.

Onboarding-чеклист и recovery assistant

Операторский слой получил два взаимодополняющих инструмента:

• Onboarding-чеклист — пошаговый guidance flow для новых установок, который проводит операторов через Bluetooth-пейринг, подключение Music Assistant и верификацию первого воспроизведения. Он остаётся доступным из шапки и отслеживает завершение шагов на основе реального состояния устройств и MA.
• Recovery assistant — предлагает actionable-рекомендации, когда что-то идёт не так: отключённые колонки, неудачные MA-подключения, устаревшие конфиги. Вместо вывалки сырой диагностики он предлагает конкретные следующие действия.

Переработка диагностики

Поверхность диагностики была разделена на простую панель Overview для ежедневного использования и расширенное представление Advanced diagnostics для экспертного траблшутинга. Per-section хелперы копирования и разворачиваемые детали raw payload заменили прежний подход «стена JSON». Это сделало диагностику пригодной для операторов, которые не читают логи подпроцессов.

Компактная дизайн-система UI

Весь dashboard перешёл на единообразный компактный дизайн-язык. Карточки воспроизведения в grid-view теперь используют более крупные превью album-art, а общая система action/badge/chip заменила разрозненные локальные CSS override’ы. Эта волна визуальной согласованности затронула экран логина, guidance-поверхности, notices, панели конфигурации и элементы управления медиа-транспортом.

Обновление CI и demo (v2.40.6)

День начался со стабильного релиза 2.40.6, который закрыл изменения CI release workflow предыдущей волны, обновления demo fixture’ов, controls для авторежима темы и улучшения async-потоков MA. Этот стабильный тег обеспечил чистую базовую точку для последовавшей работы по выделению оркестратора.

Почему это важно

v2.42.1 стал первым стабильным релизом, в котором внутренняя архитектура bridge соответствовала сложности того, что операторы реально с ним делали. Оркестратор, registry и lifecycle-слои дали runtime фундамент, на котором более поздние функции — метаданные комнат, режим standby, ужесточение безопасности — могли строиться без дальнейшей хирургии монолита.

Слои onboarding и recovery изменили отношения проекта с операторами. Вместо ожидания, что все будут читать логи и редактировать JSON, bridge теперь встречает новых пользователей guidance’ом и предлагает опытным операторам recovery-действия, когда что-то ломается.

Что дальше

Эта запись — базовая точка для доработок scan modal и guidance, вышедших на следующий день, а также для метаданных комнат и интеграции с HA area registry, последовавших позже на той же неделе.