houseplan-card/docs/specs/027-vacuum-external-source-picker.md

ТЗ #27 — Явный выбор внешнего vacuum source

• Issue: https://github.com/Matysh/houseplan-card/issues/27
• Приоритет: P1
• Статус ТЗ: реализовано по HP-VAC-02 rev.7; целевой gate v1.61.0-beta.1 пройден, ожидается публикация
• Родительский контракт: HP-VAC-02 §4.4–4.5

Цель

Позволить связать YAML/registry-less камеру XCME, которая не имеет DeviceInfo связи с vacuum device, без угадывания и последующего silent rebind.

Resolver

1. Единственный pure resolver возвращает {entityId, status, pinned, candidates} и используется renderer, dialog, fit, diagnostics и trail UI.
2. Сохранённый marker.vacuum.source sticky при ok, unsupported, unavailable, disabled, unverified и missing; автоматическая замена запрещена.
3. Automatic mode рассматривает только position-capable сущности того же HA device; глобальные камеры никогда не выбираются автоматически.
4. Порядок кандидатов детерминирован: capability score, camera выше прочего, затем entity_id; выбранный source всегда видим первым.
5. missing допустим только при авторитетном доказательстве. Незаполненный status pure resolver трактует как unverified.

Picker

• Основной список: automatic, same-device candidates и сохранённый source.
• «Все камеры» закрыт по умолчанию и сканирует camera.* только при открытии.
• Глобальный список — snapshot на одно открытие; HA ticks не перепарсивают его.
• Повторное открытие делает новый snapshot; новый dialog не наследует старый.
• Каждый кандидат показывает имя, entity id, integration и capabilities.
• Missing/disabled/unverified banner содержит собственную кнопку выбора.
• Выбор first-use source немедленно перестраивает devices; ожидание следующего HA tick запрещено.

Эдж-кейсы

• source удалён/переименован; registry ограничен правами; state unavailable;
• camera без position, но с rooms/path; несколько одинаково подходящих камер;
• первый edit ещё не материализовал marker; dialog закрыт во время scan;
• два экземпляра карточки не делят UI snapshot.

Приёмка

• внешняя XCME камера выбирается и сохраняется с первого клика;
• reload не меняет выбранный source;
• missing source остаётся видимым и исправимым;
• глобальный scan ленивый и не влияет на автоматический resolver;
• источник одинаков во всех vacuum consumers.