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

CODE-REVIEW-296-r1

• Issue: #296 «Оптимизировать» не убирает невидимую геометрию, которая блокирует ресайз
• Этап: код-ревью (PROCESS.md §2.7)
• Заход: r1 · блокирующих циклов израсходовано 0/4 до этого ревью
• SHA ревью: 89ac96a8 (ветка issue/296-optimize-hidden-obstacles, приведена к dev до ревью — 1 коммит dev поверх, разбор полный по правилу §7.2/§2.9)
• Вердикт: красный

Скоуп

Диапазон: f7a19a35 (docs(spec)) → 033ad11b (docs: review document r1) → 89ac96a8 (fix, User-Visible: yes). Продуктовый код и тесты лежат в одном коммите 89ac96a8.

Проверялись: piecewise-согласование составных partitions (§6), удаление доказанно избыточных room_drafts (§7), backend fail-closed доказательство (§8), диагностический слой скрытой геометрии в редакторе Плана (§9), отчёт/Undo/идемпотентность (§10), i18n/документация (§11, §16), AC1–AC9 (§13).

Как проверялось — гейты

Гейт	Команда	Результат
Typecheck	npx tsc --noEmit	зелёный
Unit	npm test	1267 pass / 1 skip / 0 fail
Build + сверка бандлов	npm run build; cmp dist/houseplan-card.js custom_components/houseplan/frontend/houseplan-card.js; npm run bundle:sync + cmp с demo/srv/assets/houseplan-card.js	все три копии идентичны
Docs fingerprint	node scripts/check-docs.mjs	красный — ERROR screenshot source fingerprint is stale. Проверено: на коммите-родителе 4feeebc3 (до этой задачи) тот же скрипт зелёный (Documentation checks passed) — регрессия внесена именно этим диффом
Смок-выбор	node scripts/smoke-select.mjs --base origin/dev --head HEAD	27 «прямое совпадение» + 3 «зарегистрированная связь» = 30 из 185
Named smokes (30, список ниже)	node demo/smoke_<name>.mjs	29 OK, 1 FAIL (smoke_edit_walk.mjs)
Model invariants на новой фикстуре	node scripts/model-invariants.mjs --config test/fixtures/real-plan-second-floor.json --json	3 нарушения hidden_obstacles, как и заявлено в issue/ТЗ (до Optimize)
Golden capture двух новых сценариев	node demo/golden/run.mjs --mode=capture --scenario=hidden-wall-diagnostics-plan-{light,dark}	захват прошёл (missing-baseline, ожидаемо), но визуально сценарий не показывает диагностический слой — см. High-2
Backend unit	python -m pytest tests_backend/test_validation.py -q (агентом, после pip install --user pytest voluptuous)	136 passed, 1 skipped (приватная фикстура владельца)

Смоки, прогнанные из 30 (все «прямое совпадение» + все «зарегистрированная связь»): smoke_merge_split, smoke_zero_divider_taper, smoke_decor_layer_order, smoke_decor, smoke_edit_walk, smoke_editor_gestures, smoke_free_walls, smoke_glow, smoke_grid_scale_invariance, smoke_open_passage, smoke_opening_measure, smoke_opening_tunnel_fill, smoke_optimize_coincident_partition, smoke_optimize_micro_interval, smoke_optional_space_model, smoke_plan_drawing_repairs, smoke_plan_snap_overlay, smoke_resize_audit_1550, smoke_room_autoclose, smoke_room_resize, smoke_space_scale_defaults, smoke_split_corner_wall, smoke_split_nonsnap, smoke_unified_wall_tool, smoke_wall_chain_thickness, smoke_wall_face_overlap, smoke_wall_junctions, smoke_resize_pointer_real_plan, smoke_resize_wall_thickness, smoke_wall_key_roundtrip. Все зелёные, кроме smoke_edit_walk (см. High-3).

Не прогонялось и почему: полный набор demo/smoke_*.mjs (185 файлов) — предрелизный гейт, задача не задевает всё; npm run golden:verify (нет принятых baseline для новых сценариев — принятие вне ревью, канон CI; для существующих сценариев дрейф не проверялся отдельно, см. «Не проверено»); performance-бенчмарки (demo/benchmark_coincident_partitions.mjs, demo/benchmark_safe_resize*.mjs) — не названы явно упавшими, а спецификация делает обновление бюджетов условным («только при обоснованной необходимости»); полный HA/Linux-харнесс backend — недоступен в этой среде, каноном остаётся CI на точном SHA.

Находки

High-1 — backend не доказывает удаление partition без hosted opening (§8, AC6)

custom_components/houseplan/validation.py, _safe_optimize_partition_rehost (строки ~173–274). Функция вызывается на каждый opening, и восстанавливает target_a/target_b только как footprint конкретного opening (expected_x/y ± opening_length/2), а не ось всей старой partition. Диапазоны старой partition, на которых нет opening, вообще не проверяются backend'ом — ни на покрытие solid room-стеной, ни на неуменьшение толщины.

Это ровно основной сценарий issue: partition-mt2on9ou-0 и partition-room-mt7ijuyq-0 в приложенном плане владельца не несут ни одного opening ("openings": [] в этом пространстве). Подтверждено исполняемым репро (см. отчёт субагента): (1) partition без единого opening молча удаляется без единой проверки; (2) partition с opening, покрывающим лишь часть длины (0.4–0.6 из 0–1), после Optimize теряет реальный непокрытый остаток (0.6–1.0) — валидатор не возражает.

Спецификация §8 п.1–2 требует ровно обратного: backend обязан «восстановить ось и атомарное покрытие старой partition стенами комнат в новой конфигурации» и «доказать, что удалённые диапазоны полностью покрыты solid room walls не уже старой partition» — для всей partition, а не только для той её части, где есть opening. Сейчас allow_optimize_rehost=true доверяет frontend-delta без проверки именно там, где проверка нужнее всего.

Воспроизведение: tests_backend/test_validation.py не содержит теста с partition без openings; при добавлении такого случая (partition без openings, "удалённая" в candidate без замещающей стены нужной толщины) validate_partition_opening_hosts(..., allow_optimize_rehost=True) не поднимает PartitionOpeningHostError — вызов молча проходит.

High-2 — AC7 нарушен: диагностический слой не виден в инструменте Draw (§9.2)

src/houseplan-card.ts:19582-19583 (_renderHiddenWallDiagnosticOverlay) и вызывающая точка src/houseplan-card.ts:17391-17394 явно гасят слой при this._tool === 'draw':

private _renderHiddenWallDiagnosticOverlay(): TemplateResult {
    if (!this._markup || this._tool === 'draw') return svg`` as unknown as TemplateResult;
    ...
${this._tool === 'draw'
  ? this._renderPlanSnapOverlay()
  : this._renderHiddenWallDiagnosticOverlay()}

this._tool по умолчанию равен 'draw' (src/houseplan-card.ts:1270) — то есть при входе в редактор Плана диагностика не видна вовсе, до явного переключения инструмента. AC7 (§13): «Во всех инструментах редактора Плана перекрытая partition и сохранённый draft показывают полную ось и исходные endpoints...» — «во всех» не имеет исключения для Draw ни в АС, ни в §9.2 («Слой существует во всём редакторе Плана при любом активном инструменте»).

Это не только текстовое несоответствие: именно в инструменте Draw активен buildPlanSnapGeometry(), который дедуплицирует совпадающую ось в пользу комнаты (подтверждено существующим тестом «a completed room remains the authority for a coincident deduplicated axis»). То есть ровно там, где пользователь мог бы начать рисовать рядом со скрытым объектом, скрытый объект не показан вовсе, а показанная «архитектура» — дедуплицированная, без отдельных исходных endpoints, которые и есть единственный смысл диагностики (§9.1, последний пункт).

Воспроизведение исполнением: golden-сценарии hidden-wall-diagnostics-plan-light /-dark (добавлены этим же диффом для AC7) не задают _tool, поэтому остаются на дефолте 'draw'. Захват (node demo/golden/run.mjs --mode=capture --scenario=hidden-wall-diagnostics-plan-light) даёт скриншот с чекбоксом «Thickness» и подсказкой «click a grid dot to start a wall chain» — интерфейс инструмента Draw, а не диагностический слой. AC7-евиденс «editor golden light/dark for скрытая partition/draft» фактически не демонстрирует заявленную функциональность.

demo/smoke_plan_snap_overlay.mjs эту ветку не проверяет (переключается на _activateMarkupTool('select'), не на draw), поэтому регрессия не поймана смоком.

High-3 — smoke_edit_walk.mjs красный на новой фикстуре (AC6, §253-класс дефекта)

node demo/smoke_edit_walk.mjs --seed 2 --plan real-plan-second-floor.json

падает детерминированно:

real-plan-second-floor.json, семя 2, шаг 0: ресайз room-a#2 на -3
    wall_carrier · real-second-floor:1.020833,1.266667@0.0000 · 20 см
    ...
    off_lattice_coordinate · config · вне сетки 0 → 1
FAILED: walk_second_floor_seed2: expected true, got false

demo/smoke_edit_walk.mjs — обход-фаззер из issue #297, уже существующий на dev со своей таблицей известного долга (KNOWN, PLANS[...].debt). Этот же коммит трогает файл ровно одной строкой — поднимает debt для real-plan-second-floor.json с 1 до 3, но комментарий в самом файле (строки 50-58, не изменён) прямо требует обратного: «Когда #296 закроется, число здесь станет нулём, и тест это потребует». KNOWN-таблица для seed 2 (строка 77) заявляет только off_lattice_coordinate на шаге 0; фактически шаг 0 после ресайза даёт дополнительно wall_carrier — запись толщины, отвязавшуюся от какого-либо ребра/перегородки (класс #253, «не исчезла ли запись толщины», один из трёх инвариантов, прямо названных в задании на это ревью).

Изолировано: тот же результат воспроизводится на чистом dev (4feeebc3) с одной лишь новой фикстурой (без единой строки продуктового кода этой задачи) — git worktree add origin/dev, скопирован test/fixtures/real-plan-second-floor.json и debt-строка из смока, npm run bundle:sync, тот же вызов даёт тот же wall_carrier. Значит, баг живёт в resize.ts (не тронут этим диффом) и не является регрессией координат-присвоения этой задачи — но именно эта задача выбрала внести три проблемных записи прямо в test/fixtures/real-plan-second-floor.json, разделяемый с уже существующим смоком #297, вместо предложенной самой спецификацией альтернативы («либо заводится третья фикстура», §13 AC6) — и не привела разделяемый смок в соответствие. Сейчас гейт красный на коде, уходящем в dev.

Medium-1 (в скоупе) — check-docs красный, скриншоты не пересняты

См. таблицу гейтов. docs/** изменения этой задачи вводят новый видимый слой (диагностическая проекция) и правят множество канонических документов, но docs/images/screenshots.json/фингерпринт не обновлён. PROCESS.md §8 называет ровно эту ошибку («скриншоты не пересняли в #230 и #234, и dev стоял с красным job docs») и требует пересъёмки «тем же коммитом». Чинится: Docs screenshots (workflow_dispatch) → npm run docs:accept -- --reviewed --from=<артефакт> тем же issue.

Medium-2 (в скоупе) — счётчик удаления drafts делит сообщение с «мусором сетки» (одно число, два разных источника смысла)

src/plan-optimizer.ts:634-637:

if (reconciled.removedDrafts) {
  alignReport.removedDrafts += reconciled.removedDrafts;
  ...

reconciled.removedDrafts (новая причина: draft доказанно полностью совпадает с solid-стенами, §7) прибавляется к тому же alignReport.removedDrafts, который питает существующее сообщение gs.align_removed_drafts — «Invalid outlines collapsed by the grid and removed: {n}.» / «Схлопнувшиеся на сетке некорректные контуры удалены: {n}.» (src/houseplan-card.ts:16510-16513). Единственная i18n-правка этого диффа — gs.optimize_coincident_partitions (теперь верно говорит про «hidden independent wall sections»); для удаления drafts новой строки нет вовсе.

Пользователь, у которого Optimize удалит draft-mt7igts5 (доказанно избыточный, лежит на стене — причина №2 из этого самого issue), увидит текст «схлопнувшийся на сетке некорректный контур удалён» — неверное объяснение причины. Это ровно тот класс дефекта, который правило «одно число — один источник» просит проверять: одна и та же цифра в отчёте теперь означает два разных, несвязанных события без разделения в тексте. Не механический тест test/single-source-numbers.test.mjs (он про форматирование единиц) — смысловая часть правила, ответственность ревью.

Medium-3 (в скоупе) — порядок слоёв: диагностика рисуется НАД transient-превью инструмента «Проём»

src/houseplan-card.ts:17381-17394: _renderOpeningPlacementPreview() и _renderOpeningDimensionGuides() (призрак двери/окна и размерные направляющие) находятся в шаблоне раньше нового комбинированного слоя (planSnap/ hiddenWallDiagnostic) — то есть рисуются раньше = ниже по z-order, а диагностика поверх них. §9.2 требует обратного: слой должен быть painted «до... transient previews», то есть под ними. Ниже по документу диагностика по-прежнему корректно остаётся под реальными openings и resize-chrome — нарушение касается только этих двух превью инструмента «Проём». Подтверждено чтением (агент-ревьюер диагностического слоя); не воспроизведено визуально из экономии времени, но расположение в шаблоне однозначно.

Medium-4 (в скоупе) — backend §8: неизвестные поля partition и rehost на другой residual не доказаны

Из отчёта агента-ревьюера backend (полные репро в его выводе, здесь — суть):

• Неизвестные поля исходной partition не проверяются вовсе: _safe_optimize_partition_rehost читает у old_partition только a, b, cm; в отличие от opening (old_stable == new_stable, полное сравнение ключей), партиция не сверяется на неизвестные поля. §6.1/§8 явно требуют fail-closed на этот случай.
• Когда hosted opening по правилам §6.3 переезжает на другой id остатка (второй/ третий residual), проверку берёт на себя не _safe_optimize_partition_rehost, а старый (до-#296) «строгий» путь «rigid host translation», который проверяет только jamb-margin в новой конфигурации и не сверяет абсолютную геометрию (center/angle/ length) со старым opening. Существующий тест test_partition_opening_jamb_delta_preserves_legacy_and_checks_direct_geometry показывает, что перенос partition разрешён без такой сверки.

Medium-5 (в скоупе) — тестовый план §14.7 (mutation gate) выполнен частично

scripts/mutation-gate.mjs в этом диффе только переименовывает/адаптирует два уже существовавших мутанта #276 (optimizer-coincident-opening-rehost-disabled, переименованный optimizer-coincident-residual-dropped) к новой структуре кода. Ни одного нового мутанта нет для явно перечисленных в §14 п.7 сценариев: «заменить max толщины», «доверить frontend delta», «поместить overlay под стенами». Проверено grep по всему файлу — других #296-специфичных мутантов для coincident-partitions.ts или validation.py нет.

Medium-6 (в скоупе) — пробелы и регрессия тестового покрытия ядра алгоритма

Подтверждено субагентом чтением и точечными запусками против test-build:

• AC9 явно требует «limit unit» — ни один тест не упоминает MAX_PARTITIONS/ MAX_WALLS (2000/500). Логика по чтению верна и по чтению fail-closed (лимит проверяется до мутации walls/partitions), но не защищена регрессией, как того прямо требует акцептанс-критерий.
• Нет теста на opening, целиком лежащий на остатке (§6.4, средний из трёх случаев) — только ручная проверка агентом (host.id меняется на p~r-..., геометрия и openingsRehosted не трогаются, верно, но без автотеста).
• Нет теста на разную итоговую толщину между несколькими безопасными кусками одного partition — фикстура AC1 даёт «все стали 30», что не демонстрирует раздельный max() по кускам (агент подтвердил раздельность вручную: 10/25 см на соседних кусках остаются раздельными).
• Нет теста на per-piece column-blocking (колонна блокирует один кусок многокускового partition, другие реконсилируются).
• Регрессия покрытия: удалён тест-вариант «overlapping draft» из «issue 276 fails closed for an orphan host, overlap, draft, column and unknown partition data» (переименован без слова draft) и заменён только тестом на удаление полностью избыточного draft. Случай «активный, не полностью избыточный draft блокирует partition-piece, но сам не удаляется» — из логики жив (агент подтвердил запуском), но теперь не защищён ни одним тестом ни в старом, ни в новом файле.

Проверено и корректно

• AC1/AC5 (реальный план). test/optimize-hidden-obstacles.test.mjs (issue 296 real second floor removes all three hidden blockers in one Optimize) — реальные три объекта пропадают, partitionsReconciled>=2, removedDrafts==1, профиль 30/30/30, идемпотентность на повторном Optimize. Плюс test/resize-availability-audit.test.mjs: на real-plan-second-floor.json duplicate-physical-wall: 7→0, enabled: 5→9, real-plan-first-floor.json не изменился — реальный сквозной путь через продуктовый аудит, не мок.
• Направление входа, owner-kind, per-piece толщина, per-piece columnBlocks, MAX_PARTITIONS/MAX_WALLS fail-closed, «open» ≠ «есть проём» в WallInterval — проверено чтением и точечными исполняемыми экспериментами (агент), контрпримеры не найдены.
• Гейт видимости диагностического слоя (_markup = _mode==='plan') и его отсутствие в View/kiosk — тот же гейт, что у #137, подтверждено смоком (viewHasNoOverlay).
• pointer-events/aria-hidden, изоляция от buildPlanSnapGeometry()/snap-resolver — подтверждено чтением и юнит-тестом (findSharedRoomSnapSegment(...)?.sourceKind === 'room' не меняется).
• Кэширование диагностики по _cfgEpoch, не по pointermove — подтверждено чтением, паттерн идентичен существующему _planSnapGeometrySnapshot().
• Backend: allow_optimize_rehost=true не просачивается в обычный config/set и импорт (проверено чтением вызовов в websocket_api.py/import_export.py); там, где проверка есть (opening с footprint внутри одного или нескольких room-edge), _segments_cover_target — честный геометрический пересчёт (коллинеарность + слияние интервалов), не сверка id-списков; при любом исключении парсинга — False.
• Документация (CHANGELOG.md/.ru.md, USER-GUIDE.md/.ru.md, CANVAS.md, RESIZE.md, WALL-THICKNESS.md, ARCHITECTURE.md) согласована с реализацией и друг с другом по формулировкам piecewise-поведения и диагностики.
• Трейлеры коммита: Issue: #296, User-Visible: yes, оба changelog правлены в том же коммите.

Не проверялось (и почему)

• Полный набор demo/smoke_*.mjs (185 файлов) и npm run golden:verify по всем существующим сценариям — предрелизный гейт (§8); дрейф пикселей у ранее принятых golden-сценариев (не только двух новых) не проверялся построчно из бюджета времени. Учитывая находку High-2 (изменился порядок отрисовки _renderPlanSnapOverlay относительно _renderOpeningPlacementPreview/_renderRoomHoverOutline/editing _renderOpenWalls — раньше слой стоял сразу после _renderWallBodies, теперь значительно позже), нельзя исключить визуальный дрейф существующих сценариев с активным #137-overlay; отдельно от AC7 не воспроизведено — оставляю как открытый риск для golden:verify на предрелизе.
• Performance-бенчмарки (demo/benchmark_coincident_partitions.mjs и др.) — не запускались; спецификация делает обновление бюджетов условным, а свежих мутантов на производительность в этой задаче не добавлено.
• Полный HA/Linux backend harness — недоступен в текущей среде; прогнан только «чистый» pytest tests_backend/test_validation.py без Home Assistant (не требует импорта homeassistant/fcntl, тест грузит validation.py напрямую).
• Приватная фикстура владельца C:\Temp\44.json (backend/frontend оба) — недоступна, пропускается тестами штатно (t.skip).

Закрытие раунда r0 (спецификация)

Спек-ревью (SPEC-REVIEW-296-r1, зелёное) не образует цикл (§4, #227) и не входит в бюджет код-ревью. Три Low-наблюдения того ревью (терминология §2, канонический порядок id остатков §6.3/§12.3, несуществующий бенчмарк AC9/§14.7) сняты автором ревью с явной пометкой «решить на код-ревью» — они здесь и разобраны: порядок id остатков реализован (первый в каноническом порядке = исходный id, подтверждено тестом с детерминированными id), бенчмарк не создан и не назван явно — учтено в Medium-6/«не проверялось».

Итог

Вердикт: красный. Три High-находки блокируют: backend не доказывает удаление partition без openings (ровно основной сценарий issue), диагностический слой не показывается в инструменте Draw (AC7 буквально не выполнен, и собственный golden- евиденс это не ловит), и разделяемый смок-фаззер smoke_edit_walk.mjs красный на фикстуре, добавленной этой же задачей. Шесть Medium-находок в скоупе (docs-фингерпринт, смешение счётчиков, порядок слоёв, два backend-пробела, недоделанный mutation-gate, пробелы/регрессия тестового покрытия ядра) чинятся в этом же issue при возврате.