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

# CODE-REVIEW-377-r1

- Issue: https://github.com/Matysh/houseplan-card/issues/377
- Заход: r1 (первый прогон код-ревью; предыдущая попытка `S7` вернулась в `S6`
  из-за конфликта ребейза до того, как код кто-либо читал — цикл не
  расходовался, см. комментарий владельца от 18:17)
- Ветка: `issue/377-decor-default-persist`, ребейзнута на `origin/dev` с уже
  смерженным #375
- SHA материала ревью: `2edaf1adac60f9939b836da87f5f1f549dab2548`
  (`git rev-parse HEAD` непосредственно перед подведением итогов)
- Диапазон: `git diff origin/dev...HEAD` — 33 файла, +789/-468

## Скоуп

Персист серверного ключа `settings.decor_default_style` (цвет/стиль декора
«по умолчанию» из тулбара Background-редактора, #360): переживает
перезагрузку, общий для всех редакторов плана. Три поверхности: схема
(`validation.py`), инициализация (`houseplan-card.ts`), запись
(`houseplan-editor-runtime.ts`) — ровно то, что называла аналитика и ТЗ
(SPEC-REVIEW-377-r2, зелёный).

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

Полный разбор (первый заход код-ревью для этой задачи; §2.10 неприменим).
Читал построчно: `src/editors/decor/geometry.ts` (новые
`decorStyleFromSettings`/`decorStyleToSettings`), `src/houseplan-card.ts`
(`_seedDecorStyle` и оба места вызова), `src/houseplan-editor-runtime.ts`
(`_updateDecorStyle`/`_persistDecorStyle`, все шесть UI-точек изменения
стиля), `custom_components/houseplan/validation.py` (схема),
`custom_components/houseplan/import_export.py` (путь `settings` при полном
импорте — подтверждает AC6 сверх юнита), тесты (`test/decor-style-persist.test.mjs`,
`tests_backend/test_validation.py`, `demo/smoke_decor_default_persist.mjs`),
изменения в `scripts/mutation-gate.mjs`, `test/color-picker.test.mjs`, оба
changelog и оба USER-GUIDE.

### Гейты — прогнал сам (зелёного Validate на этом SHA нет)

| Гейт | Команда | Результат |
|---|---|---|
| Typecheck | `npx tsc --noEmit` | чисто |
| Юниты | `npm test` | 1560 pass / 0 fail / 1 skipped (совпадает с заявкой автора) |
| Сборка | `npm run build` | ok, 14.5s |
| Синхронизация бандлов | `npm run bundle:sync` | ok; `git status --porcelain` после — пусто (три копии дерева байт-в-байт совпадают с закоммиченными) |
| Бюджет | `npm run bundle:budget` | initial View 276 221 Б / 300 000 (запас 23 779 Б) — проходит; отличие от заявленных автором 276 059 Б в пределах шума нединамического build (не влияет на вердикт) |
| Доки | `node scripts/check-docs.mjs` | «Documentation checks passed (7 files, 10 external links)» — diff трогает `src/**`, гейт обязателен и зелёный |
| Backend (чистое подмножество) | `python -m pytest tests_backend -q --ignore=tests_backend/test_coordinate_canonicalization.py` (после `pip install pytest voluptuous`, в базовом окружении ревьюера их не было) | 235 passed, 1 skipped — совпадает с заявкой автора байт-в-байт. `test_coordinate_canonicalization.py` падает на `ModuleNotFoundError: homeassistant` при коллекции (не `test_ha_*.py`, поэтому `conftest.py` его не глушит) — это существующий пробел окружения, не связан с #377, полный HA-harness — дело CI |
| Единственный источник числа | `node --test test/single-source-numbers.test.mjs` | 3/3 pass; смысловая часть — см. ниже |
| Мутанты (только новые, точечно `--id=`) | `node scripts/mutation-gate.mjs --id=decor-default-style-seed-cut` и `--id=decor-default-style-debounce-cut` | оба «поймано 1 из 1» — тест умеет падать |

Полный `mutation-gate.mjs` без `--id=` не гонял: это полная матрица всех
мутантов проекта (несоразмерно точечной правке), к тому же в этом окружении
падает на несвязанном backend-guard'е (тот же отсутствующий `homeassistant`).
Точечный `--id=` — правильный инструмент здесь.

### Смоки — выбор через `scripts/smoke-select.mjs --base origin/dev --head HEAD`

Инструмент дал 7 «прямых совпадений» и 13 «слабых связей» (все — по одному
имени `_saveConfig`, geometry/wall-thickness в диффе не тронуты).

Прогнал все 7 прямых совпадений — все OK:
`smoke_decor_default_persist` (новый, AC4/AC5), `smoke_bg_color`,
`smoke_color_picker`, `smoke_decor`, `smoke_dialog_zombie`, `smoke_furniture`,
`smoke_general_settings`.

Из слабых связей прогнал `smoke_config_writer` (тот же, что заявлен автором) —
OK. Остальные 12 слабых связей не гонял: диф не трогает геометрию/стены/
толщину, разделяют с диффом только имя `_saveConfig`, чей вызывающий код в
затронутых местах не менялся по поведению (только маршрутизация через
`_updateDecorStyle`). `npm run invariants` не требовался — diff не трогает
рёбра комнат, `layout`, `marker.space`, `open_spans` или записи толщины.

`npm run golden:verify` не гонял: ТЗ прямо утверждает «видимых изменений
нет», и это подтверждается кодом — `_decorStyle` управляет только дефолтом
для НОВЫХ объектов декора/мебели (`_renderDecorLayer` draft-превью,
`_renderFurniturePlacementPreview`), View эти пути не рендерит, а
`imageSha256` всех эталонных скриншотов, кроме одного, не изменился;
единственное расхождение (`06-device-display-preview.png`, 326512→326513
байт) — разница в 1 байт кодирования PNG, не связанная с decor-путём
скриншота и не относящаяся к этой правке по содержанию сцены; `check-docs`
(сверяет `sourceFingerprint`) зелёный.

## Находки

Нет ни одной High или Medium-находки.

**Low (снята без правки).** `_updateDecorStyle` заводит собственный
`window.setTimeout(…, 1000)` (`houseplan-editor-runtime.ts:9403-9411`) и не
чистит его в `disconnectedCallback` карты, в отличие от штатного
`_saveConfigDebounced.flush()` (`houseplan-card.ts:2638`, «never leave an edit
unsent on teardown»). Разобрано по коду (не исполнением): в реальности потерю
данных это создаёт только при закрытии/перезагрузке вкладки строго внутри
окна 1 с после последнего изменения цвета — при обычном пересоздании дерева
Lovelace (тот случай, для которого существует `disconnectedCallback`) таймер
переживает как обычный JS-таймер и запись всё равно долетает, просто позже.
Цена ошибки — вернуться к прежде выбранному цвету, ценность правки в рамках
этой задачи не оправдана: снимаю с записью, правки не требую.

## Проверка AC

- **AC1** (pytest, валидация): доказано исполнением —
  `tests_backend/test_validation.py::test_decor_default_style_setting`,
  10 мусорных вариантов + `"solid"` вместо объекта, все `pytest.raises`.
  Прогнал сам, 235/0 в подмножестве, включая этот тест.
- **AC2** (юнит фронта, мердж): доказано исполнением —
  `test/decor-style-persist.test.mjs` («all six fields cross the boundary»,
  частичный ключ, мусорные поля). Мутант `decor-default-style-seed-cut`
  ловит вырезание вызова — 1/1.
- **AC3** (юнит фронта, легаси): доказано исполнением — тот же файл,
  `undefined/null/'x'/7` → `DEFAULT_DECOR_STYLE`.
- **AC4** (смок, одна запись после дебаунса + сброс к дефолту без ключа):
  доказано исполнением — `demo/smoke_decor_default_persist.mjs`, прогнал сам,
  OK. Мутант `decor-default-style-debounce-cut` (дебаунс → 0 мс) ловится —
  1/1, подтверждает, что смок действительно проверяет окно, а не просто
  наличие записи.
- **AC5** (смок, посев новой карты из ключа): доказано исполнением — тот же
  смок, `seeded` (частичный ключ наследует остальные поля дефолта).
- **AC6** (round-trip импорт/экспорт): доказано исполнением на уровне схемы
  (`test_decor_default_style_setting`, byte-identical) плюс разобрано
  чтением, не исполнением — `import_export.py:1661-1669`: для non-same-source
  импорта из `settings` вычищаются только `known_devices`/`new_device_ids`,
  `decor_default_style` не в списке и проходит насквозь; `config = CONFIG_SCHEMA(config)`
  применяет ту же схему, что и юнит. Отдельного юнита самого
  `import_export.py` на этот ключ нет — при полном треке для «переносится
  штатно, без спецобработки» это достаточное доказательство: код, который мог
  бы его выбросить, прочитан и не делает этого.
- **AC7** (гейт + недостижимость в холодном View): гейты выше зелёные.
  Недостижимость в View разобрана чтением: `_updateDecorStyle`/
  `_persistDecorStyle` существуют только в `HouseplanEditorRuntime`
  (`houseplan-editor-runtime.ts`), которая грузится лениво только при входе в
  редактор; во всём `houseplan-card.ts` `_decorStyle` только читается
  (превью черновика/мебели), никогда не пишется вне рантайма. Холодный View
  этот модуль не подгружает — записи там физически нет.

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

- Схема `validation.py` соответствует ТЗ п. «Модель данных» дословно:
  диапазоны, `_COLOR`, все поля опциональны.
- Единственная точка конверсии snake_case↔camelCase
  (`decorStyleFromSettings`/`decorStyleToSettings`) — ровно то, что требовал
  ТЗ п.7 после SPEC-REVIEW-377-r1 M1; сопоставил маппинг 1:1 с текстом ТЗ.
  `decorStyleToSettings` возвращает `null` при точном совпадении с дефолтом
  (сравнение по значению всех 6 полей) — паттерн «дефолт = отсутствие ключа»
  выдержан.
- Посев (`_seedDecorStyle`) срабатывает ровно один раз на инстанс
  (`_decorStyleSeeded`) и из обоих источников первого конфига — тёплого
  кэша (`localStorage`, `houseplan-card.ts:3062-3066`) и первого серверного
  ответа (`_adoptStructuralResponses`, `houseplan-card.ts:4045-4046`);
  последующие обновления конфига не переоткрывают уже идущую сессию
  редактирования — сознательное и разумное техническое решение (в тексте
  явно откомментировано), продуктовым контрактом ТЗ не описано и не
  противоречит ему (сценарий ТЗ — «назавтра» и «второй редактор на другом
  устройстве», т.е. холодный старт, а не горячее обновление во время сессии).
- Запись идёт исключительно штатным сериализованным путём (`_saveConfig` →
  `_saveConfigDebounced` → `_writeConfig` → `_sendConfigCandidate` с
  `expected_rev`) — новый канал не создан, конфликт/тост наследуются
  бесплатно.
- Все шесть UI-точек изменения стиля (`_decorSaveShape`, тулбар,
  контекстный трей: цвет/непрозрачность, ширина, fill-чекбокс, fill-цвет,
  ещё раз в `_renderDecorBar`) переведены на `_updateDecorStyle` — ни одна не
  забыта (сверил построчно с прежними местами прямого присваивания
  `host._decorStyle =` в диффе).
- Трейлеры (`Issue: #377`, `User-Visible: yes/no`) на месте во всех трёх
  коммитах; оба changelog и оба USER-GUIDE — в том же коммите, что
  поведение (`ec76948b`), не отдельным «допишу потом».
- Мутант-регистрация (`scripts/mutation-gate.mjs`) описывает ровно тот
  дефект, который она ловит («seed-cut» — тихая деградация посева, приводит
  к молчаливому нерабочему AC2/AC5; «debounce-cut» — спам записей),
  соответствует формулировке в ТЗ «План автотестов».
- «Один источник числа»: новый ключ не дублирует уже показываемое где-то
  значение (это предпочтение по умолчанию для будущих объектов, а не
  производная величина, показанная дважды) — `test/single-source-numbers.test.mjs`
  зелёный, смысловых дублей не нашёл.

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

- Полный `npm run golden:verify` и полный `demo/smoke_*.mjs` (все ~204) — не
  оправдано объёмом правки; обоснование выбора — выше.
- Полный HA backend harness (`test_ha_*.py`, `test_coordinate_canonicalization.py`)
  — недоступен в этом окружении (нет `homeassistant`), это гейт CI/бета, не
  код-ревью; расхождение не связано с #377.
- Живое ручное тестирование в браузере (ручного цикла в процессе нет) —
  замещено чтением кода и прогоном автотестов/смоков выше.
- Гонка двух вкладок (штатный conflict #340) отдельно не воспроизводил —
  путь записи переиспользует существующий механизм, для которого этот
  сценарий уже покрыт в других смоках (`smoke_save_race.mjs`, не гонял —
  слабая связь, поведение конфликта в этой задаче не менялось).
- `import_export.py` полный интеграционный юнит именно на
  `decor_default_style` (только чтение кода + существующий байт-в-байт юнит
  схемы, см. AC6 выше).

## Вердикт

Все 7 AC доказаны (автотестом там, где это дешевле и надёжнее; чтением кода —
там, где ТЗ само на это полагалось, с явной пометкой). High/Medium-находок
нет, одна Low снята с записью. Гейты, соразмерные объёму задачи, зелёные.

Вердикт: зелёный · заход r1 · блокирующих циклов 0/4 · High: 0 · Medium: 0

Готово к очереди на пре-релиз.