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

CODE-REVIEW-307-r1

Issue: #307 · «Рисование стен: осевые линии и узлы не видны на уже поставленных сегментах цепочки до её завершения» · трек small (ТЗ в теле issue) · заход r1 (первый цикл) · бюджет циклов лёгкого трека 0/2 израсходовано.

Ветка приведена к dev конвейером до ревью (893a9aa0 → 11343454, +1 коммит dev). Разбор полный (это первый заход, вопрос «дельта vs полный разбор» из §2.10 к r1 не применяется).

Коммит под ревью: 11343454 — fix: keep the active chain axis and nodes above the wall bodies (#307). Единственный коммит в диапазоне origin/dev..HEAD.

Скоуп

Симптом: во время рисования цепочки стен (Plan → «Стены») уже поставленные сегменты не показывают осевую линию и узлы — их закрашивает непрозрачное тело свежеперсистнутого драфта. Видна только резинка (.active-axis/ .active-vertex) активного отрезка. Причина зафиксирована в issue двумя пунктами: (1) .pathline/.vertex рисовались в _renderMarkupLayer, который вставлен в композицию до _renderWallBodies; (2) снап-оверлей рисуется после тел, но намеренно исключает активный драфт из геометрии — это осознанное решение, не трогается.

Заявленное решение (вариант A из issue): вынести разметку активной цепочки в отдельный editor-слой, вставленный после тел стен и до снап-оверлея.

Соответствует Core user job из docs/SCOPE.md: J6 «Keep the plan true as the home evolves» (два редактора, drag/resize) — сам инструмент рисования стен; чинится визуальная обратная связь редактора, не продуктовая функция. Вне скоупа продукта задача не выходит: чисто editor-only правка рендеринга, никакого нового поведения, конфига или контракта.

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

Гейт	Результат	Команда
typecheck	зелёный, без вывода	npx tsc --noEmit
unit-тесты	1304 pass / 0 fail / 1 skipped	npm test
build	собран, 14 с	npm run build
сверка 3 копий бандла	идентичны после пересборки (md5sum совпал с закоммиченными dist/ и custom_components/.../frontend/, bundle:sync пересоздал недостающую demo/srv/assets/ копию)	npm run build && npm run bundle:sync
docs (docs job)	зелёный, отпечаток скриншотов совпал	node scripts/check-docs.mjs → «Documentation checks passed (7 files, 10 external links)»
новый смок demo/smoke_active_chain_ink.mjs	OK (пиксельные пробы axisMidYellow: true, nodeYellow: true, RGB [255,193,77]/[129,87,23])	node demo/smoke_active_chain_ink.mjs
тот же смок на коде до фикса (HEAD~1:src/houseplan-card.ts, пересобран)	падает: inkAboveBodies: false, axisMidYellow: false, nodeYellow: false (пиксели [255,255,255] — фон вместо оси) — тест умеет ловить регрессию	node demo/smoke_active_chain_ink.mjs на откаченном src, дерево затем полностью восстановлено до HEAD
выборка смежных смоков (smoke-select.mjs, 14 прямых совпадений по _path/_cursorPt/_markup/_contourClosed/Axis)	все 14 — OK	см. список ниже
npm run golden:verify (полная матрица, 127 сценариев)	все passed, включая 4 сценария из группы риска	npm run golden:verify
npm run invariants	не прогонялся — не применимо, см. «Чего не проверял»	—
python -m pytest tests_backend	не прогонялся — diff не касается custom_components/**/*.py	—

Прямые совпадения smoke-select.mjs, прогнанные все 14 — все OK: smoke_draw_wall_thickness, smoke_align_guides, smoke_editor_gestures, smoke_plan_drawing_repairs, smoke_plan_snap_overlay (AC3 явно требует его), smoke_room_autoclose, smoke_unified_wall_tool, smoke_wall_junctions, smoke_edit_walk, smoke_merge_split, smoke_optimize_coincident_partition, smoke_resize_audit_1550, smoke_room_resize, smoke_split_nonsnap. «Слабую связь» (18 смоков, одно распространённое имя _path/_cursorPt) не гонял — ни один не выглядит специфичным к слоям композиции плана, а прямые совпадения уже покрывают draw/junction/snap/resize/merge-split поверхность.

npm run golden:verify запускался несмотря на то, что ТЗ его не называет, по прямому предписанию процесса: diff — это переупорядочивание editor-only SVG-слоёв (изменился z-order .pathline/.vertex/.active-axis/ .active-vertex относительно тел стен), то есть «может изменить видимый результат: слои». Нашёл 4 golden-сценария в plan-режиме, которые выставляют card._path/_tool='draw' поверх настоящей геометрии стен (plan-snap-endpoint-light, plan-snap-line-gaps-dark, wall-junctions-plan-preview-light, wall-junctions-plan-t-dark — demo/golden/matrix.mjs:266-285, demo/golden/harness.mjs:965-1017) — это ровно тот класс состояния (резинка/поставленные точки цепочки поверх реальных стен), для которого правка меняет порядок отрисовки. Полная матрица прошла зелёной без единого расхождения — риск проверен и снят, а не просто предположен.

Находки

Отсутствуют. High: 0, Medium: 0, Low: 0.

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

AC1 (ось и узлы видны на поставленных сегментах). Доказано автотестом (demo/smoke_active_chain_ink.mjs), тест умеет падать — прогнан на коде до фикса, три проверки красные с ожидаемым фоновым цветом вместо жёлтого. На текущем коде все проверки зелёные, включая точные RGB-пробы в середине оси первого сегмента и в узле.

AC2 (слой цепочки между телами и снап-оверлеем, резинка не регрессирует). Доказано чтением кода и тем же смоком:

• src/houseplan-card.ts:17565 (_renderWallBodies) → :17585-17586 (новый <g class="hp-editor-only-layer"> вокруг _renderActiveChainInk()) → :17587-17588 (_renderPlanSnapOverlay) — порядок в композиции совпадает с контрактом ТЗ «после тел, до снап-оверлея».
• Смок проверяет тот же факт через compareDocumentPosition в DOM (inkAboveBodies, inkBelowSnapOverlay) — оба true.
• Резинка (.active-axis/.active-vertex) перенесена в тот же новый метод _renderActiveChainInk (:20057-20074) без изменения условий рендера — идентичный JSX-блок, только другое место вставки; смок подтверждает присутствие обоих элементов при активном курсоре.
• Инструмент «Split» использует свои собственные .pathline/.vertex внутри _renderMarkupLayer (:20033-20040) — их ТЗ явно оставляет на месте, и диф их не трогает: отдельный блок кода, не задет переносом.

AC3 (снап не меняется). src/plan-snap-overlay.ts не входит в diff (проверено — пустой git diff по файлу). smoke_plan_snap_overlay зелёный. Существующие юнит-тесты снапа входят в общий зелёный прогон npm test (1305 тестов, ни один не упал). Проверено чтением + существующим смоком, как и требует AC.

CSS не завязан на структуру родителя. .pathline, .vertex, .active-axis, .active-vertex — глобальные селекторы классов в src/styles.ts:1803-1863, не скоупятся через потомство конкретного <g>. Перенос элементов в новый <g class="hp-editor-only-layer"> (тот же паттерн, что уже используют align-guides, hidden-wall-diagnostics, opening-placement-preview, снап-оверлей — opacity="${modeVisual?.editorWeight ?? 1}") не требует правок стилей и не ломает editorWeight-затемнение в неактивных режимах.

Трейлеры и changelog. Единственный коммит несёт Issue: #307 и User-Visible: yes; оба docs/CHANGELOG.md/docs/CHANGELOG.ru.md правлены в том же коммите (проверено git show --stat, git diff по обоим файлам — согласованные формулировки на двух языках, ссылка на issue).

Формулировка ТЗ vs UI. ТЗ цитирует docs/USER-GUIDE.ru.md:372-374 дословно («поверх уже нарисованных стен видны тонкие осевые линии и точки их концов») — сверено, совпадает буквально.

Откат. Один коммит, без новых полей конфига, миграций или persisted-состояний — подтверждено диффстатом (только src/houseplan-card.ts

• сгенерированные копии + смок + changelog + отпечаток скриншотов).

«Одно число — один источник». Не применимо: диф не добавляет и не меняет ни одной пользователю видимой величины (числа, площади, подписи) — только z-order editor-only SVG-элементов. test/single-source-numbers.test.mjs входит в общий зелёный npm test.

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

• npm run invariants — не прогонял. Diff не касается геометрической модели: нет правок layout, записей толщины, marker.space, open_spans, physical-geometry.ts, plan-snap-overlay.ts. Изменение — это переупорядочивание editor-only SVG-слоёв внутри одного компонента рендеринга; ни одна из трёх инвариантных проверок (запись толщины, разрешимость ссылок, ключ записи = ключ решёточного ребра) не имеет отношения к этому диффу.
• python -m pytest tests_backend — не прогонял. Diff не касается custom_components/houseplan/**/*.py (только сгенерированная копия фронтенд- бандла в custom_components/houseplan/frontend/houseplan-card.js, класс D).
• Полный набор demo/smoke_*.mjs — не гонял все ~70+ смоков, только 1 новый + 14 прямых совпадений (см. таблицу и обоснование выше). Слабые связи (18 смоков с одним общим именем _path/_cursorPt) не прогонял — по выводу инструмента это решение ревьюера, и просмотр списка (drag/pan/split/ opening-preview на разных, не связанных с композицией плана поверхностях) не выявил кандидатов, специфичных именно к порядку SVG-слоёв.
• performance_smoke — не прогонял. Не назван в AC, диф не трогает чувствительные к перфу пути (рендер не добавляет новых вычислений — тот же шаблон переставлен в другое место композиции, число DOM-узлов не меняется).
• Ручное тестирование в браузере — не проводилось (в цикле code-review ручного тестирования нет по регламенту); функциональность подтверждена смоком с пиксельными пробами и golden-верификацией композитного рендера.

Вердикт

Все 3 AC доказаны: AC1/AC2 — автотестом, который умеет падать (проверено на коде до фикса), AC3 — чтением кода (файл снапа вне диффа) плюс существующим зелёным смоком. Дешёвые гейты (typecheck/test/build/bundle-sync/docs) зелёные. Прямые смежные смоки (14) зелёные. Полная golden-матрица (127 сценариев, включая 4 сценария из группы прямого риска — резинка/точки цепочки поверх настоящих стен в plan-режиме) зелёная без единого расхождения. Трейлеры и оба changelog корректны. Находок нет.

Зелёный.