From e03238ec1c6664debfbe61bae2dc5606212bc7e2 Mon Sep 17 00:00:00 2001 From: Sergey Matyunin Date: Mon, 24 Aug 2026 14:03:12 +0300 Subject: [PATCH] docs: clarify resize reasons and rollback Issue: #292 User-Visible: no --- docs/specs/292-resize-availability-audit.md | 55 ++++++++++++++++----- 1 file changed, 43 insertions(+), 12 deletions(-) diff --git a/docs/specs/292-resize-availability-audit.md b/docs/specs/292-resize-availability-audit.md index 5695dead..9eda291f 100644 --- a/docs/specs/292-resize-availability-audit.md +++ b/docs/specs/292-resize-availability-audit.md @@ -8,7 +8,18 @@ - **Модель данных:** schema и model version не меняются - **Зависит от:** #276, #289, #290; активная, но инертная рукоятка исправляется в #293 -## 1. Проблема и подтверждение +## 1. Сценарий, персона и подтверждение + +**Кто и где:** владелец сложного реального плана открывает Plan → Resize после +импорта либо Optimize и пытается предсказуемо изменить размеры комнаты. + +**Момент проблемы:** большинство видимых ручек приглушены. Пользователь не +понимает, является ли это неисправностью плана, ограничением безопасного +Resize или дефектом самой ручки, и не знает, какое условие мешает операции. + +**До/после:** до задачи запреты выглядят одинаково и не защищены exact audit; +после задачи каждая разрешимая стена активна, а настоящий запрет имеет +стабильную человеческую причину без внутреннего jargon. На `test/fixtures/real-plan-second-floor.json` текущий Resize показывает 37 рукояток: 11 разрешены и 26 запрещены. Текущий расклад причин запрета: @@ -24,16 +35,17 @@ Сама доля запретов не является ошибкой: unsafe resize обязан остаться запрещённым. Ошибка — ложные запреты после исправления/оптимизации геометрии, отсутствие стабильного аудита реального плана и тексты, из которых пользователь -не понимает, что именно мешает перемещению стены и что можно сделать. +не понимает, что именно мешает перемещению стены. ## 2. Пользовательский результат После попадания зависимостей и повторного Optimize каждая стена, которую можно сдвинуть без изменения topology, числа стен, физических толщин и более чем двух комнат, получает активную рукоятку. Остальные рукоятки остаются видимыми и при -click, Enter или Space объясняют ограничение обычным языком и, где применимо, -называют действие: сначала выпрямить почти осевую геометрию через Optimize либо -убрать перекрывающую независимую стену. +click, Enter или Space объясняют ограничение обычным языком и называют действие +только там, где оно безусловно: например, убрать перекрывающую independent +geometry. Статический текст не обещает, что Optimize исправит конкретную +наклонную стену. Внутренние коды (`partial-shared`, `side-angle` и т. п.) пользователю не показываются. Разрешённая рукоятка обязана реально двигаться; этот отдельный @@ -79,20 +91,22 @@ fixture expectation и объяснения в code review. ## 5. Тексты причин -RU/EN тексты должны отвечать на два вопроса: «что мешает» и «что можно сделать». +RU/EN тексты должны отвечать «что мешает», а «что можно сделать» добавляется +только для безусловного действия, не требующего нового geometry analysis. Минимальный контракт: | Класс | Пользовательский смысл | |---|---| -| angled / side angle | стена или примыкание не горизонтально/вертикально; предложить Optimize, только если кандидат #290 существует | +| angled / side angle | стена или примыкание не горизонтально/вертикально; Resize поддерживает только точные оси, без обещания автоматического Optimize | | independent overlap | поверх границы лежит отдельная перегородка, черновой контур или колонна; её нужно убрать/перенести | | partial / unequal shared | соседняя комната использует не всю ту же стену; безопасно двигать её как общую нельзя | | multiple rooms | сдвиг затронул бы более двух комнат | | thickness / opening | невозможно сохранить толщину либо безопасное положение проёма | | invalid geometry | перемещение нарушило бы структуру плана; без внутреннего кода ошибки | -Если Optimize не способен исправить конкретную стену, текст не должен обещать, -что Optimize её исправит. +Динамический признак «Optimize способен исправить эту стену» и новые варианты +`SafeResizeReason` не вводятся этой задачей. Если в будущем появится такой +контракт, он оформляется отдельно и не является условием #292. ## 6. Scope @@ -185,7 +199,24 @@ Audit выполняется только в тестах. Production render с snapshot cache: resolver не должен пересчитываться более одного раза на handle за frame. Performance budget safe Resize из `docs/RESIZE.md` не меняется. -## 9. Ожидаемые файлы +## 9. Риски и меры + +- Погоня за меньшим процентом disabled может разрешить unsafe topology. Мера: + точная negative matrix AC4 и structural/persistence preflight AC7–AC8. +- Counts могут разойтись с production render из-за второй реализации audit. + Мера: один resolver/reason type и source guard AC6. +- Статический текст может пообещать repair, которого нет для true diagonal. + Мера: §5 запрещает такое обещание; fixtures проверяют near-axis и настоящую + диагональ раздельно. +- Полный audit в render может ухудшить editor responsiveness. Мера: test-only + audit и существующий per-snapshot eligibility cache. + +## 10. Откат + +Чистый revert implementation-коммита возвращает прежнюю eligibility и тексты; +миграция/feature flag не требуются, persisted geometry/schema не меняются. + +## 11. Ожидаемые файлы - `src/resize.ts`, `src/houseplan-card.ts`; - `src/i18n/en.json`, `src/i18n/ru.json`; @@ -194,12 +225,12 @@ snapshot cache: resolver не должен пересчитываться бол - `docs/RESIZE.md`, `docs/TESTING.md`, при необходимости `docs/ARCHITECTURE.md`; - `docs/CHANGELOG.md`, `docs/CHANGELOG.ru.md`. -## 10. Release +## 12. Release Implementation-коммит имеет `Issue: #292`, `User-Visible: yes` и обновляет оба changelog. Issue не закрывается вручную: она закрывается выпуском beta. -## 11. Принятые предположения +## 13. Принятые предположения 1. Метрика 70% — диагностический сигнал, а не продуктовая цель «разрешить любой ценой»; после исправлений число запретов может оставаться высоким.