houseplan-card/docs/specs/249-multiwall-junction-bevel.md

Issue #249 — ограниченная геометрия узла из трёх и более стен

• Дата: 2026-08-23
• Тип: bug + polish · приоритет P2
• Ценность: пользовательская 7/10 · для разработки 8/10
• Сложность/риск: 5/10 и 6/10
• Issue: #249
• Ветка: issue/249-multiwall-junction-bevel
• Статус ТЗ: первая редакция, ожидает ревью

Канонические документы: docs/SCOPE.md, docs/WALL-THICKNESS.md, docs/ARCHITECTURE.md, docs/TOUCH-SUPPORT.md, docs/TESTING.md.

1. Сценарий и персона

Администратор рисует обычную пристройку или несколько комнат, сходящихся в одной точке. У трёх стен могут отличаться толщины. В View, kiosk и Static он видит не единый кладочный узел, а узкий клин, который выступает наружу на десятки сантиметров. Контуры пола рядом визуально наезжают друг на друга, хотя сохранённые оси стен и комнаты корректны.

Это нарушает J1 из docs/SCOPE.md: план перестаёт давать достоверную пространственную картину дома. Дефект постоянно виден, а не ограничен редактором.

2. Воспроизведение и измеренный дефект

Канонический regression fixture минимизируется из приложенного к issue экспорта houseplan-space-space-2026-08-22_21-33-04.json (card_version 1.67.0-beta.2, model_version 6, cell_cm = 30). В узле (0.329166667, 0.141666667) сходятся три положительных физических интервала:

Луч от узла	Второй конец	Толщина	Направление
A	(0.308333333, 0.237500000)	50 см	102.3°
B	(0.408333333, 0.100000000)	50 см	−27.8°
C	(0.379166667, 0.191666667)	70 см	45.0°

Углы между соседними лучами — 57.3°, 72.8° и 130.0°. Максимальная полутолщина H = 4.8611 render units. Текущий объединённый wall body содержит join-вершину на расстоянии 8.7312, то есть 1.80 × H, и рисует видимый зубец.

Причина подтверждена production-вызовами spaceModels() и wallBodiesGeometry(): две комнаты независимо строят митры пары 50/70 см через outsetContour()/insetContour(). Обе митры проходят общий MITRE_LIMIT = 4, после чего boolean union сохраняет противоположные выступы. junctionAt() и spaceMergeGeometry() этот узел не формируют.

3. Что человек увидит до и после

До: штриховка у многолучевого узла выходит клином далеко за физическую толщину стен; рядом видны наложенные контуры комнат.

После: те же сохранённые оси образуют один заполненный узел. Корректные короткие митры остаются острыми, а только чрезмерная join-вершина заменяется прямой локальной фаской. В узле нет щели, округления или выступа за установленный габарит. Обычные углы ровно из двух лучей выглядят как раньше.

4. Решения владельца

1. Fallback чрезмерной митры — прямая локальная фаска. Она образует единый заполненный узел; округление не добавляется.
2. В узле из 3+ различных физических лучей допустимый радиус join-вершины: R = 1.25 × H, где H — максимальная полутолщина всех сходящихся стен.
3. Правило применяется независимо от числа комнат и от того, равны ли толщины.
4. Узлы ровно из двух лучей сохраняют MITRE_LIMIT = 4 и существующий вид.
5. Исправляется одна каноническая вычисляемая геометрия для Full, Static, hidden Iso и световых барьеров. Persisted rooms/walls не переписываются.

5. Scope

Входит

• классификация физических узлов по уникальным инцидентным лучам;
• общий лимит 1.25 × max half-depth для join-геометрии узлов степени 3+;
• ограниченная митра либо прямая фаска в room inset/outset и в обязательных локальных junction pieces;
• согласованная каноническая кладка, clean-floor/room-fill границы, бумага, Full/Static/hidden-Iso и Glow/sun occlusion;
• unit-набор на 3/4 луча, разные толщины, порядок, winding и coordScale;
• browser smoke и golden-сценарий на минимизированном экспорте владельца;
• обновление docs/WALL-THICKNESS.md, docs/ARCHITECTURE.md, docs/TESTING.md и двух changelog.

Не входит

• изменение сохранённых координат комнат, walls, partitions или drafts;
• привязка узлов к сетке и Optimize-миграция старых планов;
• изменение толщины стен либо правил shared/outer/virtual interval;
• новый редакторский инструмент, настройка коэффициента в UI или i18n;
• округлённые joins, отделочные слои и отдельный материал узла;
• изменение двухлучевых острых/тупых углов;
• исправление независимой partition-топологии, уже принадлежащей linearWallJoinPatches().

6. Термины и классификация узла

physical interval — атомарный room-wall interval с положительной толщиной, который не является virtual/open. Его полутолщина уже переведена в render units существующим wallCmToUnits().

node — группа совпадающих концов физических интервалов в существующей scale-relative геометрической погрешности (openEps(pitch, coordScale) либо единый эквивалент подсистемы). Координаты не округляются к drawing grid.

ray — направление от node к противоположному концу interval:

• повтор одного физического shared interval от второй комнаты удаляется по каноническому interval key;
• совпадающие сонаправленные атомарные фрагменты считаются одним лучом и берут максимальную физическую полутолщину;
• противоположные направления прямой стены являются двумя разными лучами;
• zero-thickness и virtual intervals не увеличивают степень узла.

multi-wall node — node с тремя или более различными rays. Для него H = max(ray.halfDepth), R = 1.25 × H. Если конечные значения и положительный H получить нельзя, локальный limiter не создаёт новую геометрию и не должен ронять весь structural pass.

join vertex — точка пересечения смещённых граней либо точка локального junction patch, созданная именно для соединения интервалов в node. Дальние концы самих стен не являются join vertices и радиусом R не ограничиваются.

7. Геометрический контракт

7.1 Единая карта узлов

Один pure structural pass строит детерминированную карту multi-wall nodes из эффективных wallIntervals(). Карта не зависит от порядка rooms/walls, направления сохранённого отрезка или winding комнаты. Она строится один раз для текущей геометрии и передаётся всем contour/junction вычислениям; отдельные рендереры не распознают узел повторно.

7.2 Ограничение join

Когда вершина room profile совпадает с multi-wall node:

1. существующее пересечение смещённых граней остаётся митрой, если его расстояние от node <= R + epsilon;
2. если пересечения нет, оно не конечное либо дальше R, join содержит две штатные offset-точки соседних граней — прямую фаску;
3. каждая созданная для этого node join-вершина остаётся не дальше R + epsilon;
4. локальное соединение имеет ненулевую площадь, node не попадает в hole wall body, а тела всех инцидентных rays входят в один связный кладочный компонент;
5. boolean union не вправе вернуть в body отброшенную дальнюю вершину из другого независимого room ring. Все ring/piece producers получают одну карту и лимит до объединения.

Offset-точка фаски находится на расстоянии собственной полутолщины, поэтому для валидного interval автоматически укладывается в H <= R. Круг либо аппроксимация окружности не строятся.

7.3 Двухлучевая совместимость

Для node степени 1 или 2 сигнатуры и результат insetContour(), outsetContour() и существующих bounded junction patches не меняются: MITRE_LIMIT = 4 остаётся единственным лимитом. Новый коэффициент не становится глобальной заменой MITRE_LIMIT.

7.4 Канонические потребители

Исправленная structural geometry является общей для:

• wall body/hatch в Full, kiosk и Static;
• Plan preview сохранённой геометрии;
• hidden isometric masonry;
• clean floor, room fills и room hover, использующих внутреннюю грань;
• paper/exterior shell там, где multi-wall node принадлежит внешней границе;
• Glow/sun/light source occlusion.

Существующие structural caches продолжают ключеваться полной геометрией. Курсор, hover и HA state tick не перестраивают topology. Исправление не вводит расходящиеся SVG-only и physics-only patches.

7.5 Ошибки и fallback

• Валидный multi-wall node не может молча вернуться к дальнему MITRE_LIMIT = 4 join: если точная митра не укладывается в R, результатом служит фаска.
• Неконечный или вырожденный локальный candidate отбрасывается изолированно; он не превращает успешную остальную кладку, paper или light barriers в null/пустой план.
• Существующий fail-dark контракт обязательного structural pass сохраняется: исправление не должно маскировать независимую ошибку exterior/body/opening.

8. Данные, совместимость и производительность

• Схема и model_version не меняются; config/layout остаются byte-for-byte.
• Результат вычисляется при чтении и сразу исправляет старые планы без Save.
• Backend и WebSocket не меняются.
• Нет новых i18n, настроек, действий, жестов либо различий mouse/touch.
• Построение node map ограничено structural geometry pass; допускается линейная либо O(E log E) группировка. Новый полный O(E²) обход на каждый render/state tick запрещён.

9. Acceptance criteria и доказательства

AC1. Экспорт владельца больше не даёт шип

Минимизированный fixture хранит только необходимые rooms, wall entries и scale-параметры из экспорта. Для node (0.329166667, 0.141666667):

• wallBodiesGeometry() возвращает успешную непустую геометрию;
• H = 4.8611, и каждая join-вершина node находится не дальше 1.25 × H + epsilon;
• node не лежит в hole, локальный wall body имеет ненулевую площадь и один компонент касается тел всех трёх rays;
• повторный расчёт даёт тот же нормализованный geometry/path.

Доказательство: unit в test/wall-thickness.test.mjs и новый fixture test/fixtures/249-multiwall-junction.json.

AC2. Матрица многолучевых узлов

Те же инварианты выполняются минимум для:

• трёх стен одинаковой толщины;
• трёх стен 15/50/70 см;
• четырёх стен с равными и разными толщинами;
• перестановки rooms/walls, обратного направления intervals, обоих windings и production coordScale = 1000.

Ни один вариант не создаёт gap, self-intersection, null либо второй локальный кладочный компонент.

Доказательство: table-driven unit с численным bound и сравнением нормализованной геометрии.

AC3. Два луча не меняются

Ровно две стены одинаковой толщины под углами fixture #249 и существующие acute/obtuse contour cases возвращают прежние точки/paths и продолжают использовать MITRE_LIMIT = 4. Новый limiter не превращает корректную митру в фаску.

Доказательство: unit regression на insetContour()/outsetContour() и существующий wall-thickness unit-набор без обновления его двухлучевых expected values.

AC4. Все поверхности используют один body

На fixture #249 Full/View, Plan с сохранённым контуром, kiosk, Static, hidden Iso и light occlusion получают одну исправленную physical geometry: клина нет, а луч света не проходит через заполненный узел. Переключение темы и HA state не меняет structural path и не вызывает его пересчёт.

Доказательство: targeted browser smoke demo/smoke_multiwall_junction.mjs с path/geometry assertions и cache parity.

AC5. Golden фиксирует видимый результат

В golden matrix добавлен отдельный crop узла из минимизированного экспорта: видны три луча, фаска и отсутствие щели. Сценарий имеет semantic assertions на число rays и ограниченный габарит, поэтому пустой или неверно кадрированный PNG не может пройти.

Доказательство: demo/golden/matrix.mjs, harness/fixture и test/golden-matrix.test.mjs. Новый baseline принимается только по полному Linux CI artifact командой npm run golden:accept -- --reviewed перед бетой.

AC6. Данные и смежные контракты не меняются

Расчёт не мутирует rooms/walls/open spans, не меняет schema/model version и не затрагивает independent partition junctions, openings или двухлучевые внешние углы.

Доказательство: deep-equality unit входа до/после и зелёные существующие wall/opening/junction tests.

AC7. Гейты реализации

В цикле реализации зелёные:

• npm run typecheck;
• npm test;
• npm run build;
• targeted node demo/smoke_multiwall_junction.mjs после копирования свежего bundle в demo.

Полный smoke, golden и performance запускаются перед бетой; полный backend HA-harness не требуется, если Python/backend не меняются, но общий exact-SHA Validate остаётся обязательным.

10. Документация и changelog

• docs/WALL-THICKNESS.md: степень node, R = 1.25 × H, фаска и сохранение MITRE_LIMIT = 4 для двух лучей;
• docs/ARCHITECTURE.md: единая node map и потребители canonical masonry;
• docs/TESTING.md: unit/smoke/golden evidence #249;
• docs/CHANGELOG.md и docs/CHANGELOG.ru.md: пользовательский bugfix в том же коммите, что продуктовая правка.

11. Откат

Откатывается pure multi-wall node classification/limit и связанные tests/docs. Данные не мигрируются, поэтому отдельный data rollback не нужен. Golden baseline откатывается только вместе с соответствующей product geometry.

12. Принятые технические предположения

1. Коэффициент 1.25 — именованная константа канонической wall geometry, а не настройка и не литерал в рендерерах.
2. Shared interval, встреченный из двух room profiles, является одним физическим лучом; иначе обычный T ошибочно классифицировался бы по числу владельцев.
3. В regression fixture не переносится остальной пользовательский экспорт: сохраняется минимальная обезличенная геометрия, достаточная для численного и визуального воспроизведения.
4. epsilon берётся из существующей scale-relative геометрической политики и не ослабляется до шага drawing grid.
5. Если реализация требует отдельного bounded fill patch для положительной связности, он остаётся частью canonical structural geometry, целиком лежит в радиусе R и проходит тот же детерминизм/failure isolation; это не отдельный визуальный слой.