houseplan-card/docs/reviews/SPEC-REVIEW-138-r1.md

Ревью ТЗ — issue #138, цикл r1

• Issue: https://github.com/Matysh/houseplan-card/issues/138
• ТЗ: docs/specs/138-adjacent-room-autoclose.md, коммит 611c5a76f56ce83587eafbd00dbd6ad1a0f8c9d8
• Этап: spec (PROCESS.md §2.4)
• Вердикт: красный · цикл r1/4 · High: 1 · Medium: 0

Скоуп ревью

Прочитаны в указанном порядке: docs/SCOPE.md, AGENTS.md, PROCESS.md (§1, §2, §3, §4, §7, §12), тело issue #138 и оба комментария владельца (аналитика Q1–Q5 с defaults, подтверждение ТЗ), docs/USER-GUIDE.ru.md (терминология диалога комнаты, кнопка «Оставить замкнутыми стенами», секции про соседние комнаты и общую стену), и связанный docs/specs/137-plan-snap-overlay.md как основа, на которой строится #138.

Задача не помечена small, ТЗ корректно лежит в docs/specs/138-adjacent-room-autoclose.md и зарегистрировано в docs/specs/README.md:49. Формат ревью — полный документ, не комментарий.

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

Ревью читало не только текст ТЗ, но и код, на который оно опирается, чтобы отличить обоснованное техническое утверждение от догадки, выданной за факт:

• src/houseplan-card.ts: _markupClick() (6454–6575), _closeRoomContour() (6426–6452), _resolvePlanDrawPoint() (6011–6031), _draftEndAt() (6580–6594) — сверка с §3 «Причина дефекта», §7.1 «Порядок разрешения клика», §8 «Контракт замыкания».
• src/plan-snap-overlay.ts (1–180): структура PlanSnapSegment, sourceKind: 'room'|'draft'|'partition', cutSegments/roomEdges, дедупликация по axisKey — сверка с §7.2 «Допустимый существующий интервал» и терминологией «room-owned solid interval».
• src/wall-thickness.ts:461 applyWallThicknessToNewRoom() — сверка с §9 (наследование толщины общей стены) и AC7.
• src/i18n/ru.json:9,267–269 — существующие btn.keep_as_walls, toast.room_overlap, toast.contour_min_edges, toast.contour_cannot_close — сверка с заявлением «новых i18n-ключей не требуется» (§4.4, §6).
• docs/specs/README.md — регистрация spec-файла.

Каждое утверждение ТЗ о текущем поведении, которое удалось проверить чтением кода, подтвердилось: терминология (sourceKind, _markupClick, _closeRoomContour, _resolvePlanDrawPoint, applyWallThicknessToNewRoom, «Оставить замкнутыми стенами») — не изобретена, а взята из реального кода. Отдельно оценивалась полнота контракта: не пропущен ли граничный случай, который спецификация не проговаривает и не относит явно в non-scope.

Находки

High-1 — контракт автозамыкания перехватывает и блокирует обычный второй клик по той же стене

Где: docs/specs/138-adjacent-room-autoclose.md §7.1 (строки 105–119), §7.2 (121–139), §8.1 (155–173), §8.2 (175–186).

Формулировка: §7.1 п.3 требует проверять на автозамыкание любой обычный клик, отличный от клика в собственную первую точку контура — без условия «в контуре уже есть хотя бы одно нарисованное ребро». §7.2 требует только геометрических условий (общий room-owned solid interval, содержит A и финальную точку, положительная длина, точки различны) — тоже без условия на уже накопленное число вершин. §8.1 требует минимум три различные вершины у prospective polygon [..., P, B] + B—A, иначе (§8.2) диалог не открывается, B/P—B/B—A не записываются, и клик не превращается в обычное добавление B — то есть точка не появляется в drafting вообще, только показывается existing validation toast.

Отсюда прямое следствие: если пользователь ставит первую точку A на существующем углу (this._path = [A], houseplan-card.ts:6544), а второй клик кладёт на другой конец той же самой прямой существующей стены (что является совершенно естественным способом начать соседнюю комнату — сначала отметить оба конца общей стены, а затем обвести остальной контур), — P на этот момент равен A (в пути одна точка), и prospective polygon равен [A, B] + B—A: две различные вершины, не три. Проверка §8.1 обязана провалиться, и по букве §8.2 клик обязан быть отклонён с toast, а B — не добавлен в draft вообще.

Сегодня, до этой задачи, тот же клик работает штатно: _markupClick() не делает такой проверки и просто добавляет B как обычную точку контура (houseplan-card.ts:6573–6574, путь this._path = [...this._path, pt]; this._persistActiveDraftSegment();). Показательно, что для симметричного случая — клика в собственную первую точку — система уже сегодня специально избегает этой ловушки: строка houseplan-card.ts:6522 (const closing = this._path.length >= 3 && this._samePt(pt, this._path[0]);) трактует клик как попытку замкнуть контур только когда уже накоплено достаточно вершин; при недостатке вершин точка добавляется как обычная — ошибка «нужно минимум два ребра» никогда не показывается на пустом контуре. Новый контракт для автозамыкания (§7.1 п.3) не воспроизводит этот защитный гейт: он назначает автозамыкание кандидатом для проверки независимо от того, сколько вершин уже нарисовано, а §8.2 явно запрещает деградацию к обычному добавлению точки при провале.

Сценарий воспроизведения (по тексту ТЗ, до реализации — логическая проверка контракта):

1. Существует завершённая комната с прямой стеной A—C (общая длина, A и C — её концы).
2. Пользователь выбирает «Контур комнаты», кликает в A — this._path = [A].
3. Следующим кликом отмечает C — противоположный конец той же стены, намереваясь провести по ней первую грань новой комнаты, а затем обвести остальной периметр и замкнуть контур явным кликом в A (существующий, неизменяемый способ, приоритет 1 из §7.1).
4. По §7.1 п.3 клик в C не равен _path[0]=A, не является Ctrl/Cmd — значит проверяется как кандидат на автозамыкание. По §7.2 A и C лежат на одном sourceKind: room сплошном интервале, точки различны, длина положительна — eligibility выполнена.
5. По §8.1 prospective polygon [A, C] + C—A содержит 2 различные вершины, что меньше требуемых трёх → невалиден.
6. По §8.2 диалог не открывается, C не добавляется в draft, показывается toast «Чтобы замкнуть контур, сначала нарисуйте минимум две грани» (toast.contour_min_edges), а клик не превращается в обычное добавление точки.
7. Результат: пользователь не может продолжить рисовать — второй клик по общей стене, который сегодня работает и является естественным способом начать примыкающую комнату, теперь ничего не делает, кроме показа сообщения об ошибке, не имеющего отношения к тому, что человек пытался сделать.

Это прямая регрессия текущего, работающего поведения — причём именно в той области (рисование вдоль общей стены соседней комнаты), которую задача #138 должна улучшить, а не ухудшить. Ни один AC (§13) и ни один пункт плана unit-тестов (§14.1, пп.1–9) не покрывает этот случай: пункт 7 («одинаковые A/B, zero-length и current anchor не подходят») — про совпадающие точки, а не про две различные точки на одном интервале при пустом ранее контуре. Риск не упомянут и в таблице §17.

Почему это High, а не Medium: правило §3.8 и §2.4 требует, чтобы контракт поведения был однозначным и не содержал воспроизводимой логической ошибки; здесь ошибка выводится напрямую из текста ТЗ без домысливания реализации, и затрагивает основной, ежедневный workflow редактора (первые же клики при разметке соседней комнаты — ровно сценарий из тела issue). Это не пограничный кейс, а типичный способ начать рисовать общую стену.

Что нужно поправить в ТЗ (не решение реализации, а контракт): Автозамыкание должно проверяться только когда в контуре уже достаточно вершин, чтобы в принципе замкнуться (аналогично существующему гейту this._path.length >= 3 для клика в первую точку — т.е. до клика в B уже должно быть отрисовано хотя бы одно дополнительное ребро, не лежащее целиком на том же интервале что и A—B), либо явно указать, что при провале именно по причине «меньше трёх вершин» (в отличие от self-intersection/overlap/ zero-area) клик деградирует к обычному добавлению точки, а не блокируется toast'ом. Выбор между этими двумя вариантами — продуктовый (что видит пользователь при клике по второй точке общей стены сразу после первой): либо клик тихо добавляет обычную точку (как сегодня), либо показывает ошибку. Это ровно тот вопрос, который стоило задать владельцу вместе с Q1–Q5, и он остался незамеченным.

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

• Терминология и техническая база не выдуманы. Все ссылки на _resolvePlanDrawPoint, _markupClick, _closeRoomContour, _draftEndAt, _persistActiveDraftSegment, sourceKind: 'room'|'draft'|'partition', applyWallThicknessToNewRoom, plan-snap-overlay.ts, кнопку «Оставить замкнутыми стенами» и существующие toast-ключи — соответствуют действительному коду. §3 «Причина дефекта» описывает код, каким он есть сегодня, а не предположение.
• Обязательные разделы §7.1 PROCESS.md на месте: сценарий/персона/ поверхность (§1), «что человек увидит до/после» одной фразой без терминов реализации (§2), проблема (§3), scope/non-scope (§5–6), контракт поведения (§7–9), UX и touch-деградация (§10), модель данных/миграция (§11), AC1…AC12 с указанием способа доказательства (§13), план автотестов (§14), риски (§17), откат (§18), release-артефакты (§16).
• i18n корректно закрыт: новых ключей нет, переиспользуются существующие toast.contour_min_edges, toast.contour_cannot_close, toast.room_overlap, btn.keep_as_walls — подтверждено чтением src/i18n/ru.json/en.json.
• Наследование толщины общей стены (AC7, §9) грамотно опирается на уже существующий applyWallThicknessToNewRoom() (wall-thickness.ts:461–484), который и сегодня пропускает интервалы с уже ненулевой толщиной (cms[i] > 0) — новый код для этого не нужен, утверждение ТЗ верно.
• Проёмы и cuts (§7.3, AC4) корректно опираются на уже существующий cutSegments/canonical cuts из #137 (plan-snap-overlay.ts), не вводят второй resolver — соответствует Non-scope и архитектурному контракту §12.
• Дедупликация общей стены между двумя комнатами (§9, «не создаёт вторую физическую стену») согласуется с найденной в plan-snap-overlay.ts дедупликацией сегментов по axisKey (один PlanSnapSegment на общую ось независимо от числа комнат-источников) — заявление обосновано, не догадка.
• Открытых продуктовых вопросов действительно не осталось для того, что было явно задано: Q1–Q5 из комментария аналитики и все технические defaults подтверждены владельцем 2026-08-14 (issue-комментарий), ссылка есть в ТЗ §4 и §19.7. «Ни одного открытого вопроса» здесь не является тревожным сигналом самим по себе — вопросы были заданы и закрыты пакетом, а не обойдены.
• Release-артефакты и трек соответствуют процессу: User-Visible: yes, оба changelog в одном коммите, docs/CANVAS.md/ARCHITECTURE.md/ USER-GUIDE.ru.md в списке правок (§16), полный трек (не small/trivial) обоснован в аналитике — сложность и число задетых инвариантов оправдывают выбор.
• Non-scope сформулирован конкретно и исключает реальные соблазны расширения (путь по нескольким рёбрам, второй resolver проёмов, новая визуальная индикация, hit-radius #137) — не оставляет скрытого расширения скоупа.

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

• Реализацию — её ещё нет; это ревью ТЗ, а не кода (PROCESS.md §2.4 не предполагает исполнения на этом этапе).
• Golden/визуальные артефакты — ТЗ корректно утверждает, что новых пикселей нет (§14.3), баз для сверки нет и не требовалось.
• Производительность вживую — утверждение об O(S)-поиске только на click (§12, AC10) проверено чтением архитектуры snap-геометрии (кэшированный snapshot в _planSnapGeometrySnapshot()), не профилированием — на этапе ТЗ профилирование не требуется.
• Backend/schema — ТЗ утверждает отсутствие изменений (§11, AC12); код custom_components/houseplan/**/*.py не затрагивается по scope ТЗ, отдельно не сверялся построчно, поскольку заявленный scope его не касается.

Вывод

Один блокирующий (High) дефект контракта: связка §7.1 п.3 + §7.2 + §8.1 + §8.2 без защитного гейта по минимальному числу уже нарисованных вершин превращает обычный, сегодня работающий второй клик по общей стене в блокирующую ошибку — регрессия ровно того сценария, который issue #138 должен исправить. Остальной контракт, включая проёмы, толщину, drafts/partitions, historyCancel/Save, touch-деградацию и release-артефакты, проверен по коду и корректен.

Возврат в «ТЗ в работе» (S3-spec), цикл r1/4. Исправление: явно решить (и записать в ТЗ), что происходит при клике на другую точку того же интервала, когда в контуре ещё недостаточно вершин для валидного замыкания — деградация к обычному добавлению точки (по аналогии с текущим гейтом path.length >= 3 для закрытия по первой точке) либо иной явно обоснованный вариант, покрытый отдельным AC и unit-тестом.