houseplan-card/docs/reviews/CODE-REVIEW-178-r1.md

# Код-ревью #178 — выбор точной сущности для действия «Переключить состояние»

- **Issue:** https://github.com/Matysh/houseplan-card/issues/178
- **Цикл:** r1/4 (обычный трек — `small`/`trivial` не назначались)
- **Диапазон:** `origin/dev..HEAD`, коммиты `e46ef6f…f46be0e`, рабочий коммит
  реализации `8086399` (`feat: select exact toggle entity`)
- **ТЗ:** `docs/specs/178-toggle-entity.md`, зелёное ревью r2
  (`docs/reviews/SPEC-REVIEW-178-r2.md`)
- **Ревьюер:** Claude, свежая сессия, без контекста реализации

## Скоуп

Диапазон затрагивает: `src/device-toggle.ts`, `src/devices.ts`,
`src/houseplan-card.ts`, `src/marker-toggle-entity.ts` (новый), `src/types.ts`,
i18n en/ru; backend `validation.py`/`import_export.py`; unit
(`test/device-toggle.test.mjs`, `test/marker-toggle-entity.test.mjs`,
`test/native-select-contract.test.mjs`, `test/golden-matrix.test.mjs`) и backend
(`tests_backend/test_validation.py`, `tests_backend/test_ha_import_export.py`)
тесты; новый smoke `demo/smoke_toggle_entity.mjs`; golden-матрица (2 новых
сценария, без capture); документация (ARCHITECTURE/CONFIG-COMPATIBILITY/
USER-GUIDE ru+en/CHANGELOG ru+en); `docs/specs/README.md`. Коммит `f46be0e`
— чисто C-класс (обновление fingerprint скриншотов после ребилда), не несёт
продуктового кода.

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

| Гейт | Команда | Результат |
|---|---|---|
| Typecheck | `npx tsc --noEmit` | зелёный, без вывода |
| Unit | `npm test` | `856/856`, 0 fail |
| Build + bundle parity | `npm run build`; `cmp dist/houseplan-card.js custom_components/houseplan/frontend/houseplan-card.js`; `cmp dist/houseplan-card.js demo/srv/assets/houseplan-card.js` | build зелёный; обе копии побитово совпадают с `dist/`, `git status` после сборки чист |
| Backend, чистый Python | `pip install pytest pytest-asyncio voluptuous` (среда ревью не содержала pytest); `python -m pytest tests_backend -q` | `138 passed`. **Важно:** `homeassistant` в среде ревью не установлен, `conftest.py` игнорирует `test_ha_*.py` целиком — значит, `tests_backend/test_ha_import_export.py` (обе новые/изменённые проверки toggle_entity: `test_export_copies_toggle_entity_literal`, обновлённый `test_space_import_remaps_owned_ids_and_duplicate_policy`) **не выполнялись** этим прогоном. Подтверждено: `pytest tests_backend -k toggle_entity` → `1 passed, 137 deselected` — это единственная проверка из `test_validation.py` |
| Named production-bundle smoke (AC1/2/3/5, §18.2) | `node demo/smoke_toggle_entity.mjs` | `9/9 OK`: `selectorForMultiple`, `savedSelectionProjected`, `selectionUpdatesDraft`, `selectionUpdatesHintBeforeSave`, `writerPersistsSelection`, `reopenRestoresSelection`, `staleWarnsAndShowsAuto`, `staleLiteralSurvives`, `singleEntityHidesSelector` |
| Смежные browser smoke (тот же резолвер: group-toggle и default-light) | `node demo/smoke_ha_controls.mjs`; `node demo/smoke_light_default_tap.mjs` | оба зелёные, все под-проверки `true` |
| Golden | не запускался | Пререлизный гейт по правилу самого ТЗ (§18.4) и PROCESS §8; см. «Чего не проверял» |
| Performance | не запускался | Спецификация заявляет отсутствие нового hot path (§15.1); подтверждено чтением, не измерением |

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

- `test/device-toggle.test.mjs` → `explicit own selection joins controls without
  changing legacy groups`: без `entries.push(selectedOwnEntity...)` в
  `resolveControls` (src/device-toggle.ts:617-623) группа осталась бы только
  `['light.external']`, а тест ожидает `['light.external', 'switch.child_lock']`
  и `service: 'turn_off'` — упал бы.
- `demo/smoke_toggle_entity.mjs` → `staleWarnsAndShowsAuto`: без узла
  `role="status"` с текстом сущности выражение `warning?.textContent?.includes(...)`
  даёт `undefined`/`false` — смок падает.
- `tests_backend/test_validation.py::test_toggle_entity_is_domain_bounded_only_when_new_or_changed`:
  прогнан лично, `invalid_toggle_entity` действительно поднимается на изменённом
  значении, не поднимается на неизменённом future-литерале — код умеет и падать,
  и не падать там, где нужно.

## Проверка AC (docs/specs/178-toggle-entity.md §19)

| AC | Доказательство по ТЗ | Как проверено сейчас |
|---|---|---|
| 1 | smoke §18.2.1, golden desktop | smoke: `selectorForMultiple` (3 опции при 2 кандидатах) — **выполнено**. Golden — не запускался, см. ниже |
| 2 | unit §18.1.1, smoke §18.2.2-3 | unit `issue 178: an explicit toggle entity selects one exact composite-device channel` — выполнен; smoke `selectionUpdatesDraft`/`selectionUpdatesHintBeforeSave`/`writerPersistsSelection` — выполнены |
| 3 | unit §18.1.6, smoke §18.2.5 | smoke `singleEntityHidesSelector` — выполнен; соответствующий unit — код прочитан (`toggleEntities.length > 1 \|\| staleToggleEntity` в `src/houseplan-card.ts:18339-18340`) |
| 4 | unit §18.1.3/8, mutation floor | `npm test` зелёный целиком, включая нетронутые legacy fixtures; прочитано, что `selectedToggleEntity()` возвращает `null` при отсутствии поля → путь идентичен старому |
| 5 | unit §18.1.4/11, smoke, mobile golden | smoke `staleWarnsAndShowsAuto`/`staleLiteralSurvives` — выполнены; unit `stale selection falls back...` — выполнен. Golden — не запускался |
| 6 | unit §18.1.5/9 | оба unit-теста (`stale selection falls back while an active missing target never retargets`, `unavailable selected own group member is skipped without replacing it`) — выполнены и содержательны (проверяют `noneReason`/`skippedTargets`, а не просто отсутствие исключения) |
| 7 | unit §18.1.7-9 | `explicit own selection joins controls without changing legacy groups` — выполнен, покрывает оба направления (с полем и без) |
| 8 | unit §18.1.3/10, diff | `origin === 'legacy-cover'` возвращается до чтения `selectedToggleEntity` (src/device-toggle.ts:717-727); `isManualVirtualLightMarker`/incoming-controller путь возвращается до него же (строки 687-708) — **проверено чтением, не исполнением**, дополнительно подтверждено тем, что unit-фикстуры cover/virtual light в существующем наборе не изменились и остались зелёными |
| 9 | backend/import unit §18.1.13 | **не выполнено исполнением** — тесты живут в `test_ha_import_export.py`, недоступном без HA-harness в среде ревью. Проверено чтением: `build_space_merge` добавил `"toggle_entity"` в allowlist удаления (import_export.py:897), схема экспорта не имеет отдельного списка полей для full/space (единственное упоминание `light_entity` в файле — та же строка), значит буквальный перенос происходит тем же путём, что и `light_entity` |
| 10 | backend unit §18.1.12, full-import fixture | **выполнено исполнением**: `test_toggle_entity_is_domain_bounded_only_when_new_or_changed` прошёл в чистом Python-прогоне |
| 11 | i18n/native-select unit, smoke, golden | RU/EN-паритет — существующий `test/i18n.test.mjs` проверяет полное соответствие ключей и обязательное `.aria` для всех `marker.*.help`-ключей, включая новые (прогнан как часть `npm test`); native-select — `test/native-select-contract.test.mjs` теперь включает `marker-toggle-entity` в список проверяемых id, тест выполнен и зелёный. Golden — не запускался |
| 12 | trailers/process gate, code-review inventory | commit `8086399` несёт `Issue: #178`, `User-Visible: yes`, и в нём же — оба changelog, `USER-GUIDE.md`/`.ru.md`, `CONFIG-COMPATIBILITY.md`, `ARCHITECTURE.md` (проверено `git show --stat`) |

## Разбор реализации (проверено чтением)

- `toggleEntityCandidates()` (src/device-toggle.ts:398-404) сознательно не
  расширяет entity-binding до registry-siblings и возвращает `[]` для
  `virtual` — совпадает с §8.1 ТЗ и подтверждено unit-тестом «entity binding
  stays exact even with a sibling toggle selection».
- Порядок в `resolveToggleIntent`: `manual-virtual-light`/`incoming-controller`
  → `explicit-toggle` с `controls` → `legacy-cover` → общий single-путь с
  `selectedToggleEntity()`. Новый код не может сработать раньше guard-ов,
  которые ТЗ явно выводит из scope (§10 «cover… не использует поле»).
- `resolveGroupEntities` (существующая, не тронутая функция) дедуплицирует по
  `entityId` через `Map`, поэтому даже гипотетическое совпадение выбранной
  собственной сущности с внешним `controls`-ref не даёт дублирующегося
  вызова сервиса — крайний случай вне явного покрытия тестами, но не является
  дефектом при существующей структуре кода.
- Backend: `_LIGHT_ENTITY_RE` идентичен по паттерну для обоих полей;
  делегирование в тот же цикл (`validate_marker_light_entities`) означает, что
  `toggle_entity` автоматически проверяется на всех тех же границах, что и
  `light_entity` (websocket save/config update, import merge, `validate_all`
  import) — подтверждено `grep` по вызовам, без отдельного риска рассинхрона.
- `toggleEntityWriteFields()` (новый файл `src/marker-toggle-entity.ts`)
  повторяет транзакционную модель `light_entity`; unit-тесты покрывают все 4
  комбинации `touched × originalHas`.
- Golden-инфраструктура (`demo/golden/harness.mjs`, `demo/golden/matrix.mjs`)
  статически согласована с реальной вёрсткой: класс `.markertoggleentity` и id
  `#marker-toggle-entity` совпадают буквально с `src/houseplan-card.ts`; фикстура
  `golden-washer` в `demo/fixtures/visual-matrix.mjs` содержит ровно два
  `switch.*` (power/child_lock) для сценария «selected» и не содержит
  `switch.golden_washer_removed` для сценария «stale» — соответствует
  замыслу сценариев.

## Находки

Нет находок уровня **High** или **Medium**.

**Low-1 (не блокирует, снимается с запиской).** `docs/USER-GUIDE.ru.md` и
`docs/USER-GUIDE.md` описывают появление селектора только для «маркера с
привязкой к устройству» с 2+ сущностями, не упоминая явно, что тот же
селектор может появиться и при сохранённом stale-значении на маркере с любым
типом binding (условие «либо» из §9.1 ТЗ). Пользовательского риска нет:
поведение верно реализовано и растворено в проверке via smoke
(`staleWarnsAndShowsAuto`), формулировка документации просто не покрывает
редкий путь явно. Снимается без правки — редкий путь (stale-значение после
внешнего изменения конфигурации) не искажает основной сценарий, а
дополнять формулировку ради полноты документации при зелёном коде
избыточно для этого цикла.

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

- Совместимость без миграции: отсутствие поля даёт бит-в-бит прежний результат
  (полный `npm test` зелёный, включая нетронутые legacy-фикстуры).
- Точность explicit-выбора (single и group) и отсутствие silent retarget при
  transient unavailable — оба пути покрыты содержательными unit-тестами,
  которые я прочитал и для которых проверил, что они способны упасть.
- Транзакционность диалога (touched/stale/original) и live-preview до Save —
  подтверждено production-bundle smoke на реальном собранном бандле.
- Backend lossless delta-validation — подтверждено исполнением теста.
- i18n RU/EN паритет и accessibility-контракт нового `<select>` — подтверждено
  исполнением существующих контрактных тестов, которые уже включают новый
  элемент.
- Все три копии production-бандла (`dist/`, `custom_components/.../frontend/`,
  `demo/srv/assets/`) побитово идентичны после чистой пересборки.
- Оба changelog и вся релизная документация лежат в том же коммите, что и
  продуктовый код; трейлеры `Issue`/`User-Visible` корректны на всех 6
  коммитах диапазона.
- Не найдено нарушений scope/non-scope из ТЗ (§5/§6): `tap_target`, cover,
  virtual-light, functional role/primary и confirmation flow не тронуты по
  диффу.

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

- **`pytest tests_backend` с установленным Home Assistant** — среда ревью не
  содержит `homeassistant`/`pytest-homeassistant-custom-component`, поэтому
  `test_ha_import_export.py` целиком пропущен `conftest.py` (документированное
  ограничение AGENTS.md: «зелёный результат без HA ничего не доказывает»).
  Два новых/изменённых теста в этом файле (`test_export_copies_toggle_entity_literal`,
  обновлённый `test_space_import_remaps_owned_ids_and_duplicate_policy`)
  разобраны только чтением кода — AC9 подтверждён косвенно, не исполнением.
  Каноничный прогон — Linux CI (`backend` job).
- **`npm run golden:verify` / `golden:capture`** — не запускался. ТЗ (§18.4) и
  PROCESS.md §8 сами относят golden к предрелизному гейту для этой задачи;
  два новых сценария не имеют baseline и по правилу принимаются только из
  полного Linux CI артефакта. Статическая проверка (совпадение id/класса
  между харнессом и вёрсткой, состав фикстуры) не заменяет визуальную
  проверку, но снижает риск того, что сценарий структурно не работает.
- **Полный browser smoke-набор (127 файлов)** — не запускался целиком. Помимо
  именованного `smoke_toggle_entity.mjs` (обязателен по AC), запущены
  `smoke_ha_controls.mjs` и `smoke_light_default_tap.mjs` — они делят
  изменённый резолвер (`resolveControls`/single-путь) и являются самым
  вероятным местом регрессии за пределами нового смока. Остальные смоки не
  касаются `device-toggle.ts`/диалога устройства по диффу и не запускались —
  сознательное сужение по PROCESS.md §8.
- **Performance-профили** — не запускались. ТЗ прямо заявляет отсутствие
  нового render-пути (§15.1); диффу не хватает признаков, которые обычно
  требуют профилирования (новый per-frame/pointermove/global-scan код
  отсутствует).

## Вердикт

Зелёный. Реализация точно соответствует зелёному ТЗ r2, все проверяемые здесь
AC подтверждены исполнением или обоснованным чтением кода, быстрые гейты
зелены, именованный и два смежных production-bundle smoke зелены, находок
уровня High/Medium нет.