houseplan-card/docs/reviews/SPEC-REVIEW-29-r1.md

# SPEC-REVIEW-29-r1

- Issue: https://github.com/Matysh/houseplan-card/issues/29
- Этап: spec (PROCESS.md §2.4)
- Заход: r1 · блокирующих циклов израсходовано 0 из 4
- ТЗ: `docs/specs/029-device-inbox-lifecycle.md`
- SHA материала ревью: `a6ce1ae7e534fa4b41fcc0ab93e5ed95a693c4c1` (ветка `issue/29-device-inbox-lifecycle`)
- Трек: обычный (не `small`), лимит циклов ревью ТЗ — 4.

Это первый заход ревью по этой задаче — предыдущего вердикта в issue нет,
раздел «Унаследовано» не применяется, разбор полный.

## Скоуп разбора

Проверено:

1. `docs/SCOPE.md` — соответствие job'ам J4/J6, отсутствие выхода за
   продуктовую рамку (out-of-scope список, standing rules).
2. `AGENTS.md` и `PROCESS.md` §2.4, §7.1 — формальные требования к ТЗ и
   формат вердикта.
3. Тело issue #29 и все комментарии, включая повторную актуализацию анализа
   от 2026-08-28 и решение владельца по Q1.
4. `docs/USER-GUIDE.ru.md` (терминология «Скрытые и деактивированные»,
   «Редактор устройств», раздел про скрытие/удаление) и `docs/FILTERING.md`
   (канонический контракт hidden/removed/tombstone/entity-ownership).
5. Исходный код: `src/houseplan-card.ts` (`_bindingCandidates`,
   `new_device_ids`, `_maybeRebuildDevices`, `.slice(0, 200)` дважды),
   `src/ha-binding-status.ts` (`HaBindingStatus.kind`), `src/types.ts`
   (`marker.hidden`, `marker.removed`), `src/i18n/ru.json` и `en.json`.
6. Существующие тесты, упомянутые в AC11/§16: `test/devices.test.mjs`,
   `test/ha-binding-status.test.mjs`, `test/device-presentation*.test.mjs`,
   `demo/smoke_hidden_flag.mjs`, `demo/smoke_binding_picker.mjs` —
   существуют, содержимое `smoke_hidden_flag.mjs` прочитано целиком.
7. `docs/CONFIG-COMPATIBILITY.md` — беглая проверка на отсутствие
   противоречий заявлению «нет новых persisted-полей».

Ревью — на этапе ТЗ: продуктового кода нет, автотесты не запускались (их
ещё не существует), гейты §8 к этому этапу не относятся.

## Метод проверки

Каждое фактическое утверждение ТЗ о текущем поведении продукта
(«До», §3, §7, §8, §9, §10.1) сверено с кодом или каноническим документом, а
не принято на слово автора. Отдельно проверено, есть ли в тексте
утверждение о поведении, которого нет ни в одном документе и которое не
помечено как предположение (раздел 21 ТЗ).

## Находки

### M1 (Medium, в скоупе) — исчезновение призрачного показа скрытых/HA-disabled маркеров на плане не названо как продуктовое решение

**Файл:** `docs/specs/029-device-inbox-lifecycle.md`, §10.1 (строки 216–222).

Сегодня редактор устройств может показать скрытые и HA-disabled маркеры
прямо на плане, в их реальной позиции, призраками — режим переключается
кнопкой «Скрытые и деактивированные» (`docs/FILTERING.md` строки 84–91,
`docs/USER-GUIDE.ru.md:178` — «доступны скрытые маркеры», перетаскиваются;
подтверждено в `demo/smoke_hidden_flag.mjs`, где ghost рендерится в
`_setMode('devices')` с `_showHidden = true` и клик по нему открывает
диалог). Это единственный способ увидеть, ГДЕ на плане сидит скрытое или
деактивированное устройство, не отменяя его скрытость.

ТЗ прямо убирает этот режим: «Скрытые markers больше не рисуются поверх
плана постоянным локальным режимом: доступ к ним даёт каталог» (§10.1).
Но каталог (§10.2–10.4) не даёт эквивалента: `Find` явно доступен «только
если marker реально отрисовывается» (§10.4), а для строк категории
«Скрытые» и для «На плане, временно не отображается из-за HA status»
primary/secondary действия — это «Показать»/«Настроить», не позиция на
плане. Значит, чтобы увидеть, где стоит скрытый маркер, администратору
придётся сначала его показать (что меняет конфиг), посмотреть, и при
необходимости скрыть обратно — вместо непосредственного просмотра.

Это видимое пользователю изменение объёма функциональности («какая
персона что видит и делает» — ровно тот класс вопросов, который согласно
PROCESS.md §7.1 задаётся владельцу или явно фиксируется как принятое
предположение в §21). В тексте ТЗ оно подано как самоочевидный
технический побочный эффект объединения кнопок, а не как решение,
которое можно оспорить: обоснование «устраняет состояние панели,
неочевидное после возврата в редактор» — это плюс нового дизайна, но оно
не адресует потерю прямого просмотра позиции.

**Не High**, потому что: обходной путь существует (Показать → посмотреть/
перетащить → Скрыть), это не потеря данных и не поломка AC — просто
непроверенное продуктовое допущение, которое дёшево закрыть на этом этапе.

**Как закрыть в этом же цикле (на выбор автора):** либо явно вынести это в
блок §21 как предположение, которое ревьюер/владелец может оспорить, с
описанием обходного пути; либо задать это владельцу одним пакетным
вопросом с предложенным дефолтом (например: «Find для скрытой/disabled
строки временно подсвечивает позицию на плане не снимая hidden» как
альтернативный дизайн); либо сознательно сохранить упрощённый вариант, но
явно назвать компромисс и обходной путь в §2 «До/После» и в §18 «Риски».

### M2 (Medium, в скоупе) — устаревающая строка i18n не включена в план обновления

**Файлы:** `src/i18n/ru.json:673`, `src/i18n/en.json:673` (`marker.hide_tip`).

Текущий текст подсказки при скрытии маркера дословно ссылается на кнопку,
которую это ТЗ удаляет: RU — «Вернуть его можно через кнопку «Скрытые и
деактивированные» в редакторе устройств»; EN — `Restore it through "Hidden
and disabled" in the device editor`. §10.1 заменяет обе кнопки («Добавить»
и «Скрытые и деактивированные») одной кнопкой «Устройства» (`devbar.add`,
`devbar.show_all` перестают существовать в UI в текущем виде).

Раздел 14 (i18n) перечисляет только **новые** ключи и не содержит пункта
«обновить существующие ключи, ссылающиеся на удаляемые элементы
интерфейса». Если реализовать ТЗ как написано, `marker.hide_tip` останется
нетронутым и после релиза будет указывать пользователю нажать
несуществующую кнопку — конкретный, проверяемый дефект, а не гипотетический.

**Как закрыть:** добавить в §14 явный пункт «`marker.hide_tip` (en+ru)
обновляется, чтобы указывать на новую точку входа «Устройства»» (и
проверить, нет ли других строк с той же ссылкой — быстрый `grep` по
`show_all`/«Скрытые и деактивированные» в `src/i18n/*.json` показывает,
что это единственная пара строк такого рода, кроме самих `devbar.*`
/`title.show_all`, которые и так меняются по §10.1).

Обе находки Medium, в скоупе задачи (правки в самом файле ТЗ) — по
PROCESS.md §2.4/§2.7 они не создают отдельный issue (решение владельца
2026-08-19, #202) и возвращают ТЗ автору с жёлтым вердиктом.

## Что проверено и признано корректным

- **Формальные разделы §7.1** — сценарий, «что человек увидит до/после»,
  проблема, скоуп/не-скоуп, контракт поведения, UX, модель данных и
  миграция, i18n, AC1…AC11 с указанием способа доказательства, план
  автотестов, риски, откат, release-артефакты — все присутствуют.
- **AC1–AC11** однозначны и у каждого назван способ доказательства
  (unit/smoke/golden/review); ни один не описывает недоказуемое поведение.
- **Q1 владельца** (классификация автообнаруженного видимого устройства
  без marker) корректно отражена в §7.2 (категория `on_plan`) и в AC3 —
  соответствует решению владельца в комментарии issue.
- **Заявления о текущем поведении, использованные как база для «До»,
  подтверждены кодом и канонoм**, а не додуманы:
  - `_bindingCandidates` в `src/houseplan-card.ts:14032` — существующий
    eligibility-код, который ТЗ предлагает извлечь в общий helper (§12);
    не выдумка.
  - `HaBindingStatus.kind` (`active`/`ha_disabled`/`orphaned`/`unverified`)
    в `src/ha-binding-status.ts:14-17` — точное совпадение с таблицей §7.3.
  - `marker.hidden`/`marker.removed` в `src/types.ts:118,121` — существуют,
    семантика совпадает с `docs/FILTERING.md`.
  - Жёсткий кап на 200 элементов в существующих списках кандидатов
    (`src/houseplan-card.ts:14106`, `19114` — `.slice(0, 200)`) —
    подтверждает описанную в §8.1/AC9 проблему, которую каталог обязан не
    унаследовать.
  - `duplicate_name_area` действительно устарела: `docs/FILTERING.md:145`
    прямо говорит «Duplicate names are still numbered», не скрываются.
  - `settings.new_device_ids` фильтруется от уже скрытых id при seed
    (`src/houseplan-card.ts:3679–3684`) — подтверждает §8.2 «Первично
    отфильтрованный скрытый кандидат не получает badge, как и сегодня».
  - Терминология «Добавить», «Скрытые и деактивированные», «Правила
    иконок» — точное совпадение с `src/i18n/ru.json:455-457` и
    `docs/USER-GUIDE.ru.md`.
- **Технические предположения (§21)** промаркированы явно и корректно
  отделены от продуктовых решений — кроме пробела, описанного в M1.
- **Не входит (§6)** корректно исключает #44 (discovery-настройки), #126
  (смена area), #109 (multi-channel), bulk-операции, историю/графики,
  touch-паритет — всё по `docs/SCOPE.md` и `docs/TOUCH-SUPPORT.md`, без
  расширения скоупа.
- **Откат (§19)** реалистичен: нет новых persisted-полей и версии модели,
  откат — вернуть старые кнопки; совместимость с созданными через «Скрыть
  из списка» обычными `hidden:true` маркерами сохраняется.
- Названные тестовые артефакты существуют: `test/devices.test.mjs`,
  `test/ha-binding-status.test.mjs`, `test/device-presentation.test.mjs`,
  `test/device-presentation-policy.test.mjs`, `demo/smoke_hidden_flag.mjs`,
  `demo/smoke_binding_picker.mjs`, `scripts/smoke-select.mjs` — ни один не
  является выдумкой.

## Чего не проверял

- Не запускал никакие гейты (`typecheck`/`test`/`build`/смоки) — на этапе
  ТЗ продуктового кода нет, это не применимо (§8 относится к
  код-ревью).
- Не проверял `docs/ARCHITECTURE.md` и `docs/CANVAS.md` целиком постранично
  — только точечно то, что касается заявленных в ТЗ архитектурных решений
  (pure resolver, eligibility helper); полный аудит этих документов не
  требуется для ревью ТЗ.
- Не оценивал производительность реализации (её ещё нет); проверил только,
  что заявленная асимптотика (§12, §17) не противоречит существующему коду
  (`.slice(0, 200)` факт капа подтверждён).
- Не проверял golden/скриншот-инфраструктуру предметно — она релевантна
  коду, а не ТЗ.

## Вердикт

Полностью выполненные формальные требования ТЗ (§7.1) не отменяют жёлтый
вердикт: две находки Medium в скоупе (M1, M2) — реальные пробелы, оставить
их «в тексте ревью» без правки запрещено §12 PROCESS.md. High-находок нет.

**Вердикт: жёлтый.** ТЗ возвращается автору на правку M1 и M2; после
правки — новый заход ревью по дельте (PROCESS.md §2.10).