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

# SPEC-REVIEW-242-r1

- Issue: [#242](https://github.com/Matysh/houseplan-card/issues/242) — «Проём в толстой стене рисуется у произвольной грани, а не по центру толщины»
- Этап: ТЗ на ревью (PROCESS.md §2.4)
- Артефакт ТЗ: `docs/specs/242-opening-symbol-center.md`, ревизия `0033138`
- Ветка: `issue/242-opening-symbol-center`
- Заход: **r1**, блокирующих циклов израсходовано **0 из 4** (лимит обычного трека — 4, §4)
- Вердикт: **зелёный**

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

Первый заход — полный разбор ТЗ, без ограничения по дельте (§2.10 применяется
только со второго захода).

Проверялось:

1. Соответствие обязательным разделам §7.1 PROCESS.md.
2. Продуктовая рамка — принадлежность задачи job'ам из `docs/SCOPE.md`.
3. Верность диагноза — сверка цитируемого кода с текущим `HEAD` (та же
   ревизия, на которой ТЗ написано).
4. Проверяемость и однозначность AC1…AC8.
5. Отсутствие догадок, выданных за факт (решения без пометки, что это
   предположение автора, а не решение владельца).
6. Совпадение зафиксированных в ТЗ product-решений (§4) с ответами владельца в
   комментариях issue (Q1–Q4).
7. Техническая осуществимость геометрического контракта (§7 ТЗ) — не
   декларация ли это того, что текущая модель данных не может обеспечить.
8. Термины интерфейса — сверка с `docs/USER-GUIDE.ru.md`, а не изобретённые.
9. Полнота списка канонических документов, которые придётся обновить.

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

- Прочитаны `docs/SCOPE.md`, `AGENTS.md`, `PROCESS.md`, тело issue #242 и все
  5 комментариев (аналитика → занятие → вопросы владельцу → решения владельца
  → готовое ТЗ).
- Прочитан `docs/specs/242-opening-symbol-center.md` целиком.
- Прочитаны канонические `docs/WALL-THICKNESS.md` и `docs/ISOMETRIC.md`.
- В `docs/USER-GUIDE.ru.md` найден и прочитан раздел «Толстые стены»
  (строки 606–616) и таблица «Настройки проёма» (568–575) — источник
  интерфейсной терминологии, которую ТЗ обязано использовать без изменений.
- Прочитан код, на который ссылается диагноз ТЗ, чтобы отделить проверенный
  факт от догадки:
  - `src/wall-thickness.ts` — `OpeningWallSide`, `resolveOpeningWallAssociation`,
    `openingInnerFaceOffsetFromIndex` (строки ~2340–2530);
  - `src/partition-openings.ts` — `partitionOpeningFace` (153–165);
  - `src/render/opening-symbol.ts` — `openingVisibleMetrics`,
    `renderOpeningVisibleGeometry` (1–147);
  - `src/houseplan-card.ts` — рендер `op-hit`/`op-outline` (18530–18588) и
    позиционирование lock-бейджа (18590–18618).
- Продуктовый код и ТЗ не редактировались — ревьюер только читает.

Гейты для этапа ТЗ не запускались: PROCESS.md §8 требует их на код-ревью, а
здесь нет ни строчки кода. Автор уже отчитался о `node scripts/check-docs.mjs`
для diff'а этого захода (только `docs/specs/**`), что достаточно для этой
стадии.

## Находки

Нет. Ни одной High, Medium или Low.

## Что проверено и признано корректным

**Структура ТЗ (§7.1).** Все обязательные разделы на месте: сценарий и
персона (§1), что человек увидит до/после (§2), диагноз/проблема (§3),
скоуп и не-скоуп (§6), контракт поведения (§7–8), данные/миграция/i18n/a11y/
touch (§9), перф и безопасность (§10), AC1…AC8 с доказательством (§11), план
автотестов (§12), mutation guards (§13), гейты (§14), release-артефакты
(§15), откат (§16), риски (§17), явный блок принятых технических
предположений (§18). Ничего не подменяет продуктовый вопрос техническим и
наоборот.

**Продуктовая рамка.** Задача закрывает J4 («от нуля до плана без внешнего
редактора» — точность геометрии) и J6 («план остаётся достоверным при
эволюции комнат» — независимость от порядка `space.rooms`); во View
дополнительно поддерживает J1 (одинаковое чтение геометрии независимо от
внутреннего порядка данных), как и написано в аналитике issue. Ни одна
строка `docs/SCOPE.md` не нарушается, новых поверхностей продукта не
добавляется.

**Диагноз подтверждён чтением, а не поверил автору на слово.** Прочитанный
код на актуальном `HEAD` (`0033138`, тот же коммит, на котором писалось ТЗ)
подтверждает каждое утверждение §3 ТЗ:
- `openingInnerFaceOffsetFromIndex` действительно сортирует кандидатов по
  `order` — полю, комментарий к которому в коде прямо называет его
  «first matching room edge in config order» (wall-thickness.ts:2355) — и
  берёт `available[0]` как «natural» грань (2513–2520);
- `partitionOpeningFace` действительно фиксирует знак `side` от `flipV` и
  умножает его на `resolved.axis` — направление, которое зависит от того, как
  сохранены `partition.a`/`partition.b` (partition-openings.ts:157–164);
- `renderOpeningVisibleGeometry` переносит только группу `body` (дуга/створки/
  стекло) через `translate(swingTx swingTy)` (opening-symbol.ts:74–137);
  косяки (`op-jamb`-линии на `±half` — здесь и далее «half» это `jambHalf`,
  то есть половина физической толщины) рисуются вне этой группы (140–146) —
  то есть **уже сейчас** структурно независимы от face-сдвига. Это прямо
  подтверждает пункт контракта ТЗ §7 «Косяки всегда остаются на `±cm/2` … и
  не входят в translated группу» — не предположение, а описание уже
  существующей структуры кода, которую нужно не разрушить, а сохранить.

**Геометрический контракт (§7 ТЗ) реализуем на текущей модели данных**, а не
декларация невозможного:
- Для стены комнаты `side` (`-1`/`1`) уже вычисляется из `opening.angle` через
  `nx = -sin(rad), ny = cos(rad)` и знака `inward`-нормали ребра
  (wall-thickness.ts:2419–2441) — это уже канонический локальный базис самого
  проёма, **не зависящий от `order`**. Order используется только для выбора,
  какая из двух сторон общей стены становится «natural» (unflipped) —
  единственное, что требует замены на фиксированное правило по локальной оси.
  Никакой новой геометрической информации придумывать не нужно.
- Для partition та же независимая от направления рисования величина уже
  доступна — тот же `opening.angle`, что и для room-wall (сейчас не
  используется в `partitionOpeningFace`, но используется параллельно для
  room-wall face). Перевести partition-резолвер на тот же базис, вместо
  `resolved.axis`, зависящего от `a`/`b`, технически прямолинейно.
- **Lock-бейдж переживёт правку без отдельного контракта**, хотя ТЗ (§18.3)
  формулирует это как «принятое предположение»: `_renderOpeningLocks`
  (houseplan-card.ts:18605–18616) вычисляет офсет бейджа как
  `lockOffset * sign`, где `lockOffset` — фиксированная величина в grid units,
  **не связанная с `face.ox/oy`/`cm`** вообще; она использует только знак
  (`gateFace.side` либо `flip_v ? -1 : 1`). Смена перевода видимой группы с
  «сдвиг на грань» на «центр» этот знак не меняет ни для одного из
  зафиксированных в контракте случаев (§7 ТЗ) — прочитано и проверено
  чтением, вывод сильнее, чем у самого автора: это не предположение,
  которое ревьюер не оспорил, а проверенный факт.

**Верность отражения решений владельца.** Раздел §4 ТЗ построчно совпадает с
ответами владельца из комментария `2026-08-22T17:07:08Z` на все четыре вопроса
(Q1 flip_v-совместимость, Q2 направление ворот, Q3 parity поверхностей, Q4
окно целиком) — без искажений и без добавления нового необсуждённого
поведения. Технические детали (§18: формула локальной оси, имя типа
visual-offset) явно помечены как «принято предположительно, менять свободно»
и не выданы за продуктовое решение.

**Проверяемость AC.** Все восемь AC (§11) сформулированы через числа и
конкретные наблюдаемые свойства (нулевое смещение, идентичность метрик при
перестановке, сохранение full-depth jambs, отсутствие diff в schema), а не
через «выглядит по центру» — ровно то, что требует сама постановка issue
(«AC стоит формулировать через числа»). У каждого указан способ доказательства
в допустимом словаре (`unit`/`smoke`/`golden`/`review`).

**Терминология.** «Открывается в другую сторону» и «flip_v» использованы как
в `docs/USER-GUIDE.ru.md` (568–575), без изобретения нового языка. ТЗ явно
называет тот самый абзац «Толстые стены» (606–616) устаревшим фактическим
описанием («Створка/дуга двери и окна смещается к внутренней грани комнаты, а
створки ворот — к наружной») и относит его обновление к release-артефактам
своего user-visible коммита (§15) — список канонических документов на
обновление (`USER-GUIDE.ru.md`, `WALL-THICKNESS.md`, `ARCHITECTURE.md`,
`ISOMETRIC.md`, changelog RU+EN) полон, ничего из задетых поверхностей не
забыто.

**Не-скоуп обоснован.** Passage (нет видимого символа), wall cut/jamb depth/
opening length, lock badge, hitbox, Glow/sun/decor/vacuum, новый Iso UX или
config-migration — всё это корректно исключено и не пересекается с
задекларированным контрактом §7–8.

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

- **Не запускал автотесты/гейты** — на этапе ТЗ кода нет, гейты §8
  относятся к код-ревью.
- **Не проверял `docs/ARCHITECTURE.md` целиком** — только убедился, что файл
  фигурирует как канонический для этого изменения и включён в release-
  артефакты §15; содержимое самого файла не читал, это не требуется для
  вывода о полноте ТЗ.
- **Не оценивал `docs/specs/README.md` рассинхрон колонки «Статус ТЗ»**
  (известный открытый пункт PROCESS.md §7.3.1, не относится к #242) — запись
  строки #242 в таблице P2 корректна и не мой предмет.
- **Не проверял `iso-openings.ts`/`buildIsoOpeningBasis()` построчно** —
  прочитал только его роль по `docs/ISOMETRIC.md` («door has one jamb-hinged
  leaf… mirrors the existing opening-symbol transform algebra»); ТЗ верно
  определяет его как одну из четырёх поверхностей parity (AC5), детальную
  реализуемость там не проверял глубже необходимого для вывода «этот
  контракт возможен» — она подтверждена уже на room-wall/partition пути, а
  Iso по документации использует ту же алгебру.
- **Не проверял mutation-gate script и наличие тестовых фикстур** — на этапе
  ТЗ они не существуют, это работа код-ревью.
- Никаких browser-smoke/golden не запускал — на этапе ТЗ нет рендера для
  сравнения.

## Заключение

ТЗ полно по составу разделов, продуктово обосновано, верно отражает решения
владельца без домыслов, а диагноз и предложенный контракт подтверждены
чтением актуального кода (в том числе в пунктах, которые сам автор пометил
как непроверенное предположение — lock-бейдж, независимость косяков). High/
Medium-находок нет. Задача может двигаться в `S5-ready`.

**Вердикт: зелёный · заход r1 · блокирующих циклов 0/4 · High: 0 · Medium: 0 → в задаче**