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

# CODE-REVIEW-403-r1

- Issue: https://github.com/Matysh/houseplan-card/issues/403
- ТЗ: `docs/specs/403-area-relocation-safety.md` (ревью: `SPEC-REVIEW-403-r1.md` жёлтый → `SPEC-REVIEW-403-r2.md` зелёный)
- Диапазон: `origin/dev..HEAD`, SHA на момент вердикта — `9c4d07abe27de7d55b8fd78947dcf21579e8055a`
- Ветка: `issue/403-area-relocation-safety`
- Заход: r1 (первый код-ревью этой задачи; спек-ревью не тратит бюджет код-ревью, §7.2 PROCESS.md)
- Ребейз: ветка приведена к `dev` конвейером до ревью (024114fd → 9c4d07ab, +1 коммит `dev`) — разбор ниже полный, не по дельте, как того требует §7.2/§2.9

## Скоуп

Две находки одного аудита (`AUDIT-2026-08-31-v1700beta2.md`), одна поверхность —
`_syncAreaRelocations` в `src/houseplan-card.ts` и стек Undo позиций устройств:

- **C2 (High)**: отказ `houseplan/config/set` после успешного удаления layout
  ранее терял ручную позицию устройства без следа и без метки внимания.
- **M1 (Medium)**: переезд area одного устройства чистил весь стек
  Undo/Redo позиций, а не только записи переехавшего устройства.

Коммиты диапазона: `0d338b9c` (ТЗ), `caddeb08`/`6b515800` (документы спек-ревью,
кладутся конвейером), `94502d3d` (правка ТЗ по H1 спек-ревью r1),
`71bbc953` (**код**: `src/houseplan-card.ts`, `src/command-stack.ts`,
`test/command-stack.test.mjs`, `scripts/mutation-gate.mjs`,
`demo/smoke_area_relocation_safety.mjs` (новый), `demo/smoke_area_relocation.mjs`
(правка одной ветки), `docs/ARCHITECTURE.md`, `docs/CHANGELOG.md`/`.ru.md`,
бандл-копии), `9c4d07ab` (docs: пересъёмка скриншотов, `Issue: #403`,
`User-Visible: no`, обязательна т.к. `check-docs.mjs` считает отпечаток по всему
`src/**`).

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

### Гейты (все на SHA `9c4d07ab`)

| Гейт | Команда | Результат |
|---|---|---|
| typecheck | `npx tsc --noEmit` | 0 ошибок |
| unit | `npm test` | `pass 1697 · fail 0 · skipped 1` (`# tests 1698`) |
| build + сверка бандла | `npm run build`; `cmp dist/houseplan-card.js custom_components/houseplan/frontend/houseplan-card.js`; сверка `houseplan-assets.json` и списка файлов `houseplan-assets/`; затем `npm run bundle:sync` (пересборка + синхронизация трёх копий, включая `demo/srv/assets`) | все копии побайтово совпали **до** пересборки — в дереве уже лежит актуальный бандл; `git status --short` после пересборки пуст |
| docs-фингерпринт (обязателен, diff трогает `src/**`) | `node scripts/check-docs.mjs` | `Documentation checks passed (7 files, 10 external links)` |
| новый `any` | `node scripts/no-new-any.mjs --base origin/dev --head HEAD` | `Проверено добавленных строк: 52 в 2 файл(ах). Новых any нет` |
| провенанс коммитов/веток | `node scripts/process-gate.mjs --base origin/dev --head HEAD` | `коммитов 6, гейт пройден, предупреждений 0` (проверка 8 — статус issue — не запускалась, не нужна для ревью) |
| выбор смоков по diff | `node scripts/smoke-select.mjs --base origin/dev --head HEAD` | 22 «прямых совпадения» из 212; см. решение по каждому ниже |
| смок AC1–AC6 (новый) | `node demo/smoke_area_relocation_safety.mjs` | все 11 полей `true`, `OK` |
| смок AC7 (существующий #126) | `node demo/smoke_area_relocation.mjs` | все 18 полей `true`, `OK`, включая переименованное `failedConfigRestoredAndRetryable` |
| смок по прямому совпадению символа (`_devicePositionHistory`, `_persistDevicePlacement`) | `node demo/smoke_device_position_history.mjs` | все 32 поля `true`, `OK` |
| мутант 1 | `node scripts/mutation-gate.mjs --id=area-relocation-loses-position-on-refusal` | `тест покраснел, как обязан`, поймано 1/1 |
| мутант 2 | `node scripts/mutation-gate.mjs --id=area-relocation-clears-whole-history` | `тест покраснел, как обязан`, поймано 1/1 |

### Что НЕ прогонялось и почему

- **Остальные 19 «прямых совпадений» `smoke-select`** (`smoke_optimize_coordinate_canonicalization`,
  `smoke_room_resize`, `smoke_cold_view_toggle`, `smoke_cold_view_vacuum`,
  `smoke_help_affordance`, `smoke_junction_limits`, `smoke_lattice_write_barrier`,
  `smoke_linked_virtual_light`, `smoke_partition_openings`, `smoke_plan_upload_race`,
  `smoke_resize_audit_1550`, `smoke_resize_pointer_real_plan`, `smoke_save_race`,
  `smoke_space_tab_reorder`, `smoke_tap_ctx`, `smoke_v8_draft_write`,
  `smoke_virtual_light_toggle`, `smoke_ws_resilience`, `smoke_zero_wall_migration_unblocked`)
  — совпали только по одиночным широко используемым символам (`_showToast`,
  `_writeConfig`, `_reloadConfigOnly`), которые diff не переопределяет и вызывает
  теми же сигнатурами, что и раньше. Слабая связь по PROCESS.md §8 — повод
  посмотреть, не обязанность прогонять; ни один из этих смоков не касается
  area-relocation/undo-истории по теме. Полная матрица (212 смоков) —
  предрелизный гейт.
- **`npm run invariants -- --config <export>`** — диф трогает `layout` (позиции
  устройств), формально попадающий под правило PROCESS.md §доп. «трогает
  геометрию/ссылки на неё» (`marker.space`, `layout`). Решение: не запускать,
  явно. Причина: правка не вычисляет новые координаты/ключи и не производит
  новых записей толщины/рёбер — `_persistDevicePlacement(id, placement)` в
  ветке восстановления вызывается с тем же объектом `before`, захваченным
  `devicePlacement(this._layout, decision.id)` до удаления (`houseplan-card.ts:5180`),
  т.е. записывается обратно **байт-в-байт то же значение**, которое уже прошло
  инварианты до удаления; ключ (`deviceId`) не меняется. Сама логика инвариантов
  (`checkReferences`, `latticeProfile`) не тронута и продолжает проверяться
  юнит-тестами (`test/model-invariants.test.mjs` и смежные — в зелёном `npm test`
  выше). Ни `src/device-area-relocation.ts` (резолвер, вне скоупа ТЗ), ни
  wall/thickness/open_spans код не задеты.
- **`npm run golden:verify`** — ТЗ прямо утверждает «Видимого оформления не
  меняем» (раздел UX), и чтение диффа это подтверждает: нет правок CSS,
  разметки, `render()`; единственная пользовательская связь — переиспользуемый
  toast (`toast.pos_save_failed`, уже существующий ключ) и существующая метка
  внимания (`.newdot`, уже существующая разметка — её же проверяет наш смок
  через `fallbackEl?.querySelector('.newdot')`).
- **`python -m pytest tests_backend`** — diff не трогает `custom_components/**/*.py`.
- **Performance-профили** — не названы в AC; ТЗ утверждает «нет доп. циклов,
  подписок, сетевых вызовов сверх уже выполняемых `_syncAreaRelocations` /
  `_writeConfig`» — проверено чтением: цикл восстановления идёт по
  `deletedPlacements` (Map, максимум по числу решений `relocate` в одном
  проходе — уже ограничено существующим циклом `for (const decision of
  current.decisions)`), доп. запись конфига только при `restoreFailed.size > 0`
  (редкая ветка, не на каждый тик).

## Находки

Нет. High: 0, Medium: 0, Low: 0 (нет находок, требующих правки или списания записью).

Ниже — отдельно, для прозрачности разбора: одна проанализированная, но не
блокирующая деталь.

**Наблюдение (не находка).** Тройной отказ подряд — отказ `config/set`, затем
отказ восстановления `layout/update`, затем отказ второй, дополнительной
записи конфига с меткой внимания (`houseplan-card.ts:5273-5283`) — оставляет
локальное состояние (`_serverCfg.settings.new_device_ids` содержит id) впереди
серверного на один цикл: сама эта последняя запись не откатывается при
неудаче, в отличие от первой (`previousSnapshot`/`previousAttention`
restore чуть выше). Разобрано по коду, не воспроизведено намеренно (третий
отказ подряд у одного и того же устройства — вырожденный случай, вне
разумной проверки браузерным смоком). Самолечится: `_regSignature = ''` и
`_areaRelocationSyncKey = ''` сброшены в этой же ветке, так что следующий
authoritative rebuild пересчитает резолюцию заново и либо успешно допишет
attention на сервер (через обычный путь #126 — `nextAttention` включает
любой `committed` id независимо от исхода восстановления позиции), либо
покажет очередной toast. Тот же риск закрыт в разделе «Риски» ТЗ
(«Восстановление на сервере тоже может отказать... этот случай обязан
оставлять метку внимания» — оставляет, пусть и не гарантированно с первой
попытки). Не Low, потому что не расходится с контрактом ТЗ и не имеет
пользовательского воспроизводимого сценария потери данных — в худшем случае
лишний toast и задержка в один rebuild-тик.

## Разбор по AC

Все доказательства ниже — исполнением (браузерный смок `demo/smoke_area_relocation_safety.mjs`,
запущен выше), кроме отдельно помеченных «прочитано, не исполнено».

- **AC1** (отказ `config/set` не оставляет устройство без позиции: либо
  позиция на месте, либо `new_device_ids`). Доказано смоком:
  `rejectedWriteRestoresAfterDelete: true` (позиция восстановлена локально
  **и** на сервере — `layout/update` вызван после отказа `config/set`,
  порядок проверен по индексу вызова) и `failedRestoreLeavesAttention: true`
  (второй сценарий: отказывает и восстановление — устройство попадает в
  `new_device_ids` **и на сервере**, `.newdot` в DOM). Мутант
  `area-relocation-loses-position-on-refusal` красит именно этот смок при
  удалении восстановления — доказательство не тавтологично.
- **AC2** (успешный переезд работает как раньше). Доказано полным прогоном
  `demo/smoke_area_relocation.mjs` (18/18 `true`, включая
  `staleLayoutDeleted`, `provenanceAdvanced`, `attentionShown`) и
  `successfulRetry: true` в новом смоке (тот же сценарий после снятия
  задержки ответа сервера).
- **AC3** (delete-first: устаревшая точка не выигрывает, пока ответ сервера
  в пути). Доказано: `stalePointSuppressedWhilePending: true` — во время
  задержанного `config/set` `c._layout[relocatedId]` пуст, а устройство
  вычисляется в новой area, то есть старая точка не «воскресает» до
  подтверждения.
- **AC4** (ветка `conflict` подчиняется AC1). Доказано:
  `conflictRestoresBeforeRetry: true` — порядок вызовов
  restore(`layout/update`) → `config/get` (reload) → повторный
  `layout/delete` подтверждён по индексам в логе WS-вызовов, не только по
  финальному состоянию; `conflictEventuallyCompletes: true`. Код-путь
  проверен построчно: `await this._reloadConfigOnly(true)` (было `void`) —
  сделано намеренно awaited, чтобы блок восстановления attention ниже читал
  уже перезагруженный `this._settings`, а не гонялся с ним.
- **AC5** (переезд одного не гасит историю другого). Доказано:
  `unrelatedHistorySurvives: true`, `unrelatedUndoStillWorks: true`
  (Undo лампы после её drag остаётся рабочим после переезда другого
  устройства), `conflictKeepsUnrelatedHistory: true` в ветке conflict.
  Дополнительно юнит-тестом `test/command-stack.test.mjs` — `removeWhere`
  оставляет несвязанные undo/redo записи (`stack.undoName === 'lamp'`,
  `canRedo === true` после удаления записи `sensor`).
- **AC6** (записи переехавшего устройства удалены из истории). Доказано:
  `relocatedHistoryRemoved: true` (после удаления записи `undoName` уже не
  «Move relocating light», `canRedo` пуст). Юнит-тест то же самое проверяет
  на уровне `CommandStack.removeWhere` изолированно. Мутант
  `area-relocation-clears-whole-history` красит смок при возврате
  безусловного `clear()` — доказательство не тавтологично.
- **AC7** (существующее поведение #126 не сломано). Доказано полным зелёным
  прогоном `demo/smoke_area_relocation.mjs`; единственное изменённое
  утверждение (`failedConfigRetryable` → `failedConfigRestoredAndRetryable`)
  соответствует тексту ТЗ буквально — сверено построчно с
  `docs/specs/403-area-relocation-safety.md:174-180`.

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

- **Тип `DevicePlacement`/`deviceId`** — прочитано, не исполнено:
  `src/device-position-history.ts:1-20` подтверждает поля `x/y/s` у
  `DevicePlacement` и `deviceId/spaceId/placement` у `DevicePositionState`,
  что делает `removeWhere(({before, after}) => relocating.has(before.deviceId) ...)`
  типобезопасным (подтверждено также нулём ошибок `tsc --noEmit`).
- **Идентичность восстанавливаемого значения** — прочитано: `before` в цикле
  удаления (`houseplan-card.ts:5180`) берётся через `devicePlacement(this._layout, decision.id)`
  **до** вызова удаления, и то же самое значение (без пересчёта) передаётся в
  `_persistDevicePlacement(id, placement)` при восстановлении — ветка
  восстановления не может записать испорченные координаты.
- **i18n** — использованные ключи (`toast.pos_save_failed`, `toast.cfg_save_failed`,
  `toast.conflict`) уже существуют во всех четырёх словарях
  (`src/i18n/{en,ru,de,fr}.json`, сверено `grep`) — новых строк diff не
  добавляет, что соответствует разделу «i18n» ТЗ.
- **Трейлеры и changelog** — `71bbc953` несёт `Issue: #403` / `User-Visible: yes`
  и правит `docs/CHANGELOG.md` и `docs/CHANGELOG.ru.md` в том же коммите;
  текст точен относительно кода (сверено построчно — «restores the point
  before retrying, or marks the marker for attention if the restore also
  fails» соответствует именно реализованной логике, а не общей фразе).
  `9c4d07ab` (скриншоты) несёт `Issue: #403` / `User-Visible: no`, что верно
  — рендер не менялся.
- **`docs/ARCHITECTURE.md`** — абзац про area-relocation writer дополнен
  точным описанием восстановления и точечной инвалидации истории, без
  расхождений с кодом.
- **Одно число — один источник**: diff не добавляет и не меняет ни одной
  видимой пользователю величины (позиция маркера не отображается как число,
  Undo-кнопка — булев enabled/disabled без числа); неприменимо к этому diff.

## Унаследовано (без повторной проверки)

Не применимо — это первый код-ревью задачи (r1). Вердикт и находки
`SPEC-REVIEW-403-r1.md`/`SPEC-REVIEW-403-r2.md` относятся к другому этапу
(§7.2 PROCESS.md: цикл считается по этапу, спек-ревью не тратит бюджет
код-ревью и не подменяет его разбор) — их выводы не наследуются автоматически
в код-ревью, но диагноз C2/M1 и AC1–AC7 из зелёного `SPEC-REVIEW-403-r2.md`
использованы как контракт, против которого проверялся код в разделе «Разбор
по AC» выше.

## Вердикт

Зелёный. Обе находки аудита устранены и доказаны исполнением с
мутационным контролем (не тавтологичны); AC1–AC7 доказаны; гейты, обязательные
для объёма этой задачи, зелёные; трейлеры и changelog на месте.