houseplan-card/docs/specs/008-vacuum-support-docs-xcme-hint.md

ТЗ #8 — Матрица поддержки пылесосов и подсказка XCME

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

Цель

Пользователь должен до настройки понимать фактическое покрытие интеграции, а при найденной Xiaomi Cloud Map Extractor без нужных атрибутов — видеть точную инструкцию вместо общего «источник не найден».

Документация

В docs/VACUUM.md, пользовательском руководстве и обзорном README должна быть одна непротиворечивая матрица:

Семейство	Position	Rooms/auto-fit	Integration path	Map id	Discovery
XCME	при включённых attributes	да	да, включая subpaths	map_name при наличии	явный picker допустим
Dreame/Mova	да	да, x/y anchor	нет в Stage 1	selected_map fallback	same-device
Valetudo camera	да	при outline rooms	нет в Stage 1	обычно default	same-device
Roomba string pose	Stage 2	нет room fit	нет	—	Stage 2

Диагностика и подсказка

1. Диалог показывает source, integration/platform, статус, position, rooms, совпадения имён, path и map id.
2. Registry-confirmed same-device XCME с отсутствующей position показывает hint независимо от того, выбран ли этот source.
3. Явно выбранная camera без position также показывает hint.
4. Глобальная невыбранная camera не должна случайно активировать подсказку для другого устройства.
5. Hint содержит готовый YAML-фрагмент vacuum_position, rooms, path, map_name и ссылку на документацию.
6. Documentation action видим при любом source status, включая missing.

Локализация и доступность

• Весь текст ru/en; YAML не переводится.
• Hint имеет текстовый заголовок, код можно выделить, ссылка открывается в новой вкладке с noopener.
• Capability не сообщается только цветом.

Приёмка

• новый пользователь XCME получает конкретный путь исправления;
• матрица не обещает неподдерживаемый path;
• диагностика и реальная доступность auto-calibration используют один matcher;
• ссылки и термины одинаковы в README/User Guide/VACUUM.