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

Код-ревью — issue #210, цикл r1

• Issue: https://github.com/Matysh/houseplan-card/issues/210
• ТЗ: docs/specs/210-fixed-floor-card.md (зелёное ревью, r2, docs/reviews/SPEC-REVIEW-210-r2.md)
• Диапазон: origin/dev..HEAD, единственный продуктовый коммит 6063eea («fix: pin card instances to configured spaces»), трейлеры Issue: #210 / User-Visible: yes на месте.
• Трек: обычный (не small/trivial) — лимит циклов 4.
• Вердикт: зелёный · цикл r1/4 · High: 0 · Medium: 0

Скоуп ревью

Проверялся диапазон git diff origin/dev...HEAD против принятого ТЗ: src/types.ts, src/initial-load.ts, src/houseplan-card.ts, src/editor.ts, src/styles.ts, src/i18n/{en,ru}.json, тесты (test/fixed-floor-contract.test.mjs, обновления test/initial-load.test.mjs, test/optional-space-model-contract.test.mjs), новый смок demo/smoke_fixed_floor.mjs, scripts/mutation-gate.mjs, три tracked bundle-копии и documentation-артефакты (docs/ARCHITECTURE.md, docs/TESTING.md, docs/USER-GUIDE{,.ru}.md, оба changelog, docs/specs/README.md, docs/images/screenshots.json). Backend (custom_components/**/*.py) и golden-baselines не тронуты — вне скоупа ТЗ, подтверждено git diff --stat.

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

Сессия свежая, без контекста ревью ТЗ (§6 PROCESS.md). Прочитаны docs/SCOPE.md, AGENTS.md, PROCESS.md целиком в этой сессии, тело issue #210 и все комментарии (включая рекомендацию по имплементации и хендофф автора), ТЗ 210-fixed-floor-card.md целиком и оба документа ревью ТЗ.

Код читался построчно по каждой зоне, названной в ТЗ §11 («Ожидаемые зоны изменений»), а не только по диффу:

1. Pure resolver (src/initial-load.ts, resolveFixedFloor) — проверена каждая ветка: absent → нет свойства; строка → пустая невалидна, иначе точное совпадение по spaceIds, без coercion; число → Number.isFinite, Number.isInteger, >= 0, индекс в диапазоне; любой другой typeof → invalid-type. Побайтово сверено, что resolveInitialSpace (legacy) не изменена ни на строку — из диффа src/initial-load.ts удалена только одна строка (сигнатура типа InitialSpaceSource, аддитивно расширенная), тело легаси-функции нетронуто.
2. Единая mutation boundary (src/houseplan-card.ts, _canCommitSpace/_commitSpace) — грепом this\._space\s*=(?!=) подтверждено ровно одно вхождение прямого присваивания во всём файле, и оно лежит внутри самого _commitSpace. Все 14 остальных мест, где раньше стояло this._space = … (слайд, hash, warm-viewport, setConfig, default_floor, создание/удаление пространства, backup-import, geometry drag, marker-dialog переходы), переведены на _commitSpace/_slideTo с проверкой возврата там, где переход мог быть отклонён. test/fixed-floor-contract.test.mjs держит этот инвариант структурным тестом по исходнику — деградация до regex-проверки признана достаточной, т.к. независимо от неё это же перепроверено прогоном мутанта (см. ниже).
3. Приоритет и pending-состояние — _fixedFloorState() до получения авторитетного ответа сервера (this._loadOk) переводит valid/out-of-range numeric index и valid/unknown-id string в pending, а не даёт немедленный valid/invalid: числовой индекс не может быть принят из непроверенного кэша (порядок пространств мог измениться), а unknown-id от кэша не должен стать терминальной ошибкой раньше свежей загрузки — ровно то, что требует ТЗ §7 и таблица рисков §14. Прочитано разбором, эмпирически не воспроизведено (см. «Чего не проверял»).
4. GUI editor (src/editor.ts) — синтетический токен __houseplan_yaml_floor_index__:<n> для числового YAML-значения: подтверждено, что _formData подставляет токен как текущее значение селекта, _schema включает его как единственный дополнительный вариант, а _valueChanged преобразует '' → delete config.floor и токен обратно в исходное число. Обратное преобразование опирается на контракт HA ha-selector-select («select эмитит ровно value выбранной опции») — это тот же admitted-риск, что спек-ревью r2 явно оставило коду-ревью («не тестировалось эмпирически»); в демо-стенде ha-form/ha-selector не подключены ни в одном существующем редакторном смоке (grep по demo/*.mjs не нашёл ни одного использования этих тегов кроме объявления в src/editor.ts), так что это ограничение стенда, а не упущение задачи — оценка риска ниже.
5. View/kiosk gating — navigationSpaces, .tabadd, _swipeZone, .kioskdots, _syncCycleTimer/_cycleTick — каждое условие читает this._hasFixedFloor симметрично на всех точках входа (рендер вкладок, свайп-зона, доты, install/re-sync таймера кружки).
6. Compatibility — default_floor путь (if (!this._hasFixedFloor && config.default_floor) this._commitSpace(config.default_floor, true)) и _savedNav/_saveNav (if (this._hasFixedFloor) return null/return;) читаны построчно: отсутствие floor не меняет ни один из легаси-путей.
7. Прочитаны все затронутые документы: docs/ARCHITECTURE.md, docs/TESTING.md, docs/USER-GUIDE.md/.ru.md, оба changelog, docs/specs/README.md — термины совпадают с ТЗ и друг с другом (Initial space / Стартовое пространство; Fixed space / Закреплённое пространство).

Гейты — что прогнано и с каким результатом

Гейт	Команда	Результат
Typecheck	npx tsc --noEmit	OK, без вывода
Unit	npm test	# tests 944 / pass 944 / fail 0
Build + bundle sync	npm run build && cmp dist/houseplan-card.js custom_components/houseplan/frontend/houseplan-card.js && cmp dist/houseplan-card.js demo/srv/assets/houseplan-card.js	OK, обе копии побайтово совпадают с dist/
Целевой смок (новый)	node demo/smoke_fixed_floor.mjs	OK, 14/14 фактов true
Регрессия навигации	node demo/smoke_nav_persist.mjs	OK, 7/7 фактов true
Регрессия kiosk	node demo/smoke_kiosk.mjs	OK, 12/12 фактов true
Blast-radius: warm remount (диф трогает _warmAdopt/_warmVpArmed)	node demo/smoke_warm_remount.mjs	OK, 14/14 фактов true
Blast-radius: пустое пространство (диф трогает тот же _space='' cleanup)	node demo/smoke_optional_space_model.mjs	OK, 9/9 фактов true
Docs-гейт	node scripts/check-docs.mjs	Documentation checks passed (7 files, 10 external links)
Whitespace	git diff origin/dev...HEAD --check	чисто, без вывода
Дисциплина «тест умеет падать» для нового guard-мутанта	node scripts/mutation-gate.mjs --id=fixed-floor-transition-guard-bypassed	ok чистый прогон + ok fixed-floor-transition-guard-bypassed: тест покраснел, как обязан — независимо подтверждено ревьюером, не только со слов автора

Не прогонялось и почему:

• Полный набор из 127 браузерных смоков — диф не задевает весь продукт; прогнаны названные в плане тестирования ТЗ (smoke_fixed_floor, smoke_nav_persist, smoke_kiosk) плюс два дополнительных смока по местам, которые диф трогает напрямую, но план тестирования не называл (warm remount, optional-space cleanup). Остальные touch/kiosk-смоки (smoke_kiosk_pan_lock, smoke_touch_tips, smoke_isometric_live_touch) не запускались: диф не меняет их код напрямую, а свайп/dots/cycle-путь, который он трогает, уже покрыт зелёным smoke_kiosk.mjs (swipeSwitches, noSwipeZoomed, dblTapResets, iconScaleWorks).
• npm run golden:verify — диф не меняет визуальную геометрию/раскладку; ошибочный и invalid-state рендерятся как обычный ha-card с DOM/computed assertions в смоке, что и обещало ТЗ §13 («отдельный visual golden не нужен»).
• python -m pytest tests_backend -q — ни один файл custom_components/houseplan/**/*.py не тронут (git diff --stat подтверждает).
• Performance-профили — не названы в AC и не затронуты (pure O(число пространств) резолвер, без per-frame/per-marker работы, ТЗ §14).
• Полный mutation-gate (node scripts/mutation-gate.mjs без --id) — дорогой прогон всего реестра, это предрелизный гейт (§8 PROCESS.md); прогнан только новый мутант задачи, который и требовалось доказать.

Находки

Ни одной High, ни одной Medium, ни одной Low после независимого чтения кода и прогона гейтов.

Проверка по AC1…AC12

AC	Как доказан	Вердикт
AC1	resolveFixedFloor unit-тест (test/initial-load.test.mjs, «distinguishes absence…») + smoke_fixed_floor.mjs idWinsEveryInitialSource (валидный ID выигрывает при одновременно выставленных hash и saved nav на другой этаж).	Автотест, тест умеет падать (сам pure-резолвер тривиально ломается изменением порядка веток — проверено чтением условий).
AC2	Unit-таблица невалидных числовых кейсов + spaceIds: ['1', 'other'], floor: '1' → id: '1', source: 'id' (строка не превращается в индекс) + smoke_fixed_floor.mjs indexUsesServerOrder.	Автотест.
AC3	Unit (empty-id, unknown-id, non-finite-index и т.д.) + smoke_fixed_floor.mjs invalidFailsVisibly (data-attr reason=unknown-id, role="alert", нет .stage). Stale-cache-ветка (pending) проверена чтением _fixedFloorState, не исполнением — см. «Чего не проверял».	Автотест + частично чтением.
AC4	smoke_fixed_floor.mjs держит одновременно смонтированными fixedId (ID) и fixedIndex (index) плюс позже ordinary при общем houseplan_card_nav_v1 — legacyCardStillRestoresNav подтверждает, что соседняя обычная карточка не пострадала.	Автотест.
AC5	fixedDoesNotWriteNav (после _saveNav() на fixed-карточке общий ключ остаётся тем, что был до неё) + структурный тест test/fixed-floor-contract.test.mjs (_savedNav/_saveNav гварды по regex) + legacyCardStillRestoresNav.	Автотест.
AC6	tabAndTransitionBlocked (_commitSpace(ids[1]) возвращает false), hashIgnored, fixedKioskCycleDisabled, fixedKioskSwipeDisabled + грепом подтверждено единственное прямое присваивание _space во всём файле (структурная гарантия, не только тест).	Автотест + чтением (инвентаризация присваиваний).
AC7	onlyFixedTab (ровно один таб, без .tabadd), fixedKioskDotsHidden. Права gear/editors не менялись (диф не трогает _canEdit) — проверено чтением: рендер вкладок и gear используют тот же _spaceModel()/_canEdit, что и раньше.	Автотест + чтением.
AC8	editorPreservesYamlIndex, editorClearDeletesKey + структурный тест на точные строки преобразования токена. Реальное поведение ha-selector-select при клике в браузере не воспроизведено — деманд стенда, см. выше.	Автотест (метод) + чтением контракта HA-селектора.
AC9	Чтением: setConfig сбрасывает _hashApplied/_navApplied/_warmVpArmed при fixedChanged и безусловно перевызывает _adoptInitialSpace; оба сетевых обработчика (_adoptStructuralResponses + WS update) вызывают _adoptInitialSpace(this._model, true) после каждого принятого server config, что переоценивает floor заново и переводит карточку в invalid при удалённом ID. smoke_fixed_floor.mjs remountStillFixed подтверждает воспроизведение после технического remount, но не «удалить пространство через gear своего же экземпляра и получить invalid по live-ответу сервера» — это разобрано чтением, не исполнением.	Автотест (частично) + явно «проверено чтением, не исполнением».
AC10	smoke_kiosk.mjs (не тронутый iconScaleWorks, dblTapResets, noSwipeZoomed и т.д. — регрессии нет) + smoke_nav_persist.mjs/smoke_warm_remount.mjs/smoke_optional_space_model.mjs зелёные на blast-radius, который диф трогает напрямую. Touch-специфичные смоки не перезапускались — их код не тронут.	Автотест.
AC11	git diff --stat подтверждает правки в обоих docs/CHANGELOG*.md со ссылкой на #210 в том же коммите, docs/USER-GUIDE{,.ru}.md объясняют floor vs default_floor, ID vs index, invalid-поведение; node scripts/check-docs.mjs зелёный.	Автотест (provenance/docs check) + чтением текста.
AC12	typecheck/test/build/named smokes зелёные (таблица выше); node scripts/mutation-gate.mjs --id=fixed-floor-transition-guard-bypassed независимо подтверждает, что чистый бандл проходит, а мутированный (guard инвертирован) красит smoke_fixed_floor.mjs — «умеет падать» доказано ревьюером, не только записью автора.	Автотест, независимо перепрогнан.

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

• Единственная mutation boundary реально единственная (грепом, не на слово автора): весь легаси-код навигации (_slideTo, hash-listener, setConfig/default_floor, warm-viewport adopt, создание/удаление пространства, geometry-drag commit, backup-import, marker-dialog cross-space переходы) переведён на _commitSpace/_canCommitSpace.
• pending-состояние корректно закрывает риск «кэш на миг покажет чужой индексированный этаж» из ТЗ §14: числовой индекс и cache-only unknown-id не финализируются до this._loadOk; остальные типы невалидности (пустая строка, дробное/отрицательное/бесконечное число, посторонний тип) не зависят от модели и репортятся немедленно.
• Легаси-путь (нет floor) не тронут ни строкой в resolveInitialSpace; расширение union-типа InitialSpaceSource аддитивно.
• GUI: удаление ключа при очистке и сохранение YAML-индекса при несвязанном редактировании реализованы так, как описывало исправление M1 в ТЗ; риск, прямо оставленный код-ревью спек-ревьюером, разобран и признан низким по причине, названной выше (харнесс не подключает ha-form вообще ни для одного существующего редакторного поля — это не новый риск задачи).
• Терминология синхронизирована: «Initial space / Стартовое пространство» и «Fixed space / Закреплённое пространство» одинаковы в GUI-строках, RU/EN guide и changelog.
• Коммит один, трейлеры Issue: #210 / User-Visible: yes на месте, оба changelog в нём же; сгенерированные копии бандла побайтово идентичны.

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

• Реальное поведение ha-selector-select в браузере при явном клике по пустому варианту — демо-стенд не подключает ha-form/ha-selector ни для одного существующего поля редактора (grep по demo/*.mjs не нашёл ни одного прецедента), поэтому и smoke_fixed_floor.mjs вызывает _valueChanged напрямую с сконструированным CustomEvent. Это ограничение стенда, не этой задачи; риск оценён как низкий по стандартному контракту HA select (эмитит ровно value выбранной опции).
• pending-рендер (data-fixed-floor-state="pending") не пойман ни одним тестом — существующий смок ждёт await wait(450) и updateComplete перед проверками, к этому моменту _loadOk уже true. Логика разобрана чтением (см. выше) и признана корректной, но живой DOM с role="status" в состоянии загрузки эмпирически не воспроизведён.
• AC9, сценарий «удалить закреплённое пространство через его же gear и дождаться invalid по live server response» — разобран чтением (_adoptInitialSpace вызывается после каждого принятого конфига), не исполнением: ни unit, ни browser-тест не воспроизводит именно эту последовательность (delete → save → WS update → invalid render).
• Полный набор 127 смоков, golden:verify, performance_smoke, pytest tests_backend — не запускались; обоснование в таблице гейтов выше, ни один из этих гейтов не относится к тронутым файлам или AC.
• Ручного тестирования в браузере HA (не demo-стенде) не было — вне процесса на этой стадии.

Итог

ТЗ выполнено без сужения и без расширения скоупа. Единая mutation boundary подтверждена структурно (один this._space = во всём файле) и мутационным прогоном, а не только описанием автора. Компатибильность легаси-пути подтверждена побайтовой неизменностью resolveInitialSpace. Два риска, явно вынесенных на код-ревью спек-ревьюером (ha-selector clear-контракт и stale-cache pending-ветка), разобраны чтением и признаны низкими без находок, требующих правки. Новых High/Medium/Low не найдено.

Вердикт: зелёный · цикл r1/4 · High: 0 · Medium: 0