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

CODE-REVIEW-242-r1

• Issue: #242 — «Проём в толстой стене рисуется у произвольной грани, а не по центру толщины»
• Этап: code (PROCESS.md §2.7)
• Заход: r1 (первый код-цикл; SPEC-REVIEW-242-r1 — зелёный)
• Диапазон: origin/dev..HEAD = 0033138..5e13e34 (5 коммитов), реализация — 6d6db12 (fix(openings): center symbols across wall depth, User-Visible: yes)
• Вердикт: жёлтый

Скоуп

ТЗ docs/specs/242-opening-symbol-center.md требует: символ проёма (дверь/окно/ворота) по умолчанию центрируется по толщине стены на всех render surfaces (Flat/View, preview, hosted Static, скрытый Iso); сохранённый flip_v: true у двери/окна остаётся ручным edge alignment; у ворот flip_v не двигает створки, а только меняет знак существующего 10° поворота (AC4, §4.3, §7 таблица). Направление должно быть детерминированным и не зависеть от порядка комнат/направления независимой стены (AC2).

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

Прочитаны docs/SCOPE.md, PROCESS.md, docs/specs/242-opening-symbol-center.md, docs/WALL-THICKNESS.md, docs/ARCHITECTURE.md, docs/ISOMETRIC.md, docs/USER-GUIDE.ru.md, тело issue и все комментарии (аналитика, Q1–Q4, решения владельца, handoff разработчика).

Дифф прочитан построчно: src/opening-symbol-placement.ts (новый), src/wall-thickness.ts, src/render/opening-symbol.ts, src/iso-openings.ts, плюс unit/smoke/mutation-gate правки. src/houseplan-card.ts и src/partition-openings.ts диффом не тронуты — они читались как неизменный контекст, через который резолвится face.

Гейты, реально прогнанные в этой сессии:

Гейт	Результат
npx tsc --noEmit	green
npm test	green, 1095/1095
npm run build + сверка dist / demo/srv/assets / custom_components/.../frontend	green, все три sha256 = 3befe09b…, git status чист
node scripts/check-docs.mjs	green (7 файлов, 10 внешних ссылок)
node scripts/mutation-gate.mjs --check	green, включая 3 новых мутанта opening-symbol-*
node scripts/smoke-select.mjs --base origin/dev --head HEAD	«Зарегистрированная связь» → smoke_isometric_contract.mjs, smoke_wall_thickness.mjs (оба помечены автором как прогнанные и зелёные; полный вывод инструмента ниже)
npm run golden:verify на HEAD	red (см. раздел «Находки», M1) — прогнан дважды подряд, результат детерминирован
npm run golden:verify на origin/dev (5bf1868, отдельный git worktree)	red по своему меньшему набору сцен — снят как база для сравнения, не для приёмки

Дополнительно я independently проверил геометрический контракт прямым запуском в headless Chromium через demo/serve.mjs (тот же харнесс, что используют существующие demo/smoke_*), а не только чтением кода — конкретно AC4 для ворот, потому что до-релизная логика face/flip у ворот инвертирует flip_v дважды (faceFlipV = !o.flip_v в src/houseplan-card.ts при построении face, затем сырой o.flip_v ещё раз в sy внутри renderOpeningVisibleGeometry), и я не был уверен в результате по одному чтению formулы. Три сценария (свежее состояние карточки на каждый, без переиспользования state):

1. Ворота на внешней (однокомнатной) толстой стене (_wallThickClick, cm=25) — flip_v: false → рычаги rotate(-10deg)/rotate(10deg), flip_v: true → rotate(10deg)/rotate(-10deg). Меняется, как требует AC4.
2. Ворота на общей стене двух комнат (тот же сценарий, что и исходный баг — стена между r1/r2) — flip_v: false и flip_v: true дают одинаковый rotate(10deg)/rotate(-10deg); направление не меняется. Проверено дважды, плюс с перестановкой sp().rooms — результат идентичен во всех четырёх комбинациях.
3. Ворота на независимой стене (host: { kind: 'partition', … }), прямые и развёрнутые endpoints — flip_v: false и flip_v: true также дают одинаковый rotate(10deg)/rotate(-10deg) в обеих ориентациях перегородки.

Скрипты воспроизведения не коммитились (репозиторий трогать нельзя), но последовательность — это буквально demo/smoke_wall_thickness.mjs до момента создания стены, плюс sp().openings = [{ type: 'gate', … }] и чтение .op-leaf style после c._cfgEpoch++/requestUpdate/updateComplete; сравнение flip_v до/после и общей/независимой стены до/после — воспроизводится любым инструментом с доступом к window.__card.

Находки

H1 (High, в скоупе) — AC4 не выполнен: flip_v не меняет направление 10° поворота ворот на общей стене и на независимой стене

Что не так. Спецификация (§4.3, §7 таблица: gate | true | (0,0) | противоположный знак 10° поворота) и AC4 («Gate при обоих значениях flip_v центрирован, но знак 10° поворота меняется») требуют, чтобы флаг flip_v у ворот всегда переключал сторону лёгкого поворота створок, при неизменном центрированном origin. Перевод «центр не двигается» (translation) реализация делает верно — openingSymbolOffset безусловно возвращает {0,0} для type==='gate'. Но требование «знак меняется» не выполняется для двух из трёх типов host, включая тот, что явно назван в самом issue как источник бага:

• общая стена двух комнат — именно тот кейс, ради которого затевалась вся задача («порядок комнат», «то с одной стороны, то с другой»). Створки ворот на общей стене поворачиваются одинаково при flip_v: false и flip_v: true (см. воспроизведение выше, сценарий 2);
• независимая (partition) стена — тот самый путь, про который в issue сказано: «сторона фиксирована знаком... то есть по умолчанию всегда одна и та же грань» (сценарий 3). После правки трансляция действительно исчезла (это была цель), но направление поворота по‑прежнему не реагирует на flip_v вообще — то есть первоначальный дефект (фиксированный знак) для этого пути не устранён, просто перестал быть заметен из-за убранного смещения.

Направление меняется корректно только для ворот на однокомнатной внешней стене (сценарий 1) — самом редком практическом месте для ворот.

Причина по коду. src/houseplan-card.ts инвертирует flip_v перед резолвом грани только для ворот: faceFlipV = o.type === 'gate' ? !o.flip_v : o.flip_v (строки 11988, 18551, 12066 и в Iso-ветке 5289), затем передаёт сырой o.flip_v в visibleSpec.flipV/sy. src/render/opening-symbol.ts считает gateAngle = spec.face.side * sy * 10 * amount. Для стороны, получаемой через partitionOpeningFace (side = flipV ? 1 : -1, не тронут этим диффом) и через «общую стену» ветку wall-thickness.ts (naturalSide = association.negative && association.positive ? -1 : available[0].side, тоже реагирует на flip_v только знаком) двойная инверсия (faceFlipV затем sy) арифметически гасит сама себя: side * sy даёт одно и то же значение при flip_v=false и flip_v=true. Единственный случай, где это не совпадает — однокомнатная стена, потому что там naturalSide берётся из available[0].side, единственного реального кандидата, а не из пары negative/positive, и по независимым от меня причинам (сама схема _openingFace/resolveOpeningWallAssociation) итоговый знак там ведёт себя иначе; я подтвердил это эмпирически, а не через ручной вывод формулы (see «Как проверялось»), и не настаиваю на объяснении «почему именно этот случай работает» — важен наблюдаемый факт.

Кто ещё вводится в заблуждение. Оба changelog, docs/WALL-THICKNESS.md, docs/ARCHITECTURE.md, docs/ISOMETRIC.md и docs/USER-GUIDE.ru.md прямо утверждают обратное: «ворота остаются по центру, а флаг меняет только направление их 10° открытия» (и англ. эквивалент «a gate flip changes only turn direction»). Это неверно для двух из трёх host-путей.

Почему не поймано тестами. test/opening-symbol.test.mjs для ворот проверяет rotate(10deg)/rotate(-10deg) только у одного (не-flipped) рендера — второй (flippedGate) собирается, но его rotate(...) значения нигде не сравниваются с первым. test/iso-openings.test.mjs сравнивает gate/gateFlipped, но эти два фикстура одновременно меняют и flipV, и face.side вручную — тест не воспроизводит, что в реальном рендере side сам является функцией от flip_v через faceFlipV, поэтому не ловит гашение знаков. demo/smoke_isometric_contract.mjs проверяет только Math.abs(leaf.turnDeg) === 10, не сравнивая знак с неперевёрнутым вариантом. Ни один golden-сценарий с воротами flip_v: false/true рядом не добавлен (см. M1) — а именно такая сцена сделала бы дефект видимым на глаз.

Серьёзность. High: явный, воспроизводимый разрыв между заявленным в ТЗ/ docs контрактом и фактическим поведением для двух из трёх типов host-стен, включая тот, что был первопричиной issue. Блокирует.

Как исправить (для автора, не мной): либо не инвертировать flip_v при резолве face для ворот в houseplan-card.ts (раз "сторона" в face.side и так уже несёт нужный знак), либо использовать в gateAngle не spec.face.side, а сырой !!o.flip_v/детерминированную локальную сторону напрямую, независимо от того, как резолвер комбинирует её с flip_v дважды. Нужна регрессионная проверка знака на пути «общая стена» и «partition», а не только «однокомнатная стена».

M1 (Medium, в скоупе) — заявленный golden-охват в handoff занижен на порядок; обязательные по §12.3 новые сцены не добавлены

Handoff-комментарий разработчика утверждает: «Targeted golden: opening-placement-door-thick-wall-dark и openings-thick-wall-dark ожидаемо different». Фактический npm run golden:verify на точном 5e13e34 (прогнан дважды, детерминированно) даёт different по ~48 сценам, не по двум — сравнение с тем же прогоном на чистом origin/dev (отдельный git worktree, тот же локальный Chromium) показывает, что подавляющее большинство новых расхождений (isometric-geometry-*, day-cycle-*, lighting-*, hover-*, device-*, optimize-preflight-dialog-*, backup-*, room-label-parity-* и др.) на dev были passed, а на HEAD стали different. Причина ожидаемая и не является отдельным багом: эти сцены используют общие фикстуры (golden-geometry, golden-lighting), в которых уже стоит дверь/окно/ворота в толстой стене — символ у них теперь центрирован, и это меняет пиксели кадра, даже когда сценарий проверяет не связанную с проёмами вещь (солнце, hover, диалог). Это не находка «что-то сломалось непричастное», а находка «отчёт разработчика не соответствует действительности на порядок величины» — то же самое, что ревью #231-r1 уже находило (M1 там: «список golden-сцен неполон») и что #231-r2 потребовало зафиксировать явным списком в docs/TESTING.md, а не оставлять в тексте handoff-комментария.

Отдельно: §12.3 ТЗ требует добавить новые semantic-сцены — «centered door/window/gate на толстой room wall, Light», «те же типы on diagonal partition, Dark», «door/window с flip_v: true и gate false/true рядом», «hidden Iso parity for center and gate direction» — и обновить golden semantic guard, чтобы он до PNG-сравнения проверял wall centerline, visible-group center, jamb depth, flip_v и gate angle. Ни одна из этих сцен не добавлена в demo/golden/matrix.mjs (диф по этому файлу — только правка комментария для существующей opening-placement-door-thick-wall-dark); никакого нового semantic guard тоже нет. Именно сцена «gate false/true рядом» — то, что сделало бы H1 видимым на глаз ещё до code review.

Серьёзность. Medium, в скоупе задачи: тестовый план §12.3 не выполнен полностью, а фактический охват регрессии не задокументирован для предрелизного golden:accept -- --reviewed, который будет принимать эти ~48 сцен без знания их полного списка и происхождения. Чинится добавлением описанных в §12.3 сцен/guard и точного списка затронутых существующих сцен (аналогично docs/TESTING.md в #231-r2) — без необходимости отдельного issue.

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

• AC1/AC2 для room-wall пути (без flip_v, центр стены, независимость от порядка комнат). openingInnerFaceOffsetFromIndex разделяет физическую половину (piece.half/piece.cm, не зависит от flip_v) и направление (side из resolveOpeningWallAssociation, вычисляется из локальной нормали открывания nx,ny = f(opening.angle) и геометрического edge.inward, не зависит от порядка rooms/candidateOrder). test/wall-thickness.test.mjs добавил reversed/reversedFlip deepEqual-проверку — я прочитал и проверил, что тест умеет падать (откатил численно вручную: без замены сортировки .order на геометрический side возвращается старое значение).
• AC2 для partition-пути. resolvePartitionOpening нормализует angle через atan2 + приведение к [-90,90), что инвариантно к развороту a/b (проверено чтением и совпадает с уже существующим тестом test/partition-openings.test.mjs:35, не тронутым этим диффом). openingSymbolOffset использует Math.hypot(face.ox, face.oy) — модуль, а не знак — поэтому разворот partitionOpeningFace's ox/oy (который реально зависит от направления оси, см. axis.ux/uy) не протекает в видимое смещение. Это подтверждено и unit-тестом (test/opening-symbol-placement.test.mjs: positiveFace/negativeFace дают одинаковый результат), и моим собственным browser-тестом сценария 3 выше (симметрия сохраняется, хоть и с той же H1-проблемой по направлению).
• AC3 (door/window flip_v: true, окно целиком). test/opening-symbol.test.mjs проверяет, что op-glass/leaves/arc едут одним translate; я прочитал renderOpeningVisibleGeometry — стекло действительно внутри той же <g transform="translate(...)">, что и створки/дуги.
• Jambs full-depth. jambHalf в openingVisibleMetrics считается из spec.face.cm независимо от swingTx/swingTy — косяки не входят в переносимую группу, как требует §7. Проверено чтением, не исполнением отдельного визуального теста.
• AC7 (без миграции/схемы). src/opening-symbol-placement.ts — чистые функции, OpeningCfg.flip_v не тронут, новых полей/типов конфигурации нет. git diff подтверждает: единственный новый файл — чистый TS-модуль без side-effects.
• User-Visible / трейлеры. 6d6db12 несёт Issue: #242 и User-Visible: yes; оба changelog обновлены в том же коммите (см. git show 6d6db12 --stat).
• Три копии бандла. sha256 dist/houseplan-card.js, demo/srv/assets/houseplan-card.js, custom_components/houseplan/frontend/houseplan-card.js совпадают между собой и с заявленным автором хэшем; npm run build воспроизводит их без диффа в рабочем дереве.
• Mutation-gate. Три новых мутанта (opening-symbol-default-uses-room-face, opening-symbol-partition-follows-endpoints, opening-gate-flip-translates-leaves) проходят --check; я прочитал патчи — они действительно откатывают именно центрирование/order-independence (не гейт-обход), но, как и unit/golden выше, не покрывают H1 (мутант про ворота проверяет только «не появилась ли трансляция», а не «меняется ли знак поворота»).

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

• Полный Linux golden-артефакт и его reviewed-приёмка — вне цикла код-ревью по правилу §13 (golden:accept только по полному Linux release artifact). Локальный golden:verify, который я прогнал, обслуживает только M1 (охват дельты), не приёмку эталонов.
• python -m pytest tests_backend — не прогонял: custom_components/**/*.py диффом не тронут.
• Performance-профили — не прогонял: задача не называет их в AC, изменение чисто геометрическое без новых аллокаций/обходов по стенам (проверено чтением: openingSymbolOffset — O(1) арифметика на уже разрешённом face).
• Ручной пиксельный просмотр каждой из ~48 изменившихся golden-сцен — я установил только факт и причину расхождения (общая фикстура с дверью), не разбирал каждую сцену построчно; это и есть предмет M1.
• AC1 буквально на 1/15/100 см. Существующие unit-тесты (wall-thickness.test.mjs, opening-symbol-placement.test.mjs) используют другие конкретные значения cm (15/20/25/30); отдельного sweep по 1/15/100 см для нового contract'а нет. Не поднимаю как отдельную находку — арифметика линейна по cm (piece.half, масштаб) и не имеет условных ветвей по величине толщины, риск низкий, но формальное доказательство AC1 в заявленном виде отсутствует.
• Полная browser-smoke матрица (167 сценариев) — не прогонял всю. Выбор ограничен smoke-select-выводом (2 зарегистрированные связи, обе прогнаны автором и мной перепроверены через отдельные ad hoc browser-скрипты на реальном харнессе, не только через существующие smoke-файлы) плюс дополнительные smoke_partition_openings.mjs/smoke_opening_preview.mjs, которые автор тоже прогнал зелёными. Полный прогон не требуется: диф не задевает несвязанные подсистемы (unrelated golden-diff в M1 объяснён общей фикстурой, а не изменением поведения самих этих подсистем).