houseplan-card/docs/reviews/CODE-REVIEW-363-r2.md

# CODE-REVIEW-363-r2

## Метаданные раунда — почему это «r2», но полный разбор

Заголовок задачи фиксирует «заход r2 · блокирующих циклов израсходовано 1 из
2» для этапа **code**. Проверка меток issue (`gh api .../issues/363/timeline`)
показывает, что `S7-code-review` выставлена **впервые** в 09:49:41 — до этого
не было ни одного `S7-code-review → S6/S7` цикла. Комментариев с вердиктом
код-ревью в issue тоже нет (всего 5 комментариев, все относятся к аналитике
S2 и двум попыткам этапа spec).

Единственный потраченный блокирующий цикл (1/2) — это жёлтый вердикт
**спек-ревью** r1 (2026-08-29T09:16:10Z, `SPEC-REVIEW-363-r1.md@9d6d6eb9`),
исправленный в той же попытке до зелёного (09:22:49Z). Бюджет §4 общий на
issue, а не на этап, поэтому нумерация «заход» продолжает расти при переходе
в code, хотя это первый разбор кода.

**Следствие:** предыдущего code-review раунда, с которым можно было бы
сравнивать дельту (§2.9), не существует. Материал этого раунда — весь диапазон
`git diff origin/dev...HEAD` (4 коммита реализации), разобран полностью.
Разделы «Закрытие раунда r1» и «Унаследовано из r1» в этом документе
отсутствуют по той же причине: наследовать не от чего.

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

Диапазон: `origin/dev..HEAD`, 4 коммита:

- `e8916c71` feat: restore direct device add shortcut — `User-Visible: yes`
- `3068a97c` test: align device catalog evidence with shortcut
- `5ba0d9e1` test: accept reviewed device shortcut frames — golden baselines
- `e5ecf399` chore: preserve changelog mode after rebase (только смена прав
  доступа файла, содержимое не менялось)

Трейлеры `Issue: #363` присутствуют во всех коммитах, `User-Visible` расставлен
корректно (`yes` только там, где меняется видимое поведение и в этом же
коммите правится оба changelog).

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

Прочитаны в указанном порядке: `docs/SCOPE.md`, `AGENTS.md`/`PROCESS.md`,
тело issue #363 (ТЗ revision 2) и все 5 комментариев, `docs/USER-GUIDE(.ru).md`
(раздел Device editor), исходный код (`src/houseplan-editor-runtime.ts`,
`src/houseplan-card.ts`), тесты (`demo/smoke_editor_tabs.mjs`,
`demo/smoke_device_inbox.mjs`, `test/i18n.test.mjs`), golden-матрица
(`demo/golden/matrix.mjs`, `demo/golden/baselines/baselines-index.json`),
`docs/images/screenshots.json`, история коммита `cab8d128^` (состояние до
удаления кнопки), CSS тулбара (`src/styles/chrome.styles.ts`), а также журнал
запусков workflow через `gh run view`/`gh api` (Validate на `e5ecf399`,
докрышоты на ref `issue/363-add-device-shortcut`).

## AC-за-AC

**AC1 — видимость и порядок.** Подтверждено чтением:
`src/houseplan-editor-runtime.ts:11541-11555` — `_renderDevicesBar()` рендерит
кнопки в порядке «Добавить» (иконка `mdi:plus-box-outline`) → «Устройства» →
«Правила иконок»; `_renderDevicesBar` вызывается только при
`editorChromeMode === 'devices'` (`houseplan-card.ts:11066-11072`), в других
режимах не рендерится вовсе. Доказано динамически: `demo/smoke_editor_tabs.mjs`
проверяет `deviceToolbarButtons.length === 3`, что нулевая кнопка — Add
(текст, title, иконка), первая — Devices. Тест умеет падать: смена порядка,
иконки или подписи ломает соответствующее булево поле, которое `checkAll`
требует истинным по умолчанию.

**AC2 — прежний диалог.** `_openMarkerDialog()` без аргумента
(`houseplan-editor-runtime.ts:7628,7721-7745`) создаёt черновик с
`name: '', bindingMode: 'virtual'`, без ключа `devId` (ветка `else`). Смок
кликает по кнопке и проверяет ровно эту форму
(`!Object.prototype.hasOwnProperty.call(c._markerDialog, 'devId')`) —
мутант «вызов с аргументом» ловится: при `d` передан объект `devId` появится.
Клавиатурная семантика (Enter/Space) не эмулировалась синтетическим
`KeyboardEvent`, а подтверждена структурно
(`addDeviceButton.tagName === 'BUTTON' && !addDeviceButton.disabled`) —
нативная кнопка получает Enter/Space активацию от браузера бесплатно; это тот
же способ, каким уже проверена соседняя кнопка «Устройства». Отдельный тест
на сам факт срабатывания нативной семантики тестировал бы браузер, а не код
продукта — не считаю это пробелом.

**AC3 — каталог сохранён.** `demo/smoke_device_inbox.mjs` не тронут в части
самого каталога: `_openDeviceInbox()`, 4 вкладки, ряды `on_plan`, поиск по
комнате — без изменений. Единственная правка — переименование поля
`oneCatalogEntryPoint` → `catalogAndDirectAddEntryPoints` и добавление
позитивной проверки, что кнопка `^Add$` **есть** (ранее было наоборот, из
контракта #29). Путь «Добавить виртуальное устройство»
(`device_inbox.add_virtual`) не задет диффом вообще — регресс здесь
структурно исключён (нет изменённых строк).

**AC4 — i18n.** `src/i18n/{en,ru,de}.json` — по 2 строки в каждом. Сверено
побайтово с `git show cab8d128^:src/i18n/{en,ru}.json` — EN/RU совпадают
дословно. Немецкий («Hinzufügen», «Gerät zum Plan hinzufügen») согласован с
уже существующими `device_inbox.add`/`title.add_space` в том же словаре.
`test/i18n.test.mjs:109-112` сверяет полный набор ключей всех словарей с `en`
— пропуск любой локали или ключа ломает тест (assert.deepEqual на
отсортированных ключах), проверено чтением, дополнительных прогонов не
требовалось — тест общий, не требовал правки под #363.

**AC5 — responsive и доступность.** `.editbar` использует CSS-grid
(`minmax(0,1fr) auto`, `chrome.styles.ts:193-214`) — колонка `.editbar-end`
(Close) зафиксирована отдельной grid-колонкой и не участвует в переносе;
`.editbar-tools` — `flex-wrap: wrap`, кнопки переносятся, а не обрезаются и не
перекрываются. **Этот CSS не тронут диффом** — риск переполнения тулбара,
заявленный в ТЗ, снят тем же механизмом, что уже работает для соседних кнопок,
без новой логики. Прямого browser-смока «ширина X, нет overlap» именно для
голого тулбара (без диалога) не добавлено, но принятый golden-кадр
`device-inbox-narrow-ru-dark` (390px) визуально показывает тот же тулбар
(приглушённым) под диалогом и был вручную проверен автором при приёмке —
косвенное, но реальное подтверждение при самой узкой из используемых в матрице
ширин. Считаю риск закрытым; отдельный узкий смок был бы полезен, но не
обязателен при неизменном layout-механизме — не поднимаю как находку.

**AC6 — данные и логика неизменны.** Диф не касается persisted-схемы,
save/cancel flow, backend. Новый draft создаётся той же веткой
`_openMarkerDialog()`, что и раньше для «пустого» диалога — нет второго
create-flow. Cancel не создаёт marker (ветка `else` только формирует
локальный `_markerDialog`, запись в `_serverCfg`/`callWS` происходит по
существующему save-пути, не тронутому диффом).

**AC7 — документация и выпуск.** Оба changelog правятся в `e8916c71`
(`User-Visible: yes`), USER-GUIDE обновлён в EN и RU в том же коммите. Гейт
`check-docs.mjs`: `docs/images/screenshots.json` — `sourceFingerprint`
обновлён для всех 10 сценариев, `imageSha256` изменился **только** у
`device-editor` (7 байт разницы в PNG, автор задокументировал это как
antialiasing-флуктуацию инфраструктуры при кросс-сверке 7 прогонов workflow —
правдоподобно и не относится к продукту). Канонический workflow
«Скриншоты документации» запущен на `ref: issue/363-add-device-shortcut`
(проверено логом job `actions/checkout@v7` рана `33245780081` — вопреки
`headBranch: main` в метаданных API, что для этого репозитория штатно:
workflow-файл живёт на `main` побайтово синхронизированным с `dev` (#365), а
checkout идёт по input `ref`). `docs:accept --reviewed` выполнен, обновлённый
`docs/images/screenshots.json` закоммичен.

**AC8 — визуальный эталон.** `baselines-index.json`: изменились ровно два
хэша — `geometry-devices-editor-dark` и `device-inbox-narrow-ru-dark`;
`device-inbox-desktop-en-light` и `device-inbox-desktop-ru-dark` не менялись.
Здесь есть реальное расхождение с буквальным текстом AC8: ТЗ утверждает, что
все три `device-inbox-*` не меняются и называет единственный
`--expect-change=geometry-devices-editor-dark`. По факту
`device-inbox-narrow-ru-dark` тоже сменил хэш (102015→103240 байт PNG) —
и это ожидаемо: при ширине 390px приглушённый тулбар виден под диалогом
каталога, и новая кнопка «Добавить» видна в этом приглушённом фоне. Автор
явно задокументировал и обосновал это в комментарии к issue до приёмки, само
изменение содержимого каталога не задело. **Квалифицирую как Low, не
блокирует**: причина понятна, зафиксирована публично, поймана предсказанным
самим же спек-ревью механизмом («если поедут — находка»), пиксельная дельта
согласуется с размером одной кнопки. Рекомендация — одной строкой поправить
текст AC8 в issue (перечислить `device-inbox-narrow-ru-dark` в ожидаемо
меняющихся вместе с `geometry-devices-editor-dark`), но это не повод для
возврата автору.

## Гейты: что прогнано и что нет, и почему

- `npx tsc --noEmit`, `npm test`, `npm run build` (+ сверка 3 копий бандла) —
  **не прогонял сам**: Validate на `e5ecf399` зелёный целиком
  (https://github.com/Matysh/houseplan-card/actions/runs/33246304275, job
  «Фронтенд: типы, юниты, мутанты, синхрон бандла» = success).
- `node scripts/check-docs.mjs` — тот же Validate-прогон покрывает job
  «Предполётные проверки: документация, провенанс, процесс» = success;
  дополнительно проверил содержимое `screenshots.json` вручную (см. AC7).
- Полный набор golden (`npm run golden:verify`) и все 3 шарда browser-смоков —
  на самом `e5ecf399` эти джобы **skipped** («Переиспользование: дерево уже
  проверено»), но проверил цепочку: они реально выполнялись и были зелёными
  на run `33246023321` (headSha `a043c216`, дерево идентично `e5ecf399` за
  вычетом смены прав доступа файла) — «Golden-кадры против принятых
  эталонов» = success, все 3 шарда смоков = success. Повторный прогон не
  требовался.
- `node scripts/smoke-select.mjs --base origin/dev --head HEAD` — прогнал.
  Инструмент не нашёл «прямого совпадения» или «зарегистрированной связи»:
  вернул НЕОПРЕДЕЛЁННОСТЬ и список из 28 слабых связей (все — смоки,
  вызывающие `_openMarkerDialog`, распространённое имя). Решение: не
  прогонять — этот диф не меняет ни сигнатуру, ни поведение
  `_openMarkerDialog()`, а только добавляет ещё один вызов без аргумента
  (уже покрытый паттерн, например `demo/smoke_new_device.mjs`); целевые
  смоки для самой фичи (`smoke_editor_tabs.mjs`, `smoke_device_inbox.mjs`)
  уже обновлены автором и зелены в Validate.
- `python -m pytest tests_backend -q` — не запускал, диф не касается
  `custom_components/**/*.py`.
- Инварианты модели (`npm run invariants`) — не запускал, диф не касается
  геометрии, стен, layout, `marker.space`, `open_spans`.
- Perf-профили — не требуются ни AC, ни диффом; job перф-смока в обоих
  релевантных прогонах либо success, либо skipped по классификации файлов.
- «Одно число — один источник» — в диффе нет новых пользовательских числовых
  величин (только текстовые подписи/tooltip), проверка неприменима.

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

- Порядок, иконка, подпись и tooltip кнопки — по коду и по смоку.
- `_openMarkerDialog()` без аргумента — тот же прежний путь, каталог не
  открывается.
- i18n-паритет трёх локалей, байт-в-байт совпадение EN/RU с состоянием до
  `cab8d128`.
- Каталог и путь «Добавить виртуальное устройство» не затронуты.
- Changelog/USER-GUIDE обновлены в нужном коммите на обоих языках.
- Docs-фингерпринт и golden-баselines обновлены целиком согласованным
  набором, посторонних дрейфов не найдено.
- Docs-скриншоты сняты на верном ref ветки (проверено логом job, а не
  метаданными API).

## Находки

**L1 (Low).** Текст AC8 в теле issue #363 предсказывает, что
`device-inbox-narrow-ru-dark` не изменится; по факту эта golden-сцена
изменилась (ожидаемо и обоснованно — приглушённая кнопка тулбара видна под
диалогом на узкой ширине). Причина понятна, изменение задокументировано
автором в issue-комментарии до приёмки, риск регрессии отсутствует.
Рекомендация: точечно поправить формулировку AC8, не блокирует.

Находок Medium/High нет.

## Вывод

Диф полностью реализует ТЗ revision 2, AC1–AC8 доказаны кодом/тестами/CI,
трейлеры корректны, changelog и docs synced. Единственное замечание — Low,
снимается с запиской, отдельный issue не требуется.