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

# SPEC-REVIEW-107-r1

- **Issue:** https://github.com/Matysh/houseplan-card/issues/107
- **ТЗ под ревью:** `docs/specs/107-virtual-light-toggle.md` (коммит `af851cd`,
  ветка `issue/107-virtual-light-toggle`)
- **Роль:** ревьюер ТЗ (не автор), этап `S4-spec-review`
- **Трек:** обычный (не `small`/`trivial`) — автор корректно не поставил `small`:
  задача вводит новый backend WS-контракт, отдельное operational-хранилище и
  новый UX-контракт target preview, что прямо нарушает критерии §5 PROCESS.md
  («нет нового UX-контракта», «нет влияния на touch»)
- **Цикл:** r1/4

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

Проверялось соответствие ТЗ:

- `docs/SCOPE.md` — попадание в Core user jobs (J1/J3), сохранение
  замороженного статуса virtual devices, lock-инвариант;
- `PROCESS.md` §2.4, §2.5 (DoR), §7.1 (обязательные разделы), §12 (запреты);
- `AGENTS.md` — классы файлов, ветка `issue/107-virtual-light-toggle`, трейлеры;
- `docs/LIGHT.md` и `docs/DEVICE-LIGHT-SETTINGS-MATRIX.ru.md` — канон модели
  источника света, passive `Always`, OR-контракт controllers (#84/#88);
- `docs/CONFIG-COMPATIBILITY.md` — образец, каким должен быть раздел
  compatibility (old/new matrix, `decision-required`/`deprecated-read` и т.п.);
- `docs/TOUCH-SUPPORT.md` и `docs/UX-MODES.md` — блокирующий View/kiosk-контракт,
  разрешённые tap-действия;
- `docs/USER-GUIDE.ru.md` — терминология «Переключить состояние», роль
  «Всегда», «Виртуальное устройство»;
- фактическому состоянию кода (`src/devices.ts`, `src/device-toggle.ts`,
  `src/types.ts`) — на предмет того, что технический диагноз ТЗ (§3) не
  является непроверенной догадкой, а описывает существующий код.

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

1. Прочитан весь тред issue #107: тело issue (черновик AC1–AC4, явное решение
   владельца «обрабатывать как частный случай, не обобщать»), комментарий
   аналитики Q1–Q3 с default-ответами, комментарий владельца от 14.08.2026,
   фиксирующий Q1–Q3 без изменений (`#107#issuecomment-5287719167`), и
   комментарий «ТЗ готово».
2. Прочитан `docs/SCOPE.md` целиком: Core user jobs J1/J3, «Excess-functionality
   audit» (virtual devices — «keep, frozen (no growth)»), lock-инвариант,
   правило «никогда не удалять файл пользователя по догадке» (не касается этой
   задачи — файлов не удаляет).
3. Построчно сверены обязательные разделы ТЗ (§7.1 `PROCESS.md`) — таблица ниже.
4. Прочитан `src/device-toggle.ts` целиком, в частности `resolveToggleIntent()`
   (:590–621) и `resolveOwnEntity`/`ownRoleCandidates` (:355–419): подтверждено
   дословно то, что описывает §3 ТЗ — виртуальный marker с `tap_action=toggle`
   не имеет кандидатов в `ownRoleCandidates` (нет `bindingRef`/`entities`), и
   `resolveOwnEntity` возвращает `null`, что даёт `emptyIntent(origin,
   'no-actionable-entity')` через ветку `device.virtual || device.bindingKind
   === 'virtual'` (:616–619) — **независимо от `is_light`**. Это важно: ТЗ
   обязано менять поведение только для точной тройки, а не для любого
   virtual+toggle, и код подтверждает, что сегодня Auto/Never virtual с
   toggle-действием получают тот же `no-actionable-entity` тем же путём — AC1/
   AC3 корректно требуют, чтобы для них ничего не менялось.
5. Прочитан `resolvedLightSources()` (`src/devices.ts`:450–565), включая
   создание passive-источника `marker:<id>` с `passive: !candidate.eid` и
   `on: candidate.eid ? … : true` (:487–493) и OR-контракт контроллеров
   (:525–532: `source.on = !control?.linked || […].some(eid => … === 'on')`).
   Совпадает дословно с §3 п.1–2 и §6.3 ТЗ.
6. Прочитан `lightGraphFingerprint`/`lightStateFingerprint`
   (`src/devices.ts`:331–354) — оба фингерпринта сегодня не содержат никакого
   поля мануального override для virtual-источника. Это подтверждает
   техническую необходимость AC14 (новая runtime-revision обязана войти в ключ
   кэша) — без неё один tap не вызвал бы инвалидацию `resolvedLightSources()`,
   и Glow остался бы старым до следующего HA state tick, чего в системе для
   virtual-маркера никогда не происходит. Идея «мутантного теста» в §15.1.5
   (удаление revision из ключа кэша должно ронять тест) — конкретный и
   проверяемый способ закрыть именно этот риск.
7. Прочитан `docs/LIGHT.md` (раздел «Source, state and service identity») —
   тройная идентичность `key`/`stateEids`/`serviceEids`, три-стейт `is_light`,
   passive forced source, OR нескольких controllers — всё описанное в §3/§6
   ТЗ дословно совпадает с каноном, ничего не придумано заново.
8. Прочитан `docs/DEVICE-LIGHT-SETTINGS-MATRIX.ru.md` — матрица про
   Live/Ручн./R (цвет, яркость, радиус) не про on/off-агрегацию; задача явно
   не трогает geometry/color/brightness/radius (§13 «Не входит»), поэтому
   отсутствие правки этого файла в release-артефактах (§17 ТЗ) корректно —
   изменения принадлежат `docs/LIGHT.md`, что там и указано.
9. Прочитан `docs/CONFIG-COMPATIBILITY.md` целиком как образец формата
   compatibility-записи. §12 ТЗ («отдельный optional operational Store version
   1», «отсутствие = пустой off-set/on», «operational state не входит в
   export») по форме и содержанию соответствует принятому в проекте стилю
   (сравнимо с разделами «Per-marker light role», «marker.controls[]»).
10. Прочитан `docs/TOUCH-SUPPORT.md` («View is fully supported… must be
    convenient and reliable», «Kiosk — primary supported environment») и
    `docs/UX-MODES.md` («device tap (info / more-info / toggle per settings)» —
    разрешённое View-взаимодействие). §10 ТЗ формулирует touch/kiosk как
    блокирующие поверхности этими же словами, не эскалируя и не изобретая
    более строгий контракт, чем канон.
11. Проверена терминология `docs/USER-GUIDE.ru.md` (строки 467–470, 553–562):
    «Переключить состояние», «Является источником света: Авто/Всегда/Никогда»,
    «виртуальный маркер» — ТЗ использует ровно эти термины.
12. Проверены существующие i18n-ключи `marker.toggle_none_*` и
    `marker.toggle_effect_turn_on/off` (`src/i18n/ru.json`) — новые ключи,
    которые требует §9 ТЗ, логически продолжают уже принятую схему именования,
    а не вводят параллельную.
13. Проверена запись в `docs/specs/README.md:81` — строка на #107 присутствует
    в том же коммите, ссылка issue ↔ ТЗ двусторонняя.
14. Прочитан `docs/types.ts` — поле `tap_action`/`tapAction` существует ровно
    в том виде, на который ссылается §5 ТЗ («effective tap action равен
    `toggle`»).
15. Проверено количество и релевантность 16 AC (§14) — каждый несёт явный тип
    доказательства (`unit`/`backend`/`smoke`/«ревью кода»/`build`) из
    допустимого по DoR перечня; ни один AC не двусмысленен относительно того,
    какое конкретно поведение проверяется.

## Обязательные разделы (§7.1 PROCESS.md)

| Раздел | Есть | Комментарий |
|---|---|---|
| Сценарий (персона/поверхность/момент) | ✅ | §1 |
| Что человек увидит до/после | ✅ | §2, без терминов реализации |
| Проблема | ⚠️ частично | Явно как отдельный заголовок отсутствует; фактически покрыта §2 («до») и §3 («подтверждённая причина текущего поведения») — см. Low-1 |
| Скоуп / не-скоуп | ✅ | §5 (точное условие) / §13 |
| Контракт поведения | ✅ | §5–§8 |
| UX / i18n / accessibility / touch | ✅ | §9, §10 |
| Модель данных и миграция | ✅ | §12 |
| AC1…ACn с доказательством | ✅ | §14, 16 штук, каждый типизирован |
| План автотестов | ✅ | §15 |
| Риски | ❌ отсутствует как раздел | Риск-релевантный материал есть (fail-safe §7.5, security-граница §16, сложность 7/10 в шапке), но не сведён в один раздел с явной привязкой риск → закрывающий AC, как это сделано, например, в `SPEC-REVIEW-131-r1` — см. Low-2 |
| Откат | ✅ | §18 |
| Release-артефакты | ✅ | §17 |

Десять из двенадцати обязательных разделов присутствуют и содержательны;
два («Проблема», «Риски») по факту не выделены отдельным заголовком, хотя
материал по существу распределён по документу. Дополнительно есть корректно
обособленный §19 «Принятые технические предположения» — граница между
продуктовыми решениями (принятыми владельцем в Q1–Q3) и свободно
пересматриваемой техникой проведена явно, ни одна догадка не выдана за факт
без пометки.

## Находки

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

### Low-1 — раздел «Проблема» не выделен отдельно

**Файл:** `docs/specs/107-virtual-light-toggle.md` (между §2 и §3)

Формально PROCESS.md §7.1 перечисляет «проблема» отдельным пунктом в списке
обязательных разделов. В документе нет заголовка с этим названием — «до»
(§2) и технический диагноз (§3) вместе дают эквивалентное содержание, но
читатель, ищущий формулировку «в чём проблема» одним куском, должен собрать
её из двух разделов и самого issue.

**Почему не блокирует:** содержание есть и оно точное (см. «Как проверялось»
п.4) — диагноз в §3 построчно совпадает с реальным кодом, не является
догадкой. Это вопрос оформления, а не отсутствия решения.

**Решение ревьюера:** Low, не блокирует, снимается с записью. На усмотрение
автора — при следующей правке можно дать §2/§3 общий подзаголовок «Проблема»,
либо оставить как есть.

### Low-2 — нет консолидированного раздела «Риски»

**Файл:** `docs/specs/107-virtual-light-toggle.md`

Сложность/риск задачи оценены автором в 7/10 (шапка документа), но в отличие
от, например, `docs/specs/131-readonly-cold-start.md` (§14 «Риски», 5 пунктов,
каждый со ссылкой на закрывающий AC), здесь риск-релевантные утверждения
рассеяны по документу без единого места: fail-safe при revision gap (§7.5),
границы trust boundary (§16), решение о хранении вместо конфигурации (§4 п.1).
Отсутствует явное перечисление, например: «риск: два отдельных HA `Store`
могут разойтись при crash между save — закрыт §7.5 fail-safe reset + AC9»,
«риск: canonical-кэш не инвалидируется без HA tick — закрыт AC14 + мутантный
тест §15.1.5», «риск: manual state перекрывает controller и наоборот путает
пользователя — закрыт §6.3 + AC5/AC12».

**Почему не блокирует:** каждый реальный риск, который я смог определить при
чтении кода и канона, оказался закрыт конкретным AC или конкретным разделом
контракта (перечислено выше) — отсутствует сам факт непокрытого риска, не
хватает только сведения их в один раздел для читаемости и трассируемости.

**Решение ревьюера:** Low, не блокирует, снимается с записью. Рекомендация
автору — на следующей правке (не обязательно в этом цикле) собрать
существующие риск-утверждения в один раздел «Риски» с явной ссылкой
риск → AC, по образцу `SPEC-REVIEW-131-r1`.

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

- **Соответствие `docs/SCOPE.md`.** Задача закрывает J1 (Glow/room fill/room
  stats — одно пространственное состояние) и J3 (очевидное безопасное
  действие прямо с плана). Она не расширяет «замороженный» статус virtual
  devices в общий state engine — владелец явно одобрил именно узкое
  исключение в теле issue («не превращать в системный механизм»), и §1/§5 ТЗ
  формулируют условие исключения как точную тройку, без обобщения на другие
  роли/действия. Lock-инвариант не затронут: virtual target никогда не
  резолвится в secure entity или HA service (§8.1, §16) — соответствует
  правилу SCOPE.md «любой новый путь актуации либо отказывает locks, либо
  добавляется явным абзацем в SCOPE.md» (здесь второе не требуется, так как
  путь и так отказывает).
- **Продуктовые вопросы закрыты владельцем, не додуманы автором.** Q1
  (жизненный цикл/синхронизация), Q2 (что именно переключается — canonical
  state, а не только Glow) и Q3 (приоритет manual state над controller links)
  — все три явно продуктовые («что видит/делает пользователь», «что считается
  этим же issue»), заданы одним комментарием с default-вариантами и приняты
  владельцем дословно 14.08.2026. Открытых продуктовых вопросов в финальной
  редакции нет — и это корректно, а не подозрительно: они были заданы и
  закрыты на этапе аналитики, а не пропущены.
- **Раздел §19 корректно отделяет технику от продукта.** Все 8 пунктов
  (имя Store/класса, механизм доставки initial state, форма typed intent,
  раскладка подписок, поведение local cache, консервативный reset вместо
  угадывания истории, hidden vs tombstone, поведение импорта) — техническая
  реализация уже принятых продуктовых решений Q1–Q3, ни один пункт не прячет
  продуктовое решение под видом «технического предположения».
- **Техническая точность диагноза (§3) подтверждена чтением кода**, не
  является голословным утверждением автора: `resolveToggleIntent()`,
  `resolvedLightSources()`, `lightGraphFingerprint`/`lightStateFingerprint` —
  все три технических утверждения совпадают построчно с текущим `src/devices.ts`
  и `src/device-toggle.ts` (см. «Как проверялось» п.4–6).
- **Точность границы исключения.** Код подтверждает, что сегодня *любой*
  virtual marker с `tap_action=toggle` (Auto/Never/Always) получает
  `no-actionable-entity` одним и тем же путём (`resolveOwnEntity` → `null`);
  §5 ТЗ и AC1/AC3 корректно требуют не менять этот путь для Auto/Never, а не
  просто «для не-Always», что было бы более рискованной (и не запрошенной)
  формулировкой.
- **Canonical single-consumer contract (§6.2, AC5/AC6) методологически верный
  ответ на риск дублирования источника истины.** Проверено, что
  `resolvedLightSources()` — уже сегодня единственный вход для Glow, room fill,
  room stats, preview и `houseplan-space-card» (docs/LIGHT.md, «Source, state
  and service identity»); требование ТЗ не создавать отдельную ветку в
  рендерере, room card, preview или static card прямо предотвращает
  повторение уже случившегося в проекте расхождения слоёв (см. историю
  «layered model» в docs/LIGHT.md).
- **Кэш-инвалидация (AC14) — не декоративное требование.** Подтверждено, что
  без явного добавления runtime-revision в `lightStateFingerprint`
  манипуляция чисто виртуальным состоянием (без единой реальной HA entity)
  физически не имеет другого триггера инвалидации кэша — HA state tick для
  virtual marker никогда не придёт. План теста §15.1.5 («мутантный» тест,
  который обязан упасть при удалении revision из ключа кэша) — конкретное и
  проверяемое требование именно к этому риску, соответствует принятой в
  проекте дисциплине «тест должен уметь падать».
- **Touch/View/kiosk-контракт (§10) сформулирован дословно по канону**
  (`docs/TOUCH-SUPPORT.md`, `docs/UX-MODES.md`), не эскалирован и не ослаблен.
- **Терминология UX/i18n (§9) взята из `docs/USER-GUIDE.ru.md`**, не
  изобретена; новые ключи логически продолжают существующую схему
  `marker.toggle_none_*`/`marker.toggle_effect_*`.
- **Compatibility (§12) не вводит миграцию config/marker/export**, что
  соответствует и явному решению владельца (Q1: «operational data, не входит
  в config/export») и общему принципу `docs/CONFIG-COMPATIBILITY.md` —
  отдельный versioned Store, а не новое поле в `Marker`.
- **Не-скоуп (§13) корректно отсекает обобщение**, прямо запрещённое
  владельцем в теле issue: общий state engine для virtual devices, действие
  для других ролей/actions, создание `input_boolean`/synthetic entity,
  управление цветом/яркостью/радиусом через tap.
- **Release-артефакты (§17) перечисляют реальные существующие файлы**
  (`docs/CHANGELOG.md`/`.ru.md`, `docs/USER-GUIDE.ru.md`, `README.md`,
  `docs/LIGHT.md`, `docs/ARCHITECTURE.md`, `docs/CONFIG-COMPATIBILITY.md`, три
  bundle snapshot) — ни один не выдуман.
- **Реестр `docs/specs/README.md`** обновлён тем же коммитом, ссылка issue ↔
  ТЗ двусторонняя.
- **Трейлеры коммита `af851cd`** (`Issue: #107`, `User-Visible: no` —
  ожидаемо, так как коммит правит только ТЗ) корректны для документационного
  коммита; продуктовый код действительно не тронут (подтверждено и текстом
  ТЗ, и комментарием «ТЗ готово»: «продуктовый код не менялся»).

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

- Не проверял, реализуем ли предложенный backend design (§7: общий
  load-modify-save lock между config и operational store, атомарный WS
  toggle) без побочных эффектов на существующие писатели конфигурации — по
  §19 п.1/п.6 ТЗ это свободно изменяемое техническое предположение автора
  кода и предмет код-ревью, а не ревью ТЗ.
- Не запускал никаких автотестов, не собирал бандл и не проверял backend на
  Python — на этапе `spec` это не требуется; все технические утверждения,
  которые проверялись, проверены чтением существующего TypeScript-кода, не
  исполнением.
- Не проверял golden/скриншоты — ТЗ §15.4 явно и обоснованно откладывает их
  до pre-beta gate (переиспользуется существующая flat-сцена, новый
  художественный baseline не проектируется).
- Не проверял детали Python-реализации `houseplan.virtual_lights` (имя класса,
  формат хранения) — §19 п.1 прямо помечает точные имена как свободно
  изменяемые технические детали.
- Не проверял полноту 127 browser-smoke сценариев и не запускал ни одного —
  на этапе ревью ТЗ это не требуется и не относится к гейтам код-ревью §8
  PROCESS.md; целевой smoke-сценарий (§15.3 ТЗ) описан достаточно конкретно
  (одна eligible лампа, один контроллер, один независимый источник, две full
  card и одна static card) для последующей проверки на этапе код-ревью.
- Не проверял, действительно ли предложенный «typed operational target»
  (§8.1) может быть добавлен в `ResolvedToggleIntent` без расширения его типа
  несовместимым образом — вопрос реализации, накрытый AC6 и предметом
  код-ревью.

## Вердикт

Зелёный. High: 0, Medium: 0. Две находки Low — (1) раздел «Проблема» не
выделен отдельным заголовком, содержание фактически распределено по §2/§3;
(2) риск-релевантный материал не сведён в консолидированный раздел «Риски»
со ссылками риск → AC. Обе не блокируют: содержание по существу присутствует
и подтверждено построчной сверкой с реальным кодом и каноном подсистемы,
открытых продуктовых вопросов нет (Q1–Q3 закрыты владельцем 14.08.2026), AC
однозначны и типизированы, скоуп/не-скоуп точно повторяют явное решение
владельца «не обобщать». Обе находки сняты с записью в этом документе, на
усмотрение автора учесть при следующей правке.