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

CODE-REVIEW-126-r1

• Issue: #126 — «Смена area устройства в HA не переносит иконку в новую комнату, если позиция была сохранена»
• Этап: code (PROCESS.md §2.7)
• Заход: r1 (первый код-ревью, спек уже принят зелёным на r2 cfd9c0fd)
• Диапазон: origin/dev...HEAD, HEAD = 34b99b95 (продуктовый коммит 24251a25 + docs: refresh canonical screenshots)
• Вердикт: жёлтый · блокирующих циклов кода 1/4 · High: 1 · Medium: 1 → в задаче

Скоуп

Полный трек, новая подсистема: pure resolver src/device-area-relocation.ts, интеграция в houseplan-card.ts (persistence coordinator, _livePos, drag cancel/history clear), в space-card.ts/space-render.ts/space-geometry.ts (hosted Static, read-only projection), backend schema/import-export (marker_area_snapshot), правка семантики Save в Device dialog (roomTouched), доки, unit/backend/browser-smoke тесты.

Разбор полный (не по дельте) — это первый код-ревью раунд для #126.

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

Дешёвые гейты прогнаны на 34b99b95:

• npx tsc --noEmit — green;
• npm test — green, 1679/1680 pass, 1 known skip, 0 fail;
• npm run build — green;
• npm run bundle:sync — green, dist/custom_components/.../frontend/demo/srv/assets синхронны (git status после — чисто);
• node scripts/check-docs.mjs — green (docs-check запускался, т.к. диф трогает src/**; отпечаток скриншотов уже обновлён коммитом 34b99b95).

Инварианты модели (npm run invariants) не запускал: диф не трогает рёбра комнат, записи толщины, layout schema (x/y/s/k не менялись) или open_spans — resolver только читает существующие room.poly для point-in-room проверки, ничего геометрического не пишет.

Geometry/perf-профили не запускал — не названы в AC и не задеты диффом. python -m pytest tests_backend не гонял целиком, но точечно прочитал новые тесты в tests_backend/test_validation.py и tests_backend/test_ha_import_export.py — оба соответствуют §16 ТЗ и реально проверяют границы (bad binding, лишний ключ, MAX_MARKER_AREA_SNAPSHOT+1, cross-source drop, same-source preserve).

Отбор smoke. node scripts/smoke-select.mjs --base origin/dev --head HEAD дал 38 «прямых совпадений» и 37 «слабых связей» (общие символы _markerDialog, _model, NORM_W, _showToast, _writeConfig, _reloadConfigOnly, _snap и т.п. — задеты фоново из-за размера диффа в houseplan-card.ts/ houseplan-editor-runtime.ts, не из-за новой логики Area relocation). Прогнал целевую выборку по риску, не всю матрицу:

Smoke	Категория	Прогнан	Результат
demo/smoke_area_relocation.mjs	новый, AC1/2/3/7/9/11	да	OK (все 13 проверок true)
demo/smoke_subarea.mjs	слабая связь (_markerDialog), тематически прямое попадание — explicit room override между spaces	да	FAIL, 6/14
demo/smoke_marker_stay.mjs	слабая связь, «позиция не движется при смене комнаты» — тот же механизм записи room	да	OK, но см. находку H1 — тест не детектирует регрессию
demo/smoke_controls.mjs	слабая связь (_markerDialog)	да	OK (virtual binding, не задет)
demo/smoke_hidden_flag.mjs	не в списке инструмента, проверил вручную по тому же паттерну кода	да	OK (virtual binding, не задет)
demo/smoke_device_inbox.mjs	слабая связь, тематика #29 lifecycle, которую §4 ТЗ явно наследует	да	OK
demo/smoke_new_device.mjs	слабая связь, переиспользуемая метка new_device_ids	да	OK
demo/smoke_disabled_device.mjs	слабая связь, ha_disabled eligibility (§8 п.4 ТЗ)	да	OK
demo/smoke_readonly_cold_start.mjs	слабая связь (_canEdit), тематика read-only/cold-start, которую сам новый smoke не покрывает	да	OK
Остальные 30 «прямых» / 29 «слабых»	символы из типов (DevItem,Marker,Layout,SpaceModel) или несвязанные путём диффа строки (_cfgContentFingerprint,_reloadConfigOnly в контексте drag/upload/optimize, не Area)	нет	не прогонял — связь по имени, не по функции; риск низкий, задача их не касается

smoke_subarea.mjs — единственный найденный красный результат; воспроизвёл дважды и сверил с чистым origin/dev (отдельный git worktree, тот же Chromium) — там он проходит полностью. Регрессия принадлежит этой ветке.

npm run golden:verify не запускал — рендер/геометрия/стили/слои не меняются (маркер продолжает использовать существующий defaultPositions() путь и существующую красную точку, новый визуальный язык не вводится, это прямо зафиксировано в ТЗ §19 и подтверждается диффом — новых CSS/SVG путей нет).

Находки

H1 (High, блокирует) — Save диалога устройства без изменения комнаты больше не пишет явный room override; регрессия существующего smoke

Файл: src/houseplan-editor-runtime.ts:8192-8213 (_saveMarker), зеркально _markerDraft:12321-12330.

Новый флаг roomTouched — правильная и нужная часть задачи: раньше любое сохранение диалога устройства навсегда закрепляло эффективную HA-комнату как marker.room_id/marker.area (потому что dlg.room всегда непустой — он показывает текущее эффективное размещение), что при принятии #126 сделало бы открытие/сохранение диалога эквивалентным явному override и тихо уничтожало бы саму фичу (после первого же захода в Device editor устройство переставало бы следовать HA Area). Флаг это чинит: писать marker.room_id теперь можно только если dlg.roomTouched === true (реальный @change на #marker-room) либо маркер уже был явным раньше (previousExplicit).

Побочный эффект: единственное место в продуктовом коде, которое выставляет roomTouched: true, — это буквально обработчик @change <select id="marker-room"> (houseplan-editor-runtime.ts:12852-12855). Любой код (включая существующие тесты), который выставляет _markerDialog.room напрямую, минуя реальное DOM-событие, больше не производит запись явного room override — writePlacement остаётся false.

demo/smoke_subarea.mjs — существующий, не тронутый в этом диффе smoke — делает именно это: c._markerDialog = { ...c._markerDialog, room: 'garden#@garden-shed-a' } для реального HA-устройства d_light1 без marker, затем _saveMarker(). Раньше это был штатный (и единственный) способ протестировать «явный выбор комнаты в другом space побеждает HA Area» (#83/#317 контракт). Сейчас:

$ node demo/smoke_subarea.mjs
FAILED (6):
  - haMarkerSaved: expected true, got false
  - haRuntimePlacement: expected true, got false
  - crossSpaceCentered: expected true, got false
  - haReopenRoom: expected true, got false
  - invalidPairPlaceholder: expected true, got false
  - sameSpaceRoomSaved: expected true, got false

На чистом origin/dev (тот же Chromium, отдельный worktree) этот smoke проходит полностью (все 14 проверок true) — регрессия принадлежит этой ветке, не окружению.

Настоящий пользовательский путь (клик по <select>) действительно выставляет roomTouched: true вместе с room, так что для живого клика в браузере регрессии, видимо, нет — но:

1. это не доказано ни одним тестом с реальным DOM-событием (dispatchEvent) на #marker-room, только предположением по коду;
2. demo/smoke_marker_stay.mjs использует тот же паттерн прямой записи room для auto-устройства без marker (строка 16) и теперь тоже тестирует не то, что заявлено: stayAfterRoomChange: true проходит не потому что позиция осталась на месте при смене комнаты, а потому что смена комнаты стала no-op (запись marker.room_id не происходит вовсе) — тест зелёный, но перестал быть доказательством;
3. git diff --stat подтверждает, что ни smoke_subarea.mjs, ни smoke_marker_stay.mjs не редактировались в этом диффе — автор не перепрогнал существующую smoke-матрицу после изменения контракта _markerDialog.

Воспроизведение: node demo/smoke_subarea.mjs на 34b99b95 (см. вывод выше); node demo/smoke_subarea.mjs на origin/dev (worktree) для контраста — зелёный.

Что нужно: обновить существующие smoke (smoke_subarea.mjs, smoke_marker_stay.mjs и любые другие с тем же паттерном) так, чтобы они ставили roomTouched: true вместе с room при симуляции пользовательского выбора — это восстановит их как реальное доказательство приёмки #83/#317, а не тихо превратит их в vacuous pass. Альтернативно, если реальный сценарий сохранения room должен остаться доступным программно без roomTouched, нужно явное решение о контракте, а не побочный эффект нового поля.

Это находка внутри скоупа задачи (её же код это сломал) — правится в этой же ветке, без отдельного issue.

M1 (Medium, в скоупе) — Browser smoke не покрывает 4 из 8 сценариев, обязательных по §19 ТЗ

docs/specs/126-ha-area-marker-relocation.md §19 требует, чтобы demo/smoke_area_relocation.mjs (или эквивалент) «обязан проверить»: same-space (✓ есть), cross-space, standalone entity marker, explicit room override и composite exclusion, cold-start stale backfill, red badge (✓), hosted Static (✓), no-op при unchanged rebuild (✓).

Фактический файл покрывает 4 из 8: same-space drag, badge/acknowledgement, hosted Static read-only projection, no-double-write. Cross-space, standalone entity, explicit override/composite exclusion и cold-start backfill проверены только на уровне чистого resolver в test/device-area-relocation.test.mjs — это доказывает корректность формул, но не то, что _maybeRebuildDevices, _syncAreaRelocations, resolveHaBindingStatus, _openMarkerDialog/_saveMarker и cold-boot таймингов authoritative-флага действительно проводят эти случаи через реальный production bundle. Ни один из этих четырёх интеграционных путей не имеет альтернативного покрытия (в houseplan-card.ts вообще нет unit-тестов уровня класса — весь integration-контур тестируется только smoke).

Учитывая, что H1 — это как раз пример: логика, безупречная в pure-модуле, сломалась именно на стыке с Device dialog, которого чистый unit-тест не видит. Отсутствие cross-space/entity/explicit/cold-start smoke — это конкретно обязательство ТЗ (AC2 «unit + smoke», AC6 «unit + cold-start smoke»), которое сейчас закрыто только наполовину.

Что нужно: дополнить demo/smoke_area_relocation.mjs (или отдельный файл) четырьмя недостающими сценариями либо явно задокументировать в ТЗ/issue, почему интеграционное покрытие для них не требуется — молчаливое сужение недопустимо.

Находка в скоупе — правится в этой же ветке, без отдельного issue.

Что проверено и корректно (по коду, где явно указано «прочитано, не исполнено»)

• AC1/AC2 (resolver-формулы для same-space/cross-space). Прочитано построчно resolveDeviceAreaRelocations (src/device-area-relocation.ts:137-230) против §11/§12 ТЗ: порядок проверок (duplicate-Area guard → known-binding area-changed → backfill by saved point) соответствует §11 п.1-3 и §12 случаям 1-5 один в один; юнит-тесты (test/device-area-relocation.test.mjs) реально могут падать — проверил, что при обратной логике (sameRoom/staleRoom) падают ожидаемо. Cross-space путь через полный бандл — см. M1, не доказан.
• AC3 (read-only/static truth). space-render.ts:280-286 считает areaRelocationIds тем же чистым resolver'ом без побочных эффектов; markerPos() (space-geometry.ts:629) получает ignoreSaved и не обращается к записи/сети. Подтверждено smoke staticReadOnlyProjection + staticMadeNoWrites.
• AC4/AC5 (explicit wins, eligibility). registryFollowingBinding (device-area-relocation.ts:95-107) читает как отсекающий guard: virtual, unverified, explicit area/room, removed, binding mismatch, markerless entity (композитная light-group). Прочитано против §8 построчно, юнит-тест explicit placement, virtual markers and composite groups... реально различает 7 кейсов включая disabled (eligible per §8 п.4 — код специально НЕ фильтрует ha_disabled, только unverified; прочитано в паре с devices.ts:1203-1206, где ha_disabled маркер остаётся в rest[] с актуальным area из полного реестра — реактивация получит верную комнату).
• AC8 (rebind provenance). previous?.binding === binding guard — различие binding трактуется как новый baseline, не relocation; юнит-тест rebind establishes a new baseline... бьётся именно на этом.
• AC9 (fail-safe, delete-first). _syncAreaRelocations (houseplan-card.ts:5137-5251): цикл await this._persistDevicePlacement(id, null) до формирования nextSnapshot/nextAttention; при неудаче удаления deleteFailed=true → _areaRelocationSyncKey='' для ретрая на следующий authoritative pass; при неудаче записи конфига — восстановление marker_area_snapshot/new_device_ids только если конкурентная мутация не успела заменить именно эту попытку (сверка по contentFingerprint). Подтверждено smoke (failedConfigRetryable, configRetrySucceeded) — сценарий реально симулирует отказ houseplan/config/set через перехват hass.callWS и проверяет ретрай на следующий window.__setRegistryArea.
• AC10 (no Undo). При _areaRelocationIds.size вызывается _cancelDeviceDrag() и _devicePositionHistory.clear() (houseplan-card.ts:5058-5059) на каждый authoritative rebuild, в котором есть relocation — до применения новых позиций. Прочитано, не покрыто отдельным unit/smoke именно на срез «Undo не воскрешает» — риск невысокий, т.к. .clear() детерминированно опустошает стек, но формально AC10 просит «history unit/source contract», а такого точечного теста нет (не поднимаю до Medium: это самый безопасный из недостающих кейсов — .clear() тривиален по семантике и уже покрыт существующими unit-тестами device-position-history.ts).
• AC12 (compatibility). custom_components/houseplan/validation.py:1936-1949 — схема соответствует §16 (bounded map, _NONEMPTY_TEXT, regex на binding, MAX_MARKER_AREA_SNAPSHOT); import_export.py:1727 роняет marker_area_snapshot вместе с known_devices/new_device_ids при чужом источнике — совпадает с §16 «Full import из другого source удаляет...». Backend-тесты реально проверяют оба направления (same-source preserve, cross-source drop) и границы схемы (5 негативных кейсов + предел+1). scripts/config-field-registry.mjs и docs/CONFIG-COMPATIBILITY.md обновлены в одном духе.
• Save-диалог, writePlacement/previousExplicit (кроме регрессии H1). Логика сохранения существующего явного override при повторном Save без касания комнаты (previousExplicit && !dlg.roomTouched → взять значения из previousMarker, не из dlg.room) корректна и необходима для §15 ТЗ («При Save обязан заново разрешить binding... stale room draft не может вернуть marker в прежнюю комнату»). Именно это подтверждает roomDraftRefreshed/noStaleExplicitOverride в новом smoke.
• Doc/gate discipline. Оба changelog правлены в том же коммите, что и продуктовый код (24251a25, User-Visible: yes); трейлеры Issue/ User-Visible на месте на обоих коммитах; docs/CONFIG-COMPATIBILITY.md, docs/ARCHITECTURE.md, docs/FILTERING.md, EN/RU USER-GUIDE, docs/TESTING.md обновлены по существу, без выдумывания несуществующей терминологии (используют «Area», «House Plan room», «red attention dot» — термины уже приняты в USER-GUIDE.ru.md/en).
• Одно число — один источник. Диф не вводит новую видимую пользователю величину, дублируемую в двух местах (нет второго badge/подписи/числа); единственная воспроизведённая сущность — булево «отмечено вниманием», которое явно переиспользует существующий new_device_ids (_newIds getter объединяет settings.new_device_ids и _areaRelocationIds в одно множество, houseplan-card.ts:5254-5257) — один источник для чтения, один для записи (после коммита _areaRelocationIds пусто, new_device_ids содержит id). Регрессии по классу #234/#233 не вижу.

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

• Полную smoke-матрицу (210 файлов) — не запускал, обоснование выбора выше по выводу smoke-select.mjs; 30 «прямых»/29 «слабых» совпадений не прогнаны — риск по существу (не по имени символа) оценил как низкий, диф их не затрагивает функционально.
• npm run golden:verify, npm run invariants, performance-профили, python -m pytest tests_backend -q целиком — обоснование выше (визуальный язык/геометрия/производительность не меняются; backend прочитан точечно, но полный прогон питон-сьюта не выполнял).
• Реальный DOM dispatchEvent('change') по #marker-room для верификации, что живой пользовательский клик действительно не задет H1, — сделал вывод чтением обработчика (houseplan-editor-runtime.ts:12852-12855), не исполнением; учитывая, что именно предположение по коду и подвело в этой же задаче, эту конкретную гипотезу стоит подтвердить исполнением при доработке.
• Мобильный/touch рендер и kiosk-режим для самой Area-релокации специально — косвенно закрыто тем, что renderSpaceStatic (used by hosted Static/kiosk) и interactive card используют один и тот же resolver и одну и ту же markerPos/_livePos точку входа; отдельного touch-smoke для #126 не запускал, т.к. в §15 ТЗ явно сказано «View и kiosk на touch обязаны показать то же положение, что desktop View» без нового UI на touch.