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

CODE-REVIEW-313-r1

Issue: #313 · этап: код (code) · трек: small (лёгкий, лимит циклов код-ревью — 2) · заход: r1 · блокирующих циклов израсходовано: 0 из 2 · SHA материала ревью: 5e5dad277cbdc238a5af899ff6727aed60d604b1

Скоуп

Ветка issue/313-wallthick-standalone, один коммит 5e5dad27 поверх dev. Конвейер привёл ветку к dev до ревью (§7.2/#257): поверх лёг 1 коммит dev (docs: review document for #313, ffe0f0c7 — сам SPEC-REVIEW-313-r1, уже принятый и слитый). Это не смысловой ребейз продуктового кода — единственный родительский коммит между старым и новым состоянием документ-only, диапазон origin/dev...HEAD по-прежнему ровно один коммит 5e5dad27. Разбор в любом случае полный: это первый заход код-ревью (r1), раздел «Унаследовано из r(N-1)» неприменим — предыдущего раунда код-ревью не было.

Реализует ТЗ из тела issue #313 (light-трек, SPEC-REVIEW-313-r1 зелёный): инструмент «Толщина» резолвит/пишет также перегородки (space.partitions) и сегменты сохранённых черновиков (space.room_drafts[]), с приоритетом независимой кладки при точном наложении, без кнопки «на всю комнату» для неё, с отказом нуля/пусто для независимой кладки.

Диф: src/houseplan-card.ts (+109/-…), новый смок demo/smoke_wallthick_standalone.mjs, второй патч мутанта wall-thickness-writer-bypasses-common-barrier в scripts/mutation-gate.mjs, оба CHANGELOG, docs/USER-GUIDE.ru.md, docs/images/screenshots.json (только fingerprint), три копии бандла.

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

Читал: docs/SCOPE.md, AGENTS.md, PROCESS.md (§1–§12), тело issue #313 и все 3 комментария (аналитика с тремя решениями владельца, зелёный вердикт SPEC-REVIEW, хендофф автора), docs/WALL-THICKNESS.md целиком (§1, §6, §9 особенно), срез docs/USER-GUIDE.ru.md по «Толщине», SPEC-REVIEW-313-r1.md.

Код читался на HEAD @ 5e5dad27, полный git diff origin/dev...HEAD. Ключевые утверждения не приняты на слово, а исполнены:

Гейты — прогнал

Гейт	Команда	Результат
typecheck	npx tsc --noEmit	зелёный, без вывода
unit	npm test	1335 pass / 1 skip / 0 fail (1336 total) — совпадает с хендоффом
build + bundle sync	npm run build && npm run bundle:sync	cmp dist/houseplan-card.js custom_components/houseplan/frontend/houseplan-card.js → совпадают; cmp dist/houseplan-card.js demo/srv/assets/houseplan-card.js → совпадают
docs fingerprint	node scripts/check-docs.mjs (diff трогает src/**, гейт обязателен)	«Documentation checks passed (7 files, 10 external links)»
выборка смоков	node scripts/smoke-select.mjs --base origin/dev --head HEAD	25 «прямое совпадение»; из них прогнал 5 по существу диффа (ниже)
demo/smoke_wallthick_standalone.mjs (новый, AC1–AC4)	node demo/smoke_wallthick_standalone.mjs	OK — и подтверждено, что тест умеет падать: собрал бандл с того же файла на origin/dev (ffe0f0c7, чистый worktree, свой node_modules симлинком) — без правки _wallThickHit/_wallThickApply/_wallDialog.source смок бросает необработанное исключение (TypeError в _wallThickApply), а не тихо проходит
demo/smoke_wall_thickness.mjs (AC4, комнатные стены)	node demo/smoke_wall_thickness.mjs	OK, все под-проверки true
demo/smoke_wallthick_hover_width.mjs (AC4)	node demo/smoke_wallthick_hover_width.mjs	OK
demo/smoke_resize_wall_thickness.mjs (AC4)	node demo/smoke_resize_wall_thickness.mjs	OK
demo/smoke_optimize_coincident_partition.mjs (тематически смежный с AC3 — #308-сценарий, два прямых совпадения символов _wallDialog/_wallThickApply, не «слабая связь»)	node demo/smoke_optimize_coincident_partition.mjs	OK, все под-проверки true, включая thicknessToolSelectsCanonicalWall/thicknessChangesSingleBody
мутация (точечно, не полный набор)	node scripts/mutation-gate.mjs --id=wall-thickness-writer-bypasses-common-barrier	«поймано 1 из 1» — но см. находку Medium ниже: результат обманчив
инварианты модели	npm run invariants -- --config test/fixtures/276-coincident-partition.json	1 нарушение — предсуществующее и ожидаемое (та же fixture #276/#308: перегородка поверх ребра комнаты; не следствие этого диффа — plan-geometry-preflight.ts/near-axis.ts/coordinate-canonicalization.ts, которые видит скрипт, диффом не тронуты). Не запускал отдельный export с реальной записью толщины независимой кладки: диф не меняет wall_segments[]/ключи/open_spans, пишет только partition.cm/draft.segments[i].cm тем же способом, что уже существующий _savePhysicalDialog (houseplan-card.ts:8287-8300, select-инструмент) — не новая форма мутации модели

Остальные 20 «прямых совпадений» от smoke-select — не прогонял: связь через широко переиспользуемые символы (_activeDraftId, _geometrySnapshot, _showToast, wallIntervals) без содержательного пересечения с изменённым кодом (_wallThickHit/_wallThickApply/_wallDialog/шаблон диалога); полный прогон — предрелизная обязанность, не гейт этого ревью. golden/pytest tests_backend/perf — не запускал: диф не меняет визуальный результат (нет новых компонентов рендера — существующая полоса hover и диалог переиспользуются как есть) и не трогает custom_components/**/*.py или performance-чувствительные пути; в AC они не названы.

AC — как доказаны

• AC1 (перегородка: hit → диалог → запись partition.cm → тело перерисовывается → Undo). Доказано смоком smoke_wallthick_standalone (hit/диалог/запись) плюс моей отдельной проверкой исполнением — Undo смок не тестирует (комментарий в файле сам это признаёт: «server history is async-free here» без единого вызова undo). Я воспроизвёл отдельно: _wallThickClick → правка на 35 → _wallThickApply → Control+z → значение вернулось к исходным 20, _geometryHistory.size === 1 (один Undo, как того требует контракт). AC1 закрыт.
• AC2 (сегмент драфта: диалог с cm сегмента, запись draft.segments[i].cm, активный драфт не виден). Смоком подтверждена happy-path запись (12 → 18) и исключение активного драфта — по коду (draft.id === this._activeDraftId continue, houseplan-card.ts:11971-11973). Не подтверждена находкой ниже — см. High: для segments[i].cm === 0 диалог показывает не cm сегмента, а выдуманное значение. Формально AC2 просит «диалог с cm сегмента» — для этого конкретного, документами же допускаемого состояния контракт не выполнен.
• AC3 (приоритет наложения; ноль/пусто отказ). Смок подтверждает обе части на #308-фикстуре (перегородка cm:30 поверх ребра комнаты left) и отказ нуля с сохранением значения и открытым диалогом. Дополнительно прогнал smoke_optimize_coincident_partition — тот же топологический класс («перегородка поверх ребра») с независимой (не игрушечной) фикстурой, thicknessToolSelectsCanonicalWall/thicknessChangesSingleBody зелёные. AC3 закрыт.
• AC4 (комнатные стены не регрессируют). Три названных смока + npm test (1335/1335, включая ~200 юнитов #278/#282 wall-model-barrier) — все зелёные, golden не переприёмывался (диф не меняет рендер-геометрию комнат — только резолвер инструмента и рендер диалога). Код wallIntervals(...) в комнатной ветке резолвера байтово не менялся (только обёрнут в offer(..., false) — при отсутствии независимых кандидатов offer воспроизводит старое сравнение d < best.d строго, тай-брейк по независимости не участвует). AC4 закрыт.

Находки

High — 1

Смешение «сегмент отсутствует» и «cm сегмента равен нулю» в резолвере драфтов; следствие — тихая порча данных при клике «Применить» без правки поля.

src/houseplan-card.ts:11976:

open: false, cm: Number(draft.segments[i]?.cm) || 15,

RoomDraftCfg.segments[i].cm — обязательное number (src/types.ts:60), 0 — легитимное для проекта значение того же самого поля: docs/WALL-THICKNESS.md §6 прямо документирует «Empty / 0 leaves the new wall thin» для сегментов черновика, и соседняя функция validCm (src/houseplan-card.ts:13447-13448, value >= 0 ? value : null) в этом же файле трактует 0 как валидное текущее значение того же поля при трассировке уже сохранённой независимой кладки — разработчик уже один раз учёл это же поле как «0 — не отсутствие», просто в другом методе. || в новом коде не различает «сегмента с таким индексом нет» (законная защита от рассинхрона points/segments) и «сегмент есть, cm = 0» — оба варианта схлопываются в 15.

Воспроизведение (исполнением, не догадкой) — синтетический конфиг, page.evaluate на собранном бандле HEAD (demo/serve.mjs):

room_drafts: [{ id: 'thin-draft', points: [[0.6,0.5],[0.9,0.5]], segments: [{ cm: 0 }] }]
// tool = 'wallthick'
_wallThickHit([0.75*NORM_W, 0.5*NORM_W]).cm        // → 15  (истинное значение — 0)
_wallThickClick(...)
_wallDialog.value                                   // → "15" (должно быть "" — cmToField(0,…) === '')
_wallThickApply(false)   // пользователь просто закрывает диалог, ничего не меняя
serverCfg.spaces[0].room_drafts[0].segments[0].cm   // → 15  (было 0!)

Результат — ровно то, что напечатал скрипт: {"hitCm":15,"trueStoredCm":0,"dialogValue":"15","cmAfterApplyWithoutEdit":15}.

Сценарий отказа. Черновик, нарисованный «тонким» (без толщины) — состояние, которое канон подсистемы называет существующим («Empty / 0 leaves the new wall thin»), не рисуется в редакторе как обычная стена по толщине, но геометрически существует. Владелец открывает «Толщину», наводит на этот сегмент, видит полосу подсветки шириной 15 см (реального 0 не видно — тоже следствие того же hit.cm), кликает, видит в поле «15», нажимает Enter/Apply, думая, что просто закрывает диалог или подтверждает увиденное — сегмент необратимо (без второго явного намерения) становится физической стеной 15 см. Это ровно класс «одно число — один источник» (PROCESS.md §8): подсветка инструмента, поле диалога и итоговая запись показывают одно и то же неверное число, полученное из одного неверного источника (_wallThickHit), а не три независимых.

Партиционная ветка той же строки (Number(partition.cm) || 0, houseplan-card.ts:11963) не страдает: 0 — единственное значение, при котором фолбэк вообще участвует, и он совпадает с истинным (для PartitionCfg нет задокументированного «тонкого» состояния и нет пути создания cm: 0, в отличие от драфтов).

В скоупе ли находка. Да: это тот же файл, тот же метод, что ТЗ описывает («Диалог: для перегородки/драфта — cm сегмента»), правка — одна строка.

Medium — 1, в скоупе

Второй патч мутанта wall-thickness-writer-bypasses-common-barrier не проверяет то, что заявлено в коммите; заявление «краснота обоих проверена исполнением» не подтверждается.

Коммит 5e5dad27 добавляет второй patches[]-элемент в scripts/mutation-gate.mjs:1221-1227, целящий именно новую точку коммита (_wallThickApply, независимая кладка) — и заявляет в теле коммита: «Мутант расширен вторым патчем на новую точку коммита (#278-гвард), краснота обоих патчей проверена исполнением». Проверил раздельно, применяя патчи мутанта по одному к src/houseplan-card.ts (с восстановлением файла после каждой проверки, git status чист):

• только 1-й патч (легаси-точка, history.wall_thickness в комнатной ветке) применён → node --test --test-name-pattern="production source routes physical writers" test/wall-union-isolation.test.mjs красный (как ожидается);
• только 2-й патч (новая точка, независимая кладка) применён, легаси-точка цела → тот же тест зелёный — не ловит.

Причина: гвард-тест (test/wall-union-isolation.test.mjs:107) — это регэксп-поиск текста _commitPhysicalGeometry\(this\._t\('history\.wall_thickness' по всему исходнику одной строкой (без s/multiline-режима на .), а не проверка конкретного места. Он совпадает только с легаси-вызовом (написан в одну строку), потому что новый вызов (houseplan-card.ts:12064-12066) обёрнут переносом строки сразу после _commitPhysicalGeometry( — до this._t(...) в исходнике перевод строки, через который движковый . без флага s не проходит. Поэтому при --id=wall-thickness-writer-bypasses-common-barrier (оба патча вместе, как в проверил и в реальном CI-запуске мутанта) тест краснеет целиком за счёт первого патча; второй патч можно откатить, ничего не изменится в результате — «поймано 1 из 1» в отчёте mutation-gate.mjs не отличает эти случаи.

Проверил и поведенчески — не только по регэкспу, но и по факту: применил только 2-й патч, пересобрал бандл, прогнал сам новый demo/smoke_wallthick_standalone.mjs — тоже зелёный. Мутация (_recordGeometry вместо _commitPhysicalGeometry) не даёт _saveConfig() (houseplan-card.ts:7402, единственное место записи на бэкенд в _commitPhysicalGeometry) — смок читает мутированное поле прямо из _serverCfg (объект уже изменён присваиванием partition.cm = cmRaw до вызова коммита), поэтому не видит разницы между «записано с проверкой и уходом на сервер» и «переживено локально, история есть, на бэкенд ничего не ушло». Практическое следствие обхода барьера в этой ветке — не гипотетическое: _commitPhysicalGeometry пропускаетfail-closed валидацию геометрии (_checkSpacePhysicalGeometry) и обязательный _saveConfig(); будущий рефакторинг, случайно подставивший «облегчённый» путь записи именно в этой новой ветке, ни один из двух существующих гейтов не поймает.

В скоупе ли находка. Да: и файл (scripts/mutation-gate.mjs, класс B, но через issue этой задачи — AGENTS.md таблица классов, «может использовать issue того изменения, которое покрывает»), и утверждение (текст коммита #313) — целиком продукт этой задачи.

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

• Приоритет независимой кладки при точном наложении (offer(...), houseplan-card.ts:11940-11946): тай-брейк independent && !best.independent && d <= best.d + 1e-9 — корректно предпочитает независимую кладку только при равном/лучшем расстоянии, не переопределяет явно более далёкий кандидат. Порядок перебора (комнаты → перегородки → драфты) не создаёт систематического смещения: тай-брейк явный, не полагается на порядок вставки для двух разных источников.
• sp (_curSpaceCfg, сырой конфиг) и space (_spaceModel(), отмасштабированная проекция) — разные объекты, но id партиций/драфтов сохраняются 1:1 через проекцию (src/space-geometry.ts:167-180); поиск по id в _wallThickApply корректен, тот же паттерн, что уже использует _wallThickClick→_wallDialog для комнатных стен и _savePhysicalDialog для партиций/драфтов (houseplan-card.ts:8287-8300) — не новая, а переиспользованная связка.
• Диалоговая кнопка «на всю комнату» скрывается корректно по d.source.kind === 'room' (houseplan-card.ts:12636), без нового UX-контракта — остальной диалог тот же компонент.
• Валидация диапазона (1–100, отказ 0/пусто для независимой кладки) идёт ДО ветвления по источнику и применяется к обеим веткам одинаково; после ветвления для независимой кладки — отдельный явный отказ на 0/пусто, соответствует решению владельца №2. Тост переиспользован (toast.physical_range), новый ключ toast.wallthick_set уже существовал в обоих src/i18n/en.json/ru.json:535 до этого коммита (проверил — не добавлен этим диффом, i18n не тронут, как и заявлено в аналитике «новых ключей не требуется»).
• Оба CHANGELOG (docs/CHANGELOG.md/.ru.md) правлены в том же коммите, трейлеры Issue: #313/User-Visible: yes на месте — соответствует AGENTS.md.
• docs/USER-GUIDE.ru.md дополнен двумя строками таблицы («Значение», «Какие стены») терминологией, уже принятой в этом документе (не изобретает новых слов), корректно описывает и отказ нуля, и приоритет наложения.
• docs/images/screenshots.json: изменился только sourceFingerprint/ sourceSha256 (совпадает с текущим src/**, проверено check-docs.mjs), imageSha256 не тронуты — ни один из 10 задокументированных сценариев не показывает Plan-редактор с инструментом «Толщина», пересъёмка не требовалась; фингерпринт обязан был устареть при любой правке src/** и был обновлён правильно.
• Мутант wall-thickness-writer-bypasses-common-barrier при обоих патчах вместе (как запускает CI) действительно ловит регресс — см. Medium выше, почему это не то же самое, что «оба патча по отдельности эффективны».

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

• Golden/скриншоты, pytest tests_backend, performance — не запускал: диф не меняет визуальный рендер и не трогает Python/бэкенд; не названы в AC. Если ошибаюсь и где-то в full/static рендере тело диалога/полосы отличается от существующего компонента — это откроет полный прогон перед бетой.
• Полный smoke-select список (остальные 20 из 25 «прямых совпадений») — осознанно не прогонял, см. таблицу выше; риск считаю низким, но это решение, а не факт.
• Столбы (space.wall_columns) инструментом «Толщина» — вне ТЗ и вне этого диффа, как и зафиксировал ревьюер ТЗ; не проверял, потому что не должен быть затронут (не проверял чтением, что резолвер их не подхватывает — это уже не добавлено кодом, а не «пропущенная проверка»).
• Не проверял поведение при коллинеарной перегородке РЯДОМ (не точно на ребре) с контуром комнаты, вне #308-фикстуры — тот же пробел, что явно оставил открытым ревьюер ТЗ («это забота код-ревью... или находка для отдельного цикла»); не нашёл в этом диффе признаков, что общий случай (не точное наложение, а близкое соседство) обрабатывается иначе, чем раньше — резолвер использует то же distToSegment/pull-радиус, что и для комнатных стен исторически, поведение не новое для этого диффа. Оставляю как открытый вопрос для будущей задачи, не завожу отдельный issue: это не находка ПРОТИВ #313, а недоказанное свойство, унаследованное из старого кода.
• Не проверял #306 (замена 0 на виртуальную стену) — вне скоупа, ТЗ прямо говорит, что этой задаче нужен только шов (switch по источнику), а не реализация; шов на месте (houseplan-card.ts:12052-12056, единственная точка ветвления по d.source.kind).

Вердикт

Красный. Единственная High-находка — конкретный, воспроизведённый исполнением дефект в коде, который сама задача добавляет (_wallThickHit, драфт-ветка): диалог «Толщины» лжёт о текущей толщине сегмента черновика, когда она равна 0 (легитимное, задокументированное в docs/WALL-THICKNESS.md §6 состояние), и безusловный клик «Применить» без правки поля молча превращает такой сегмент из 0 в 15 см. Это прямое нарушение AC2 («диалог с cm сегмента») для конкретного достижимого состояния модели, а не гипотетическое. Medium-находка (обманчивая мутационная защита новой точки коммита) в скоупе той же задачи, чинится там же.

Обе находки локальны (одна строка кода на High; тестовый патч + при необходимости сам тест на Medium) — переписывания ТЗ/скоупа не требуют.