houseplan-card/legacy/reviews/v1.64.0/CODE-REVIEW-107-r1.md

Код-ревью issue #107 — переключение виртуального источника света «Всегда» (r1)

• Issue: https://github.com/Matysh/houseplan-card/issues/107
• ТЗ: docs/specs/107-virtual-light-toggle.md, ревью SPEC-REVIEW-107-r1.md — зелёное, High 0 / Medium 0.
• Диапазон: origin/dev...HEAD, коммит 1079cdfab25617df924b8c3592631aa40e078d87 ("feat: add persistent virtual light toggles"), ветка issue/107-virtual-light-toggle.
• Ревьюер: Claude (код-ревью ≠ ревью ТЗ, свежая сессия, без контекста реализации).
• Цикл: r1/4.

1. Скоуп изменения

Backend: новый Store houseplan.virtual_lights (virtual_lights.py, const.py, store.py), новая WS-команда houseplan/virtual_light/toggle, дополнение houseplan/config/get полем virtual_lights, согласование состояния во всех писателях конфигурации (websocket_api.py, __init__.py — миграция при setup).

Frontend: новый модуль src/virtual-light-state.ts (нормализация wire-снапшота, монотонное применение событий, reconciliation при смене config revision); интеграция в resolveToggleIntent/resolvedLightSources (device-toggle.ts, devices.ts), в live-sync и localStorage-кэш (config-store.ts, houseplan-card.ts), в статическую карточку (space-card.ts, space-render.ts); i18n EN/RU; unit-тесты (test/virtual-light-state.test.mjs, дополнения device-toggle.test.mjs, devices.test.mjs); backend-тесты (test_virtual_lights.py, test_ha_virtual_lights.py, дополнение test_ha_setup.py); целевой browser smoke demo/smoke_virtual_light_toggle.mjs; документация (docs/LIGHT.md, docs/CONFIG-COMPATIBILITY.md, docs/ARCHITECTURE.md, docs/USER-GUIDE.ru.md, README.md, оба changelog).

Соответствует заявленной поверхности ТЗ. Продуктовое соответствие docs/SCOPE.md: J1/J3, узкое исключение к замороженным virtual devices, не пересмотрено ревьюером ТЗ повторно (не входит в код-ревью).

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

Гейт	Команда	Результат
Typecheck	npx tsc --noEmit	зелёный, без вывода
Unit (frontend)	npm test	781/781 pass
Build + сверка бандлов	npm run build && sha256sum dist/houseplan-card.js custom_components/houseplan/frontend/houseplan-card.js demo/srv/assets/houseplan-card.js	один и тот же SHA-256 caffc463…d23bbc89 для всех трёх копий; рабочее дерево осталось чистым (git status --short пусто) — сборка воспроизводима и совпадает с закоммиченным бандлом
Backend pytest (чистое подмножество, без HA)	python3 -m venv /tmp/venv-review && /tmp/venv-review/bin/pip install pytest voluptuous && PYTHONPATH=. /tmp/venv-review/bin/pytest tests_backend -q	упал сбором — tests_backend/test_virtual_lights.py не собирается без homeassistant (см. находку M1). Полный HA-харнесс (pytest-homeassistant-custom-component) в этом окружении не установлен и не входит в его canonical Linux CI набор по факту — только офлайн-подмножество, которое теперь не запускается вовсе. test_ha_virtual_lights.py/test_ha_setup.py разобраны чтением (см. §4)
Целевой browser smoke	node demo/smoke_virtual_light_toggle.mjs (после npm run build и синхронизации трёх копий бандла, Chromium/Playwright уже установлены в среде)	FAILED (2): clickEverywhereOff: expected true, got false; reloadFirstStateOff: expected true, got false. Остальные 5 проверок (initialEverywhereOn, secondClickEverywhereOn, touchSingleToggle, oneServerTogglePerGesture, noHaServiceCalls) — true. См. находку H1

Не прогонялись (осознанно, вне гейта код-ревью для этого объёма изменений по PROCESS.md §8): npm run golden:verify (изменение не трогает художественный baseline — новая fixture по плану идёт в golden только на pre-beta gate), полный набор demo/smoke_*.mjs (127 сценариев — задача не задевает все поверхности, а точечный сценарий уже прогнан выше и провалился), performance-профили (в AC не назван численный бюджет; §15.4 ТЗ явно откладывает его на pre-beta). Прогон полного HA backend harness (pytest-homeassistant-custom-component) недоступен в этом окружении — AC2/AC3/AC4/AC8/AC9, доказываемые test_ha_virtual_lights.py, разобраны чтением, не исполнением (см. §4).

3. Находки

H1 (High, блокирует). Собственная презентация маркера (иконка/CSS-класс on/off) не отражает ручное состояние, когда у того же маркера есть исходящие controls — подтверждено исполнением целевого smoke

Файл: src/device-presentation.ts (не тронут этим PR), проявляется через src/houseplan-card.ts (_devicePresentation/_stateClass), src/space-card.ts, src/space-render.ts.

Сценарий воспроизведения: ровно fixture demo/smoke_virtual_light_toggle.mjs — маркер binding: 'virtual', is_light: true, tap_action: 'toggle', controls: ['light.ceiling'] (эта же тройка + исходящий controls, то есть ровно сценарий AC12). Запуск node demo/smoke_virtual_light_toggle.mjs на чистом собранном бандле даёт:

FAILED (2):
  - clickEverywhereOff: expected true, got false
  - reloadFirstStateOff: expected true, got false

Причина, подтверждена чтением и точечной инструментацией (debug-копия смока, запущена и удалена, в репозиторий не попала): resolvePresentationSources() (src/device-presentation.ts:279-280) выбирает sourceKind = 'controls', как только у устройства есть хоть один источник с via === 'controls' — это ветка для «маркер-контроллер показывает лицом состояние того, что включает». Для точной тройки #107 marker.controls — это исходящая, не относящаяся к ролям Auto/Always связь (AC12 требует, чтобы она сохранялась lossless и не вызывала HA-сервис, но не говорит, что она должна забирать приоритет у собственного ручного состояния маркера). Проверено инструментацией: без поля controls та же тройка _stateClass/иконка корректно показывает off после клика (sourceKind: 'light', visualSources: [{"eid":"marker:...","state":"off"}]); с полем controls _devicePresentation() даёт sourceKind: 'controls', visualSources: [{"eid":"light.ceiling","state":"on"}, {"eid":"marker:...", "state":"off"}] — правильное ручное состояние присутствует в списке, но не выбрано для лица маркера, поэтому _stateClass()/CSS-класс on остаются завязаны на состояние light.ceiling, а не на ручной toggle.

Это касается всех трёх типов потребителей презентации маркера (_devicePresentation полной карточки, второй полной карточки, статической — все три вызывают resolveDevicePresentation с одним и тем же resolvePresentationSources), поэтому и on(first), и on(second), и staticOn() остаются залипшими на состоянии light.ceiling, а не на ручном toggle — что и даёт false в обеих сравнительных проверках смока.

Почему это блокирует, а не Low/Medium: ТЗ §6.2 требует «один и тот же resolved source обязан дать одинаковый результат» для списка потребителей, явно включающего «room card и device presentation»; AC5 требует source.on= false … во всех canonical light consumers»; AC10/AC12 — это ровно комбинация (манильный маркер + сохранённые исходящие controls), которую тестирует сам смок. Реализация проходит AC1–AC9 (см. §4) и логику toggle/persistence, но для этой явно предусмотренной ТЗ комбинации собственная иконка маркера не меняется — заявленный сценарий («нажатие выключает его … Одновременно меняются его Glow и все room-light consumers») не выполняется полностью: Glow/room fill меняются (подтверждено smoke-проверками oneServerTogglePerGesture, noHaServiceCallsи раздельно нижеприведённым разбором devices.ts), а лицо самого маркера — нет. Это ровно тот класс дефекта, который должен доказываться исполнением, а не чтением: без прогона smoke эта находка осталась бы незамеченной, потому что unit-тестыdevices.test.mjs/device-toggle.test.mjsне строят презентацию черезresolveDevicePresentation()и поэтому не видят приоритетsourceKind`.

Что не задето: сама персистентность, атомарность toggle, авторизация, отсутствие HA-сервисного вызова, поведение без controls — всё корректно (unit-тесты и 5/7 smoke-проверок это подтверждают).

M1 (Medium, обязан стать отдельным issue). tests_backend/test_virtual_lights.py не собирается pytest без установленного homeassistant, хотя заявлен как «чистый» тест

Файл: tests_backend/test_virtual_lights.py:1,4.

Сценарий воспроизведения:

python3 -m venv /tmp/venv-review
/tmp/venv-review/bin/pip install pytest voluptuous
PYTHONPATH=. /tmp/venv-review/bin/pytest tests_backend -q

даёт

ERROR tests_backend/test_virtual_lights.py
ImportError while importing test module '.../tests_backend/test_virtual_lights.py'
tests_backend/test_virtual_lights.py:4: in <module>
    from custom_components.houseplan.virtual_lights import (...)
custom_components/houseplan/__init__.py:9: in <module>
    from homeassistant.components.frontend import add_extra_js_url
E   ModuleNotFoundError: No module named 'homeassistant'
Interrupted: 1 error during collection !!!!!!!!!!!!!!!!!!!!

Это полная остановка сбора — ни один тест tests_backend/ не выполняется, включая ранее рабочие чистые файлы вроде test_validation.py.

Причина: файл заявляет в докстринге «Pure operational-store rules independent of the HA WebSocket harness» и импортирует модуль обычным путём from custom_components.houseplan.virtual_lights import …. Такой импорт обязан сначала выполнить custom_components/houseplan/__init__.py (пакетный __init__), который безусловно импортирует homeassistant.components.frontend и другие модули HA. Существующий test_validation.py (не тронут этим PR) решает ту же задачу иначе и специально: докстринг «validation.py is loaded by path, without importing the HA integration package», реализовано через importlib.util.spec_from_file_location, ровно чтобы не тянуть homeassistant для чистых тестов.

AGENTS.md фиксирует это же поведение как контракт: «Locally only the pure subset runs; python -m pytest tests_backend/ -q without Home Assistant silently skips test_ha_*.py … so a green result proves nothing» — то есть не-test_ha_* файлы обязаны собираться и выполняться без HA. Этот PR впервые нарушает инвариант: вместо тихого пропуска — полная остановка сбора для всего каталога.

Почему не блокирует: CI-джоб backend (.github/workflows/validate.yml:206) всегда ставит pytest-homeassistant-custom-component, так что зелёный проход в CI не страдает — сами тесты внутри test_virtual_lights.py корректны и проверяют то, что заявлено (см. §4). Ломается только локальный/офлайн путь без HA, который прежде «доказывал что-то» для остальных чистых файлов. Соответствует критерию Medium: реальный, воспроизводимый дефект вне заявленных AC, требует отдельного issue со ссылкой на #107 (тип tech-debt, поверхность — тестовая инфраструктура backend).

4. Что проверено и корректно

• AC1 (eligibility matrix, unit): isManualVirtualLightMarker()/ eligible_virtual_light_ids() (frontend virtual-light-state.ts, backend virtual_lights.py) требуют точную тройку binding==='virtual' + is_light===true + tap_action==='toggle' + removed!==true; unit-тест test_eligibility_is_the_exact_triple_and_hidden_is_not_lifecycle и frontend devices.test.mjs/device-toggle.test.mjs покрывают Auto/Never/wrong-action/ non-virtual/removed — доказано автотестом, тест умеет падать (проверено изменением условия вручную не потребовалось: тест явно перечисляет все отрицательные варианты одним assert на множество).
• AC2/AC3 (persistence, atomic concurrency, backend): async_toggle_virtual_light вызывается из ws_virtual_light_toggle внутри rt.write_lock — тот же lock, что использует ws_config_get/ws_config_set, поэтому конкурентные toggle-запросы физически сериализуются на уровне WS-хендлера, а не только внутри virtual_lights.py. Backend-тест test_invalid_target_and_concurrent_toggles_are_server_atomic (файл требует полного HA harness — прочитан, не исполнен: заявленное поведение — две последовательные server revisions (1,False),(2,True) — соответствует коду async_toggle_virtual_light, который читает текущий snapshot, инвертирует и сохраняет одной операцией под общим локом).
• AC4 (права, ревью кода): ws_virtual_light_toggle не вызывает _check_write/ may_write — команда доступна любому аутентифицированному соединению, соответствует ТЗ §7.4. not_toggleable возвращается без изменения store и без события (if result is None: connection.send_error(...); return — находится внутри async with rt.write_lock, до send_result/async_fire).
• AC5 (canonical source.on, unit): devices.ts:536-548 — цикл идёт по ВСЕМ passive-источникам (if (!source.passive) continue), сначала считает обычный OR по incoming-контроллерам, затем безусловно переопределяет source.on через virtualLightIsOn(), если isManualVirtualLightMarker — то есть ручное состояние выигрывает и когда control есть, и когда его нет. devices.test.mjs («manual virtual state is canonical and invalidates the light cache») это явно проверяет для случая с входящим контроллером. Данный путь работает корректно на уровне Glow/room-графа; H1 — это отдельный путь (device-presentation), который не использует этот безусловный override напрямую, а получает свой собственный resolvedLightSources() вызов без virtualLights, скорректированный через lightSources: planLightSources, что ломается только при наличии собственных controls у того же маркера (см. H1).
• AC6 (typed intent, unit + ревью кода): resolveToggleIntent() (device-toggle.ts:610-632) возвращает operation: {kind:'virtual-light', markerId} и command: null для точной тройки, до общей ветки controls — marker ID никогда не подставляется в ToggleCommand/entity_id; test/device-toggle.test.mjs («exact manual virtual light wins over saved HA controls») подтверждает on.command === null и стабильность sameToggleOperationTargets при смене направления.
• AC7 (i18n, диалог): новые ключи marker.virtual_light_target/ virtual_light_current/virtual_light_state_on/off есть в EN и RU (src/i18n/en.json, src/i18n/ru.json), formatter в houseplan-card.ts (~17025-17046) ветвится по target.via === 'virtual-light' до общего toggle_hint_current/toggle_hint_single — старый no_actionable_entity hint для этой тройки не строится, так как resolveToggleIntent возвращает ненулевой intent раньше проверки no-actionable-entity.
• AC8 (initial snapshot, backend): ws_config_get вызывает async_virtual_light_snapshot внутри rt.write_lock, тем же config_rev, что и возвращаемый config/rev — снэпшот согласован с той же ревизией конфигурации, на которой backend проверял eligibility (прочитано в коде; test_default_toggle_event_and_restart_persistence подтверждает восстановление off после async_reload — прочитано, не исполнено, требует HA harness).
• AC9 (config writer lifecycle, backend): все места, где раньше был прямой rt.config_store.async_save({...}) (_converge_pair, ws_config_set, ws_plan_optimize, ws_plan_optimize_undo, миграция в __init__.py), заменены на async_save_config_state, которая безусловно вызывает async_reconcile_virtual_lights с явным previous_rev/previous_config_rev — единая точка, разрозненных ручных virtual_light_store.async_save() не найдено (grep по websocket_api.py/__init__.py подтверждает единственный вызывающий путь). Fail-safe на неизвестный revision gap (state_config_rev == config_rev иначе off = set()) реализован и в async_virtual_light_snapshot, и в async_reconcile_virtual_lights — прочитано, соответствует ТЗ §7.5.
• AC11/AC13/AC14 (live-sync, confirmation, cache invalidation): config-store.ts/houseplan-card.ts подписываются на houseplan_virtual_light_updated рядом с существующими событиями, applyVirtualLightEvent монотонна по rev (тест «events are monotonic and never optimistic» и «event-before-response ordering never rolls state back» в test/virtual-light-state.test.mjs» умеют падать — проверено инверсией условия мысленно: rev <= current.revиначеevent.onне проверялся бы).virtualLightFingerprintучаствует в ключеRESOLVED_LIGHT_CACHE (devices.ts), поэтому событие инвалидирует Glow/room-граф без HA state tick — подтверждено smoke-проверкой oneServerTogglePerGesture(одно серверное действие на один жест) и фактическим обновлениемstaticOn/on(second)в дебаг-прогоне безcontrols`.
• AC15 (build/bundle parity): npm run build воспроизводим, три копии бандла побайтно идентичны (см. §2).
• AC16 (документация): оба changelog, README.md, docs/LIGHT.md, docs/ARCHITECTURE.md, docs/CONFIG-COMPATIBILITY.md, docs/USER-GUIDE.ru.md обновлены в том же коммите, ссылаются на #107, описывают точную тройку, persistence/permissions, исключение из экспорта — сверено построчно, расхождений с реализацией не найдено (кроме того, что H1 делает фразу README «updates Glow, room fill/statistics, full cards and houseplan-space-card together» неполной для комбинации с controls — само по себе не отдельная находка, устранится вместе с H1).
• Трейлеры: коммит 1079cdf несёт Issue: #107, User-Visible: yes, оба changelog правлены в том же коммите — соответствует.

5. Чего не проверял

• Полный HA backend harness (pytest-homeassistant-custom-component) — недоступен в этой среде (не .venv-backend, чистый Linux-раннер без предустановленного пакета). AC2/AC3/AC4/AC8/AC9, чьё единственное автотест-доказательство — test_ha_virtual_lights.py, разобраны только чтением кода и тестового файла (см. §4), не исполнением. Тесты выглядят корректными и умеющими падать по структуре (явные значения rev/on на каждом шаге, явный monkeypatch для forced-failure сценария), но это не заменяет фактический прогон — Linux CI job backend остаётся канонической проверкой для них.
• npm run golden:verify, полный набор из 127 demo/smoke_*.mjs, performance-профили — не прогонялись, обоснование в §2 (объём соразмерен задаче по PROCESS.md §8; они относятся к pre-beta gate).
• Продуктовое соответствие docs/SCOPE.md/выбор J1/J3 — не пересматривалось повторно, это было предметом ревью ТЗ, а не код-ревью.
• Не проверялся весь возможный матрикс is_light/tap_action смены онлайн (rename/move/hidden/tombstone и т.д., AC9 edge cases) сверх того, что показывает test_lifecycle_preserves_hidden_and_prunes_when_eligibility_ends — тест прочитан и логически согласован с кодом, не исполнен.

6. Вердикт

H1 — реальный, воспроизведённый прогоном собственного целевого smoke-теста дефект: презентация маркера (иконка/CSS-класс, используемый полной и статической карточками) не отражает ручное состояние виртуального света, когда у того же маркера есть сохранённые исходящие controls — то есть ровно в комбинации, которую требует покрывать AC10+AC12 и которую строит сам demo/smoke_virtual_light_toggle.mjs. Это High: блокирует.

M1 — дефект тестовой инфраструктуры (не блокирует CI, но ломает документированный локальный офлайн-прогон pytest tests_backend -q из AGENTS.md для всего каталога, а не только для нового файла) — Medium, обязан стать отдельным issue.

Задача возвращается в S6-in-progress.