houseplan-card/legacy/reviews/v1.65.0/SPEC-REVIEW-174-r1.md

# SPEC-REVIEW-174-r1

- **Issue:** https://github.com/Matysh/houseplan-card/issues/174
- **ТЗ:** [`docs/specs/174-linked-virtual-light-controller.md`](../../specs/174-linked-virtual-light-controller.md)
  (commit `4a8958291d28fbd86d0233e6ac9208b068b24f76`, ветка `issue/174-linked-virtual-light`)
- **Ревьюер:** Claude (ревью ТЗ ≠ автор), этап `S4-spec-review`
- **Цикл:** r1/4 (обычный трек — issue не `small`/`trivial`, что подтверждено
  комментарием аналитики)

## Скоуп ревью

Ревью ТЗ #174: изменение authority-правила пассивного forced-источника
«Всегда» + виртуальная лампа при наличии входящей связи от контроллера
(умного выключателя/реле), плюс переадресация клика по такой лампе на реальные
driver-сущности вместо operational `virtual_lights` toggle (#107).

Не в скоупе ревью: код ещё не написан (issue в `S4-spec-review`), поэтому
проверка кода/тестов — предмет будущего code-review.

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

Прочитано в заданном порядке:

1. `docs/SCOPE.md` — job'ы J1/J3, инвариант замка (не затронут: driver-сущности
   ограничены `light.*`/`switch.*`).
2. `AGENTS.md`, `PROCESS.md` (полностью, включая §7.1 и §5).
3. Issue #174 body + все 3 комментария (владелец подтвердил семантику
   18.08.2026, аналитика оценила трек, автор сдал ТЗ).
4. `docs/USER-GUIDE.ru.md` — раздел «"Тупая" лампа с умным выключателем»
   (строки 559–589), сверены термины «Всегда», «Переключить состояние»,
   «Управляет другими источниками света», Glow.
5. Канонические документы подсистемы: `docs/LIGHT.md` (раздел «Source, state
   and service identity»), `docs/specs/084-passive-forced-light-sources.md`,
   `docs/specs/107-virtual-light-toggle.md`,
   `docs/DEVICE-LIGHT-SETTINGS-MATRIX.ru.md`.
6. Само ТЗ `docs/specs/174-linked-virtual-light-controller.md` целиком.
7. Текущий код на ветке `issue/174-linked-virtual-light` (тот же коммит, где
   лежит ТЗ; продуктовый код не менялся) — `src/devices.ts`
   (`resolvedLightSources`, строки 484–608, включая безусловный override на
   567–572), `src/device-toggle.ts` (`resolveToggleIntent`, 604–659;
   `resolveControls`, 490–601; `sameToggleOperationTargets`, 686–698),
   `src/virtual-light-state.ts` — чтобы убедиться, что цитаты кода и
   утверждения о причине бага в ТЗ и в issue соответствуют реальному коду, а не
   пересказу автора. Совпадение построчно точное (см. «Проверено и корректно»).
8. Существование упомянутых тестовых/смоук-файлов:
   `test/devices.test.mjs`, `test/device-toggle.test.mjs`,
   `test/device-presentation.test.mjs`, `demo/smoke_virtual_light_toggle.mjs`,
   `demo/smoke_controls.mjs` — все существуют, ТЗ не ссылается на
   несуществующие файлы кроме нового `demo/smoke_linked_virtual_light.mjs`,
   что явно помечено как новый файл.

Гейты (typecheck/test/build) не прогонялись — на этапе ревью ТЗ кода нет,
прогон гейтов здесь не предмет доказательства (это часть code-review,
PROCESS.md §2.7).

## Проверка формальных требований §7.1

Все обязательные разделы присутствуют: сценарий и персона (§1), что человек
увидит до/после одной фразой без терминов реализации (§2 — использует «Glow» и
«HA state», но это установленный интерфейсный термин из
`docs/USER-GUIDE.ru.md`/`docs/LIGHT.md`, а не изобретённый жаргон), проблема с
подтверждённой причиной (§3, код процитирован точно), скоуп/не-скоуп (§6/§7),
контракт состояния и действия (§8/§9), единые визуальные consumers (§10),
модель данных и совместимость (§11), UX/i18n/touch (§12), AC1–AC14 с указанием
доказательства (§13), план автотестов (§14), риски/perf/security (§15),
откат (§16), release-артефакты (§17), явный блок принятых технических
предположений (§18).

Каждый AC пронумерован, имеет ровно один заявленный способ доказательства
(`unit`/`smoke`/`ревью кода`/`build`) и формулировку, допускающую одну
интерпретацию — за одним отмеченным ниже исключением (Low-1).

Продуктовых вопросов владельцу не осталось: единственное решение владельца,
требовавшееся для этой задачи (семантика «два умных устройства»), уже принято
в комментарии от 18.08.2026 и корректно перенесено в §4 ТЗ. Автор не подменил
догадкой ни одного продуктового пункта — там, где формат ответа мог требовать
нового текста (driver-group hint), ТЗ явно откладывает решение как «отдельная
продуктовая находка», а не придумывает текст (§12).

## Находки

### Low-1 — формулировка AC6 читается двусмысленно в отрыве от §9.1

**Файл:** `docs/specs/174-linked-virtual-light-controller.md:309-310`

AC6 гласит: «клик по controller сохраняет #84/#94 group semantics и
переключает тот же driver projection, которым вычисляется linked source».
При нескольких контроллерах на одну лампу эта фраза, прочитанная изолированно,
может означать «клик по одному контроллеру должен переключить объединение
driver-сущностей ВСЕХ контроллеров лампы» — что было бы неверно и опасно
(один выключатель дистанционно переключил бы другой). По коду
(`resolveControls`, `devices.ts:490-601`) и по явной строке §9.1 «в простой
паре команда содержит реальный relay controller» видно, что имелось в виду
другое: клик по контроллеру продолжает переключать только *свою* сущность,
а утверждение AC6 — про переиспользование одного и того же вычислителя
driver-проекции (не про объединение по всем входящим связям цели). Строка
риска «Source click при нескольких controllers переключит только один relay» →
«Детерминированный union/dedupe и group tests» (§15) относится к клику по
**лампе** (AC4), а не по контроллеру, и путаницу создаёт именно совпадение
формулировок.

**Воспроизведение неоднозначности:** контроллер A и контроллер B оба ссылаются
на одну и ту же passive-лампу L (валидная конфигурация по #84 §5.2, OR).
Буквальное прочтение AC6 «тот же driver projection, которым вычисляется
linked source» для L равно `{A.entity, B.entity}` — так что тест AC6 в
такой формулировке можно было бы написать так, что клик по A потребует
службы к B, чего продукт не хочет и чего не просит владелец.

**Вердикт:** не блокирует — контекст §9.1 и таблица рисков снимают
неоднозначность, а код (`resolveControls`) уже реализует корректную,
per-controller семантику, которую AC6 обязан только сохранить. Снимаю без
правки ТЗ: автор код-ревью обязан читать AC6 вместе с §9.1 буквально «свой
relay, не объединение», и я фиксирую это здесь как явное толкование для
будущего код-ревью, а не как повод для нового цикла.

Больше High/Medium-находок нет.

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

- **Причина бага подтверждена исполнением, а не пересказом.** Цитаты кода из
  issue и ТЗ (`source.on = !control?.linked || ...`; `isManualVirtualLightMarker`
  override в `resolvedLightSources`, и ранняя проверка в `resolveToggleIntent`)
  совпадают построчно с текущим `dev`-кодом на ветке. Ни одно техническое
  утверждение о причине не является догадкой.
- **Продуктовое решение владельца корректно перенесено.** Формулировка §4 ТЗ
  («два умных устройства», HA state — единственный источник истины,
  lifecycle-граница create/remove link) слово в слово соответствует
  комментарию владельца и последующей аналитике.
- **Контракт §8/§9 согласован с уже принятыми канонами #84/#107**, а не
  придумывает новую модель: OR нескольких контроллеров, zero-driver → dormant
  (не constant-on), lossless `controls`, запрет `marker:*` в `callService` —
  всё это уже нормативно закреплено в #84 и просто применяется к
  ранее заблокированному случаю. Новизна ТЗ ограничена ровно точкой конфликта
  (#84 OR vs #107 manual override) и симметричной переадресацией клика лампы —
  это соответствует заявленному скоуфу и не расширяет его.
- **Не входит в задачу (§7)** корректно исключает автосвязывание, новые
  UI-поля, AND/NOT-логику, синхронизацию цвета/яркости и историю — ничего из
  этого не запрашивал владелец.
- **Compatibility (§11)** — не меняются `Marker`/`ServerConfig`/backend schema,
  что подтверждается кодом: единственная правка — в вычислении `source.on` и в
  выборе operation, оба уже существующих pure-функциях без сериализации.
- **AC изложены с однозначным способом доказательства** и практически все —
  с единственной трактовкой; мутационные требования присутствуют явно
  (AC1, AC7) как и требует #85/PROCESS §2.7 «тест умеет падать».
- **Release-артефакты (§17)** включают оба changelog, `USER-GUIDE.ru.md`,
  `LIGHT.md`, `DEVICE-LIGHT-SETTINGS-MATRIX.ru.md`, supersession-заметку в
  `107-virtual-light-toggle.md` — то есть именно те документы, чьи текущие
  формулировки (`USER-GUIDE.ru.md:583-589`, `LIGHT.md:149-159`) сейчас описывают
  старое (заменяемое) поведение и стали бы враньём без обновления.
- **Откат (§16)** не требует миграции данных — корректно, так как формат
  конфигурации не меняется.
- **Технические предположения (§18)** отделены от продуктовых решений и явно
  помечены как «можно менять свободно», ревьюеру не выдано ни одной догадки
  под видом факта.

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

- Реализацию — её нет: issue находится в `S4-spec-review`, продуктовый код не
  менялся с предыдущего merged-состояния (`git diff origin/dev...HEAD` для
  `src/**` пуст).
- Гейты `typecheck`/`test`/`build`/browser smoke — не относятся к этапу
  ревью ТЗ; будут предметом code-review (PROCESS.md §2.7/§8).
- `custom_components/houseplan/**/*.py` — ТЗ и код подтверждают отсутствие
  backend-изменений, поэтому backend-тесты не запускались.
- Golden/perf-эталоны — ТЗ явно заявляет отсутствие нового visual baseline;
  не перепроверял рендер вручную, так как речь о будущей реализации.

## Вердикт

Все обязательные разделы §7.1 присутствуют, каждый AC однозначен и имеет
названный способ доказательства, продуктовых открытых вопросов не осталось
(решение владельца зафиксировано и корректно перенесено), догадок под видом
факта не найдено. Единственная находка — Low, снята без цикла возврата, с
явной запиской для код-ревью.

**Вердикт: зелёный · цикл r1/4 · High: 0 · Medium: 0 → нет · Документ:
docs/reviews/SPEC-REVIEW-174-r1.md**