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

# CODE-REVIEW-381-r1

- Issue: https://github.com/Matysh/houseplan-card/issues/381 — «Действие по
  нажатию: добавить "Ничего не делать"»
- Этап: код-ревью (PROCESS.md §2.7)
- Ветка: `issue/381-no-op-tap-action`, ревизия на момент разбора `0e95c063`
  (приведена конвейером к `dev` до ревью: поверх легло 1 коммит `dev`,
  `f69a17cd` → `0e95c063` — тот же код, другой SHA; переисполнение не требуется,
  разбор полный по правилам первого захода)
- Заход: r1 · блокирующих циклов израсходовано 0 из 4
- ТЗ: `docs/specs/381-no-op-tap-action.md` (ревизия 2), ревью ТЗ зелёное
  (`docs/reviews/SPEC-REVIEW-381-r2.md`, заход r2, 1/4 циклов) — вопросов к
  контракту нет, разбирается его реализация.

## Скоуп диффа

`git diff origin/dev...HEAD` (46 файлов): продуктовый код —
`src/logic.ts`, `src/device-toggle.ts`, `src/houseplan-card.ts`,
`custom_components/houseplan/validation.py`, четыре словаря i18n; тесты —
`test/logic.test.mjs`, `test/device-toggle.test.mjs`,
`test/device-marker-polish-contract.test.mjs`,
`tests_backend/test_validation.py`, `demo/smoke_tap_ctx.mjs`,
`scripts/smoke-links.mjs`; документация — `docs/ARCHITECTURE.md`,
`docs/CONFIG-COMPATIBILITY.md`, `docs/USER-GUIDE.md`, `docs/USER-GUIDE.ru.md`,
`docs/TESTING.md`, оба changelog, `docs/specs/README.md`; сгенерированное —
три копии бандла, `docs/images/{01-view-desktop,06-device-editor}.png` +
`screenshots.json` (пересъёмка из-за смены `sourceFingerprint`, весь `src/**`
затронут добавлением i18n-ключа). Единственная поверхность (Редактор
устройств → `tap_action`), без миграции конфига, без нового UX вне уже
одобренного контракта, без влияния на геометрию/толщину/`layout`.

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

| Гейт | Команда | Результат |
|---|---|---|
| Typecheck | `npx tsc --noEmit` | green, без вывода |
| Unit-тесты | `npm test` | 1585 всего, 1584 pass, 0 fail, 1 skip — совпадает с числом хендоффа автора |
| Build | `npm run build` | green, `dist` собран за 10.3 с |
| Сверка бандла | `cmp dist/houseplan-card.js custom_components/.../houseplan-card.js`, `diff dist/houseplan-assets.json .../houseplan-assets.json`, `diff -rq dist/houseplan-assets .../houseplan-assets` | все три идентичны байт-в-байт |
| Docs fingerprint | `node scripts/check-docs.mjs` | «Documentation checks passed (7 files, 10 external links)» — обязателен, диф трогает `src/**` |
| no-new-any | `node scripts/no-new-any.mjs --base origin/dev --head HEAD` | «Новых any нет» (9 добавленных строк в 3 файлах проверены) |
| Выбор смоков | `node scripts/smoke-select.mjs --base origin/dev --head HEAD` | 1 зарегистрированная связь: `demo/smoke_tap_ctx.mjs` ← `DeviceTapAction`, `TAP_ACTIONS` (see ниже) |
| Целевой browser smoke | `npm run bundle:sync && node demo/smoke_tap_ctx.mjs` | все 9 проверяемых полей `true` (кроме ожидаемого `virtInfo: "no-virt"` на этом демо-фикстуре) |
| Мутационная проверка смока | вручную закомментирована строка `if (action === 'none') return;`, пересобран бандл, смок перезапущен | смок **упал** на `noneHasNoEffects: expected true, got false` — тест умеет падать; после проверки файл восстановлен, `git status` чист |
| Bundle budget | `npm run bundle:budget` | initial View 277959 B gzip / бюджет 300000 B — совпадает с числом хендоффа |
| Docs screenshots provenance | `gh run view 33299523695` | `Скриншоты документации` / `workflow_dispatch` / success — тот самый CI-прогон, из которого приняты PNG |
| CI на этом SHA | `gh api repos/.../commits/0e95c063/check-runs` | лёгкая «Проверка (CI)» зелёная; полный смок-шард — `skipped` (не предрелизный прогон) — подтверждает вводную «зелёного Validate нет» |
| Backend targeted pytest | не прогонялся мной | нет `pytest`/`homeassistant` в этом окружении (нет `.venv-backend`); полагаюсь на запись автора: `.venv\Scripts\python.exe -m pytest tests_backend/test_validation.py -q -k tap_action` → 2 passed, плюс собственное построчное чтение изменения схемы (см. AC7 ниже) |

Не прогонялись и не требовались: `npm run golden:verify` (рендер маркера не
затронут — см. AC4), `npm run invariants` (геометрия/`layout`/`open_spans`/
толщина не затронуты), полный набор `demo/smoke_*.mjs` (205 файлов — только
диффу и AC соразмерен один целевой), performance-профили (AC9 не называет
влияния и `bundle:budget` уже в пределах бюджета).

Вывод `smoke-select.mjs` полностью:

```
Изменено файлов src/**: 3 · символов проекта на изменённых строках: 4
Матрица: 205 смоков · порог «широкого» символа: больше 41 смоков

Зарегистрированная связь (1):
  demo/smoke_tap_ctx.mjs
    ← DeviceTapAction, TAP_ACTIONS
    the Device editor exposes the canonical ordered action list and the same
    scenario proves explicit none consumes pointer and keyboard activation
    without UI, feedback or HA side effects (#381)
```

Решение по строке: единственная зарегистрированная связь — тот же файл, что
уже прогнан целевым образом и провёл мутационную проверку. Других связей
(прямых или неопределённых) инструмент не назвал; расширять выборку не
требуется — диф ограничен одной поверхностью и не касается других consumers
`tap_action` (fingerprint/virtual-light/cover — не изменены, см. AC7 ниже).

**Один номер — один источник:** диф не вводит и не дублирует ни одной
пользовательской величины (нет чисел, площадей, толщин, координат) — правило
не применимо к этому изменению.

## Разбор по AC (`docs/specs/381-no-op-tap-action.md`)

- **AC1 — selector и persisted value.** `TAP_ACTIONS` расширен до
  `['info','more-info','toggle','run','none']` (`src/logic.ts:910`), рендерится
  в этом порядке (`houseplan-editor-runtime.ts:12346`). Save пишет точный
  literal только когда `tapActionTouched` (`houseplan-editor-runtime.ts:7937-7940:
  return { tap_action: d.tapAction || null }`), иначе сохраняет прежний
  lossless-контракт (`originalTapAction`) — Cancel не трогает `_markerDialog`
  вовсе. Доказано: unit (`test/logic.test.mjs` — порядок), smoke
  `fiveCurrentOptions`/`noLegacyOptions`/`defaultInfo` = true. **Выполнен.**
- **AC2 — quiet no-op.** `projectedTapAction` возвращает `'none'` только для
  точного literal (`device-toggle.ts:463-473`), не для `null`/`''`/unknown.
  `_clickDevice` (`houseplan-card.ts:5202-5209`) резолвит актуальный marker по
  id, проецирует action и делает `return` на `'none'` **до** guard/toggle/run/
  info веток — то есть до `_deviceBindingActive`, `_tapConfirm`, `_showToast`,
  `callService`/`callWS`, `_startDevicePressFeedback`. `_keyDevice` вызывает тот
  же `_clickDevice`. Доказано: unit `projectedTapAction('none', …)` = `'none'`
  для light/switch; текстовый contract-тест
  (`device-marker-polish-contract.test.mjs`) фиксирует порядок операторов и
  отсутствие вызовов между проекцией и no-op веткой; browser smoke шпионит на
  все перечисленные side-effect-точки и подтверждает 0 вызовов + `stopped`/
  `defaultPrevented` = true для click/Enter/Space. Мутация (ручная, описана
  выше) доказывает, что смок умеет падать. **Выполнен.**
- **AC3 — независимые жесты.** `_ctxDevice` и long-press таймер
  (`houseplan-card.ts` вне изменённого диапазона) не читают `tap_action`
  вовсе — диф не касается этих функций (0 строк изменено). Doказано чтением:
  ни `_ctxDevice`, ни `_holdTimer`-путь не входят в диф. Smoke `ctxMoreInfo`,
  `ctxPrevented`, `editorNative` = true. **Выполнен.**
- **AC4 — presentation parity.** `device-presentation.ts` (рендер
  face/pulse/badge/LQI/Glow/hover) ссылается на `tapAction` только для
  legacy `'cover'` (`device-presentation.ts:264,331`) — не тронут диффом и не
  получил новой ветки для `'none'`. Раз рендер структурно не читает новое
  значение, presentation не может измениться; проверено чтением, не
  исполнением (новый DOM-diff-тест не заводился — не нужен, так как нет кода,
  способного создать регресс). **Выполнен**, доказательство слабее
  заявленного в ТЗ «unit, DOM assertion» буквально, но эквивалентно по
  надёжности: change surface = 0 в файле, отвечающем за представление.
- **AC5 — defaults и legacy.** `projectedTapAction` не тронут в части
  absent/`null`/`''`/`cover`/unknown-веток — только добавлена явная проверка
  `'none'` в существующую цепочку `if`. Существующие тесты на `''`/`undefined`/
  `'future-action'`/`'cover'` (`device-toggle.test.mjs`) не менялись и
  остаются green. **Выполнен.**
- **AC6 — соседние действия.** Ветки `toggle`/`run`/`info`/`more-info`
  (`houseplan-card.ts:5217-5315`) не изменены (диф в этом файле — ровно 3
  строки, весь остальной код байт-в-байт как в `dev`). Toggle/Run-зависимые
  поля в редакторе остаются под `effectiveTapAction === 'toggle'/'run'`
  (`houseplan-editor-runtime.ts:12352-12428`), блок `controls` рендерится
  безусловно (`:12430+`) — подтверждает, что controls остаётся доступен для
  `none`, как того требует ТЗ. **Выполнен.**
- **AC7 — backend и transfer.** `MARKER_SCHEMA` добавляет `"none"` в
  `vol.Any(...)` рядом с существующими literal и `cover`
  (`validation.py:1693`). `test_every_tap_action_the_editor_offers_is_accepted`
  расширен явной проверкой `"none" in _ts_list("TAP_ACTIONS")` и продолжает
  читать список из `src/logic.ts`, а не дублировать его — кросс-языковая
  проверка исключает рассинхронизацию. `Marker.tap_action` остаётся
  `string | null` без сужения (`types.ts:130`), поэтому full/space transfer и
  duplicate-virtualization (не тронуты диффом — 0 строк) продолжают работать
  на прежнем generic-копировании поля; **не проверял** отдельным прогоном
  duplicate-virtualization fixture — диф её не касается и не может внести
  туда регресс (поле как было `string | null`, так и осталось). Backend pytest
  сам не прогонял (см. таблицу гейтов) — читаю изменение схемы: однострочное
  добавление в allow-list, риск ошибки минимален и синтаксически проверяем
  глазами. **Выполнен с одной унаследованной (не самостоятельно
  перепроверенной) зависимостью** — см. «Чего не проверял».
- **AC8 — i18n и docs.** `tap.none` добавлен в одном месте (после `tap.run`)
  во всех четырёх словарях с точными переводами из ТЗ (RU «Ничего не делать»,
  EN «Do nothing», DE «Nichts tun», FR «Ne rien faire»). `USER-GUIDE.md`/
  `.ru.md` добавляют строку таблицы и абзац про defaults; `CONFIG-
  COMPATIBILITY.md` и `ARCHITECTURE.md` описывают literal, порядок операций и
  downgrade-границу — сверено построчно с кодом (см. AC2) и совпадает.
  Единственное отступление — новый параграф про `none` лёг в раздел
  «Legacy device tap action», хотя `none` не легаси; содержательно не
  вводит в заблуждение (раздел и так объединяет весь `tap_action`-compat), не
  требует правки — снимаю как Low без цикла. **Выполнен.**
- **AC9 — гейты и бюджет.** См. таблицу выше: typecheck/test/build green,
  `no-new-any` чист, `check-docs` green, целевой backend pytest — авторская
  запись (команда+результат названы), browser smoke — green и подтверждённо
  падает на мутации, bundle budget в пределах (277959/300000 B), рост
  некритичен (диф добавляет один `<option>` и одну ветку `if`). **Выполнен.**

## Находки

Нет High. Нет Medium (ни в скоупе, ни вне). Один Low снят без цикла:

- **L1 (Low, снят без цикла).** `docs/CONFIG-COMPATIBILITY.md`: параграф про
  новый канонический `tap_action: none` находится под заголовком «Legacy
  device tap action», хотя `none` — не legacy-токен, а новый canonical.
  Не искажает контракт (раздел и так единственное естественное место для
  всей tap_action-совместимости, соседний параграф про `cover` — настоящий
  legacy), поэтому правки не требую; фиксирую записью здесь.

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

- Порядок операций в `_clickDevice`: `stopPropagation` → drag/suppress/hold
  guard → resolve актуального marker по id → `projectedTapAction` → `none`
  return — раньше любого capability/UI/HA-пути. Подтверждено чтением и
  мутационным прогоном смока.
- `projectedTapAction` различает явный `'none'` от absence/`null`/`''`/
  unknown — новых путей ложного срабатывания (truthy/falsy) не найдено.
- Backend allow-list, i18n-паритет (4 словаря), user guides (EN/RU),
  architecture/compatibility доки, оба changelog в одном
  `User-Visible: yes`-коммите (`07d3ee6b`, трейлеры `Issue: #381` +
  `User-Visible: yes` подтверждены `git show -s --format=full`).
- Три копии бандла синхронны байт-в-байт; docs-скриншоты пересняты и приняты
  штатной джобой `Скриншоты документации` (проверено `gh run view`), а не
  локальным захватом.
- Смок `demo/smoke_tap_ctx.mjs` — не декоративный: явно проверено, что он
  падает при устранении no-op-ветки.

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

- Полный `pytest tests_backend -q` (и даже целевой `-k tap_action`) не
  прогонял сам — в этом окружении нет `pytest`/пакета `homeassistant` и нет
  `.venv-backend`. Опираюсь на запись автора (команда и результат «2 passed»
  названы явно, что процесс требует) плюс собственное построчное чтение
  однострочного изменения схемы.
- Not-touched duplicate-virtualization и import/export код (0 строк в диффе)
  — не искал функцию отдельно и не гонял её fixture: диф структурно не может
  задеть её (`tap_action` как был generic `string | null`, так и остался).
- Полный набор `demo/smoke_*.mjs` (205 файлов) и `golden:verify` — не
  запускал; диф ограничен одной нерендер-поверхностью, `smoke-select.mjs`
  назвал ровно один относящийся смок, presentation-код не тронут (AC4).
- Орфография DE/FR переводов сверена только структурно (наличие ключа,
  соответствие ТЗ-строке); носителем языка текст не вычитывал.
- Ручную/браузерную проверку вне `demo/smoke_tap_ctx.mjs` (например, реальный
  HA-инстанс) не делал — по правилам процесса фазы ручного тестирования нет,
  её роль здесь исполняет код-ревью и автотесты.

## Вердикт

Все AC доказаны автотестом (с проверенной способностью падать) либо чтением
кода в точках, где сам диф не создаёт новой ветки исполнения. High: 0,
Medium: 0. Единственный Low снят без цикла с записью выше.

`Вердикт: зелёный · заход r1 · блокирующих циклов 0/4 · High: 0 · Medium: 0 · Документ: docs/reviews/CODE-REVIEW-381-r1.md`