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

# SPEC-REVIEW-186-r1

- **Issue:** https://github.com/Matysh/houseplan-card/issues/186
- **ТЗ под ревью:** [`docs/specs/186-partition-opening-jamb-margin.md`](https://github.com/Matysh/houseplan-card/blob/issue/186-partition-jamb-margin/docs/specs/186-partition-opening-jamb-margin.md)
  (коммит `7d4d3f0`), обычный трек — не `small`/`trivial`
- **Роль:** ревьюер ТЗ (не автор), этап `S4-spec-review`
- **Трек:** обычный, лимит циклов ревью ТЗ — 4 (§4 PROCESS.md)
- **Цикл:** r1/4

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

ТЗ #186 — follow-up к #132 (найдено на код-ревью `CODE-REVIEW-132-r1.md`,
Medium-1): вводит содержательный jamb safety margin (половина фактической
толщины independent-стены у каждого торца) для door/window/gate/passage,
размещённых в `partition`, вместо нынешнего `jambMargin=0` в
`resolvePartitionOpening()` и голого `1e-9`-эпсилона в backend. Затрагивает
placement/drag/dialog в Plan editor, frontend commit validation, backend
semantic delta validation (`config/set`, optimize, import) и compatibility
уже сохранённых near-end проёмов.

Не в скоупе ревью: продуктовый код. Ветка `issue/186-partition-jamb-margin`
содержит один коммит (`7d4d3f0`, `Issue: #186 · User-Visible: no`) — только
спецификация и обновление `docs/specs/README.md`, реализации нет.
Гейты (`typecheck`/`test`/`build`) не прогонялись: на этапе ревью ТЗ
продуктового кода не существует, прогон к этому этапу не относится
(PROCESS.md §2.4/§8).

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

1. Прочитаны `docs/SCOPE.md`, `AGENTS.md`, `PROCESS.md` целиком (действующая
   редакция, включая §1, §2.2–§2.4, §5, §7.1, §8, §10.2).
2. Прочитано тело issue #186 и все три комментария: аналитика владельца
   (оценка 5/10 · 6/10 · 5/10 · P2 · `bug`, обычный трек с явным
   обоснованием, три вопроса с default), решение владельца (все три default
   приняты дословно) и хендофф «ТЗ готово к ревью».
3. Построчно сверены технические утверждения §4 ТЗ с кодом на этой ветке:
   - `resolvePartitionOpening()` (`src/partition-openings.ts:35-61`) —
     параметр `jambMargin = 0` подтверждён; проверка `does-not-fit`
     (`along - length/2 < jambMargin - 1e-9 || along + length/2 >
     axisLength - jambMargin + 1e-9`) действительно единственное место, где
     `jambMargin` используется.
   - Продакшн call sites (`src/houseplan-card.ts:7455, 7920, 7953, 11300,
     11604, 11613, 17569`, `src/space-render.ts:214`) действительно не
     передают шестой аргумент — ТЗ не завышает диагноз issue.
   - Формула §4: `wallDepth = wallCmToUnits(cm, cellCm, gridPitch)`,
     `jambMargin = wallDepth/2` — проверено по `wallCmToUnits()`
     (`src/wall-thickness.ts:70-73`, `= (cm/cellCm) * gridPitch`) и по
     фактическому вызову на `houseplan-card.ts:7455-7457`, где
     `lengthScale=NORM_W` и `gridPitch=this._gridPitch` (геттер возвращает
     `GRID_PITCH`, `src/houseplan-card.ts:5771`, `GRID_PITCH = NORM_W /
     GRID_N`, `GRID_N = 240`, `src/space-geometry.ts:197-201`). В render-
     единицах (`NORM_W`-масштаб) формула самосогласована с `axisLength` и
     `length`, которые в этом же call site тоже в render-единицах.
   - Backend-эквивалент §4: `partition.cm / cell_cm / 240 / 2` в
     normalized units (масштаб хранения, 1.0 = ширина канвы) — пересчитан
     независимо: `wallCmToUnits` в render-единицах даёт `(cm/cellCm) *
     (1000/240)`; деление на `NORM_W=1000` (переход в normalized) даёт
     `(cm/cellCm)/240`, и `/2` для margin — **формула ТЗ подтверждена
     арифметически**, это не придуманная константа, а имеющийся `GRID_N=240`
     (`src/space-geometry.ts:197`, тот же литерал уже упомянут комментарием в
     `custom_components/houseplan/validation.py:445`, «240 cells across the
     unit width»).
   - `_space_geometry_invariants()` (`custom_components/houseplan/
     validation.py:813-852`, встроена в `SPACE_SCHEMA` через `vol.All`) —
     подтверждён zero-margin fit-check с `1e-9` (строка 845), встроенный в
     структурную схему, а не в semantic-слой — совпадает с диагнозом issue и
     §8 ТЗ («Структурная SPACE_SCHEMA сохраняет прежний zero-margin fit
     check»).
   - `validate_partition_opening_hosts()` (`validation.py:55-79`) — реально
     существующий semantic delta validator с сигнатурой `(config,
     previous=None)`, уже используется в `config/set`
     (`websocket_api.py:1260`) и в optimize (`websocket_api.py:1372`, тот же
     блок вызывает `validate_marker_controls`/`validate_opening_passages`/
     `validate_partition_opening_hosts` с явным комментарием «Optimization is
     a normal configuration write with an additional layout transaction. It
     must enforce the same marker-link semantics as config/set»). Это
     подтверждает AC6 («config/set и optimize применяют один semantic
     validator») как реальный, не гипотетический паттерн.
4. Прочитан `docs/CONFIG-COMPATIBILITY.md` целиком, включая уже принятый
   аналогичный прецедент «Independent-wall opening host (#132)» и «Open-
   passage opening type (#157)» — оба используют тот же приём (new/changed
   строго, existing/unrelated толерантно), что и §8 ТЗ #186 предлагает для
   jamb margin; терминология («legacy», «read-compatibility», «drop-on-
   validation») не изобретается заново.
5. Прочитан `docs/USER-GUIDE.ru.md` §9 («Двери, окна, открытые проёмы, ворота
   и замки», строки 428-479) и §20 («Хранение, совместная работа и
   резервные копии», строки 1207-1244) — терминология диалога («независимая
   стена», «край проёма», «торец») совпадает с уже принятым текстом;
   отдельно проверено описание **полного** экспорта/импорта (см. находку
   High-1 ниже).
6. Прочитан `docs/WALL-THICKNESS.md` — термин «jamb» (jamb return, строки
   94-134) уже канонический для геометрии откоса; «jamb safety margin» ТЗ не
   вводит новую непонятную лексику, а расширяет существующее семейство.
7. Проверен полный путь **full import** (кнопка «Полная копия» из §20
   USER-GUIDE), которым оперирует §8 ТЗ:
   - `prepare_apply()` (`custom_components/houseplan/import_export.py:1304-
     1344`): при `document["kind"] == "full"` (строка 1330) вызывается
     **только** `CONFIG_SCHEMA(config)` (строка 1344) — ни
     `validate_marker_controls`, ни `validate_opening_passages`, ни
     `validate_partition_opening_hosts` не вызываются вовсе для этого пути.
     Сравнить с `document["kind"] != "full"` (строка 1339,
     `build_space_merge`), который **вызывает** semantic-валидаторы, но
     всегда с новым `space_id` (реассайн id, USER-GUIDE строка 1218), из-за
     чего delta-сравнение по id всё равно никогда не находит «старую» запись.
   - `ws_import_apply()` (`websocket_api.py:365-444`) на `kind == "full"`
     (строка 426) сохраняет **текущий** `config_data.get("config")` в
     `_OPTIMIZE_BACKUP` метаданных ради одной отмены (`can_undo`, строка 499)
     — то есть «предыдущая» версия конфига физически загружена и доступна в
     этот момент, просто не передаётся ни в один semantic validator.
   - Итог: на сегодня **full import вообще не проверяет partition-opening-
     host инварианты семантически** — ни downgrade guard, ни (будущий) jamb
     margin; единственный барьер — структурная `SPACE_SCHEMA` с её
     zero-margin fit-check. §8 ТЗ вводит для этого пути принципиально новую,
     а не расширяемую проверку. См. находку High-1.
8. Проверено соответствие `docs/SCOPE.md`: задача — геометрическая
   достоверность плана (J4 «zero to a working plan... room polygons bound to
   areas», J6 «keep the plan true as the home evolves»), персона home admin,
   поверхность — desktop Plan editor + backend validation; View/kiosk не
   затрагиваются. Полное резервное копирование/восстановление — тоже прямо
   часть J6 («keep the plan true») и задокументировано в USER-GUIDE §20 —
   поэтому конфликт из находки High-1 лежит внутри того же core job, который
   ТЗ заявляет закрывать, а не в смежной, посторонней функции.
9. Проверено, что issue не помечен `small`/`trivial`: аналитика владельца
   явно называет причины (новый видимый граничный контракт,
   compatibility-решение) — критерии §5 PROCESS.md («нет нового UX-
   контракта», «нет compatibility-полей») не выполняются, обычный трек
   обоснован корректно, файл ТЗ в `docs/specs/` создан как требуется.

Гейты (`typecheck`/`test`/`build`, browser smoke, golden, backend pytest) не
прогонялись — продуктового кода нет, что и ожидается на этапе ревью ТЗ.

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

| Раздел | Есть | Комментарий |
|---|---|---|
| Сценарий (персона/поверхность/момент) | ✅ | §1: home admin, Plan editor, размещение/перемещение проёма в independent-стене |
| Что человек увидит до/после | ✅ | §2, одна фраза до/после без терминов реализации |
| Проблема | ⚠️ | Нет отдельного заголовка «Проблема»; содержание фактически есть в §2 «До» и подтверждено issue. Формальный, не содержательный пробел — см. Low-1 |
| Скоуп / не-скоуп | ✅ | §5/§6, конкретны, «доп. зазор между проёмами» и «resize partition» явно исключены |
| Контракт поведения | ✅ | §7 (placement, drag/dialog, перемещение host) + §8 (backend) |
| UX | ✅ | §9, таблица состояний, 8 строк |
| Модель данных и миграция | ✅ | §10: «модель данных и schema полей не меняются» — явно и обоснованно |
| i18n | ✅ | §10, RU/EN строка для banner приведена дословно |
| AC1…ACn с доказательством | ✅ | §11, 6 штук, у каждого назван способ доказательства (unit/backend/smoke) |
| План автотестов | ✅ | §12, разделён на implementation-loop и pre-review гейты |
| Риски | ✅ | §13, 7 строк риск/мера — но не покрывает риск найденного противоречия (High-1) |
| Откат | ✅ | §14, без миграции, возврат к zero-margin |
| Release-артефакты | ✅ | §15, оба changelog, USER-GUIDE, CONFIG-COMPATIBILITY, TESTING |

Присутствует также обязательный блок «Принятые технические предположения»
(§16, 4 пункта) — все технические (rigid translation, `type`-only edit,
имена helper/reason/i18n key, malformed `cm`/`cell_cm` fallback), ни один не
маскирует продуктовый вопрос. Однако именно то, что должно было попасть в
этот блок или в пачку вопросов владельцу — трактовка full import как
«без trusted previous» — вместо этого записано как решённый факт в §5/§8/§11
(AC4). См. находку High-1.

## Находки

### High-1 — «строгая» проверка full import противоречит уже принятому владельцем round-trip-инварианту и ломает документированный backup/restore

**Файл:** `docs/specs/186-partition-opening-jamb-margin.md`, §8 (строки
163-166), §5 (строка 68), AC4 (строки 223-231).

**Что заявлено.** §8: «Полный import/restore без trusted previous
рассматривает все hosted openings как новые и проверяет strict.» AC4 явно
фиксирует это в тесте: «Direct geometry edit и full import того же нарушения
отклоняются» (строка 228), с доказательством «backend delta/import tests с
previous и без него» (строка 230).

**Почему это противоречие, а не деталь реализации.**

1. Owner-decision #3 (принята дословно в комментарии от 2026-08-19 08:02):
   «Уже сохранённые проёмы, нарушающие новый предел, остаются видимыми и
   рабочими, не сдвигаются автоматически и допускают неизменённый round-trip
   при посторонних правках... Новый предел применяется при создании,
   перемещении, изменении длины или перепривязке.» Ни исходный default
   аналитика, ни решение владельца ни разу не называют «полный
   экспорт/импорт» как один из триггеров нового предела — речь только о
   прямых geometry-действиях над самим проёмом/host.
2. «Полная копия» — не гипотетическая, а прямо задокументированная в
   `docs/USER-GUIDE.ru.md` §20 (строки 1207-1244) функция **этого же** J6
   («keep the plan true as the home evolves», `docs/SCOPE.md`): «Экспорт
   предлагает... Полная копия — ...её импорт заменяет текущую модель
   целиком; до следующего изменения плана доступна одна отмена.» Наличие
   «одной отмены» — прямое доказательство (`websocket_api.py:426-444`,
   `_OPTIMIZE_BACKUP`), что это рутинная операция на **той же** живой
   инсталляции (восстановление вчерашней резервной копии после неудачных
   правок), а не только перенос на чистый новый инстанс.
3. Полный импорт **не переприсваивает id** (`import_export.py:1330-1344`,
   ветка `kind == "full"`: `config = imported_config` без ремаппинга, в
   отличие от `space`-merge, который явно генерирует новые id — USER-GUIDE
   строка 1218). Значит id пространств/проёмов в восстановленном файле
   буквально совпадают с id, под которыми они хранились в момент экспорта.
4. Итог сценария: администратор на v1.65.0-beta.2 создал проём впритык к
   торцу independent-стены (валидно на тот момент). После обновления до
   версии с #186 он делает «Полная копия» (рутинный совет из
   `docs/USER-GUIDE.ru.md` перед крупной правкой, строка 1358) — экспорт
   содержит этот проём без изменений, потому что по decision #3 он остаётся
   «видимым и рабочим». Позже (после неудачного эксперимента, или после
   переустановки HA, или просто ради восстановления) он импортирует **тот
   же самый, ничем не изменённый файл** обратно. По §8 ТЗ и AC4 этот импорт
   **обязан быть отклонён** ровно из-за геометрии, которая мгновение назад
   была признана допустимой для чтения/рендера/экспорта. Это прямое
   нарушение decision #3 «допускают неизменённый round-trip» и очень
   вероятный сценарий (единственное действие пользователя — сделать и
   восстановить резервную копию, ничего не редактируя).
5. Технически ничего не мешало сохранить round-trip хотя бы для случая
   «restore на ту же инсталляцию»: `ws_import_apply()` уже загружает текущий
   `config_data.get("config")` в этот самый момент (используется как backup
   для отмены, строка 429) — тот же объект мог бы быть передан в semantic
   validator как `previous`, как это уже делается для `config/set`
   (`websocket_api.py:1260`) и optimize (`websocket_api.py:1372`). Но даже
   это не спасает случай disaster-recovery на **пустой** инсталляции
   (переустановка HA, `config_data.get("config")` пуст) — там по любому
   id-based delta-подходу «предыдущего» совпадения не найдётся, и restore
   старого валидного бэкапа всё равно будет отклонён. Это структурное
   ограничение самой архитектуры full-import (нет модели «that record is the
   same one, unchanged»), а не деталь одной реализации — то есть вопрос
   принципиально не имеет тихого технического решения и должен решаться
   владельцем.
6. Формулировка §8 предъявлена как принятое решение, а не как assumption:
   она не попала ни в блок §16 «Принято предположительно», ни в пачку
   вопросов владельцу, хотя по своей природе — это ровно тот тип вопроса,
   который согласно PROCESS.md §7.1 обязан идти владельцу: «поведение в
   пограничном случае» и «что считать приемлемой деградацией». Оценка
   аналитика (Touch/Performance были явно взвешены) не рассматривала этот
   write-path вовсе.

**Последствие для процесса.** Утверждение о поведении (full import —
strict), которого нет ни в одном согласованном документе и которое
противоречит уже зафиксированному владельцем decision #3, подано как факт.
Это ровно тот класс дефекта, который PROCESS.md называет «худшим видом» —
предположение, записанное как решение, потому что оно read как решение и
прошло бы имплементацию буквально по AC4.

**Требуемое действие.** Автор обязан вынести это отдельным продуктовым
вопросом владельцу (в формате §7.1: что неясно · что изменится от ответа ·
default), например:

> Full import/restore того же полного бэкапа, содержащего legacy near-end
> proём — тоже вариант «посторонней правки» с сохранением round-trip
> (decision #3), или отдельный, более строгий путь, где такой бэкап нужно
> будет сначала починить? Default: round-trip сохраняется всегда, когда id
> пространства/проёма совпадает с уже хранимой записью (сравнение с текущим
> `config_data.get("config")`, который и так загружается для undo-бэкапа);
> при restore на пустую/чужую инсталляцию (нет совпадения по id) — new/strict,
> как сейчас предложено.

Это High: находка блокирует переход в `S5-ready`, поскольку задевает уже
принятое владельцем решение и заложена в AC4 буквально — реализовать ТЗ как
написано значит намеренно сломать документированный сценарий backup/restore
для любого дома с legacy near-end проёмом.

### Low-1 — нет отдельного раздела «Проблема»

**Файл:** `docs/specs/186-partition-opening-jamb-margin.md`, между §1 и §3;
ближайшее место — §2 «До / после» (строки 13-22).

PROCESS.md §7.1 перечисляет «проблема» отдельным обязательным разделом.
Содержательно проблема изложена — в §2 «До» и в теле issue («Практическое
следствие: дверь/окно/ворота можно поставить в перегородку впритык к самому
её концу, без зазора на откос»), но отдельного заголовка/абзаца «Проблема» в
файле ТЗ нет. Ни один AC от этого не становится неоднозначным.

**Решение ревьюера:** Low, не блокирует. Снимаю без возврата ТЗ на правку;
рекомендую добавить короткий явный абзац «Проблема» при следующей правке
файла (тот же цикл, что закроет High-1), а не отдельным циклом ревью.

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

- **Физическая формула margin (§4 ТЗ) арифметически верна и не выдумана** —
  проверена независимо через `wallCmToUnits()`, `GRID_PITCH`/`GRID_N=240`
  (`src/space-geometry.ts:197-201`) на фронтенде и пересчитана в normalized-
  масштаб для backend; итоговая backend-формула `cm/cell_cm/240/2` совпадает
  с ТЗ буквально, включая уже присутствующий в кодовой базе литерал `240`
  (комментарий `validation.py:445`).
- **Диагноз issue подтверждён кодом**: `jambMargin=0` по умолчанию,
  production call sites его не передают (`partition-openings.ts:41`,
  8 реальных call sites), backend fit-check использует только `1e-9`
  (`validation.py:845`) — ТЗ не завышает и не занижает масштаб проблемы.
- **AC6 («config/set и optimize — один semantic validator») подтверждён
  реальным существующим паттерном**: `validate_partition_opening_hosts()`
  уже вызывается из обоих путей с явным комментарием о необходимости
  одинаковой семантики (`websocket_api.py:1260, 1372`).
- **§8 корректно описывает существующее устройство структурной схемы**:
  `_space_geometry_invariants()` действительно встроена в `SPACE_SCHEMA`
  через `vol.All` и продолжит принимать zero-margin legacy-геометрию, если
  её саму не менять — ТЗ явно требует именно это («Структурная SPACE_SCHEMA
  сохраняет прежний zero-margin fit check»).
- **Терминология соответствует канону**: «независимая стена», «торец»,
  «край проёма» — из `docs/USER-GUIDE.ru.md`; «jamb» как основа термина —
  из уже принятого `docs/WALL-THICKNESS.md`. Диалоговое сообщение (RU/EN)
  не изобретает новую лексику для пользователя (само слово «jamb»
  наружу не выходит).
- **`docs/CONFIG-COMPATIBILITY.md`-паттерн выбран корректно** для описанных
  путей (config/set, optimize): «new/changed strict, unrelated tolerant» —
  тот же приём, что уже принят для #132 (host) и #157 (passage) в этом же
  документе; никакой новой персистентной модели/поля не вводится, что
  соответствует §10 ТЗ и Rule №1 AGENTS.md (класс A без новых
  compatibility-полей не требует отдельного решения о миграции).
- **AC1, AC2, AC5 однозначны и снабжены допустимым способом доказательства**
  (pure unit matrix, backend parametrized tests, browser smoke), включая
  точную границу (equality valid) и матрицу `cm=1/15/100` — тестируемо и не
  расплывчато.
- **Touch-декларация присутствует буквально**: «Touch editor: best effort /
  intentionally degraded» (§10) — соответствует `docs/TOUCH-SUPPORT.md`
  Documentation rule, без нового жеста и с явным safety floor (tap/pinch/
  pointercancel).
- **Откат (§14) реалистичен**: без persisted-полей нет обратной миграции;
  просто удаление strict-политики и семантического валидатора.
- **§16 «Принятые предположения» не маскирует продуктовый вопрос** — все
  четыре пункта (rigid translation, `type`-only edit, публичность имён,
  malformed cm/cell_cm) действительно технические и не требуют решения
  владельца сами по себе.

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

- Реализацию — её нет: ветка содержит один документный коммит (`7d4d3f0`),
  продуктовый код (`src/**`, `custom_components/houseplan/**/*.py`) не
  менялся — проверено чтением diff коммита и содержимого текущих файлов
  (`resolvePartitionOpening`, `validate_partition_opening_hosts`,
  `_space_geometry_invariants`, `prepare_apply` не тронуты этой веткой).
- Гейты `typecheck`/`test`/`build`/browser smoke/golden/`pytest
  tests_backend` — не относятся к этапу ревью ТЗ; предмет будущего
  код-ревью (PROCESS.md §2.4/§8).
- Все восемь текущих production call sites `resolvePartitionOpening()`
  построчно — проверены три (`houseplan-card.ts:7455`, и по номерам строк
  для остальных сверено только наличие вызова через `grep`, не полный
  контекст каждого) и одно место в `space-render.ts:214`; для целей ревью
  ТЗ этого достаточно (диагноз issue про default-параметр не зависит от
  конкретного call site), но при код-ревью потребуется пройти все.
- Численную точность оценок аналитики (5/10 · 6/10 · 5/10 · P2) по существу
  — поле владельца (PROCESS.md §2.2), уже принятое явным решением до
  написания ТЗ.
- Совместимость found-High-1 сценария с другими фичами полного импорта
  (missing-plan/attachment проверки, `model_version` restore) — не относится
  к предмету находки, эти проверки независимы от partition-opening host
  semantics.

## Вердикт

Красный. High: 1 (§8/AC4 «full import — всегда strict» противоречит уже
принятому владельцем round-trip-инварианту decision #3 и ломает
задокументированный в `docs/USER-GUIDE.ru.md` §20 сценарий backup/restore
для любого дома с legacy near-end проёмом; не помечено как assumption,
подано как решённый факт). Medium: 0. Low: 1 (отсутствует отдельный
заголовок «Проблема» — не блокирует, снимается с рекомендацией). Остальная
часть ТЗ технически точна: физическая формула margin проверена независимым
пересчётом и совпадает с реальными константами кода (`GRID_N=240`), AC1/AC2/
AC5/AC6 однозначны и снабжены допустимым доказательством, compatibility-
подход для config/set и optimize соответствует уже принятому в проекте
паттерну. Возврат в `S3-spec`: автору нужно вынести found High-1 отдельным
батчем вопросов владельцу (по шаблону §7.1 — что неясно · что изменится ·
default) прежде чем ТЗ сможет получить зелёное ревью.

**Вердикт: красный · цикл r1/4 · High: 1 · Medium: 0 → нет · Документ:
docs/reviews/SPEC-REVIEW-186-r1.md**