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

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

- **Issue:** https://github.com/Matysh/houseplan-card/issues/210
- **ТЗ:** `docs/specs/210-fixed-floor-card.md` (коммит `0bd6094`, ветка
  `issue/210-fixed-floor`)
- **Трек:** обычный (аналитика явно исключила `small`/`trivial`; сложность
  6/10, риск 6/10, метка `small` на issue отсутствует)
- **Вердикт:** жёлтый · цикл r1/4 · High: 0 · Medium: 1 (в скоупе задачи) ·
  Low: 1

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

Проверялось ТЗ `docs/specs/210-fixed-floor-card.md` как артефакт этапа
`S4-spec-review`: обязательные разделы §7.1 PROCESS.md, однозначность и
доказуемость AC1…AC12, соответствие `docs/SCOPE.md`, `docs/UX-MODES.md`,
`docs/TOUCH-SUPPORT.md`, `docs/CONFIG-COMPATIBILITY.md` и
`docs/USER-GUIDE.ru.md`, а также фактическая проверка причинных утверждений
ТЗ (§3, §7) против текущей реализации в `src/initial-load.ts`,
`src/houseplan-card.ts` и `src/editor.ts` — то есть не пересказ автора, а
независимое чтение кода, который ТЗ описывает как «до». Продуктового кода по
#210 не существует (issue в `S4-spec-review`, диапазон коммитов веток —
только документация), поэтому гейты §8 PROCESS.md к этому циклу неприменимы.

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

1. Прочитаны `docs/SCOPE.md`, `AGENTS.md`, `PROCESS.md` целиком.
2. Прочитано тело issue #210 и все три комментария (аналитика,
   «взял в работу», «ТЗ готово»).
3. Прочитан файл ТЗ `210-fixed-floor-card.md` целиком (327 строк).
4. Прочитаны `docs/CONFIG-COMPATIBILITY.md` и `docs/UX-MODES.md` целиком, а
   также `docs/TOUCH-SUPPORT.md` целиком — как канонические документы
   затронутых подсистем (навигация, конфигурация, touch/kiosk-контракт).
5. Прочитан `docs/USER-GUIDE.ru.md` в месте, описывающем `default_floor` и
   несколько карточек (строки 122-125, 1327-1339) — подтверждает, что именно
   это описание текущего (ошибочного) поведения ТЗ обязано заменить/уточнить
   в release-артефактах (§15 ТЗ это учитывает).
6. Независимо сверены причинные утверждения ТЗ §3/§7 с кодом:
   - `resolveInitialSpace()` (`src/initial-load.ts:27-42`) — подтверждён
     буквальный холодный приоритет `hash → current → saved → default → first`;
   - общий ключ `houseplan_card_nav_v1` (`LS_NAV`, `src/houseplan-card.ts:482`,
     `_savedNav`/`_saveNav` :5866-5881) — подтверждён как единственный,
     без per-instance scoping;
   - `_warmAdoptViewport()` (`src/houseplan-card.ts:2625-2644`) — подтверждено
     восстановление пространства из viewport-memo поверх saved/default;
   - множественные прямые присваивания `this._space = …` вне единой точки
     (grep дал >15 мест: :1150, :1188, :1820, :2430, :2635, :2925, :3179,
     :13522, :13531, :13573, :13644, :14297, :16459, :16487 и др.) —
     подтверждает риск «новый guard пропустит прямое `_space =`» из таблицы
     §14 ТЗ как реальный, а не гипотетический;
   - kiosk swipe (`src/houseplan-card.ts:5405`) и cycle (`:1191-1193`,
     `:1951-1953`) — подтверждены как условные пути, которые можно
     дополнительно закрыть проверкой fixed-authority без переписывания их
     структуры;
   - GUI editor (`src/editor.ts:42-73`) — подтверждён текущий паттерн
     `default_floor` (dropdown со stable ID при доступных `spaces`, textbox
     fallback при недоступности WS) как прямой прецедент для нового поля
     `floor`, на который ссылается §6.2 ТЗ.
7. Проверено соответствие `docs/SCOPE.md`: задача закрывает возможность
   «Home admin» держать несколько выделенных fullscreen/kiosk-панелей по
   этажам без взаимного вмешательства навигации — часть уже закрытых J1/J6
   («live spatial overview», «keep the plan true», несколько карточек с
   собственным стартовым этажом уже документировано как поддерживаемый
   сценарий в `USER-GUIDE.ru.md:1327-1332`); задача не расширяет и не
   нарушает ни одну строку scope.
8. Код не запускался, гейты не прогонялись — на этапе ревью ТЗ продуктового
   кода нет.

## Находки

### M1 — контракт не говорит явно, что очистка `floor` в GUI должна удалять ключ, а не записывать невалидную пустую строку

**Файл:** `docs/specs/210-fixed-floor-card.md:101-111` (§6.2), в противоречии
с `:92` (§6.1, п.3) и AC8 (`:239`)

§6.1 п.3 явно объявляет пустую строку невалидным значением `floor` — при её
наличии в конфиге карточка обязана уйти в fail-closed error state (§9, AC3:
«Unknown ID и все невалидные типы/числа fail closed… без чужого
плана/fallback»). При этом §6.2 описывает GUI-контроль как «dropdown со
stable ID и пустым вариантом «не закреплять»», а AC8 требует, чтобы GUI «умел
очистить `floor`» — но ни §6.2, ни §7, ни AC8 не говорят явно, **что именно**
происходит в конфиге при выборе этого пустого варианта: должен ли
`floor`-ключ удаляться из объекта конфигурации целиком (что вернёт legacy
navigation, как того требует «не закреплять»), или контрол просто запишет
`floor: ''` (что по буквальной формулировке §6.1 п.3 является невалидным
значением и включит error state).

Это не абстрактный риск: `_valueChanged()` в текущем `src/editor.ts:99-104`
делает `{ ...this._config, ...ev.detail.value }` — то есть механически
переносит то, что вернул `ha-form`, без специальной зачистки пустых полей;
никакого существующего прецедента «optional selector с явной очисткой ключа»
в этом редакторе сейчас нет (`default_floor` never being cleared — у него нет
пустого варианта). Если реализация просто повторит текущий паттерн, самое
частое и ожидаемое админом действие — «я больше не хочу закреплять этот
экран» — приведёт не к обычной навигации, а к видимой ошибке ровно того типа,
который вся задача обязана устранить.

**Почему это Medium, а не High:** ни один AC не сформулирован неверно и не
описывает ошибочное поведение как целевое — пробел чисто в определении, какую
именно мутацию конфигурации должен произвести один конкретный UI-контрол;
это устраняется одной уточняющей фразой в тексте ТЗ, не меняя ни архитектуру,
ни один AC, ни скоуп. Находка в скоупе собственного AC8 задачи — правится в
текущем ТЗ.

**Требуется:** явно зафиксировать в §6.2 (и, для симметрии, в §16 как принятое
техническое решение), что выбор пустого варианта удаляет ключ `floor` из
конфигурации целиком, а не заменяет его на пустую строку/`null` — то есть
GUI обязан обеспечивать инвариант §6.1 «отсутствует, только если свойства нет
в конфиге» на собственном пути записи, а не полагаться на то, что позже это
поле случайно совпадёт с одним из уже описанных invalid-путей.

### L1 — обязательный раздел «i18n» присутствует по содержанию, но не оформлен отдельным заголовком

**Файл:** `docs/specs/210-fixed-floor-card.md` (содержание разбросано по
§6.2 — подписи полей GUI на двух языках, и §9 — требования к тексту ошибки)

PROCESS.md §7.1 перечисляет i18n отдельным обязательным разделом ТЗ. Формально
такого заголовка в документе нет: русские/английские подписи полей GUI даны
прямой строкой в §6.2 («Fixed space / Закреплённое пространство», «Initial
space / Стартовое пространство»), а требования к содержимому error-текста —
в §9, без перечисления конкретных ключей `en.json`/`ru.json`. Это не создаёт
двусмысленности для реализации (именование ключей — техническая деталь,
которую агенты решают сами, PROCESS.md §7.1) и не блокирует ни один AC, но
формально отклоняется от структуры, которую требует процесс, и усложняет
беглую проверку «оба языка учтены» без чтения всего документа целиком.

Не блокирует. Снимается на решение автора — либо выделить короткий
одноимённый раздел (даже как ссылку на уже написанные §6.2/§9), либо оставить
как есть с этой пометкой в документе ревью.

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

- **Причина дефекта (§3)** — построчно подтверждена кодом: единый
  `houseplan_card_nav_v1`, приоритет `resolveInitialSpace()`, влияние
  `_warmAdoptViewport()`; это не пересказанная, а самостоятельно
  верифицированная причинно-следственная цепочка.
- **Обязательные разделы §7.1 PROCESS.md** — все присутствуют по содержанию:
  сценарий (§1), что видит пользователь до/после (§2, без терминов
  реализации), проблема (§3), скоуп/не-скоуп (§4/§5), контракт поведения
  (§6-§9), UX (§8), данные/совместимость/безопасность (§10), архитектурный
  контракт (§11), AC1…AC12 с доказательством для каждого (§12), план
  автотестов (§13), риски и откат (§14), release-артефакты (§15).
- **Продуктовая часть контракта не содана как догадка**: аналитика (комментарий
  владельца) прямо сказала «продуктовых вопросов по заданному контракту нет»,
  и §16 «Принятые предположения» корректно отделяет технические решения (7
  пунктов) от уже отвеченного владельцем продуктового контракта, помечая
  каждое как решение автора, открытое для оспаривания ревьюером — ни одно не
  подано как установленный факт без основания.
- **Предположение №1 (§16)** — расширение «floor выше всех источников
  навигации» на URL hash, хотя исходная формулировка issue перечисляла только
  saved nav/tabs/swipe/cycle — признано обоснованным: это техническая деталь,
  которую issue прямо разрешает решать на этапе ревью («Technical details are
  assumed and may change freely»), и оно последовательно с продуктовым
  утверждением «After: … не участвует в общей истории выбора этажей».
- **Риск «новый guard пропустит прямое `_space =`»** (§14 таблицы) —
  подтверждён как реальный, не гипотетический: код действительно содержит
  более 15 разрозненных прямых присваиваний `this._space =`; выбранная мера
  («инвентаризация всех assignments + единая mutation boundary», §11) —
  адекватный ответ.
- **Соответствие `docs/TOUCH-SUPPORT.md`** — §8 несёт буквальный канонический
  тег `Touch editor: best effort / intentionally degraded.`, требуемый
  «Documentation rule»; удаление kiosk swipe/cycle/dots для fixed-инстанса не
  нарушает гарантию «View/kiosk — fully supported touch surface», поскольку
  pan/pinch/zoom и безопасные действия текущего пространства прямо сохранены,
  а «переключение между этажами» перестаёт быть релевантным действием там,
  где второго этажа для переключения не предусмотрено конфигурацией.
- **Соответствие `docs/UX-MODES.md`** — правило «Header в View: только
  вкладки пространств, счётчик устройств, zoom-кластер» и принцип «редакторы
  не просачиваются в View» не нарушаются: §8 ТЗ убирает лишние
  навигационные элементы (другие вкладки, Add, kiosk dots), но не трогает
  editors/gear текущего пространства и не вводит новых интерактивных
  поверхностей.
- **`docs/CONFIG-COMPATIBILITY.md`** — корректно не упомянут как файл для
  правки: `floor` — Lovelace card config, а не персистентное серверное поле
  House Plan (§10 ТЗ), и уже существующие card-level опции (`default_floor`,
  `cycle`, `kiosk`) в этом реестре также не зарегистрированы — задача не
  создаёт исключения из этого паттерна.
- **AC1…AC12** — каждый однозначен и указывает способ доказательства
  (unit/browser smoke/DOM assertions/config refresh test), включая AC12
  («новый guard доказан failing-before-fix») — это прямое выполнение
  требования code review «тест умеет падать» уже на этапе постановки ТЗ.
- **Совместимость (§10, §16 п.6)** — отсутствие `floor` не меняет ни один
  существующий путь навигации; `default_floor` остаётся ровно тем полем,
  которое описывает действующий `USER-GUIDE.ru.md`; невалидный `floor` прямо
  не откатывается на `default_floor`, что снимает риск «молча показать чужой
  этаж» — именно то, из-за чего заведён issue.
- **Откат (§14)** — единый revert без миграции хранилища; отсутствие поля
  на старом фронтенде корректно описано как «fixed guarantee отсутствует», а
  не как повреждение данных.

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

- **Фактическая работоспособность будущей реализации** — на этапе ревью ТЗ
  продуктового кода не существует; проверка ограничена текстом ТЗ и текущим
  («до») кодом.
- **`ha-form`/`ha-selector` внутреннее поведение при очистке optional select**
  не тестировалось эмпирически (нет собранной карточки с новым полем) — M1
  сформулирована как пробел в тексте ТЗ, а не как утверждение о конкретном
  поведении HA-компонента.
- **`demo/smoke_fixed_floor.mjs`, `smoke_nav_persist.mjs`, `smoke_kiosk.mjs`**
  не запускались — файл нового смока пока не существует (создаётся в
  реализации), а существующие смоки не относятся к этому циклу (нет кода для
  проверки).
- Гейты `typecheck`/`test`/`build`/smoke/golden не прогонялись — на этапе
  ревью ТЗ раздел неприменим (PROCESS.md §8: гейты код-ревью, не ТЗ-ревью).

## Итог

Блокирующих находок нет. Единственный Medium (M1) устраняется точечной
правкой текста §6.2 (и, по желанию автора, зеркальным пунктом в §16) — без
изменения архитектуры, скоупа или какого-либо AC. Low (L1) — на решение
автора, можно снять с запиской без правки. Вердикт — жёлтый, возврат автору
в рамках текущего issue.