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

# Код-ревью issue #174 — r1

- **Issue:** https://github.com/Matysh/houseplan-card/issues/174
- **ТЗ:** `docs/specs/174-linked-virtual-light-controller.md` (ревью:
  `docs/reviews/SPEC-REVIEW-174-r1.md`, вердикт зелёный)
- **Диапазон:** `origin/dev..HEAD`, коммиты
  `4a89582` (ТЗ) · `da10b3d` (spec-review doc) · `2f9cced` (реализация,
  `User-Visible: yes`) · `ea2633a` (docs-only, screenshot fingerprint)
- **Ревьюер:** Claude, свежая сессия, без контекста реализации

## Скоуп проверки

Правка меняет authority для manual-eligible виртуального источника света
(точная тройка #107: `binding=virtual` + `is_light=true` + `tap_action=toggle`)
при наличии входящей связи `controls: [marker:<id>]` от реального контроллера:
вместо безусловного перекрытия ручным state теперь реальный driver HA — единый
источник истины, а клик по любому из двух marker переключает реальное
устройство. Несвязанный источник сохраняет поведение #107 без изменений.

Затронуты: `src/devices.ts` (canonical light graph, `resolvedLightSources`),
`src/device-toggle.ts` (`resolveToggleIntent`, `resolveControls`), их тесты,
`demo/smoke_linked_virtual_light.mjs`, документация и оба changelog.
`src/houseplan-card.ts` не тронут — confirmation/re-resolve уже был общим
механизмом через `sameToggleOperationTargets`, что подтверждено чтением.

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

| Гейт | Команда | Результат |
|---|---|---|
| Typecheck | `npx tsc --noEmit` | зелёный, без вывода |
| Unit | `npm test` | 838/838 pass, 0 fail (совпадает с хендоффом) |
| Build | `npm run build` | зелёный, `dist/houseplan-card.js` создан за 10.9s |
| Три копии бандла | `sha256sum dist/houseplan-card.js custom_components/houseplan/frontend/houseplan-card.js demo/srv/assets/houseplan-card.js` | все три `d79008ee8d74…502e8` — совпадают побайтово и совпадают с SHA-256 из хендоффа |
| Целевой smoke (AC9–AC11) | `node demo/smoke_linked_virtual_light.mjs` | `OK`, все 31 проверка `true` (клик по лампе/контроллеру, HA-tick, Glow/fill/label, touch tap/long-press/pan/pinch/pointercancel, unlink→manual restore) |
| `git status` после build | — | пусто, сгенерированные копии не разошлись с закоммиченными |

**Дисциплина «тест умеет падать» — не поверье, а проверено мутацией:**

1. В `src/devices.ts` временно убрано условие `!control &&` перед перекрытием
   ручным state (возвращена версия бага). Пересборка `test-build` →
   `node --test test/devices.test.mjs` → красные ровно AC1-тесты:
   `issue 174: linked manual virtual source follows controller state…` и
   `issue 174: one cached reverse graph owns linked state…`. Файл восстановлен,
   тесты снова зелёные (78/78 в этом файле).
2. В `src/device-toggle.ts` временно убрана ветка `if (incoming) return
   resolveIncomingControllers(...)` в `resolveToggleIntent`. Пересборка →
   `node --test test/device-toggle.test.mjs` → красные ровно 3 теста AC3/AC4/AC5
   («redirects its toggle to the real controller driver», «source unions all
   drivers…», «keeps partial availability…»). Файл восстановлен, 35/35 зелёные.
3. После обоих восстановлений — полный `npm run build`, сверка трёх копий
   бандла и `git status` пусты: рабочее дерево вернулось к committed-состоянию.

**Не прогонялось, и почему:**

- **Полный набор `demo/smoke_*.mjs` (127 файлов).** Diff ограничен резолвером
  canonical light graph и explicit Toggle; остальные поверхности (проёмы,
  стены, sun, изометрия и т.д.) не затронуты ни одним изменённым файлом.
  Достаточно целевого smoke, названного в AC9–AC11.
- **`npm run golden:verify`.** Проверено чтением фикстур: ни один сценарий
  `demo/golden` не использует комбинацию `binding: virtual` + `is_light` +
  входящую связь `controls: [marker:*]` (`grep` по конфигу голден-сцен не дал
  совпадений на `virtual`/`is_light`). Диапазон изменения не может задеть
  существующие эталоны, а новый не нужен — визуал on/off не меняется, меняется
  только источник его вычисления.
- **`python -m pytest tests_backend -q`.** Diff не касается ни одного файла
  `custom_components/houseplan/**/*.py`; `git diff --stat` подтверждает.
- **Performance-профили.** В ТЗ (§15) заявлено «нового численного budget нет»;
  reverse-граф переиспользует уже существующий кэш `lightGraphOf`
  (`LIGHT_GRAPH_CACHE`, инвалидация по структурному fingerprint конфигурации,
  не по HA state/pointer-событию) — проверено чтением, не исполнением. Профиль
  не назван в AC, оставлен пре-релизному гейту.

## AC — разбор

| AC | Доказательство | Вердикт |
|---|---|---|
| AC1 | unit, мутация красит | Подтверждено |
| AC2 | unit (`resolvedLightSources` с изменённым HA-state и неизменным `virtualLights.rev`, а также с изменённым `rev` без смены driver — оба случая в тесте «one cached reverse graph…») | Подтверждено |
| AC3 | unit, мутация красит; `on.targets[0].via === 'control-marker-driver'`, `toggleOperation(on).kind === 'ha-service'` | Подтверждено |
| AC4 | unit («source unions all drivers…»): `switch.a`+`switch.b`, детерминированный порядок, any-on → `turn_off` объединения | Подтверждено |
| AC5 | unit («keeps partial availability…»): missing/unavailable/ha-disabled пропущены и объяснены `skippedTargets`; zero-driver `dormant` → `command: null`, `noneReason: 'configured-targets-missing'`, `toggleOperation(none) === null` (без `virtual-light` fallback) | Подтверждено |
| AC6 | unit («source unions all drivers…», вторая половина): клик по `relayA`/`relayB` даёт только собственный target каждого, тем же `driverEids`, что участвуют в linked-состоянии источника | Подтверждено |
| AC7 | unit (переименованный тест #107→#174, ветка `unlinked`) + отдельный regression-тест #107 без incoming link (`test/device-toggle.test.mjs:73`, `controls: ['light.saved']` — это исходящая ссылка устройства, не входящая) остался зелёным без изменений | Подтверждено |
| AC8 | ревью кода: `sameToggleOperationTargets` меняет идентичность target set при переходе linked↔manual (unit-тест `unlinked` в device-toggle.test.mjs: `sameToggleOperationTargets(on, unlinked) === false`); confirmation в `houseplan-card.ts` уже переоценивает intent через этот примитив на каждый confirm — проверено чтением `src/houseplan-card.ts:4387-4396`, не исполнением через реальный UI-диалог | Подтверждено (частично чтением) |
| AC9 | smoke `smoke_linked_virtual_light.mjs`: `sourceCallsRelay`, `controllerCallsRelay`, `offTickUpdatesAll`, `controllerTickUpdatesAll`, `noOperationalToggleWhileLinked` | Подтверждено |
| AC10 | тот же smoke: `touchTapCallsOnce`, `longPressOpenedInfo`/`longPressNoService`, `pointerCancelNoService`, `panNoService`, `pinchNoService` | Подтверждено |
| AC11 | тот же smoke: `externalStateUpdateWorks` (HA-tick без клика), `unlinkRestoresManualOff`, `manualToggleRestored` | Подтверждено |
| AC12 | ревью кода + unit: единственный `incomingLightControls()`/`lightGraphOf()` — переиспользован и `resolvedLightSources`, и `resolveControls`/`resolveIncomingControllers`; `grep` не находит второй независимой reverse-graph реализации | Подтверждено чтением |
| AC13 | `npm test` 838/838, включая нетронутые тесты #84/#94/#107; `npm run build` + сверка трёх SHA-256 | Подтверждено |
| AC14 | `git diff --stat origin/dev...HEAD`: ни один файл `custom_components/**/*.py`, `manifest.json`, `hacs.json`, i18n не изменён; в diff нет optimistic-state (смок явно проверяет `noOptimisticVisual`), polling или новых network paths; lock/alarm invariant не затронут (Toggle-путь не касается secure targets) | Подтверждено чтением |

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

- Один reverse-index (`incomingByMarker` в `lightGraphOf`) — единственный
  authority и для `source.on`, и для двух Toggle-путей (клик по linked source,
  клик по controller), как требует AC12/§8.2 ТЗ.
- Lifecycle: добавление связи не стирает `off`-bit (`virtualLights.off` не
  читается/не пишется в linked-режиме); снятие последней связи возвращает
  точное сохранённое значение — подтверждено и unit, и smoke.
- Zero-driver случай — safe no-op (`command: null`,
  `configured-targets-missing`) без отката к `virtual-light` — именно то, что
  требует §9.2 ТЗ и AC5.
- Документация (`docs/LIGHT.md`, `docs/USER-GUIDE.ru.md`,
  `docs/DEVICE-LIGHT-SETTINGS-MATRIX.ru.md`, supersession-заметка в
  `docs/specs/107-virtual-light-toggle.md`) переписана консистентно с новым
  контрактом и терминологией USER-GUIDE («Всегда», «Переключить состояние»,
  «управляет другими источниками света»); оба changelog в том же коммите, что
  `User-Visible: yes`.
- Трейлеры: все четыре коммита несут `Issue: #174`; `User-Visible: yes` только
  на коммите `2f9cced`, который и содержит оба changelog-файла в этом же
  коммите. Follow-up docs-коммит `ea2633a` — `User-Visible: no`, что верно
  (только фингерпринт скриншотов).
- Отсутствие изменений в `src/houseplan-card.ts` — не пропуск, а следствие
  того, что confirmation/`resolveToggleIntent`-flow уже был общим механизмом с
  #94; проверено чтением вызывающего кода.

## Находки

Нет High. Нет Medium. Нет Low.

## Чего не проверял (см. таблицу гейтов выше для причин)

- Полный набор `demo/smoke_*.mjs` (127 файлов) — не запускался, диапазон не
  задевает не затронутые поверхности.
- `npm run golden:verify` — не запускался; проверено чтением, что ни один
  golden-сценарий не использует затронутую конфигурацию.
- `python -m pytest tests_backend -q` — не запускался, backend не тронут.
- Performance-профиль (`benchmark_large_house` и т.п.) — не запускался, budget
  не назван в AC, оставлен пре-релизному гейту.
- Ручной проход через реальный `tap_confirm`-диалог в браузере (AC8) — разобран
  по коду, не исполнялся как отдельный smoke; общий confirmation-механизм не
  получил специального сценария в новом smoke-файле.

## Вердикт

Зелёный. Все 14 AC доказаны — unit-доказательства проверены на способность
падать прямой мутацией кода, targeted smoke пройден живым запуском Chromium,
типы/тесты/сборка зелёные, три копии бандла побайтово совпадают, трейлеры и
changelog на месте. Продуктовое решение владельца (комментарий от 18.08.2026)
реализовано без искажений: связанная пара ведёт себя как два умных
устройства, HA state — единственный источник истины, несвязанный источник не
регрессировал.