houseplan-card/docs/specs/229-merge-collinear-partitions.md

Issue #229 — сращивание коллинеарных отрезков стен

• Issue: https://github.com/Matysh/houseplan-card/issues/229
• Связанные контракты: #173 (инструмент «Стены»), #218/#223/#224 (устойчивость геометрии к floating-point), #228 (проблемы при рисовании)
• Тип: enhancement, обычный полный трек
• Приоритет: P2
• Пользовательское изменение: да
• Touch editor: not exposed — задача не добавляет ни одного жеста; поведение на сенсорных экранах не меняется вовсе (docs/TOUCH-SUPPORT.md §153).

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

Персона: администратор плана — тот, кто рисует и поддерживает планировку (docs/SCOPE.md, job J6).

Сценарий: длинную наружную стену рисуют не одним движением, а в несколько кликов — так удобнее ставить точки по узлам сетки и следить за длиной. Стена получается прямой, но состоит из отрезков, и на каждом стыке остаётся узел. Дальше этот узел мешает: при выделении цепляется не та часть, при перетаскивании стена ломается пополам, толщину приходится назначать по кускам.

Момент: сразу после завершения цепочки в режиме «Стены».

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

До: прямая стена, нарисованная в пять кликов, — это пять отрезков с четырьмя узлами. Внешне шов не виден, но он проявляется при первом же взаимодействии.

После: та же стена — один отрезок без узлов. Узел остаётся только там, где для него есть причина: примыкание другой стены или пересечение.

3. Подтверждённая причина

_finishWallChain (houseplan-card.ts:6538) режет цепочку по числу поставленных точек и добавляет по одной независимой перегородке на сегмент:

for (let i = 0; i < segmentCount; i++) {
  const segment = segments[i];
  sp.partitions.push({ id: `partition-${seed}-${i}`, a: …, b: …, cm: segment.cm });
}

Слияния коллинеарных соседей нет ни здесь, ни позже.

Асимметрия. Стены комнат такую компактизацию проходят: normalizeWallIntervals (wall-thickness.ts:1258) «compact every maximal solid run of one thickness», оптимизатор её вызывает (plan-optimizer.ts:483) и считает результат в wallsMerged. Независимые перегородки в оптимизаторе только выравниваются по сетке (align-grid.ts:262). То есть правило «одна физическая протяжённость — одна запись» уже сформулировано и действует на половину модели.

Подтверждено на данных. В экспорте владельца из #228 (1.json, 9 перегородок) есть пара коллинеарных соседей одной толщины с общим концом: #0 (cm=29, 48.95 м) и #4 (cm=29, 16.05 м), угол 0.0°.

4. Продуктовые решения владельца (2026-08-21)

1. Момент слияния — сразу при завершении цепочки. Нарисовал прямую в пять кликов, получил одну стену.
2. Уже нарисованные планы сращиваются в «Оптимизировать планы» — явным действием, с отчётом и возможностью отмены.
3. Проём на стыке не отменяет слияние: отрезки сращиваются, а позиции проёмов пересчитываются так, чтобы двери и окна остались физически на месте.

5. Цели

• Прямой участок одной толщины без причин для узла хранится одной записью.
• Ни один проём не смещается физически при слиянии.
• Правило «одна протяжённость — одна запись» действует и для перегородок.

6. Scope

• Чистый модуль слияния (src/wall-merge.ts) — правила без DOM, проверяемые юнитами.
• Вызов при завершении цепочки (_finishWallChain, houseplan-card.ts:6538).
• Вызов в «Оптимизировать планы» с новым счётчиком в отчёте.
• Пересчёт host.t и материализованной проекции x/y/angle проёмов, висящих на сращиваемых перегородках.
• i18n строки счётчика (en + ru), оба changelog.

7. Не входит в задачу

• Стены комнат — их компактизация уже работает (normalizeWallIntervals), не трогаем.
• Колонны и черновики контуров — у них своя жизнь, слияние к ним неприменимо.
• Разрезание сросшейся стены — существующий инструмент, поведение не меняется.
• Промахи примыкания (#228, пункт 2) — соседняя причина зубцов, отдельная задача.
• Автоматическое слияние при любой записи конфига — отвергнуто решением §4.1/§4.2.

8. Контракт поведения

8.1. Когда две перегородки сращиваются

Обе одновременно:

1. одинаковая толщина — cm совпадает точно;
2. коллинеарны — модуль векторного произведения направляющих ≤ EPS_ANGLE;
3. имеют общий конец — расстояние между концами ≤ EPS_JOIN;
4. на общем конце нет причины для узла (§8.2).

Результат — одна запись: концы дальние, cm прежний, id — от той из двух, что идёт раньше в массиве (детерминированно, не по времени создания).

8.2. Что считается причиной оставить узел

На общем конце сходится что-то ещё:

• третья перегородка (любой толщины, любого направления);
• ребро комнаты;
• колонна;
• конец сохранённого черновика контура.

Пересечение (не касание концами) узла не создаёт: перегородки в модели независимы и пересекаться могут без общей вершины — такой случай не является стыком и в слиянии не участвует.

Все четыре причины проверяются одним допуском EPS_JOIN — тем же, которым проверяется совпадение концов самих перегородок (§8.3). Отдельного допуска для ребра комнаты, колонны или черновика нет: иначе один и тот же зазор считался бы стыком в одном случае и не считался в другом, а AC2 перестал бы быть однозначным. Точка стыка берётся у ребра комнаты — ближайшая точка на любой стороне полигона, а не только его вершина; у колонны — её центр, у черновика — конец сохранённого контура.

Именно сторона, а не вершина: T-стык перегородки к середине комнатной стены — штатный случай продукта (docs/specs/141-wall-junctions.md §13.1 прямо называет примыкание «к середине существующей wall/partition»), и такой узел обязан пережить слияние. Примитив для этого в коде уже есть — distToSegment по рёбрам комнаты (plan-snap-overlay.ts:313), считающий расстояние до отрезка. Ревизия r3: прежняя редакция говорила «ближайшая вершина полигона» и пропускала ровно этот случай (находка M1 ревью r2).

8.3. Допуски

Один источник истины на обе проверки, объявленный константами в модуле:

• EPS_ANGLE — коллинеарность;
• EPS_JOIN — совпадение концов.

Оба выражаются в долях шага сетки, а не в абсолютных единицах: планы живут при cell_cm от 1 до 25 (см. #230), и абсолютный допуск на одном масштабе будет слишком строгим, на другом — слишком щедрым.

Отдельно про floating-point. После #218/#223/#224 известно, что почти совпадающие координаты — норма. Допуск обязан их прощать, но не настолько, чтобы склеить то, что разведено намеренно: нижняя граница — заведомо больше ULP-шума, верхняя — заведомо меньше одного шага сетки.

8.4. Проёмы

Позиция проёма хранится как доля длины хозяина: along = host.t * axisLength (partition-openings.ts:64). При слиянии длина меняется, поэтому для каждого проёма, чей хозяин участвует в слиянии:

1. вычисляется абсолютная позиция вдоль старого хозяина;

2. пересчитывается в долю новой длины с учётом того, какой конец стал началом;

3. если хозяин поглощён — host.id переписывается на выжившую запись.

4. пересчитывается материализованная проекция x/y/angle того же проёма.

docs/CONFIG-COMPATIBILITY.md (#132) объявляет legacy x/y/angle обязательной компаньонкой хоста: «the legacy x/y/angle siblings remain a materialized compatibility projection for older readers», и прямо требует, чтобы full export, plan-only export, merge и оптимизация сохраняли согласованность. В коде это уже норма: после любого изменения хозяина вызывается materializePartitionOpening (houseplan-card.ts:7824 — перетаскивание перегородки, :12007 — правка проёма). Слияние — такое же изменение хозяина и обязано делать то же самое.

Инвариант: координаты центра проёма в единицах плана до и после слияния совпадают с точностью до EPS_JOIN — и в резолвленном виде, и в материализованной проекции. Именно это проверяет AC3: не «поле пересчитано», а «дверь физически не сдвинулась», причём для обоих читателей — текущего фронтенда и того, который умеет читать только x/y/angle.

8.5. Границы применения

• слияние применяется многократно до стабилизации: три отрезка подряд дают одну запись, а не две;
• порядок обхода не влияет на результат (проверяется перестановочным тестом, как в #218).

8.6. Что именно сращивается при завершении цепочки

Решения §4.1 и §4.2 делят работу: рисование чинит свой шов, накопленное чинит «Оптимизировать планы» — там для этого есть отчёт и отмена.

Поэтому при завершении цепочки слияние затрагивает только записи, связанные с этой цепочкой: сегменты самой цепочки и те существующие перегородки, с которыми она имеет общий конец, — далее транзитивно, пока цепочка стыков не оборвётся. Иными словами, компонента связности по общим концам, содержащая хотя бы один новый сегмент.

Перегородки, не связанные с новой цепочкой, не трогаются, даже если между собой они образуют шов, подлежащий слиянию. Такой шов дождётся оптимизатора.

Почему не «всё пространство». В пространстве владельца из #228 уже лежит коллинеарная пара #0/#4. Если дорисовать стену в другом углу, «слияние по всему пространству» молча починило бы и эту пару — то есть правка старых данных без отчёта и без выделенной отмены, ровно то, что §4.2 обещает делать только по явной команде.

9. Данные, i18n, a11y, privacy, security

• Данные: формат перегородки не меняется; меняется их количество и host.id части проёмов. Новых полей нет, CONFIG_SCHEMA не трогается, миграции нет.
• i18n: строка счётчика в отчёте «Оптимизировать планы» (en + ru).
• a11y, privacy, security: без изменений.

10. Performance

Слияние — разовый проход по перегородкам пространства при завершении цепочки (десятки записей) и при оптимизации. Влияния на кадр рендера нет: в горячем пути ничего не добавляется, наоборот, записей становится меньше.

11. Риски

1. Проём уезжает. Главный риск: host.t относителен. Закрывается §8.4 и AC3 с проверкой в единицах плана, а не в долях.
2. Склеили то, что разведено намеренно. Пользователь мог оставить два отрезка с зазором меньше допуска. Нижняя граница EPS_JOIN и AC5 стерегут это.
3. Потеря узла, который был нужен. Узел на примыкании — часть модели стен; §8.2 перечисляет причины явно, AC2 проверяет каждую.
4. Недетерминированность. Выбор выжившего id и порядок обхода не должны зависеть от времени или порядка кликов — AC6.

12. Acceptance criteria

1. AC1 — прямая цепочка становится одной записью. Пять кликов по одной прямой при неизменной толщине дают одну перегородку без узлов; концы совпадают с крайними точками цепочки. Доказательство: unit + smoke.
2. AC2 — узел с причиной остаётся. Слияния не происходит, если на общем конце есть третья перегородка, ребро комнаты, колонна или конец черновика — четыре отдельных случая. Случай «ребро комнаты» проверяется T-стыком к середине стороны, а не только к её углу: тест с примыканием в середину длинного ребра красный, если реализация ищет лишь вершины полигона. Доказательство: unit.
3. AC3 — проём не двигается, в обоих представлениях. Перегородка с дверью посередине сращивается с соседней; координаты центра, полученные через resolvePartitionOpening, до и после совпадают, host.id указывает на существующую запись, host.t в пределах [0,1]. Одновременно материализованные x/y/angle того же проёма пересчитаны и согласованы с резолвленной позицией (#132). Тест красный до реализации §8.4 — и остаётся красным, если пересчитан только host.t, а проекция устарела. Доказательство: unit.
4. AC4 — разная толщина не сращивается. Два коллинеарных отрезка с разными cm остаются двумя записями. Доказательство: unit.
5. AC5 — допуски. Отрезки, разведённые на расстояние больше EPS_JOIN, не сращиваются; отрезки, отличающиеся на ULP-шум, — сращиваются. Доказательство: unit.
6. AC6 — детерминизм. Результат не зависит от порядка перегородок в массиве: перестановка входа даёт тот же набор записей (сравнение по геометрии). Доказательство: unit.
7. AC7 — оптимизатор. «Оптимизировать планы» сращивает уже накопленные швы, отчёт показывает их число, повторный запуск ничего не меняет (идемпотентность). Доказательство: unit (optimizePlans).
8. AC8 — ничего лишнего. Стены комнат, колонны и черновики контуров не изменяются; количество комнат и их геометрия те же. Отдельно: завершение цепочки не трогает перегородки вне её компоненты связности — пространство с готовым швом в стороне после рисования новой стены сохраняет этот шов до запуска оптимизатора (§8.6). Доказательство: unit + diff review.
9. AC9 — release-артефакты. Оба changelog, строка счётчика в обоих языках, dist/demo/integration бандлы идентичны друг другу. Доказательство: diff + сверка копий бандла.

13. План автотестов

• test/wall-merge.test.mjs — чистые правила: AC1, AC2 (четыре причины), AC4, AC5, AC6, плюс многократное слияние из §8.5.
• test/ рядом с оптимизатором — AC7 (слияние накопленного, идемпотентность).
• Проёмы (AC3) — юнит на пересчёт host.t с проверкой абсолютных координат через resolvePartitionOpening.
• demo/smoke_wall_chain_merge.mjs — цепочка из пяти кликов по прямой в браузере: на выходе одна запись, узлов на прямом участке нет.
• Существующие смоки рисования и smoke_subarea — прогон без правок.

14. Мутационный гейт (scripts/mutation-gate.mjs)

id	Патч	Guard
partition-merge-disabled	не вызывать слияние в _finishWallChain	смок AC1
partition-merge-ignores-thickness	сращивать при разном cm	юнит AC4
partition-merge-ignores-junction	сращивать через примыкание третьей стены	юнит AC2
junction-checks-room-vertices-only	искать примыкание комнаты только по вершинам полигона	юнит AC2 (T-стык)
partition-merge-keeps-relative-t	не пересчитывать host.t	юнит AC3
partition-merge-skips-materialization	не обновлять x/y/angle проёма	юнит AC3
chain-merge-sweeps-whole-space	сращивать все перегородки пространства, а не компоненту цепочки	юнит AC8

15. Release-артефакты

• docs/CHANGELOG.md + docs/CHANGELOG.ru.md — User-Visible: yes;
• строка счётчика в отчёте оптимизатора (en + ru);
• docs/USER-GUIDE* — одна строка о том, что прямой участок хранится одной стеной, а узлы остаются на примыканиях;
• golden не затрагивается: видимый результат на плане не меняется, меняется внутреннее представление.

16. Откат

Слияние необратимо в данных (две записи стали одной), но это не потеря: разрезать стену обратно можно существующим инструментом. Код откатывается снятием вызова; для планов, уже прошедших слияние, откат не нужен — они остаются валидными.

17. Принятые предположения (техническое, менять свободно)

1. Отдельный модуль src/wall-merge.ts вместо правки на месте: правила тогда проверяются юнитами без браузера — тот же приём, что в space-order.ts (#220).
2. Выживает id записи, идущей раньше в массиве. Любое правило годится, лишь бы оно было детерминированным и не зависело от времени; это — самое простое.
3. Конкретные значения EPS_ANGLE и EPS_JOIN подбираются при реализации; ТЗ фиксирует только их природу (доли шага сетки) и границы (§8.3).
4. Область слияния при завершении цепочки описана нормативом §8.6, а не здесь: это не свободное предположение, а граница между двумя решениями владельца (§4.1 и §4.2). Ревизия r2: прежняя редакция говорила «применяется ко всему пространству» — сращивало бы и старые швы в другом углу, обходя обещанный для них отчёт и отмену (находка M1 ревью r1).