houseplan-card/legacy/specs/199-optimize-geometry-preflight.md

Issue #199 — geometry preflight перед записью Optimize

• Issue: https://github.com/Matysh/houseplan-card/issues/199
• Тип / приоритет: tech-debt / P1
• Оценка: пользовательская ценность 8/10; ценность для разработки 9/10; сложность 7/10; риск 8/10
• Трек: обычный
• Область: explicit whole-plan Optimize, canonical physical geometry, preview/Apply, RU/EN i18n, unit/smoke/performance
• Модель данных: без изменений и миграции
• Связано: #197, #198, #223, #224, #229, docs/CANVAS.md §9.5, docs/WALL-THICKNESS.md, docs/TOUCH-SUPPORT.md

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

Персона: домашний администратор, который обслуживает старый или импортированный план через «Общие настройки → Оптимизировать планы».

Поверхность и момент: администратор открывает preview Optimize и собирается подтвердить единое изменение всех пространств. Один из maintenance-pass создаёт candidate, для которого production geometry builder не может построить кладку либо бумагу хотя бы одного пространства.

Задача поддерживает J6 из docs/SCOPE.md: долговечный редактируемый план не должен становиться непригодным после штатной операции обслуживания. Она также закрывает safety floor docs/TOUCH-SUPPORT.md: editor-действие не имеет права молча записать повреждённую геометрию. View/киоск не получают нового control, но защищаются от результата опасной записи.

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

До: preview показывает обычный структурный отчёт и разрешает Apply, даже если candidate уже не строится тем же geometry engine, которым затем рисуется план. Ошибка становится видна только после записи; one-deep Undo исчезает после следующего изменения.

После: если хотя бы одно пространство candidate не проходит production- эквивалентную проверку, preview называет проблемные пространства, сообщает, что планы не изменены, и не показывает кнопку «Оптимизировать». Ни config, ни layout не записываются.

3. Подтверждённая проблема

Текущий путь на origin/dev:

1. HouseplanCard._openAlignDialog() вызывает чистый optimizePlans(this._serverCfg, this._layout);
2. OptimizeResult содержит exact config/layout, отчёт и changed, но не состояние канонической geometry;
3. _renderAlignDialog() показывает отчёт только по структурным счётчикам;
4. _runAlignToGrid() отправляет сохранённый candidate в houseplan/plan/optimize;
5. backend проверяет permission, size, expected revisions, schema, marker/light/ opening semantics и наличие файлов, после чего crash-resumably записывает два Store и создаёт one-deep snapshot;
6. ни frontend preview/Apply, ни Python endpoint не вызывают wallBodiesGeometry()/floorFootprintGeometry() для candidate.

#197 доказал цену этого разрыва: один junction patch делал wallBodiesGeometry() === null после Optimize, а пользователь обнаруживал исчезнувшую кладку уже после записи. #197 исправил конкретный patch-loop, но не общий барьер. #198/#229 меняют отдельные optimizer-pass, #223 очищает координаты внутри Optimize, #224 канонизирует координаты на общих write barriers. Ни одна из этих задач не проверяет итоговую renderability candidate, поэтому #199 не является дубликатом.

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

Владелец принял defaults 2026-08-22:

1. отказ любого пространства блокирует весь whole-plan Optimize;
2. уже деградированное пространство также блокирует запись, даже когда candidate не выглядит хуже исходника;
3. preview показывает понятное сообщение и названия пространств, не раскрывает exception/polyclip details и не показывает Apply.

Эти решения являются продуктовым контрактом, а не техническими предположениями.

5. Scope

В задачу входят:

1. чистый production-equivalent preflight exact config candidate по всем пространствам;
2. единая подготовка geometry inputs для preflight и production renderer либо общий чистый helper, исключающий два расходящихся алгоритма;
3. проверка room masonry/paper вместе с независимыми partitions, незаконченными drafts, columns, обычными и hosted-partition openings;
4. различение structural failure (null/exception) и корректного пустого результата;
5. fail-closed preview и Apply: один failure блокирует всю операцию и ноль WS writes;
6. понятное RU/EN сообщение с детерминированным списком пространств;
7. привязка preflight result к exact candidate fingerprint и отсутствие повторной проверки при неизменном candidate;
8. сохранение нынешней одной backend-транзакции и one-deep Undo для успешного candidate;
9. unit, production-bundle smoke, visual state, mutation и large-house performance evidence;
10. пользовательская, архитектурная, тестовая и release-документация.

6. Non-scope

• исправление geometry, из-за которой preflight стал красным;
• частичная оптимизация только исправных пространств;
• сравнение «до/после» и разрешение уже существующего structural failure;
• raw-ring, centreline либо renderer-specific fallback;
• замена polyclip-ts, общая смена tolerance/precision или новый geometry engine;
• port polygon boolean engine в Python;
• новый persisted field, PLAN_MODEL_VERSION, schema migration или Store;
• фоновая проверка при обычном Save/read/render/import;
• сохранение stack trace или исходного config в диагностике/telemetry;
• новый ручной repair control;
• изменение срока жизни Optimize Undo;
• публичное включение скрытой изометрии.

Найденная preflight проблема получает отдельный bug issue с reproducer; #199 не используется как umbrella для её попутного исправления.

7. Контракт geometry preflight

7.1 Exact candidate и область проверки

checkOptimizeGeometry(config) (рабочее имя) является чистой функцией: не читает DOM/Lit/HA state, не пишет Store, не мутирует config и не зависит от активного этажа. Вход — exact OptimizeResult.config; выход содержит:

• content fingerprint входа;
• ordered list пространств со статусом ok | failed | not-applicable;
• публичный failure list только из spaceId и безопасного display name;
• внутренний bounded reason code для unit/diagnostic assertions без exception text.

Порядок совпадает с config.spaces; перестановка пространств меняет только порядок отчёта, не результат каждого пространства.

Проверяются все пространства candidate, не только активное и не только изменённые по счётчикам Optimize. Проверка запускается лишь когда OptimizeResult.changed === true: no-op preview ничего не записывает и сохраняет действующее сообщение «Все планы уже используют актуальную…».

7.2 Production-equivalent inputs

Для каждого пространства используются те же чистые источники и параметры, что production render pipeline:

• spaceModels() и NORM_W для render coordinates;
• persisted walls в config coordinates;
• resolveOpenCuts() для explicit/legacy room spans;
• ordinary room openings и валидные hosted-partition openings с тем же compat resolver;
• wallIntervals() + partitionOpeningHasCompositeRoomWall() для решения, режет ли hosted opening совпавшую room masonry;
• physicalBodyParts() с PartitionOpeningCut[] для partitions/drafts/columns;
• GRID_STEP_N, cell_cm, GRID_PITCH, NORM_W;
• wallBodiesGeometry() для общей masonry/paper geometry;
• floorFootprintGeometry() только там, где есть хотя бы одна комната и нет уже построенного paperGeom.

Подготовка opening/physical inputs выносится в общий pure helper либо напрямую переиспользует существующие pure resolvers. Копия private card-логики с отличающимися условиями запрещена.

7.3 Успех, failure и not-applicable

Пространство успешно, когда каждый обязательный production pass, который должен быть вызван для его данных, завершился без exception и вернул не-null geometry.

• При наличии wall records либо independent physical bodies wallBodiesGeometry() обязан вернуть object. Его документированный successful empty result не является failure сам по себе.
• При наличии комнат должен существовать paper/floor result: paperGeom от wall pass либо floorFootprintGeometry() без него.
• Пространство без комнат, wall records и independent bodies имеет not-applicable, а не failure: image-only/пустой новый этаж разрешён.
• Пространство без комнат, но с валидными partitions/drafts/columns проверяет physical/masonry pass; отсутствие room floor не является ошибкой.
• Невалидный hosted opening, который действующий compat renderer намеренно не материализует, остаётся обязанностью schema/semantic validation и не получает новую альтернативную трактовку в preflight.
• Любой неожиданный exception внутри подготовки или boolean pass превращается в bounded failure reason; наружу и в UI exception text не выходит.

Preflight ничего не чинит, не округляет и не канонизирует сверх уже полученного Optimize candidate.

7.4 Fingerprint и повторная проверка

Preflight result хранит contentFingerprint(candidate.config). Dialog хранит тот же exact candidate и result.

• Обычный Apply использует готовый зелёный result и не выполняет второй дорогой boolean pass.
• Перед WS call код снова вычисляет дешёвый fingerprint. Совпадает — result применим. Не совпадает — preflight выполняется заново для изменившегося candidate.
• Красный повтор переводит dialog в тот же failure state и не вызывает WS.
• Изменение server config другим клиентом по-прежнему ловится backend revision conflict; preflight не заменяет optimistic locking.
• Result не кладётся в глобальный render cache и не переживает закрытие dialog.

8. UX-контракт

8.1 Failure preview

При failure обычный отчёт о сдвигах/миграциях не показывается как предложение к записи. Вместо него dialog показывает:

• RU: «Не удалось безопасно проверить геометрию следующих пространств: {spaces}{more}.»
• RU hint: «Планы не изменены. Обновите House Plan и повторите. Если ошибка останется, приложите экспорт пространства к отчёту об ошибке.»
• EN: Could not safely verify the geometry of the following spaces: {spaces}{more}.
• EN hint: Plans were not changed. Update House Plan and try again. If the error persists, attach a space export to the bug report.

Display name: непустой space.title, иначе space.id, иначе локализованное «Пространство N» / Space N. Первые три имени перечисляются в config order; при большем числе добавляется локализованный suffix «и ещё N» / and N more. Lit text binding экранирует имена; HTML интерполяция запрещена.

Footer содержит только «Отмена»/закрытие. Кнопка «Оптимизировать» не рендерится, а не только получает disabled: пользователь не должен принимать failure как предупреждение, которое можно обойти.

Title, Escape, focus trap, scrim close и restore focus остаются общими для hp-dialog. Новых жестов нет. На узком/touch экране сообщение переносится и остаётся целиком доступным; editor touch parity не обещается, но safety floor блокирует запись так же, как на desktop.

8.2 No-op и success

• changed: false: действующий gs.align_none, без preflight failure UI и без Apply.
• changed: true, preflight green: нынешний точный отчёт, warning и Apply без текстовых/поведенческих изменений.
• Cancel/close в любом состоянии ничего не пишет.
• Успешный Apply по-прежнему показывает gs.align_done; Undo по-прежнему доступен до следующего edit.

9. Backend, atomicity, compatibility и security

houseplan/plan/optimize не получает новый параметр. Python не имеет и не должен получать вторую реализацию TypeScript/polyclip geometry. Preflight — защитный барьер штатной карточки, не security attestation от недоверенного клиента.

Backend сохраняет независимые гарантии:

• admin permission и size limit;
• schema/semantic validation;
• expected config/layout revisions;
• missing-plan validation;
• intent-first config+layout commit;
• one-deep snapshot и crash recovery.

При красном preflight endpoint не вызывается вообще, поэтому не создаются pending/backup, revisions и update events. При зелёном вызывается ровно один существующий endpoint с exact candidate; частичной записи по пространствам нет.

Старый сохранённый config читается без миграции. Новые i18n keys — единственное добавление к пользовательскому контракту. Неизвестные поля candidate, files, layout metadata и backend Undo сохраняются существующими механизмами.

Имена пространств считаются недоверенным пользовательским текстом и выводятся только через Lit escaping. Exception, geometry coordinates и config payload не логируются в browser console как часть штатного failure и не отправляются третьим сторонам.

10. Производительность

Проверка user-triggered и выполняется не чаще одного раза для одного открытого dialog/candidate. Она запрещена в:

• render/update и HA state tick;
• pointermove, pan, pinch и hover;
• обычном config/layout Save;
• переключении этажа, темы или View/Plan режима.

Базовое измерение автора ТЗ 2026-08-22 на текущем Windows checkout после npx tsc -p tsconfig.test.json && node scripts/fix-test-build.mjs: прямой production wall/physical pass существующей large-house fixture (3 пространства, 60 комнат, 100 проёмов, 60 partitions, 40 columns) — median 155.9 ms, p95 162.56 ms, max 163.67 ms по 20 warm samples.

Acceptance budget для готового helper на той же fixture:

• все 3 пространства green;
• p95 не больше 250 ms после не менее 3 warmups и 20 samples;
• wrapper/input-preparation overhead относительно прямого production builder того же процесса не больше 20% + 15 ms;
• повторный Apply неизменного candidate не вызывает второй geometry pass;
• heap/result cache не растёт после закрытия dialog.

Отдельный benchmark script печатает fixture counts, median/p95/max, baseline и candidate timings. Если абсолютный budget нестабилен в CI, ревьюер не повышает его молча: измеряет same-run baseline и заводит отдельный performance issue; для #199 остаётся обязательным относительный budget.

11. Acceptance criteria

AC	Критерий	Доказательство
AC1	Exact Optimize candidate проверяется по всем пространствам теми же room/opening/wall/physical builders и параметрами, что production renderer; вход не мутируется.	Focused unit + code review call-site parity table.
AC2	Валидная матрица room masonry, ordinary/hosted openings, partitions, drafts, columns, image-only и empty space даёт ok/not-applicable без false positive.	Parameterized unit fixtures.
AC3	Forced wallBodiesGeometry() === null, floor failure и thrown exception дают bounded failure соответствующего пространства; successful empty geometry не считается failure.	Injectable seam/mutant unit.
AC4	Failure одного из нескольких пространств возвращает deterministic ordered list и блокирует whole-plan operation; исправные пространства не записываются отдельно.	Multi-space unit + browser smoke.
AC5	Уже красное исходное пространство не получает исключения «не стало хуже»: changed candidate блокируется и оставляет exact config/layout/revisions без изменений.	Before/after regression unit + browser smoke.
AC6	Failure dialog выводит первые три безопасных display names, RU/EN suffix остальных и plain-language hint без exception; Apply отсутствует, Cancel/Escape/focus работают.	i18n/UI unit + production-bundle smoke + dark/light golden candidate.
AC7	changed:false сохраняет прежний no-op dialog без preflight; green candidate сохраняет прежний report/Apply/toast.	UI unit + existing Optimize smokes.
AC8	Green fingerprint используется ровно для exact config candidate; unchanged Apply не повторяет geometry pass, changed fingerprint rechecks и fail-closes до WS.	Controlled-call-count unit.
AC9	Красный preflight делает 0 houseplan/plan/optimize calls, не меняет _serverCfg, layout, revisions, history/Undo и не создаёт events; green делает ровно один atomic call.	Production-bundle smoke with WS recorder.
AC10	Успешный Apply/Undo, revision conflict и backend semantic validation остаются без изменений.	Existing frontend/backend suites + targeted smoke.
AC11	Large-house helper выполняет budget §10, не попадает в render/state/pointer пути и не оставляет растущий cache.	Targeted benchmark + call-count regression.
AC12	Mutation gates ловят bypass preflight, active-space-only check, acceptance null и отображение Apply при failure.	scripts/mutation-gate.mjs entries, каждый caught 1/1.
AC13	RU/EN changelog, user/canvas/testing/status docs и три bundle-копии актуальны; docs fingerprint green.	check-docs, bundle byte comparison, doc review.
AC14	Рабочие gates задачи зелёные.	typecheck, unit, build, targeted smoke, targeted golden candidate/benchmark as required by process.

12. План реализации и тестов

12.1 Код

1. Добавить pure module src/plan-geometry-preflight.ts (имя может быть изменено ревьюером) с per-space preparation/check и result/fingerprint types.
2. Вынести из houseplan-card.ts только необходимую production input projection в pure helpers либо переиспользовать существующие resolvers напрямую; renderer и preflight должны сходиться на одной функции, а не копиях условий.
3. Расширить private _alignDialog preflight result и integration в _openAlignDialog, _runAlignToGrid, _renderAlignDialog.
4. Добавить RU/EN i18n keys для failure, hint, fallback name и more suffix.
5. Backend endpoint и persisted schema не менять.

Предполагаемые продуктовые файлы: src/plan-geometry-preflight.ts, src/houseplan-card.ts, при необходимости общий geometry/opening helper, src/i18n/ru.json, src/i18n/en.json.

12.2 Автотесты

• test/plan-geometry-preflight.test.mjs: AC1–AC5, AC8, call parity, immutability, empty/failure matrix;
• существующие plan-optimizer, wall-thickness, partition-openings tests остаются зелёными;
• demo/smoke_optimize_geometry_preflight.mjs: собранный bundle, multi-space red/green/no-op, RU/EN, zero/one WS calls, state/Undo preservation;
• demo/benchmark_optimize_geometry_preflight.mjs: §10;
• golden matrix: failure dialog dark/light; baselines принимаются только из полного Linux CI artifact через golden:accept -- --reviewed;
• mutation ids: optimize-preflight-bypassed, optimize-preflight-active-space-only, optimize-preflight-accepts-null, optimize-preflight-renders-apply-on-failure либо эквивалентные точные anchors.

До S7-code-review выполняются fast gates и targeted smoke/benchmark из AC. Полный smoke set, golden verify и общий performance остаются pre-beta gates.

13. Риски и меры

Риск	Мера
Preflight расходится с renderer	Общий pure input helper + AC1 parity table; никакого упрощённого polygon check.
Проверяется только активный этаж	Pure function обходит ordered config.spaces; mutant active-space-only.
False positive на пустом/virtual-only плане	Явный not-applicable и successful-empty contract, parameterized AC2/AC3.
Старый failure пропускается как «не хуже»	Решение владельца Q2 и AC5: любой candidate failure блокирует.
Whole-plan Apply становится частичным	Ноль WS calls при любом failure; backend endpoint вызывается один раз только на green.
UI показывает внутреннюю ошибку или ломается от title	Bounded reason codes, Lit escaping, список ≤3 + count.
Дорогой boolean pass тормозит обычный View	Только explicit dialog, fingerprint reuse, budget и call-count tests.
Cache удерживает config/geometry	Result живёт только в dialog; geometry не хранится, только statuses/fingerprint.
Старый browser bundle может вызвать endpoint без preflight	Это не security boundary; пакет поставляет card+integration вместе. Backend продолжает schema/semantic guards, но не дублирует polyclip.

14. Touch и accessibility

Touch editor: best effort, но safety behavior полностью поддерживается. Проверка запускается той же кнопкой General settings; failure не допускает запись ни мышью, ни tap. Message/footer не требуют hover, помещаются в общий responsive hp-dialog, Escape/focus restore остаются desktop guarantees. Новых pointer handlers и рисков pinch/pointercancel нет. View/киоск rendering не меняется; предотвращение повреждённой записи улучшает их надёжность.

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

Изменение пользовательское. Implementation commit имеет User-Visible: yes и включает:

• docs/CHANGELOG.md и docs/CHANGELOG.ru.md со ссылкой на #199;
• docs/USER-GUIDE.ru.md — failure behavior Optimize и действие пользователя;
• docs/CANVAS.md — preflight/fingerprint/whole-plan contract;
• docs/ARCHITECTURE.md — граница frontend geometry barrier/backend atomicity;
• docs/TESTING.md — unit/smoke/mutation/performance evidence;
• docs/STATUS.md — фактическая release-line запись;
• RU/EN i18n, tests, smoke, benchmark, mutation entries;
• recapture demo/docs/capture.mjs/docs/images/screenshots.json для актуального source fingerprint при любом src/** diff;
• три byte-identical bundle-копии;
• dark/light golden candidate; acceptance baseline только по reviewed full Linux artifact перед beta.

Security report, schema migration, backend release note и persisted recovery artifact не требуются.

Rollback — revert implementation commit. Persisted данные не меняются новым preflight, поэтому обратной миграции нет. После rollback Optimize снова разрешит запись unchecked candidate; уже успешно оптимизированные планы и Undo snapshots остаются в прежнем формате.

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

Эти решения не наблюдаемы пользователем и могут быть изменены ревьюером без нового решения владельца, если AC сохраняются:

1. Pure module/result/type names не являются публичным API.
2. Fingerprint использует существующий contentFingerprint, а не новый hash.
3. No-op candidate не проверяется: Apply отсутствует, значит опасной записи нет.
4. Preflight result хранит statuses/reasons, но не polygon geometry, чтобы dialog не становился вторым render cache.
5. Backend endpoint не требует декларативного preflight_passed поля: без возможности исполнить polyclip оно не добавляет доказательства и ломает старые clients.
6. Performance budget относится к geometry helper отдельно от уже существующего optimizePlans(); same-run baseline отделяет новый overhead от polygon engine.
7. space.title → id → Space N — единственный display-name fallback.
8. Targeted file/fixture names могут меняться без изменения доказательной матрицы AC.