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

# SPEC-REVIEW-358-r1

**Issue:** #358 — «Холодная вкладка + пылесос (реальная телеметрия): `_vacMapId`
бросает в `willUpdate` — карточка перестаёт обновляться»
**Этап:** spec (PROCESS.md §2.4) · **Трек:** small (§5, метка `small`,
подтверждено владельцем: комментарий S2→S3 от 2026-08-28) · **Заход:** r1 ·
блокирующих циклов израсходовано 0 из 2.

## Скоуп

Лёгкий трек: ТЗ живёт в теле issue #358 (раздел «## ТЗ (small-трек, S3)»),
файла в `docs/specs/` нет — соответствует §5, проверено `ls docs/specs/`.

ТЗ описывает три пункта контракта:

- **К1** — перенос реализации `_vacMapId` с `houseplan-editor-runtime.ts` на
  `houseplan-card.ts` (владелец полей — карта), runtime делегирует в host. Тот
  же приём, что #357 применил к `_toggleIntent`.
- **К2** — два защитных гарда: `_decorShapeDown` (парный гард к
  `_decorShapeDbl` из #337) и рендер диалога `_vacCalConfirm` за
  `this._editorRuntime ?`.
- **К3** — новый холодный смок `demo/smoke_cold_view_vacuum.mjs`, закрывающий
  слепое пятно демо-фикстуры (`vacuum.mower` без атрибутов позиции).

AC1–AC4 повторяют issue-AC1…4 с указанием способа доказательства (smoke /
smoke + мутант / smoke + чтение кода). Откат — один revert, без миграций.

## Как проверялось

Ревью ТЗ этапа `spec` не гоняет гейты (§8 относится к код-ревью) — предмет
проверки этого этапа: выполнимость и однозначность ТЗ, и то, что автор не
выдал догадку за факт. Проверка велась чтением действующего исходника на
`61911b86` (текущий `HEAD`, тот же SHA, на котором зелёный CI Validate уже
подтверждён — #343) и сопоставлением каждого утверждения ТЗ с кодом.

Прочитано и сверено:

1. `docs/SCOPE.md` — сценарий issue закрывает J1 («живой обзор дома»): баг
   останавливает весь цикл обновления Lit, то есть бьёт по ядру продукта
   (кухня/дача с киоском), а не по периферийной функции.
2. `PROCESS.md` §2.4, §5, §7.1 — обязательные разделы лёгкого трека
   (проблема · контракт · AC с доказательством · откат) присутствуют.
3. Тело issue #358 целиком + единственный комментарий (владелец, S2→S3).
4. `docs/VACUUM.md` — цепочка фолбэка `map_name → current_map → map_index →
   selected_map → default` совпадает с описанием К1.
5. Код:
   - `src/houseplan-card.ts:11707-11709` — сегодняшняя жёсткая заглушка
     `_vacMapId`, вызываемая без гарда из `_captureRenderDeviceSnapshot`
     (`:4471`, внутри `willUpdate`) и `_renderVacuums` (`:11807`) — подтверждён
     ровно тот баг, который описывает issue;
   - `src/houseplan-editor-runtime.ts:9979-9985` — реализация, которую К1
     предлагает перенести. Текст в ТЗ (`const sel = ve ? planHass?.states?.[ve]
     ?.attributes?.selected_map : null; return vacMapIdWithFallback(tele.mapId,
     sel);`) и комментарий HP-1541-01 процитированы буквально, без искажений;
   - `src/vacuum.ts:252` — `vacMapIdWithFallback` действительно экспортируется
     оттуда и реализует «не-nullish» правило, о котором говорит комментарий;
   - `src/houseplan-editor-runtime.ts:11633-11648` — прецедент того же приёма
     на `_toggleIntent` из #357: карта владеет реализацией, runtime держит
     делегирующего двойника (`return this.host._toggleIntent(...)`), внутренние
     вызовы runtime (`this._toggleIntent(...)` на `:11929`, `:11648`) продолжают
     работать без изменений. К1 в точности повторяет эту схему — не догадка, а
     проверенный шаблон;
   - `src/houseplan-card.ts:7630-7632` — `_decorShapeDown` действительно жёсткая
     заглушка без гарда; `:7639-7642` — `_decorShapeDbl` действительно уже
     несёт `if (!this._editorRuntime) return;` (гард из #337, на который К2
     ссылается как на образец);
   - `src/styles/plan.styles.ts:664` — `.decorlayer .dshape { pointer-events:
     none; }` вне `mode-decor` подтверждает, что реальный указатель не достаёт
     фигуру в View, а значит только синтетический `pointerdown` (как в плане
     смока К3-г) может воспроизвести падение — соответствует помеченной в
     issue пометке «проверено» (исполнением, не гипотеза);
   - `src/houseplan-card.ts:11346-11361` — ряд редакторских диалогов
     действительно рендерится по шаблону `${this._X ? this._editorRuntime ?
     html\`…\` : nothing : nothing}`, а `_vacCalConfirm` (`:11351`) — единственный
     из них без внешнего гарда `this._editorRuntime ?`. К2 описывает точное
     целевое выражение, совпадающее с этим шаблоном;
   - `src/houseplan-editor-runtime.ts:10038,10052` — `_vacCalConfirm`
     присваивается truthy-значение только внутри runtime; в
     `houseplan-card.ts` встречается лишь сброс в `null`. Значит утверждение
     AC4 «кейс недостижим исполнением по построению» — не догадка, а факт,
     подтверждённый полным grep всех присваиваний;
   - `src/houseplan-card.ts:11730-11731` — `_vacApplyCalibrationProposal`
     (кнопки диалога) — тоже жёсткая заглушка, как и указано в issue.
6. `demo/smoke_vacuum.mjs`, `demo/smoke_cold_view_toggle.mjs`,
   `demo/serve.mjs` (`launchColdView`) — механика инъекции сущности с
   телеметрией через `card.hass`/`card._serverCfg`/`card._layout` и трекинг
   `page.on('request'/'pageerror')` уже существует и покрывает ровно то, что
   требует план К3 (несколько кадров `hass`, отсутствие запроса
   `houseplan-editor-runtime-*.js`, ноль pageerror, синтетический pointerdown).
   Смок, описанный в К3, технически реализуем без новой инфраструктуры.
7. `scripts/mutation-gate.mjs` — реестр мутаций, шаблон записи
   `cold-view-toggle-delegated-to-runtime` (добавлен в #357) — ревертит
   `_toggleIntent` карты назад на делегацию в runtime и проверяется тем же
   холодным смоком. AC3 просит зеркальную запись для `_vacMapId`; формулировка
   ТЗ («вернуть делегацию `_vacMapId` в runtime») однозначно отображается на
   эту механику — проверяемый, а не расплывчатый критерий.
8. `demo/smoke_static_icon.mjs`, `demo/smoke_vacuum_firstuse.mjs` — подтверждён
   слепое пятно демо-фикстуры: `vacuum.mower` заведён без `vacuum_position`,
   значит ни один существующий смок (включая холодные) не проходит через
   ветку `telemetry ? this._vacMapId(...) : null`.

## Находки

Нет. High: 0, Medium: 0, Low: 0.

Отдельно проверено на «догадку, выданную за факт» (главный риск по инструкции
ревью): каждое утверждение К1/К2/К3/AC1-4, сформулированное как факт о текущем
коде, сверено с исходником построчно (см. таблицу выше) и подтвердилось без
исключений. Технические решения, оставленные без явного обсуждения (имя файла
смока, точный id мутанта, порядок гардов), относятся к классу «агенты решают
сами» (§7.1) и не требуют пометки «принято предположительно» — они не
затрагивают видимое пользователю поведение.

## Что проверено и корректно

- Соответствие лёгкому треку (§5): ТЗ в теле issue, файла в `docs/specs/` нет.
- Обязательные разделы ТЗ лёгкого трека присутствуют и однозначны.
- Каждый AC называет способ доказательства (smoke / smoke+мутант /
  smoke+чтение кода) и не содержит открытых вопросов.
- К1 текстуально и по логике совпадает с действующим кодом-источником
  (`houseplan-editor-runtime.ts`) и с прецедентом #357.
- К2 описывает ровно два реальных гэпа (найдены построчным grep всех
  присваиваний/рендеров) и предлагает решение по образцу уже принятого кода.
- К3 реализуем на существующей инфраструктуре демо-стенда без новых
  примитивов.
- Продуктовая рамка (сценарий, кого касается, почему это выше по тяжести, чем
  #357) присутствует в теле issue и совпадает с J1 из `docs/SCOPE.md`.
- Открытых продуктовых вопросов к владельцу нет — и по факту не должно быть:
  ожидаемое поведение («карточка живёт на холодной вкладке») уже
  зафиксировано как баг, а не как решение с вариантами.
- Откат описан («один revert, конфиг/контракты не меняются») и достаточен для
  этого класса правки (без миграций, без нового UX-контракта).

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

- Гейты `npx tsc --noEmit` / `npm test` / `npm run build` не гонялись: на
  этапе `spec` кода ещё нет (issue не покидал `S3/S4`), гонять их не над чем.
  Дешёвые гейты на `61911b86` (последнем коммите `dev`) уже зелёные —
  Validate: https://github.com/Matysh/houseplan-card/actions/runs/33198366583.
- Исполнение самого смока `demo/smoke_cold_view_vacuum.mjs` — он ещё не
  написан, это предмет реализации, не ТЗ. Оценивалась только его
  осуществимость на существующей инфраструктуре (`launchColdView`, паттерны
  инъекции сущности), а не его будущий текст.
- `scripts/smoke-links.mjs` / реестр обнаружения смоков — не проверял,
  требует ли новый файл смока отдельной регистрации там; это техническая
  деталь реализации, а не предмет ТЗ, и её увидит код-ревью.
- Golden/визуальные эталоны, backend-тесты (`tests_backend`),
  performance-профили — вне скоупа: правка не трогает `custom_components/**`,
  не меняет визуальный результат и не названа в AC как влияющая на
  производительность.

## Вердикт

Зелёный. ТЗ выполнимо, каждый AC проверяем и снабжён способом доказательства,
фактические утверждения о коде подтверждены построчно, догадок, выданных за
решения, не найдено. Готово к разработке.