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

# CODE-REVIEW-319-r1

**Issue:** [#319](https://github.com/Matysh/houseplan-card/issues/319) — «beta.3: бэкенд навсегда отклоняет все структурные записи после v8→v9 миграции с осиротевшим open_span»
**Трек:** `small` (ТЗ в теле issue, ревью ТЗ — комментарий, зелёное, r1)
**Ветка:** `issue/319-model-upgrade-not-outdated`
**SHA материала ревью:** `3ab6fa9f8a1ef1c35730c3fb03870f69c3e50be6` (единственный коммит поверх `origin/dev`)
**Заход:** r1 · блокирующих циклов израсходовано 0 из 2 (лёгкий трек — лимит 2)

## Скоуп

Диапазон `git diff origin/dev...HEAD`, 6 файлов:

- `custom_components/houseplan/validation.py` — единственная правка контракта: в
  `validate_wall_model_transition` условие охраны «unchanged wall catalogue»
  сужено с `old_model >= 8 and new_model >= 8` до
  `old_model >= 8 and 8 <= new_model <= old_model`.
- `docs/CHANGELOG.md` / `docs/CHANGELOG.ru.md` — запись об исправлении, оба
  файла в том же коммите (`User-Visible: yes`).
- `test/fixtures/319-orphan-span-migration.json` — пара `stored`(v8, с
  осиротевшим `open_span`, продукт писателя v1.68.0-beta.2) /
  `sent`(v9, продукт текущей миграции).
- `test/wall-segment-model.test.mjs` — тест, пинящий фикстуру к текущей
  JS-миграции побайтово (защита фикстуры от дрейфа).
- `tests_backend/test_wall_segment_model.py` — регрессионный тест
  `test_first_write_of_a_newer_model_is_not_outdated_even_without_catalog_change`
  на AC1–AC3.

Продуктовый код класса A — только Python (`validation.py`); `src/**` не
тронут. Соответствует J6 `docs/SCOPE.md` («Keep the plan true as the home
evolves» — структурные записи и апгрейд модели стен не должны намертво
блокировать редактирование).

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

Материал — `origin/dev...HEAD`, ручного тестирования нет, поэтому все AC
проверены исполнением, не только чтением.

| Гейт | Статус | Результат |
|---|---|---|
| `npx tsc --noEmit` | прогнан | чисто, без вывода |
| `npm test` | прогнан | `1346 pass, 0 fail, 1 skipped` (skip — `issue 281 private exact fixture`, не связан с #319, зависит от отсутствующей приватной фикстуры) |
| `npm run build` + сверка `dist/` vs `custom_components/houseplan/frontend/` | прогнан | сборка чистая, `cmp` — файлы идентичны |
| `node scripts/smoke-select.mjs --base origin/dev --head HEAD` | прогнан | «Исполняемого frontend-диффа нет (`src/**/*.ts` не тронут). Browser-smoke этим диффом не выбираются». Смоки не запускались — выбирать нечего, а не пропуск |
| `node scripts/check-docs.mjs` | **не прогнан** | не требуется: диффом не тронут `src/**` |
| `npm run golden:verify` | **не прогнан** | не требуется: видимый рендер/геометрия не меняются, правка — только серверная валидация допустимости записи |
| `node scripts/model-invariants.mjs` | **не прогнан** | не требуется: диффом не тронуты рёбра/`layout`/`marker.space`/`open_spans`-производство — только guard, решающий принять/отклонить уже готовую запись |
| `python -m pytest tests_backend -q` | прогнан (полный набор, включая `test_ha_*`) | окружение ревью по умолчанию без `homeassistant`/`.venv-backend`; установил `pytest-homeassistant-custom-component`+`home-assistant-frontend` через pip, чтобы получить реальный, а не «молчаливо пропущенный» результат. Итог: `405 passed, 1 skipped, 1 error`. Ошибка — `test_ha_upload.py::test_upload_ok`, воспроизводится дважды подряд и не по файлу диффа: teardown-ассерт `pytest-homeassistant-custom-component` о фоновом потоке (`_run_safe_shutdown_loop` не `_DummyThread`/`waitpid-`), сам тест **passed**, падает только фикстура очистки. Не относится к `validation.py`/`wall_segment_model.py`, файл `test_ha_upload.py` диффом не тронут — квирк среды ad hoc-инсталляции, не регрессия задачи |
| Performance-профили | не требуется | не названы в AC, диффом не тронуты чувствительные к перфу пути |

**Тест умеет падать (проверено, не заявлено).** Патч `validation.py`
временно откачен (`git apply -R`), новый pytest-тест
`test_first_write_of_a_newer_model_is_not_outdated_even_without_catalog_change`
перезапущен изолированно:

```
FAILED …/test_wall_segment_model.py::test_first_write_of_a_newer_model_is_not_outdated_even_without_catalog_change
custom_components.houseplan.validation.WallModelClientOutdatedError: stored model=8; unchanged wall catalogue
```

— ровно та ошибка, что описана в симптоме issue. Патч восстановлен
(`git apply`), дерево чистое (`git status --porcelain` пусто), тест снова
зелёный (`17 passed`).

## AC — доказательство

- **AC1** (чистая миграционная запись v8→v9 проходит). Доказано исполнением:
  `validate_wall_model_transition(sent, stored)` в тесте не бросает, тест
  красный до фикса (см. выше), зелёный после.
- **AC2** (то же с независимым черновиком `room_drafts`). Доказано тем же
  тестом (`with_draft`), тем же красный/зелёный циклом.
- **AC3** (эхо той же версии 9→9 с изменёнными контурами и неизменным
  каталогом по-прежнему отклоняется). Доказано исполнением: тот же тест,
  блок `echoed`, ловит `WallModelClientOutdatedError` с сообщением
  `unchanged wall catalogue`; плюс существующий
  `test_stale_client_echoing_v8_catalog_gets_the_named_error` зелёный
  (первая ветвь `if` не тронута правкой — граница добавлена только
  условием `<= old_model`, которое не меняет поведение при `new_model ==
  old_model`).
- **AC4** (ветка «легаси-клиент», `old_model >= 8 and new_model < 8`, не
  изменена). Проверено чтением и исполнением: правка не касается первого
  `if`-блока (строки 181–192 не тронуты диффом), существующие тесты
  `test_stale_client_round_trip_is_hydrated_but_structural_change_is_rejected`
  и смежные — зелёные в полном прогоне.

## Продуктовое рассуждение (не только AC)

Ослабление гарда — не дыра в целостности данных. Проверено чтением
вызывающего кода, не только заявлением автора: в `websocket_api.py`
(строки 1324–1325 и 1644–1662) `validate_wall_model_transition` вызывается
**перед** `CONFIG_SCHEMA(...)` в обоих обработчиках сохранения, и
`CONFIG_SCHEMA` всегда прогоняет `_config_wall_segment_invariants`
(`validation.py:1772`) независимо от того, что решил guard в этой задаче.
Этот независимый инвариант жёстко сверяет `room.poly`/`wall_ids` с
`wall_segments` по ключу ребра, требует `id` у сегментов черновика и не
допускает `open_spans`/`open_to` при `model_version >= 9`. Значит, даже
теоретически «сломанная» запись с поднятой версией и неизменным каталогом
не проскочит мимо структурной проверки — она либо валидна, либо отклонена
`CONFIG_SCHEMA` отдельно от гарда staleness.

Предпосылка «устаревший клиент не может поднять `model_version`» опирается
на то, что `model_version` в записи — не пользовательский ввод, а константа
сборки клиента (`WALL_SEGMENT_MODEL_VERSION`/`PLAN_MODEL_VERSION`, сейчас
`9` и в `src/wall-segment-model.ts`, и в
`custom_components/houseplan/wall_segment_model.py`, и в
`custom_components/houseplan/const.py`) — проверено чтением исходников,
согласуется с тем, что уже сверял ревью ТЗ.

## Найдено и корректно

- Правка минимальна и буквально реализует контракт ТЗ: «гард применяется
  только при `new_model <= old_model`» — ровно `8 <= new_model <= old_model`
  в коде.
- Комментарий у изменённой строки объясняет постпродукт-причину (#319) не
  тривиальным образом — обоснован по правилам написания комментариев.
- Фикстура `test/fixtures/319-orphan-span-migration.json` — не рукописная:
  `stored` подтверждённо продукт реального писателя v1.68.0-beta.2,
  `sent` — реального текущего мигратора; JS-тест
  `the #319 pair fixture matches the current initial migration byte for byte`
  защищает её от рассинхронизации, пересчитывая `sent` из `stored` через
  боевой `commitWallSegmentModel`.
- Трейлеры коммита: `Issue: #319`, `User-Visible: yes`; оба changelog
  правлены в этом же коммите — соответствует правилу.
- «Одно число — один источник»: правка не вводит новую отображаемую
  пользователю величину (это guard принятия/отклонения записи, а не
  вычисляемое значение на экране) — раздел неприменим по существу.
- Ветка легаси-клиента (`new_model < 8`) не затронута — предотвращает
  регрессию по «правка ломает ранее принятый AC» (#102-класс риска).

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

- `check-docs.mjs`, `golden:verify`, `model-invariants.mjs`,
  performance-профили и browser-смоки — не запускал: диффом не тронут
  `src/**`, видимая геометрия/рендер и чувствительные к перфу пути;
  инструмент выбора смоков подтвердил «выбирать нечего».
- HA-харнесс (`test_ha_*.py`) прогнан не на пиновком CI-образе, а на
  ad hoc `pip install` в среде ревью — как и предупреждает `AGENTS.md`,
  «канон — Linux CI»; здесь это использовано только для получения
  неслепого, исполняемого результата вместо «not verified», а не как
  замена CI-гейта. Один teardown-квирк (`test_ha_upload.py`, не файл
  диффа) зафиксирован и не отнесён на счёт задачи.
- CI-прогон ветки (`https://github.com/Matysh/houseplan-card/actions/runs/32984859492`),
  на который ссылается автор, отдельно не открывал — верификация в этом
  документе получена независимым локальным исполнением на том же SHA.

## Вердикт

High: 0, Medium: 0. Все AC1–AC4 доказаны исполнением (не только заявлением),
тест-регрессия умеет падать (проверено откатом патча), ослабление гарда не
открывает дыру в целостности — подтверждено чтением независимого инварианта
схемы и его места вызова. Зелёный.