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

CODE-REVIEW-356-r1

Issue: #356 — «layout/set без expected_rev тоже перезаписывает молча — тот же класс C4, что и config/set (#340)» Трек: trivial (S1→S2→S5→S6→S7, ТЗ в теле issue, без spec-review-документа) Заход: r1 · блокирующих циклов израсходовано 0/2 (лимит trivial-трека — 2) SHA материала: 24c9a169ace86e8de502143b51874690828e0994 (единственный коммит в диапазоне origin/dev..HEAD, git rev-parse HEAD совпадает)

Скоуп

Диапазон git diff origin/dev...HEAD:

custom_components/houseplan/websocket_api.py | 22 ++++++--
docs/ARCHITECTURE.md                         |  2 +-
docs/CHANGELOG.md                            |  5 ++
docs/CHANGELOG.ru.md                         |  5 ++
docs/TESTING.md                              | 10 ++--
tests_backend/test_ha_websocket.py           | 80 ++++++++++++++++++++++++++++

Чисто бэкенд + документация; src/** не тронут вовсе (фронтенд не вызывает layout/set — использует point-wise layout/update, см. «Проверено» ниже). Ветка соответствует issue (issue/356-layout-revision), коммит несёт трейлеры Issue: #356 и User-Visible: yes, оба changelog правлены в том же коммите.

AC из тела issue (trivial-трек, ТЗ = issue):

• AC1 — layout/set без expected_rev при current rev > 0 возвращает conflict до canonical no-op/записи; store/rev/служебные поля не меняются, houseplan_layout_updated не отправляется. Доказательство: backend HA websocket test.
• AC2 — bootstrap rev=0 без expected_rev остаётся допустимым и создаёт rev=1; явный совпадающий expected_rev работает; явный stale rev получает conflict. Доказательство: backend HA websocket test + существующая CAS-матрица.
• AC3 — schema оставляет expected_rev optional только ради bootstrap и стабильного доменного conflict; документация не обещает больше compatibility blind overwrite; EN/RU changelog сообщает о защите от тихой потери позиций. Доказательство: ревью кода и docs checks.

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

Дешёвые гейты. Подтверждённый в задании прогон Validate на этом же SHA (https://github.com/Matysh/houseplan-card/actions/runs/33179882646) я перепроверил напрямую (gh run view 33179882646 --json jobs): conclusion: success, headSha совпадает с HEAD. Разбивка по job:

Job	Результат
changes (классификация)	success
reuse	success
предполётные (docs/provenance/process-gate)	success
hacs	success
hassfest	success
frontend (typecheck/test/build/bundle-sync)	skipped
backend (pytest в Home Assistant)	success
golden, smoke, performance_smoke	skipped

Важное уточнение к тексту задания: npx tsc --noEmit / npm test / npm run build в этом прогоне не «подтверждены зелёным», а корректно пропущены job'ом changes — путевой фильтр frontend требует изменений в src|demo|test|dist|custom_components/houseplan/frontend|package(-lock).json| rollup.config|tsconfig, и диапазон коммита ни одного из них не касается (проверено: git diff origin/dev...HEAD --stat не содержит src/**, и grep -n "layout/set" src/ показывает единственное упоминание — в комментарии, подтверждающем, что фронтенд ходит через layout/update, а не layout/set). Поэтому пропуск этих гейтов не тихий — они здесь не применимы к диффу; гонять их вручную ради нулевого покрытия диффа не стал.

backend job — единственный релевантный этому диффу тяжёлый гейт — реально прогнан и зелёный на точном SHA; это и есть исполнение нового теста test_issue_356_layout_set_without_revision_is_bootstrap_only в CI на Linux с настоящим HA-харнессом. Локальный прогон pytest в этой ревью-среде недоступен (python3 -c "import homeassistant" → ModuleNotFoundError, .venv-backend отсутствует) — ожидаемое ограничение окружения ревьюера, см. PROCESS.md «Backend»/AGENTS.md «Environments».

Не прогонялось и почему:

• npm run golden:verify, браузерные смоки, node scripts/check-docs.mjs — диф не трогает src/**/визуал, не применимо;
• npm run invariants -- --config … — диф не трогает геометрию комнат, рёбра, marker.space, open_spans; это чисто транспортный CAS-гейт над уже существующим layout-документом, модель не меняется;
• «одно число — один источник» — в диффе нет новой пользовательски видимой величины (это код отказа записи, а не отображаемое значение), не применимо.

Прочитано вручную (доказательство «чтением, не исполнением» там, где автотеста нет — AC3 и общая согласованность):

• полный текст ws_layout_set (websocket_api.py:559-616) построчно, сверка порядка проверок с симметричным ws_config_set (audit C4/#340, websocket_api.py:1286-1334) — паттерн идентичен: warning без содержимого → send_error("conflict") → return, до вычисления _live_layout/no-op/записи;
• все остальные точки записи layout (grep async_save_layout_state) — websocket_api.py:130,208,226,679,742,778,1096,1787,1803,1871,1882 и __init__.py:160,169,223 — вызывают async_save_layout_state напрямую, не через ws_layout_set; правка их не касается, что соответствует заявленному «не-цели: layout/update, layout/delete, import/optimize не меняются»;
• существующие вызовы houseplan/layout/set без expected_rev в tests_backend/test_ha_websocket.py (строки 136, 214, 249, 320 и др.) — во всех случаях это первый layout-write в своём тесте (rev=0 на входе), то есть законный bootstrap-путь, который правка не ломает; это же неявно подтверждено зелёным backend job (эти тесты входят в тот же файл и тот же прогон);
• docs/ARCHITECTURE.md, docs/TESTING.md, docs/CHANGELOG(.ru).md — текст соответствует фактическому поведению после правки, не обещает больше «blind overwrite для совместимости».

Находки

Не найдено. High: 0, Medium: 0.

Разобрано отдельно и не сочтено находкой: тест «An equal body is still a write attempt and must not bypass the CAS guard» (test_ha_websocket.py:602-611) — хорошее покрытие ровно того случая, где conflict-проверка обязана стоять до сравнения с canonical no-op, а не полагаться на то, что no-op сам по себе безопасен без ревизии. Порядок в коде это подтверждает (см. выше).

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

• AC1 — доказано автотестом (test_issue_356_layout_set_without_revision_is_bootstrap_only, ветка «stale_client without expected_rev»), тест умеет падать: без правки старый код проверяет только "expected_rev" in msg (ложно) и не возвращает conflict, дошёл бы до записи нового rev/события — тогда assert not rejected["success"] и assert layout_events == [] были бы красными. Подтверждено также прогоном на CI (backend job, success, тот же SHA).
• AC2 — доказано тем же тестом (bootstrap-ветка rev=0→1, явный совпадающий expected_rev=1 в конце) плюс не сломанной существующей CAS-матрицей (explicit stale rev в других тестах файла, не тронутых диффом).
• AC3 — проверено чтением: docstring, ARCHITECTURE.md (табличная строка layout/set), TESTING.md (пункт про backend hardening) и оба changelog синхронно описывают новое поведение; формулировка симметрична описанию #340 для config/set.
• Утечки данных в лог нет: тест явно проверяет "stale-secret" not in caplog.text.
• Область изменения не задевает фронтенд, layout/update, layout/delete, import/optimize, что соответствует заявленным «не-целям» задачи и риск-оценке аналитика (P3, риск 3/10, ограничен старыми/сторонними клиентами).
• Трейлеры и changelog-дисциплина в порядке (Issue: #356, User-Visible: yes, правки в обоих changelog в том же коммите).

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

• npx tsc --noEmit / npm test / npm run build — не прогонял вручную; диф не содержит ни одного файла из frontend-фильтра, гейт CI сам корректно их пропустил (see «Как проверялось»), перегонять вслепую смысла не было бы: проверяли бы код, который не менялся.
• Полный python -m pytest tests_backend -q локально — недоступен в этой среде (нет homeassistant/.venv-backend); полагаюсь на зелёный backend job CI на точном SHA (перепроверено gh run view напрямую, не со слов автора).
• Golden, браузерные смоки, performance — не применимо, диф не трогает визуал/фронтенд.
• Инварианты модели геометрии — не применимо, диф не трогает геометрию.

Вердикт

Зелёный. AC1–AC3 выполнены и доказаны (автотест, который умеет падать, плюс независимо перепроверенный зелёный CI на точном SHA); находок нет; скоуп не расширен; трейлеры и changelog в порядке.