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

# SPEC-REVIEW-132-r1

- **Issue:** https://github.com/Matysh/houseplan-card/issues/132
- **ТЗ под ревью:** `docs/specs/132-partition-openings.md` (коммит `2aaabc48d65b8886b72578907e9622379807d991`, ветка `issue/132-partition-openings-v2`)
- **Связанный bug в том же scope:** #185 (решением владельца исправляется в рамках #132)
- **Роль:** ревьюер ТЗ (не автор), этап `S4-spec-review`
- **Трек:** обычный (не `small`/`trivial`) — сложность/риск 9/10, несколько
  поверхностей (placement, geometry, light, room-topology, HA state, i18n,
  golden); лёгкий трек корректно не применён, файл ТЗ в `docs/specs/`
  создан, как требуется
- **Цикл:** r1/4

## Скоуп ревью

Проверялось соответствие ТЗ:

- `docs/SCOPE.md` — попадание в Core user jobs (J4, с поддержкой J1/J2/J3),
  отсутствие расширения скоупа, lock-инвариант, правило «никогда не удалять
  файл по догадке» (задача файлов не касается — у openings нет attachments,
  §16 ТЗ это явно фиксирует);
- `PROCESS.md` §2.4, §2.5 (DoR), §7.1 (обязательные разделы), §12 (запреты);
- `AGENTS.md` — классы файлов, ветка `issue/132-partition-openings-v2`,
  трейлеры, связь issue ↔ ТЗ в `docs/specs/README.md`;
- канонические документы затронутых подсистем: `docs/LIGHT.md`,
  `docs/WALL-THICKNESS.md`, `docs/SUN.md`, `docs/CANVAS.md`,
  `docs/UX-MODES.md`, `docs/CONFIG-COMPATIBILITY.md`,
  `docs/TOUCH-SUPPORT.md` — на предмет того, что технические утверждения ТЗ о
  «текущем поведении» не являются непроверенной догадкой, а описывают код и
  контракты, которые действительно существуют;
- `docs/USER-GUIDE.ru.md` — терминология («Стены», «Проём», «Перегородка»,
  «Открытый проём») берётся оттуда, а не изобретается;
- весь тред issue #132 (7 комментариев, 3 раунда вопросов владельцу, две
  редакции ТЗ) — на предмет того, что продуктовые вопросы были заданы
  владельцу, а технические автор решил сам и пометил как предположения.

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

1. Прочитан весь тред issue #132: исходный отчёт, решение владельца «проём
   пропускает свет» (2026-08-13), аналитика S2 (сложность 8/10 → 9/10 после
   переоценки от 2026-08-19 после релиза #173), вопросы Q1–Q3
   (комментарий 2026-08-14) и их дефолты, принятые владельцем без изменений
   (2026-08-15), первая редакция ТЗ (`issue/132-partition-openings`,
   коммит `da05728`), актуализация аналитики после #173 (комментарий
   2026-08-19, семь конкретных пунктов о том, что изменилось), вопросы Q4–Q5
   и их принятие владельцем вместе с решением включить фикс #185 в этот же
   issue, финальная редакция ТЗ (`issue/132-partition-openings-v2`,
   коммит `2aaabc4`).
2. Прочитаны issue #173 (единый инструмент «Стены», слияние
   room-outline/partition) и #157 (`passage` — «Открытый проём») — оба
   закрыты и уже выпущены в `v1.65.0-beta.2` (см. `git log` — коммит
   `54c5ca3 test: accept v1.65.0-beta.2 golden baselines` уже в истории до
   ветки задачи). Прочитан #185 (bug, замыкание контура ломается проёмом на
   участвующей стене) — открыт, без статусной метки `S*`, что нормально: по
   `AGENTS.md`/`PROCESS.md` §9 issue без статуса вне процесса, а решение
   владельца прямо говорит, что #185 закрывается кодом #132 и тем же
   код-ревью — отдельная метка статуса ему на данном этапе не нужна.
3. Построчно сверены обязательные разделы ТЗ (`PROCESS.md` §7.1) — таблица
   ниже.
4. Проверены **технические утверждения ТЗ о текущем (уже реализованном)
   поведении** чтением реального кода на этой же ветке, а не поверено на
   слово:
   - §3 «current opening placement/index принимает только derived room
     walls» — подтверждено: `openingWallIndex()` (`src/wall-thickness.ts:2059-2092`)
     строит `edges` только из `for (const room of rooms || [])` →
     `roomWallProfile(...)`; `partitions` в этой функции не участвуют вовсе;
   - §3 «Physical union специально добавляет partitions после opening cuts»
     — подтверждено: `_lightBarriers()` (`src/houseplan-card.ts:14157-14231`)
     режет `walls` проёмами (`openCuts`/`passages`) и передаёт уже нарезанные
     `walls` вместе с сырым (без вычетов) `physical` в `wallBodiesGeometry(...)`;
     `physicalBodySet()`/`physicalBodyParts()` (`src/physical-geometry.ts:108-173`)
     строят тела partitions/drafts/columns и их junction-патчи независимо от
     `openings` — ни один вызов не режет их проёмом;
   - §3 «#173 заменил отдельный инструмент "Перегородка" одной цепочкой
     "Стены"; активные сегменты живут в `room_drafts`, явное завершение
     превращает каждый сегмент в `partition`» — подтверждено кодом
     (`src/houseplan-card.ts:6657` комментарий «Walls: every completed
     segment is crash-safe in room_drafts until an […] finish») и текстом
     `docs/USER-GUIDE.ru.md:282-315` («Выберите Стены… сегменты сохранятся
     обычными независимыми стенами»), а также `docs/CANVAS.md` разделами
     «Architectural connection overlay» и «Planar wall faces» (эти разделы
     явно добавлены после #173 и описывают именно ту архитектуру, на которую
     опирается ТЗ #132);
   - §11/#185 «room-face detection режется опенингом» — подтверждено:
     `buildPlanSnapGeometry()` (`src/plan-snap-overlay.ts:118-132`) строит
     `sources` из `roomEdges(...)` и явно передаёт `cuts: roomCuts` на каждый
     сегмент — то есть сегодня граф для замыкания комнаты режется по
     opening cuts, что и есть причина #185; `docs/CANVAS.md` раздел «Planar
     wall faces» прямо говорит «any physical gap — including an opening
     cut — remains a gap» про действующее поведение;
   - `OpeningCfg` (`src/types.ts:169-181`) сегодня не содержит `host` —
     подтверждено; заявление ТЗ §7 «получает optional host discriminator»
     корректно описывает это как новое поле, а не переименование
     существующего.
5. Сверены type-specific light-правила §13 ТЗ (door/gate/passage прозрачны
   при полу с обеих сторон, window всегда opaque, source внутри exterior
   opening/window fail-dark) с `docs/LIGHT.md` («Deliberately opaque…»,
   «The classifier is an explicit `door | gate | passage` allowlist») —
   ТЗ не придумывает новую световую семантику, а переиспользует
   существующую type-specific политику один в один для нового host kind.
6. Сверены sun-правила §14 («partition window не создаёт exterior wedge») с
   `docs/SUN.md` («For every opening of type "window" sitting on an EXTERIOR
   wall… windows on interior walls do not participate») — совпадает, это не
   новое правило, а прямое следствие уже принятого канона.
7. Сверена толщина/cut-геометрия §10 (1–100 см для partition, jamb returns,
   composite cut только для collinear-покрывающих тел) с
   `docs/WALL-THICKNESS.md` §9 («1–100 cm for draft and partition segments»,
   «unioned with room-wall bodies only after door/window/gate cuts») —
   совпадает дословно.
8. Сверена терминология с `docs/USER-GUIDE.ru.md`: «Стены» (§8, «Выберите
   Стены»), «Проём» (§9, подменю «Окно / Дверь / Открытый проём / Ворота»),
   host kind «Перегородка» (уже используется в §8 таблице инструментов и в
   контекстной панели, см. заголовок скриншота «Выбранная перегородка»);
   ТЗ не вводит новых, не согласованных с гайдом слов.
9. Проверено `docs/CONFIG-COMPATIBILITY.md` — раздел «Open-passage opening
   type (#157)» уже фиксирует, что `passage` запрещает `contact/lock/invert/
   flip_h/flip_v` даже при `null`/`false`; ТЗ §4 п.1 и §15 корректно этого не
   меняют и не противоречат зарегистрированной схеме совместимости.
10. Проверено `docs/TOUCH-SUPPORT.md` на предмет обязательного заявления
    `Touch editor: supported / best effort / not exposed` для новой editor
    feature — в тексте ТЗ такого явного маркера нет (см. находку Low-2).
11. Проверены трейлеры коммитов `b9bf210`/`2aaabc4` (`Issue: #132`,
    `User-Visible: no` — верно для документации ТЗ) и двусторонняя ссылка
    issue ↔ ТЗ в `docs/specs/README.md:91`.
12. Не запускал автотесты и не собирал бандл — на этапе `spec` это не
    требуется; факты о существовании кода и функций проверены чтением
    файлов на диске, не исполнением.

## Обязательные разделы (§7.1 PROCESS.md)

| Раздел | Есть | Комментарий |
|---|---|---|
| Сценарий (персона/поверхность/момент) | ✅ | §1 — администратор, инструменты «Стены»/«Проём», Plan editor (поверхность называется через инструменты, не текстом «Редактор плана», но однозначно определяется) |
| Что человек увидит до/после (без терминов реализации) | ⚠️ | §2 — см. Low-1: использует внутренний термин «host-сегмент» |
| Проблема и связь со scope | ✅ | §3, с подтверждённым построчно техническим диагнозом |
| Скоуп / не-скоуп | ✅ | §5 / §6, оба конкретны и проверяемы |
| Контракт поведения | ✅ | §7–17: модель данных, resolver, placement, толщина/cut, room topology (#185), floor/tunnel, light, sun, HA state/actions, move/edit/delete, orphan |
| UX | ✅ | §9 (placement), §16 (move/edit/delete) |
| i18n / accessibility | ⚠️ | §19 — строки описаны по смыслу, но не перечислены как конкретные ключи en+ru; см. Low-3 |
| Touch | ⚠️ | затронуто по существу (§9, §21, AC10), но нет обязательного по `docs/TOUCH-SUPPORT.md` явного маркера `Touch editor: …`; см. Low-2 |
| Модель данных и миграция | ✅ | §7, §18 — explicit host discriminator, backward compatibility, no schema migration |
| Критерии приёмки AC1…ACn с доказательством | ✅ | §20, 12 штук, у каждого назван тип доказательства (unit/backend/smoke/golden/reviewed golden) |
| План автотестов | ✅ | §21 — Unit/Backend/Browser smoke/Golden/Performance, конкретные сценарии |
| Риски | ✅ | §23, 9 пунктов с мерами (без явной ссылки на закрывающий AC — необязательно по §7.1, но снижает читаемость) |
| Откат | ✅ | §23, последний абзац |
| Release-артефакты | ✅ | §24 — оба changelog, USER-GUIDE.ru.md, шесть канонических документов, TESTING.md |

Все обязательные по `PROCESS.md` §7.1 разделы присутствуют и содержательны.
Дополнительно есть §25 «Принятые технические предположения», корректно
отделяющий свободно изменяемые технические решения от продуктовых решений
владельца.

## Находки

Находок уровня **High** и **Medium** нет.

### Low-1 — §2 использует термин реализации «host-сегмент»

**Файл:** `docs/specs/132-partition-openings.md:22`

Раздел «Что человек увидит до и после» обязан по `PROCESS.md` §7.1
формулироваться «одной фразой, без терминов реализации». Текущая
формулировка — «выбранный door/window/gate/passage вырезает её тело,
следует за конкретным **host-сегментом** и ведёт себя как тот же тип
проёма в обычной стене» — использует «host» и «host-сегмент», термины
модели данных этого же ТЗ (§7), которых нет ни в `docs/USER-GUIDE.ru.md`,
ни в обычной речи пользователя. Человек не думает про «host» — он видит,
что дверь/окно теперь можно поставить на перегородку и она держится на
своём месте при переносе стены.

**Почему не блокирует:** раздел присутствует, разбит на «до» и «после»,
и по существу корректен; страдает только буквальное соответствие «без
терминов реализации». AC и контракт поведения (§7–17) не зависят от этой
фразы.

**Решение ревьюера:** Low, не блокирует. Рекомендация — заменить
«host-сегмент» на «эту перегородку» при следующей правке; можно также
оставить как есть с записью здесь, так как продуктовый смысл раздела не
искажён.

### Low-2 — нет обязательного маркера `Touch editor: …` по `docs/TOUCH-SUPPORT.md`

**Файл:** `docs/specs/132-partition-openings.md` (раздел §9/§21, отсутствует
явное заявление)

`docs/TOUCH-SUPPORT.md` требует буквально: «New editor feature
specifications and code reviews must state one of: `Touch editor:
supported`; `Touch editor: best effort / intentionally degraded`; `Touch
editor: not exposed`.» ТЗ #132 добавляет новую функциональность
Plan-редактора (placement/drag/delete проёма на перегородке) и по существу
описывает touch-поведение («Touch placement — best effort;
pointercancel/multi-touch не сохраняют draft», AC10, browser smoke «touch
cancel/pinch safety»), но нигде не даёт этой ровно сформулированной строки.

**Почему не блокирует:** содержательно контракт уже соответствует
best-effort политике редакторов (`docs/TOUCH-SUPPORT.md`: «Plan editor:
Best effort»), никакого расхождения с политикой нет — не хватает только
формальной декларативной строки, которую сам канон требует именно текстом.
View/kiosk (обязательная touch-поверхность) в этом ТЗ — чисто presentation
(рендер уже существующим пайплайном через общий resolver, AC7), интерактива
там не добавляется.

**Решение ревьюера:** Low, не блокирует. Рекомендация — добавить строку
`Touch editor: best effort / intentionally degraded` в §9 или §21 при
следующей правке.

### Low-3 — i18n-раздел не перечисляет конкретные ключи en/ru

**Файл:** `docs/specs/132-partition-openings.md:330-342`

DoR-чеклист (`PROCESS.md` §2.5) требует на входе в «Готово к разработке»:
«i18n: ключи en + ru перечислены». §19 ТЗ описывает нужные строки по
смыслу («Стена или перегородка» в placement guidance/error», host kind
«Перегородка» и т.д.), но не называет литеральные идентификаторы ключей
(например `opening_no_wall_or_partition`, `opening_host_kind_partition`).

**Почему не блокирует:** выбор конкретных строковых констант — техническое
решение (именование), прямо подпадающее под §25 «точная форма discriminator
fields может меняться на ревью» по духу того же принципа: разработчик и
ревьюер кода решают его сами, без продуктового смысла. Из текста однозначно
понятно, какие строки нужны и где.

**Решение ревьюера:** Low, не блокирует. Рекомендация — при переводе issue
в `S5-ready` дописать в §19 (или в отдельном комментарии) точные ключи,
чтобы DoR-пункт был закрыт буквально, а не только по духу.

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

- **Соответствие `docs/SCOPE.md`.** Функция закрывает J4 («от нуля до
  рабочего плана без внешнего SVG/YAML») и корректно поддерживает J1/J2/J3
  через сохранение геометрии/contact/lock/actions идентичными room-wall
  contract — ни один пункт «Out of scope» не задет, `passage` не создаёт
  новую семантику (§6 явно это исключает), lock-инвариант не расширяется
  (§15: «Door/gate lock action остаётся единственной sanctioned opening
  surface», «Passage остаётся inert»).
- **Продуктовые вопросы владельцу заданы корректно и по существу.** За три
  раунда (Q1–Q3, затем Q4–Q5) все вопросы — это «что человек видит/делает»
  (какие типы проёма разрешить, что видно при переносе/удалении
  перегородки, нужен ли отдельный chooser при совпадении стен) или «сколько
  видимых изменений входит в issue» (включать ли уже реализованный
  `passage`, сворачивать ли фикс #185 в этот же issue) — ни одного чисто
  технического вопроса владельцу не передано; каждый вопрос шёл с
  предлагаемым default. Владелец принял все defaults без правок.
- **Технические решения по существу верны и отделены от продуктовых.**
  Обширный раздел «Актуализация после #173/#157» (комментарий 2026-08-19)
  и итоговая ревизия ТЗ корректно диагностируют, что изменилось в кодовой
  базе после #173/#157/#185 и что это означает для #132 — проверено
  построчным чтением реального кода (см. «Как проверялось» п.4–7):
  расхождений между заявленным и действительным поведением не найдено.
  Раздел §25 явно маркирует свободно изменяемые технические предположения
  (форма host-поля, имя resolver'а) отдельно от settled-решений владельца
  (§4) — никакая догадка не выдана за факт без пометки.
- **AC1–AC12 однозначны и у каждого указан тип доказательства** из
  допустимого по DoR перечня (unit/backend/smoke/golden/reviewed golden).
  AC5 отдельно требует production-bundle smoke, который «краснеет на
  `origin/dev`» — то есть автор заранее закладывает воспроизводимость
  регресса #185 тестом, который **умеет падать** до фикса; это ровно тот
  стандарт доказательства, который код-ревью потребует на следующем этапе
  (`AGENTS.md`, issue #143 про смок, не умеющий падать).
- **Не-скоуп (§6) корректно отсекает смежные соблазны:** новый opening
  type, несколько host segments на один opening, конверсия старых
  room-wall openings в partition openings, новый способ завершения Walls
  chain, изменение light/window semantics, sun rays от внутреннего окна,
  полная touch parity редактора, свободное удаление host без confirmation —
  все типичные места, где скоуп мог бы незаметно расшириться.
- **Миграция и совместимость (§18) корректны:** старые данные не
  мигрируют, `host` — чисто additive optional-поле, поведение
  room-wall openings без host не меняется; согласуется с
  `docs/CONFIG-COMPATIBILITY.md` (существующая запись про `passage` не
  противоречит новым правилам).
- **Откат описан симметрично** (§23, последний абзац): запрет на создание
  новых partition-host openings плюс явный запрет тихой авто-конвертации
  уже сохранённых host-объектов в room-wall openings.
- **Release-артефакты (§24) называют реальные документы**, шесть из семи
  канонических файлов подсистемы (`ARCHITECTURE.md`, `CANVAS.md`,
  `UX-MODES.md`, `WALL-THICKNESS.md`, `LIGHT.md`, `SUN.md`,
  `CONFIG-COMPATIBILITY.md`) плюс `USER-GUIDE.ru.md`/`TESTING.md`/оба
  changelog — соответствует правилу «документация в том же коммите, что
  поведение».
- **Трассируемость:** `docs/specs/README.md:91` ссылается на ТЗ и на #185
  одной строкой в обе стороны; трейлеры обоих коммитов ТЗ (`Issue: #132`,
  `User-Visible: no`) корректны для чисто документационного изменения.
- **Решение свернуть #185 в #132** — явное решение владельца
  (комментарий 2026-08-18), а не самовольное расширение скоупа автором; в
  `AGENTS.md`/`PROCESS.md` нет запрета объединять связанный bug в feature
  issue по решению владельца, а отсутствие статусной метки `S*` у #185 не
  создаёт противоречия, так как #185 явно не идёт по процессу отдельно —
  его код и доказательство целиком описаны AC5/AC6 этого ТЗ.

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

- Не проверял, что предложенный `ResolvedOpeningHost` resolver (§8)
  реализуем без побочных эффектов на существующие `_glowClipCache`/
  `OpeningWallIndex` кеши — по §25 п.7 это свободно изменяемое техническое
  решение автора кода, предмет код-ревью, а не ревью ТЗ.
- Не запускал автотесты, не собирал бандл и не гонял golden/смоки — на
  этапе `spec` это не требуется; существование упомянутых модулей и
  контрактов проверено чтением файлов на диске (см. «Как проверялось»
  п.4–7), не исполнением кода.
- Не проверял, сколько именно golden-сцен с перегородками изменится
  визуально (владелец просил оценить это заранее в первом комментарии) —
  это в явном виде эксплуатируется через переоценку сложности 8→9/10 и
  через требование «reviewed Flat/Iso/Glow golden artifacts» (§24); точное
  число сцен — вопрос реализации и пре-релизного гейта, не ревью ТЗ.
- Не проверял реализуемость composite room-wall/partition cut в текущей
  boolean-геометрии (`polyclip-ts`) на предельных случаях (например, три и
  более совпадающих тела) — §23 называет это риском («Composite overlap
  режет nearby/crossing body») с мерой («collinear full-interval coverage +
  negative units»), достаточной для ТЗ; сама корректность реализации —
  предмет код-ревью на unit-тестах §21.
- Не проверял статус issue #185 на предмет корректности процесса
  еженедельной гигиены (issue без `S*`-метки дольше некоторого срока) — это
  вне скоупа ревью ТЗ #132.

## Вердикт

Зелёный. High: 0, Medium: 0. Три находки Low (жаргон в §2, отсутствие
обязательной по `docs/TOUCH-SUPPORT.md` строки `Touch editor: …`,
отсутствие конкретных i18n-ключей) — ни одна не блокирует переход в
«Готово к разработке»; все три — точечные текстовые дополнения, не
меняющие контракт поведения или AC. Технические утверждения ТЗ о текущем
состоянии кодовой базы (после #173/#157) проверены построчным чтением
реального кода на этой же ветке и подтверждены без расхождений. Продуктовые
вопросы за три раунда обсуждения заданы владельцу корректно (что видит/
делает человек, какой объём входит в issue) и закрыты явными решениями;
технические вопросы автор решил сам и промаркировал как предположения
(§25), не выдавая догадку за факт.