houseplan-card/docs/specs/242-opening-symbol-center.md

# Issue #242 — символ проёма по центру толщины стены

- Дата: 2026-08-22
- Тип: bug · приоритет P2 · ценность 6/10 · сложность/риск 5/10 и 6/10
- Issue: [#242](https://github.com/Matysh/houseplan-card/issues/242)
- Ветка: `issue/242-opening-symbol-center`
- Статус ТЗ: на ревью

Канонические документы: `docs/SCOPE.md`, `docs/ARCHITECTURE.md`,
`docs/WALL-THICKNESS.md`, `docs/TOUCH-SUPPORT.md`,
`docs/ISOMETRIC.md`, `docs/CONFIG-COMPATIBILITY.md`,
`docs/USER-GUIDE.ru.md`.

## 1. Сценарий и персона

Администратор дома размещает дверь, окно или ворота в толстой стене комнаты
либо независимой стене. Во View он ожидает, что символ обозначает один и тот же
физический проём независимо от порядка комнат в конфигурации и от направления,
в котором была нарисована стена.

Сейчас видимая створка/дуга/стекло сдвигается к выбранной грани стены. Для
общей стены выбор зависит от первой комнаты в model order, для независимой — от
направления segment. Поэтому перестановка комнат или разворот endpoints меняет
вид готового плана без изменения его архитектуры.

## 2. Что человек увидит до и после

**До:** символ проёма находится у одной из граней толстой стены; выбранная грань
может измениться после перестановки комнат либо при эквивалентной записи стены с
обратным направлением.

**После:** обычный символ проёма находится точно на центральной оси толщины
стены на всех render surfaces. Косяки по-прежнему показывают полную глубину
проёма. Сохранённый `flip_v: true` остаётся явным ручным исключением для двери
и окна, а у ворот меняет только направление лёгкого поворота створок.

## 3. Подтверждённый диагноз

Дефект подтверждён на актуальном `dev`:

1. `openingInnerFaceOffsetFromIndex()` выбирает natural room side после
   сортировки кандидатов по `order`, то есть зависит от порядка комнат.
2. `partitionOpeningFace()` выбирает normal side из направления endpoints
   независимой стены.
3. `renderOpeningVisibleGeometry()` переводит всю видимую группу на `face.ox`
   / `face.oy`; окно переносит вместе с ней стекло, дверь — створку и дугу,
   ворота — обе створки.
4. `buildIsoOpeningBasis()` использует те же offsets для скрытого Iso.
5. Косяки вычисляются отдельно из полной `face.cm`, поэтому сам физический
   tunnel уже имеет правильную глубину и не требует изменения.

Тесты и golden сейчас закрепляют старое edge-aligned поведение, включая
room-order dependency; их необходимо заменить новым инвариантным контрактом.

## 4. Зафиксированные продуктовые решения

1. Если `flip_v` отсутствует либо равен `false`, дверь, окно и ворота
   центрируются по толщине host wall.
2. Для двери и окна сохранённый `flip_v: true` остаётся ручным выравниванием к
   грани на стороне «открывается в другую сторону». Сторона определяется
   собственной канонической локальной осью проёма и не зависит от model order
   комнат либо направления endpoints host wall.
3. Створки ворот остаются по центру при обоих значениях `flip_v`; флаг меняет
   только знак существующего 10° поворота.
4. Один контракт действует в committed Flat/View, preview размещения, hosted
   Static и скрытом Iso.
5. У окна центрируется вся видимая группа: стекло, створки и дуги. Косяки всех
   типов сохраняют полную физическую глубину стены.

## 5. Цели

- убрать случайную зависимость положения символа от порядка комнат и
  направления рисования стены;
- сделать default-положение физически честным и одинаковым на всех surfaces;
- сохранить совместимость сохранённых `flip_v` и направленность ворот;
- не менять cut, tunnel, hit geometry, свет, HA state и persisted schema.

## 6. Границы задачи

### Входит

- разделение физической толщины/направления face и визуального translation;
- центрирование door/window/gate на room-wall и partition host;
- детерминированная локальная сторона для `flip_v: true` у door/window;
- preview, Flat/View, hosted Static и hidden Iso parity;
- обновление unit, browser smoke, golden и нормативной документации;
- оба changelog в user-visible implementation commit.

### Не входит

- изменение wall cut, jamb depth, opening length или безопасного остатка стены;
- новый persisted field, миграция, backend/schema/compatibility change;
- изменение passage: у него нет видимого символа;
- новая UI-настройка или переименование существующего `flip_v`;
- изменение lock badge, hitbox, info/action, contact/lock state;
- изменение Glow/spill, солнца, room fill, decor или vacuum;
- публикация скрытого Iso либо новый Iso UX.

## 7. Геометрический контракт

Resolver проёма обязан различать три независимые величины:

- `cm` — полная физическая толщина host wall;
- `side` — детерминированное направление в локальной системе проёма;
- visual translation — сдвиг видимой группы относительно центральной оси.

Для любого valid host и конечной положительной толщины:

| Тип | `flip_v` | Translation видимой группы | Направление |
|---|---:|---|---|
| door | absent / `false` | `(0, 0)` | default local side |
| door | `true` | `normal * side * cm/2` | opposite local side |
| window | absent / `false` | `(0, 0)` | default local side |
| window | `true` | `normal * side * cm/2` | opposite local side |
| gate | absent / `false` | `(0, 0)` | знак текущего 10° поворота |
| gate | `true` | `(0, 0)` | противоположный знак 10° поворота |
| passage | любое | нет видимой группы | не применяется |

`normal` вычисляется из канонической локальной оси opening, а не из первого
room candidate и не из сырого порядка endpoints host. Эквивалентная геометрия
с переставленными room objects или reversed partition endpoints должна давать
битово одинаковые center/translation и визуально одинаковое направление.

Косяки всегда остаются на `±cm/2` от центральной оси и не входят в translated
группу. Window glass входит в ту же translated группу, что створки/дуги.
Gate leaves используют centered origin, а только их angle зависит от `side`.

Invalid/non-finite host geometry сохраняет действующий fail-safe и не получает
новых попыток inference. Эта задача не меняет правила выбора host.

## 8. Render parity

Один resolved geometry contract используется:

- в preview до клика и в записанном Flat/View;
- для legacy room-wall и explicit partition-hosted opening;
- в hosted Static card;
- в скрытом Iso через `buildIsoOpeningBasis()`.

Переход между Plan/View, reload и HA state tick не должен менять center. Preview
и committed opening обязаны совпадать при той же геометрии и `flip_v`.
`hide_openings` продолжает скрывать только символ по существующему контракту.

## 9. Данные, compatibility, i18n, a11y и touch

**Данные и migration:** отсутствуют. `OpeningCfg.flip_v` сохраняет boolean
формат; read/write/export/import и backend schema не меняются. Обновление
`docs/CONFIG-COMPATIBILITY.md` не требуется.

**i18n:** новых строк нет. Существующая подпись «Открывается в другую сторону»
остаётся применимой; подробная геометрическая семантика фиксируется в guide.

**A11y:** DOM controls и accessible names не меняются. Исправление касается
только SVG-геометрии.

**Touch editor: parity, no new interaction.** Preview и committed symbol на
touch используют тот же center contract; жесты, hit targets, pinch, pan и
`pointercancel` не меняются.

## 10. Производительность и безопасность

Изменение остаётся pure arithmetic на уже разрешённом opening/host. Нельзя
добавлять поиск комнат, обход всех стен или allocation cache на каждый render.
HA-only state tick не должен пересчитывать wall index чаще текущего поведения.

Новых service calls, доверенных строк, HTML и persisted input нет. Existing
guards для orphan/invalid opening и actions остаются единственным authority.

## 11. Acceptance criteria

| AC | Требование | Доказательство |
|---|---|---|
| AC1 | Door/window/gate без `flip_v` находятся на центральной оси стен толщиной 1/15/100 cm для horizontal/vertical/diagonal room wall и partition | geometry unit + reviewed golden |
| AC2 | Перестановка room objects и reversed partition endpoints не меняют default-символ и направление gate; физически эквивалентные fixtures дают одинаковые metrics | unit permutation matrix + browser smoke |
| AC3 | `flip_v: true` у door/window детерминированно выравнивает видимую группу к противоположной локальной грани; window glass движется вместе со створками/дугами | unit + golden |
| AC4 | Gate при обоих значениях `flip_v` центрирован, но знак 10° поворота меняется; jambs остаются full-depth | unit + golden |
| AC5 | Preview, committed Flat/View, hosted Static и hidden Iso используют один center/flip contract | cross-render smoke + golden |
| AC6 | Passage, wall cut, tunnel, hitbox, lock badge, HA state/actions, Glow и sun остаются без изменений | targeted regression units/smokes |
| AC7 | Existing configs round-trip без migration; schema/backend diff отсутствует | diff review + existing config tests |
| AC8 | Typecheck, unit, build и три bundle-копии зелёные; оба changelog и normative docs обновлены | gates + diff review |

## 12. План автотестов

### 12.1. Unit

- `openingInnerFaceOffsetFromIndex` либо новый resolver: empty/one/shared room,
  room-order permutations, 1/15/100 cm и non-finite guards;
- partition resolver: original/reversed endpoints, horizontal/vertical/diagonal;
- `openingVisibleMetrics` и SVG geometry для door/window/gate, оба `flip_v`;
- window glass, leaves/arcs and gate angle; full-depth jamb endpoints;
- Iso basis center and flip direction;
- negative checks для passage, lock badge и hit metrics.

### 12.2. Browser smoke

- разместить door/window/gate в толстой room wall и independent partition;
- сравнить preview с committed View;
- переставить rooms в fixture и развернуть partition endpoints без видимого
  изменения;
- переключить `flip_v`, reload и Plan/View;
- проверить hosted Static и hidden Iso semantic geometry;
- убедиться, что lock/action и HA state продолжают работать.

### 12.3. Golden

Обновить/добавить semantic scenes:

- centered door/window/gate на толстой room wall, Light;
- те же типы на diagonal partition, Dark;
- door/window с `flip_v: true` и gate `false/true` рядом;
- hidden Iso parity для center и gate direction.

Golden semantic guard обязан до PNG сравнения проверить wall centerline,
visible-group center, jamb depth, `flip_v` и gate angle. Baseline принимается
только из reviewed Linux release artifact перед бетой; локальный accept
запрещён.

## 13. Mutation guards

| id | Что ломает | Что обязано покраснеть |
|---|---|---|
| `opening-symbol-default-uses-room-face` | возвращает room-order-dependent translation по умолчанию | AC1/AC2 unit + smoke |
| `opening-symbol-partition-follows-endpoints` | разворот partition endpoints меняет symbol side | AC2 permutation matrix |
| `opening-gate-flip-translates-leaves` | `flip_v` снова переносит ворота к грани | AC4 unit + golden guard |

Минимум основной мутант выполняется локально: clean test зелёный, возвращённый
дефект красный. Реестр mutation gate обновляется по действующему формату проекта.

## 14. Гейты реализации

Обязательные:

```text
npm run typecheck
npm test
npm run build
сверка dist / integration frontend / demo bundle
node scripts/smoke-select.mjs --base origin/dev --head HEAD
все выбранные opening/static/iso browser smokes
node scripts/mutation-gate.mjs --check
основной мутант #242
npm run golden:verify
node scripts/check-docs.mjs
```

Backend pytest не требуется, пока backend/schema не затронуты. Отдельный
performance benchmark не требуется; действующий geometry/performance smoke
прогоняется, если его выберет `smoke-select`.

## 15. Release-артефакты

User-visible implementation commit одновременно обновляет:

- `docs/CHANGELOG.md` и `docs/CHANGELOG.ru.md`;
- `docs/USER-GUIDE.ru.md` — default center и сохранённая семантика `flip_v`;
- `docs/WALL-THICKNESS.md` — centerline, full-depth jamb и render parity;
- `docs/ARCHITECTURE.md` и `docs/ISOMETRIC.md` — разделённые physical direction
  и visual translation;
- затронутые opening golden scenes/semantic guards.

Пользовательский docs screenshot не нужен: инструкция текстовая, а визуальное
доказательство даёт reviewed golden. Если реализация всё же изменит canonical
изображение guide, оно обновляется только workflow `Docs screenshots` и
`npm run docs:accept -- --reviewed --from=<run-id>`.

## 16. Откат

Одна code revision возвращает прежний face translation. Данные и migration для
отката не нужны: формат `flip_v` не меняется. Откат снова возвращает заявленный
визуальный дефект, но не повреждает сохранённые планы.

## 17. Риски

1. **Центрирование створки ломает jamb depth.** Митигация: separate metrics и
   AC1/AC4 с толщинами 1/15/100 cm.
2. **`flip_v` теряет сохранённое значение.** Митигация: round-trip не меняется,
   оба значения покрыты unit/golden.
3. **Gate становится визуально симметричным и теряет направление.** Митигация:
   angle использует side отдельно от translation, AC4.
4. **Flat исправлен, preview/Static/Iso расходятся.** Митигация: shared resolver
   и AC5.
5. **Новая канонизация меняет не только представление host.** Митигация:
   permutation matrix и явные negative checks cut/hit/light.

## 18. Принятые предположения (техническое, менять свободно)

1. Предпочтительно расширить resolved face отдельным полем visual offset либо
   передавать policy в общий renderer; точные имена типов и helper свободны.
2. Каноническая локальная ось может строиться из нормализованного opening angle
   или эквивалентного stable tangent; важен инвариант, а не конкретная формула.
3. Lock badge остаётся на существующей позиции: задача исправляет только
   видимый symbol opening и не меняет action affordance.
4. Existing golden можно заменить новой сценой, если прежняя была создана
   только для доказательства ошибочного inner-face offset.

**Не являются предположениями:** default center, ручное edge alignment только
для `flip_v: true` у door/window, centered gate с меняющимся 10° направлением,
full-depth jambs и parity всех четырёх render surfaces — решения владельца.