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

# Код-ревью issue #103 · цикл r1/4

Toggle confirmation: показывать текущее и ожидаемое состояние.

- **Issue:** https://github.com/Matysh/houseplan-card/issues/103
- **ТЗ:** `docs/specs/103-toggle-confirmation-state.md`, принято зелёным
  `docs/reviews/SPEC-REVIEW-103-r1.md`
- **Диапазон:** `origin/dev..HEAD`, 3 коммита
  (`a449edc` ТЗ, `6c7958c` ревью ТЗ, `9327737`/`9327737...cf` реализация)
- **Ревьюер:** Claude, свежая сессия без контекста реализации

## Скоуп

Диапазон изменил:

- `src/device-toggle.ts` — новый pure `formatToggleConfirmation()` и тип
  `ToggleConfirmationFormatter`; `resolveToggleIntent`/резолвер не менялись;
- `src/houseplan-card.ts` — `_tapConfirm` расширен до discriminated union
  `{kind:'toggle', lines, initialIntent, deviceId, exec}` /
  `{kind:'run', text, exec}`; новый `_toggleConfirmationLines()` и
  `_toggleConfirmationStateText()`; шаблон диалога рендерит `lines` для toggle
  и прежний `<p>` для run;
- `src/styles.ts` — `.tapconfirm-body`/`.tapconfirm-line` (перенос длинных
  строк, нет горизонтального скролла);
- `src/i18n/en.json` + `src/i18n/ru.json` — 15 новых ключей `confirm.*` в обоих
  файлах;
- `test/device-toggle.test.mjs` — юнит-тесты форматтера;
- `demo/smoke_toggle_confirmation.mjs` — новый браузерный смок;
- `docs/CHANGELOG.md` / `docs/CHANGELOG.ru.md`, `docs/USER-GUIDE(.ru).md`,
  `docs/TESTING.md`, `docs/specs/README.md` — документация и changelog в
  том же коммите, что и поведение;
- три копии бандла (`dist/`, `custom_components/.../frontend/`,
  `demo/srv/assets/`) и `docs/images/screenshots.json` (обновление
  `sourceFingerprint`/`sourceSha256`, `imageSha256` каждого сценария не
  изменился — визуальный контент прежний).

Соответствует `docs/SCOPE.md` J3 («tap-to-toggle for safe domains») и не
задевает lock invariant: secure-цели (`lock`/`alarm_control_panel`/guarded
`cover`) резолвер отфильтровывает раньше формирования intent, `toggleOperation`
для них `null`, confirmation не открывается — новая ветка кода это условие не
меняет.

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

| Гейт | Команда | Результат |
|---|---|---|
| Typecheck | `npx tsc --noEmit` | green |
| Unit | `npm test` | 880/880 green |
| Build + сверка бандлов | `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` | green, три копии идентичны |
| Целевой browser smoke (AC1,3,6,7,8,9) | `node demo/smoke_toggle_confirmation.mjs` | green, все 9 подпроверок true |
| Регрессия смежных confirmation-путей | `node demo/smoke_cover_tap.mjs`, `node demo/smoke_virtual_light_toggle.mjs`, `node demo/smoke_tap_run.mjs`, `node demo/smoke_ha_controls.mjs`, `node demo/smoke_controls.mjs` | все green |
| Golden | `npm run golden:verify` (свежий бандл) | 100% `passed`, 0 failed/error — новых сценариев dialog нет, стили аддитивны и не задели существующие сцены |
| i18n-паритет | `node -e "..."` сравнение ключей `en.json`/`ru.json` | равны, расхождений нет |
| Process gate | `node scripts/process-gate.mjs` | «гейт пройден, предупреждений 0» (без `--issues`, офлайн-часть) |
| Backend | не прогонялся | `custom_components/**/*.py` в диффе нет — гейт не применим |
| Performance-профили | не прогонялись | не названы в AC, изменение — только текст/CSS диалога |

**Дисциплина «тест умеет падать» — проверено для прогнанных тестов:**

- временно нейтрализовал ветку `isGroup && nextEffect==='turn-on'` в
  `formatToggleConfirmation` → `npm test` дал `not ok 159` (тест группы), после
  отката снова 880/880;
- временно подменил `closed → confirm.state_open` в
  `_toggleConfirmationLines` → `node demo/smoke_toggle_confirmation.mjs` дал
  `englishCurrentExpected: false` и `russianCurrentExpected: false`, после
  отката снова все 9 true и бандлы пересобраны/сверены заново.

## AC — разбор

| AC | Доказательство | Вывод |
|---|---|---|
| 1. current/expected lines для исполняемой цели | unit `toggle confirmation formats every next effect...`; smoke `englishCurrentExpected`/`russianCurrentExpected` | подтверждено |
| 2. expected строго по `nextEffect`, не по домену | unit-тест перебирает все `ToggleNextEffect` на одном intent с фиксированным `state`; чтение `formatToggleConfirmation` — ветвление только по `nextEffect`/`isGroup`, не по domain/semantics | подтверждено |
| 3. локализация power/cover/valve/virtual/group | unit (partial/all-off group, virtual) + smoke `englishGroupAndVirtualCopy`, RU/EN рендер | подтверждено |
| 4. partial group не обещает изменение skipped | unit `describes executable group targets and skipped targets separately` (denominator = только `targets`, skipped — отдельная строка); проверено на способность теста падать | подтверждено |
| 5. `toggle` → «решит HA» | unit-тест `nextEffect: 'toggle'` → `expected:by-ha` | подтверждено |
| 6. no-op не открывает confirmation | smoke `noOperationDoesNotOpen` (guarded cover, secure no-op) | подтверждено |
| 7. Confirm выполняет заново разрешённый intent | smoke `sameTargetUsesCurrentDirection` (cover меняет state closed→open между открытием и подтверждением, выполняется `close_cover`, а не команда снимка) | подтверждено |
| 8. смена target set отменяет actuation, старый toast | smoke `changedTargetCancels` (переброс bindingRef на другую cover-сущность → 0 service calls, `toast.tap_target_changed`) | подтверждено |
| 9. desktop/mobile, keyboard, screen-reader order | smoke `accessibleDomOrder` (`dialog.title === текст вопроса`, `data-line 0/1`, 2 кнопки) + `narrowDialogDoesNotScrollHorizontally` на 390px; keyboard focus/Escape/scrim — **проверено чтением, не исполнением**: `dismiss-on-scrim`, `@hp-close` и структура footer/кнопок в диффе не изменены | подтверждено (смок + чтение) |
| 10. run/другие confirmations не регрессируют | smoke `smoke_tap_run.mjs` green; чтение шаблона — ветка `kind==='run'` рендерит тот же `<p>{text}</p>` с тем же заголовком `btn.run`, что и раньше | подтверждено |

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

- Инвариант lock/alarm/guarded-cover не тронут: секьюрные цели отфильтровываются
  резолвером `#94` до формирования `nextEffect`/`targets`, confirmation для них
  не строится ни при каком новом коде.
- `formatToggleConfirmation` — чистая функция, не знает про HA/DOM; вся i18n и
  HA-formatter-специфика инкапсулированы в `_toggleConfirmationStateText`/
  `_toggleConfirmationLines` в `houseplan-card.ts`, как и требовало ТЗ §5
  («`houseplan-card.ts` не выводит next state по domain самостоятельно»).
- Direction всегда берётся из `intent.nextEffect`, не из `currentState` —
  единственный источник расчёта — резолвер #94; UI не дублирует его логику.
- Denominator группы — количество фактических `targets` (`byEntity` без
  skipped), а не число сконфигурированных ссылок; skipped выводится отдельной
  строкой и не входит в «включено N из M».
- Race-контракт #94 не нарушен: `exec()` заново находит `currentDevice` →
  пересчитывает intent → сравнивает через `sameToggleOperationTargets` с
  исходным снимком; при совпадении целей выполняется **текущее**
  направление/команда (не снимок на момент открытия).
- `run`-подтверждение осталось на прежней простой форме (`text` + `<p>`),
  discriminated union не заставил его притворяться toggle — ТЗ §7 требование
  выполнено буквально.
- i18n: все 15 новых ключей присутствуют в обоих словарях; в целом по файлам
  `en.json`/`ru.json` расхождений ключей нет.
- Три копии бандла синхронны (`cmp` byte-for-byte), `docs/images/screenshots.json`
  обновил только fingerprint/sourceSha256 — `imageSha256` каждого сценария не
  изменился, то есть визуальный результат существующих сцен не задет; отдельного
  golden-сценария для диалога не требовалось (ТЗ §11 — narrow smoke покрывает).
- Оба changelog правлены в том же коммите, что и поведение (`932773773f0b`),
  трейлеры `Issue: #103`/`User-Visible: yes|no` на месте на всех трёх коммитах.

## Находки

Ни одной High/Medium-находки. Три ранее отмеченные Low из ревью ТЗ
(`SPEC-REVIEW-103-r1.md`) не имеют кодового следствия — направление в рантайме
берётся из `nextEffect`, а не из нормативной таблицы ТЗ, поэтому неточность
таблицы (`closing` в одной строке с `open`) не воспроизвелась в коде.

- **Low (снято, без правки).** `houseplan-card.ts`, ветка
  `if (actionDevice.marker?.tap_confirm) { const lines = this._toggleConfirmationLines(initial); if (!lines.length) return; ... }`
  — защитный `if (!lines.length) return` недостижим при нынешних инвариантах
  резолвера: везде, где `toggleOperation(intent)` истинен (единственное условие,
  пропущенное раньше по коду), у intent уже гарантированно есть `nextEffect` и
  `targets.length >= 1` (прослежено по всем веткам `resolveToggleIntent`/
  `resolveGroupEntities`/virtual-light intent). Формально это тихий no-op вместо
  открытия диалога, если бы условие когда-нибудь стало достижимым, но сегодня
  это мёртвый код, а не наблюдаемый дефект. Правка не требуется; снимаю с
  записью здесь, как того требует §8/§12 процесса.

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

- **Backend** (`python -m pytest tests_backend`) — не прогонял: диапазон не
  затрагивает ни одного файла `custom_components/**/*.py`.
- **Performance-профили** — не прогонял: AC их не называет, изменение не
  трогает чувствительные к перфу пути (только текст диалога и аддитивный CSS).
- **Полный набор из 127 браузерных смоков** — прогнал только целевой
  (`smoke_toggle_confirmation`) плюс пять смежных по confirmation/cover/virtual-
  light/run поверхности; остальные 121 не запускал — diff не задевает
  геометрию, wall-thickness, canvas, sun/light рендер и т.д., которые они
  покрывают.
- **Ручная проверка в реальном браузере вне demo-харнесса** (реальный screen
  reader, реальная Tab-навигация) — не выполнялась; keyboard/Escape/scrim
  утверждение AC9 закрыто чтением кода (структура диалога не менялась), как и
  предусмотрено самим ТЗ («narrow browser smoke + code review»).
- **`node scripts/check-docs.mjs --external`** — не перепрогонял; автор в
  хендоффе указал green, доверяю без повторного запуска (внешний, не входит в
  обязательный набор ревью).
- **`process-gate.mjs --issues`** (сетевая проверка статуса issue через `gh`) —
  не прогонял с токеном; офлайн-часть (`process-gate.mjs` без флага) прошла
  чисто.

## Вердикт

Зелёный. Все 10 AC доказаны — юнитами/смоками, которые я прогнал и убедился,
что они умеют падать, либо явным «проверено чтением, не исполнением» там, где
так предусмотрено самим ТЗ (клавиатура/screen-reader в AC9, идентичность
`run`-ветки в AC10). High: 0, Medium: 0. Единственная Low-находка — недостижимая
защитная ветка — снята без правки, с записью выше.

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