houseplan-card/docs/specs/029-device-inbox-lifecycle.md

ТЗ #29 — единый каталог и жизненный цикл устройств

• Issue: https://github.com/Matysh/houseplan-card/issues/29
• Приоритет: P1
• Тип: feature
• Трек: обычный
• Связано: #44 (настройки discovery), #109 (поиск каналов устройства), #126 (смена HA area), #262 (возврат exact entity после удаления device)

1. Сценарий

Персона: администратор дома из docs/SCOPE.md.

Поверхность: полный houseplan-card, desktop-first редактор устройств.

Момент: пользователь добавил, скрыл или удалил устройства, Home Assistant обнаружил новые или деактивировал существующие, и теперь нужно понять, какие объекты представлены на плане и что с каждым из них можно сделать.

2. Что человек увидит до и после

До: в панели отдельно находятся «Добавить» и «Скрытые и деактивированные»; они позволяют выполнить операцию, но не дают единой картины и не объясняют, почему конкретного устройства нет на плане.

После: одна кнопка «Устройства» открывает каталог всех относящихся к плану HA-привязок с поиском, понятной категорией, причиной текущего состояния и доступным следующим действием; автоматически появившееся устройство уже считается находящимся на плане и отдельно помечается как новое.

3. Проблема

Текущая реализация уже поддерживает несколько устойчивых состояний:

• автоматически отображаемое устройство без сохранённого marker;
• явный видимый marker;
• пользовательски или автоматически скрытый hidden:true marker;
• временно неактивную HA-привязку (ha_disabled, orphaned, unverified);
• удалённую exact binding с removed:true, которую можно добавить заново;
• отдельную entity:X, возвращённую из-под tombstone родителя device:D.

Эти состояния обслуживаются разными UI-путями и не образуют объяснимого каталога. Пользователь вынужден помнить разницу между скрытием, удалением, деактивацией в HA, фильтрацией и автоматическим появлением. В результате одинаковое отсутствие значка визуально выглядит как несколько разных причин, а поиск уже размещённого устройства возможен только глазами на плане.

Старое ТЗ от 9 августа дополнительно считало любую binding без marker «новой». Это расходится с текущим zero-config поведением: автообнаруженное устройство в привязанной HA area уже рисуется без marker.

4. Цель и метрики результата

Создать одну read-only при открытии проекцию lifecycle, которая использует существующие данные и действия, а не вводит второй источник истины.

Результат считается достигнутым, если:

1. для каждой включённой в каталог exact binding существует ровно одна базовая категория;
2. каталог отличает пользовательское намерение от временного статуса HA;
3. открытие, поиск, смена вкладки и просмотр причины не меняют config, layout и их revisions;
4. все существующие операции — найти, настроить, добавить, показать и добавить заново — доступны из одной поверхности;
5. текущая автоматическая раскладка, tombstones, exact entity ownership и фильтрация не меняют семантику.

5. Скоуп

Входит:

• единый каталог в редакторе устройств;
• pure resolver строк каталога;
• категории, статусы, причины, счётчики и поиск;
• действия над одной строкой;
• возврат из существующего диалога устройства обратно в каталог;
• локальное выделение найденного marker на плане;
• desktop, узкая responsive-компоновка без горизонтального скролла, keyboard navigation;
• RU/EN i18n, unit/smoke/golden, пользовательская и каноническая документация.

6. Не входит

• изменение правил автоматического discovery, группировки света и списка исключённых интеграций — это #44;
• управление HA registry: активация, деактивация, переименование или смена area;
• автоматический перенос marker при смене HA area — это #126;
• исправление отсутствующих каналов конкретного multi-channel устройства — #109;
• bulk hide/show/delete/add;
• история устройств, графики и статистика;
• добавление виртуальных markers в lifecycle-каталог: они не имеют HA binding и остаются редактируемыми кликом на плане;
• гарантированная полнофункциональность редактора на touch по docs/TOUCH-SUPPORT.md.

7. Термины и две независимые оси

7.1 Exact binding

Ключ строки — точная привязка device:<device_id> либо entity:<entity_id>. device:D и entity:X, принадлежащая D, являются разными ключами и могут осознанно сосуществовать. Семейство HA device не является единицей дедупликации.

7.2 Базовая категория — пользовательское намерение

Категория	Условие	Смысл
on_plan — «На плане»	Binding представлена runtime-устройством на плане либо живым marker с hidden !== true	Объект уже принадлежит плану. Отсутствие сохранённого marker не делает автоустройство «не добавленным»
available — «Доступны»	Активная допустимая binding не представлена runtime-устройством, живым marker или tombstone	Её можно добавить впервые
hidden — «Скрытые»	Живой marker имеет hidden:true	Объект сохранён, но пользовательское намерение — не показывать его
readd — «Доступны снова»	Exact binding имеет removed:true и её существование сейчас подтверждено	Объект был удалён с плана и может быть создан заново

Приоритет категорий для одного exact key:

removed → hidden → on_plan → available.

Живой exact marker перекрывает tombstone той же exact binding. Tombstone родителя device:D не перекрывает живую entity:X, и наоборот, согласно #262.

7.3 Операционный статус — состояние Home Assistant

Статус накладывается на категорию и не переносит строку между вкладками:

Статус	Источник	Поведение
active	HaBindingStatus.kind === 'active' либо положительное доказательство для нового кандидата	Доступны обычные действия категории
ha_disabled	Авторитетный registry подтверждает деактивацию	Строка помечена «Отключено в Home Assistant»; показать, добавить и выполнить Find нельзя
orphaned	Авторитетный registry подтверждает отсутствие сохранённой binding	Строка сохраняет свою базовую категорию, получает предупреждение и безопасные действия Edit/Delete
unverified	Registry недоступен или ограничен	Нельзя делать отрицательный вывод; строка не объявляется удалённой или деактивированной

Пример: сохранённый видимый marker, который позже деактивировали в HA, остаётся в «На плане», но строка сообщает, что сейчас он временно не показывается. hidden:true + HA-disabled остаётся в «Скрытые» и показывает обе причины.

8. Состав каталога

Pure resolver строит детерминированный snapshot из:

• runtime _devices;
• config.markers;
• settings.new_device_ids;
• авторитетного или ограниченного HA registry snapshot;
• live states и текущей проекции доступности;
• действующих product filters и synthetic light groups;
• связей HA area → пространство/комната.

Кандидаты собираются из того же источника и по тем же eligibility-правилам, что текущий Add picker. Нельзя поддерживать отдельную, постепенно расходящуюся копию правил.

Виртуальные markers исключаются. Tombstone без положительного доказательства, что exact binding снова существует, не показывается как «Доступно снова». Limited registry никогда не превращает неизвестность в ha_disabled, orphaned или readd.

8.1 Entity-уровень

• Уже размещённые entity:* markers всегда присутствуют в каталоге.
• В категории «Доступны» individual child entities показываются после включения фильтра «Показывать сущности», как в текущем Add dialog.
• Поиск выполняется по полному индексу и может найти exact entity независимо от её позиции после первых 200 элементов; hard cap до фильтрации запрещён.
• Явные device:D и entity:X не скрывают друг друга из каталога. Residual automatic parent продолжает строиться по текущему контракту buildDevices.

8.2 Признак «Новое»

settings.new_device_ids остаётся единственным серверным источником этого признака.

• Автоматически появившееся и уже видимое устройство находится в «На плане» и получает badge/фильтр «Новое».
• Открытие каталога и действие Find не подтверждают новизну.
• Открытие существующего диалога настройки через Edit подтверждает новизну по текущему контракту.
• Первично отфильтрованный скрытый кандидат не получает badge, как и сегодня.

9. Причины и объяснения

Строка может иметь одну основную lifecycle-причину и дополнительные статусы. В UI используются локализованные сообщения, не внутренние regex или raw id.

Stable reason enum:

• visible_auto — найдено автоматически и уже находится на плане;
• visible_explicit — добавлено или настроено явно;
• manual_hidden — скрыто пользователем;
• automatic_hidden — скрыто автоматически, точная историческая причина не доказуема;
• service_entry;
• excluded_integration;
• excluded_domain;
• grouped_light / represented_by_parent;
• removed;
• no_bound_room — доступно, но HA area не связана с комнатой плана;
• ha_disabled_device, ha_disabled_entity, ha_disabled_all_entities;
• orphaned_device, orphaned_entity;
• registry_unavailable.

duplicate_name_area удаляется из старого ТЗ: совпадающие имена сейчас нумеруются, а не скрываются.

Если точную причину старого seed-marker нельзя доказать по текущему registry и правилам, показывается честное «Скрыто автоматически». Новое поле с исторической причиной в config не добавляется.

Raw binding и диагностические детали допускаются в раскрываемой строке «Технические сведения» и копируются отдельно; они не заменяют пользовательское объяснение.

10. UX

10.1 Панель редактора

• Кнопки «Добавить» и «Скрытые и деактивированные» заменяются одной кнопкой «Устройства» с иконкой списка/устройств.
• «Правила иконок» остаётся отдельной кнопкой.
• Существующий локальный режим показа скрытых и HA-disabled markers призраками на плане сохраняется, включая их реальную позицию, выбор, настройку и перетаскивание. Его переключатель переносится с основной панели внутрь каталога; это не persisted-настройка и не меняет marker.hidden.
• После закрытия каталога выбранный локальный режим действует до выхода из редактора устройств, как сегодня. При повторном входе в редактор он выключен; кнопка «Устройства» показывает активное состояние, чтобы режим не был скрыт от пользователя.

10.2 Диалог

Используется wide hp-dialog с заголовком «Устройства на плане».

Верхняя область:

1. поле поиска с initial focus;
2. действие «Добавить виртуальное устройство»;
3. вкладки/фильтры со счётчиками:
   • На плане;
   • Доступны;
   • Скрытые;
   • Доступны снова;
4. дополнительный фильтр «Новые» для «На плане»;
5. «Показывать сущности» для «Доступны»;
6. локальный switch «Показывать скрытые на плане». Он доступен во всех вкладках, включает существующий ghost-render скрытых и HA-disabled markers и ничего не сохраняет в config/layout сам по себе.

Строка содержит:

• текущую иконку;
• пользовательское имя;
• тип «Устройство»/«Сущность»;
• пространство и комнату, если известны;
• интеграцию/модель, если известны;
• badge «Новое» и operational status;
• одну короткую причину;
• primary action и меню дополнительных действий.

Поиск регистронезависим и работает по имени, модели, интеграции, названию пространства/комнаты, entity_id и exact binding. Сначала фильтруется полный snapshot, затем применяется progressive rendering. Первые 100 строк выводятся сразу, остальные — кнопкой «Показать ещё» порциями по 100; счётчики всегда относятся к полному результату.

Пустое состояние каждой вкладки объясняет, что сюда попадает и какое действие может изменить результат.

10.3 Действия строк

Категория/статус	Primary	Дополнительные действия
На плане, реально отображается	Найти на плане	Настроить, Скрыть
На плане, временно не отображается из-за HA status	Настроить	Найти призрак при включённом ghost-режиме; Открыть в HA; Удалить через существующий dialog
Скрытые, active	Показать	Найти призрак при включённом ghost-режиме; Настроить
Скрытые, HA-disabled	Настроить	Найти призрак при включённом ghost-режиме; Открыть в HA; «Показать» disabled с объяснением
Доступны	Добавить	Скрыть из списка
Доступны снова	Добавить заново	—

Hide/Show — обратимые одиночные действия без подтверждения, как текущий флаг скрытия. Delete остаётся только в существующем диалоге и сохраняет текущее подтверждение. Add/Re-add не сохраняют объект немедленно: они открывают существующий device dialog с preselected exact binding; Cancel ничего не пишет.

«Скрыть из списка» материализует обычный hidden:true exact marker и переносит строку в «Скрытые». Это не tombstone и всегда обратимо.

10.4 Find и возврат из настройки

Find:

• доступен для обычного marker, если тот реально отрисовывается, и для hidden/HA-disabled marker, если включён локальный ghost-режим; в противном случае действие disabled и объясняет, что сначала надо включить «Показывать скрытые на плане»;
• переключает пространство при необходимости;
• закрывает каталог;
• перемещает viewport так, чтобы marker оказался внутри безопасной центральной области, не меняя zoom без необходимости;
• выделяет marker существующим selection style и дополнительным конечным акцентом не дольше 1,5 секунды;
• не открывает карточку, не выполняет tap action и не подтверждает badge «Новое».

Add/Edit/Show через существующий device dialog временно заменяют каталог. Cancel или Save возвращают пользователя в тот же tab/search/filter и к той же логической строке; snapshot пересчитывается. После удаления открывается обновлённая категория «Доступны снова», если binding подтверждена HA.

Registry/config refresh при открытом каталоге обновляет строки и счётчики, но не сбрасывает tab/search/filter. Открытый device dialog не закрывается из-за refresh; результат применяется после возврата.

11. Модель данных, сохранение и конкуренция

Новых persisted-полей и версии модели нет.

• Категория, статус, reason и состояние UI вычисляются в памяти.
• Tab, search, entity/new filters, progressive limit, scroll anchor и returnToInbox — локальное состояние текущего экземпляра карточки и не переживают reload.
• Hide/Show используют существующий marker.hidden.
• Delete/Re-add используют существующий marker.removed и текущую очистку layout/files/trails.
• New badge использует settings.new_device_ids без смены формата.
• Любая mutation проходит существующий config revision/expected-rev путь. Конфликт не создаёт дубликат: карточка перечитывает snapshot, сохраняет tab/search и показывает локализованный toast.
• Открытие каталога, Find, поиск, смена вкладки, раскрытие причины и Show more не вызывают _saveConfig, layout update или acknowledgement.

Существующий filter_seeded остаётся compatibility-механизмом. Если старый config материализуется при входе редактирующего клиента, это отдельная идемпотентная миграция текущего продукта; каталог не инициирует и не маскирует её как пользовательское действие.

12. Архитектурный контракт

Новый pure-модуль (рабочее имя src/device-inbox.ts) владеет:

• DeviceInboxRow, category/status/reason enums;
• сборкой и дедупликацией exact bindings;
• capability flags действий;
• поисковым индексом и стабильной сортировкой.

Он не импортирует Lit, не пишет config и не выполняет service calls.

Eligibility новых bindings обязана использовать общий helper текущего Add picker. В ходе реализации общая логика извлекается из houseplan-card.ts::_bindingCandidates; две независимые реализации запрещены.

Стабильная сортировка внутри вкладки:

1. new;
2. blocking operational status;
3. localized display name;
4. exact binding как tie-breaker.

Runtime complexity: O(devices + entities + markers) на snapshot плюс O(rows) на поиск. Нельзя для каждой строки повторно обходить все registry entities. Результат memoize по config epoch, registry revision, device roster signature, new ids и UI entity filter.

13. Доступность и responsive

• hp-dialog сохраняет focus trap и restore focus.
• Search получает initial focus; Escape закрывает dialog.
• Tabs имеют role=tablist, выбранная вкладка — aria-selected; стрелки переключают вкладки.
• Строка и каждое действие достижимы Tab; icon-only действия имеют aria-label.
• Изменение результатов поиска объявляется ненавязчивым aria-live=polite.
• На узкой ширине метаданные переносятся под имя, действия не создают горизонтальный скролл.
• View/киоск не меняются. Редактор на touch остаётся best effort; каталог не должен ломать pinch/pan View и не добавляет gestures на сам план.

14. i18n

Новые ключи создаются одновременно в src/i18n/en.json и src/i18n/ru.json для:

• кнопки и заголовка каталога;
• четырёх вкладок, счётчиков и empty states;
• search, Show entities, New, Show more;
• Add virtual, Find, Edit, Hide, Show, Hide from list, Add, Re-add;
• всех reason/status из §9;
• unavailable action hints, refresh/conflict toast и accessibility labels.

Существующий marker.hide_tip в обоих языках обновляется: вместо удаляемой кнопки «Скрытые и деактивированные» он направляет в каталог «Устройства». Перед реализацией выполняется поиск остальных ссылок на старые названия кнопок; пользовательские строки не должны вести к отсутствующему UI.

Имена integration/model/binding не переводятся. Формулировки интерфейса синхронизируются с RU/EN user guide.

15. Критерии приёмки

AC1 — единая точка входа (golden + smoke)

В Device editor вместо двух кнопок Add/Show hidden отображается одна кнопка «Устройства»; она открывает каталог с четырьмя категориями, поиском и счётчиками. Локальный ghost-toggle доступен внутри каталога, а его активность видна на кнопке «Устройства». «Правила иконок» остаётся доступной.

AC2 — детерминированная классификация (unit)

Матрица покрывает auto no-marker, explicit visible, manual/automatic hidden, HA-disabled, orphaned, unverified, removed active, removed missing, device-parent tombstone + live entity child, synthetic light group и candidate без bound room. Каждая включённая exact binding находится ровно в одной базовой категории.

AC3 — принятое правило auto/new (unit + smoke)

Автообнаруженное уже видимое устройство без marker находится в «На плане» и получает «Новое», если его runtime id есть в new_device_ids. Открытие каталога и Find badge не снимают; Edit снимает по текущему контракту.

AC4 — lifecycle и HA status независимы (unit)

hidden:true + ha_disabled остаётся в «Скрытые» с двумя объяснениями; hidden:false + ha_disabled остаётся в «На плане»: Show недоступен, а Find доступен только для призрака при включённом ghost-режиме. Limited registry не создаёт ложный disabled/orphaned/readd.

AC5 — exact binding и повторное добавление (unit + smoke)

device:D tombstone и живой entity:X образуют две корректные строки. Re-add exact binding заменяет только её tombstone, не создаёт дубликат, не возвращает старую позицию/файлы/trail и сохраняет соседний parent/child lifecycle.

AC6 — действия используют существующие транзакции (smoke)

Find, Edit, Hide, Show, Add, Hide from list и Re-add дают результат §10.3. Cancel из Add/Re-add не меняет данные; Delete остаётся подтверждаемым действием существующего dialog.

Переключатель ghost-режима внутри каталога воспроизводит текущий локальный показ hidden и HA-disabled markers: после закрытия каталога их можно найти, выбрать, настроить и перетащить без изменения marker.hidden; выход из редактора сбрасывает режим.

AC7 — read-only открытие (unit + smoke)

Snapshot config, layout и обе revisions до/после открытия, поиска, tab switch, reason expand, Show more и Find идентичны. Ни один из этих путей не вызывает config/layout websocket write.

AC8 — возврат и live refresh (smoke)

После Edit/Save/Cancel каталог возвращается с прежними tab/search/filter и логическим scroll anchor. Registry/config refresh пересчитывает строку без закрытия открытого device dialog и без дубликатов.

AC9 — поиск и большие реестры (unit + smoke)

Поиск находит строку по каждому полю §10.2, включая entity за пределом первых 200 исходных записей. Progressive rendering не меняет total counts и не приводит к вложенному полному обходу registry на каждую строку.

AC10 — accessibility/responsive (smoke + golden + review)

Диалог работает с клавиатуры, восстанавливает focus, не имеет горизонтального скролла на narrow fixture и корректен в RU/EN и light/dark. Touch View и kiosk не получают новых интерактивных слоёв.

AC11 — compatibility (unit + existing regressions)

Текущие тесты devices, ha-binding-status, device-presentation, binding_picker и hidden_flag сохраняют смысл. Старые markers/settings читаются без миграции, а каталог не меняет auto-placement, filtering, light aggregation, LQI/climate или opening references.

16. План автотестов

• test/device-inbox.test.mjs — pure resolver, reason/capability/search/sort, large registry и exact-binding matrix;
• test/devices.test.mjs, test/ha-binding-status.test.mjs — соседние регрессии lifecycle;
• demo/smoke_device_inbox.mjs — реальный dialog, read-only assertions, row actions, return state, late registry refresh;
• адаптация demo/smoke_binding_picker.mjs и demo/smoke_hidden_flag.mjs без потери существующих проверок: smoke_hidden_flag включает ghost-режим через каталог и по-прежнему проверяет позицию, клик/настройку и drag скрытого marker;
• golden: desktop RU/EN, light/dark; narrow RU с длинными причинами;
• node scripts/smoke-select.mjs --base origin/dev --head HEAD определяет дополнительный набор перед код-ревью.

Минимальные локальные гейты реализации:

npx tsc --noEmit
npm test
npm run bundle:sync
node scripts/check-docs.mjs
node scripts/smoke-select.mjs --base origin/dev --head HEAD
node demo/smoke_device_inbox.mjs
node demo/smoke_binding_picker.mjs
node demo/smoke_hidden_flag.mjs
npm run golden:verify

17. Производительность

• полный индекс может включать тысячи entity, но DOM получает не более 100 строк за одну порцию;
• поиск и counts считаются по полному memoized snapshot;
• registry refresh инвалидирует snapshot один раз на revision;
• новый код не добавляет рендеров или observers в View/киоск;
• performance benchmark обязателен только если smoke-select либо ревью выявят затронутый бюджет; synthetic unit на большой registry остаётся обязательным.

18. Риски

Риск	Защита
Auto no-marker ошибочно показан как не добавленный	Effective runtime presence важнее наличия marker; AC3
Device/entity parent-child дедуплицируются слишком широко	Exact binding key и fixture #262; AC5
Limited registry создаёт ложные причины	Только positive evidence; AC4
Catalog и Add picker расходятся	Один общий eligibility helper
Открытие UI материализует данные	Явный no-write contract и websocket assertions; AC7
Историческая причина скрытия выдумывается	Generic automatic_hidden fallback
Большой registry блокирует dialog	O(N) snapshot + progressive rendering
Возврат из nested flow теряет контекст	Локальный returnToInbox snapshot; AC8
Перенос ghost-toggle делает активный режим незаметным после закрытия каталога	Активное состояние кнопки «Устройства» и сброс при выходе из редактора; AC6
#29 поглощает redesign фильтров	#44 явно вне скоупа

19. Откат

Изменение не мигрирует config и не создаёт новых persisted-полей. Откат возвращает две прежние кнопки и Add picker; markers, tombstones, hidden flags, layout и attachments остаются совместимыми. Созданный через «Скрыть из списка» hidden:true marker уже поддерживается старым UI и может быть показан обычным способом.

20. Release-артефакты

• docs/CHANGELOG.md и docs/CHANGELOG.ru.md со ссылкой на #29;
• раздел Device editor в docs/USER-GUIDE.md и docs/USER-GUIDE.ru.md;
• docs/FILTERING.md — каталог как единая presentation surface, без изменения lifecycle semantics;
• docs/ARCHITECTURE.md — pure resolver и shared eligibility helper;
• актуальные golden baselines и публичный screenshot редактора устройств, если документационный capture затронут;
• backend, security и model migration release notes: не требуются.

21. Принятые технические предположения — ревьюер может менять свободно

1. Pure resolver живёт в src/device-inbox.ts, а не внутри Lit-компонента.
2. Existing Add eligibility извлекается в общий helper; имя модуля не является продуктовым контрактом.
3. Tab/search/filter/scroll state хранится только в экземпляре карточки.
4. Progressive page = 100 строк; конкретное число можно скорректировать по golden/performance без изменения пользовательской семантики.
5. Точная историческая причина seed не сохраняется; при отсутствии доказательства используется automatic_hidden.
6. #44 расширит тот же dialog advanced-настройками позже, но #29 не ждёт #44 и не меняет discovery settings.