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

SPEC-REVIEW-319-r1

Issue: #319 · Этап: spec (лёгкий трек small) · Заход r1 · блокирующих циклов 0/2

Скоуп

Правка одной ветки условия в validate_wall_model_transition (custom_components/houseplan/validation.py:169-203): гард «unchanged wall catalogue» (строки 193-203) должен применяться только при new_model <= old_model, а не безусловно при old_model >= 8 and new_model >= 8. Цель — пропускать первую запись клиента v9 поверх v8-документа с осиротевшим open_span/open_to, которую миграция #306 делает нередактируемой навсегда. ТЗ — в теле issue (small-трек), файла в docs/specs/ нет, что соответствует §5 PROCESS.md.

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

Ревью полное (заход r1, дельты нет). Материал: тело issue #319 + комментарий S2-analysis владельца (решение зафиксировано 2026-08-26), текущий код custom_components/houseplan/validation.py, src/wall-segment-model.ts, src/plan-optimizer.ts, существующие тесты tests_backend/test_wall_segment_model.py, канон docs/SCOPE.md, docs/WALL-THICKNESS.md.

1. Прочитан validate_wall_model_transition целиком (строки 169-203) — условие и текст ошибки в коде дословно совпадают с тем, что описывает issue («причина, доказана исполнением»). Ветка old_model >= 8 and new_model < 8 (легаси-клиент) действительно отдельная и правкой не затрагивается.
2. Проверена посылка контракта «устаревший клиент не может поднять model_version»: WALL_SEGMENT_MODEL_VERSION = 9 (src/wall-segment-model.ts:21) — константа кода, commitWallSegmentModel всегда пишет config.model_version = WALL_SEGMENT_MODEL_VERSION (src/wall-segment-model.ts:724), независимо от того, что было прочитано. plan-optimizer.ts («Оптимизировать планы») использует ту же константу (PLAN_MODEL_VERSION = 9, src/plan-optimizer.ts:38) и сам вызывает commitWallSegmentModelInPlace. Значит клиент старой сборки (константа 8) физически не может отправить new_model=9 — посылка верна, это не догадка.
3. Проверено, не открывает ли ослабление гарда дыру в целостности данных: независимая схемная проверка _config_wall_segment_invariants (validation.py:1766-1817) при model_version >= 8 жёстко сверяет room.poly edge-by-edge с координатами wall_segments (_canonical_segment_key, строка 1793-1795) и space.walls с wall_segments (строка 1811-1817) — независимо от validate_wall_model_transition. Реальное изменение геометрии контура без соответствующего обновления каталога wall_segments отклоняется этой схемной проверкой в любом случае, даже если гард транзита ослаблен. Гард транзита ловит только специфический случай: _catalog_coupled_wall_ geometry_projection включает open_spans/open_to, поэтому просто удаление легаси-поля миграцией меняет «проекцию контура», не трогая ни poly, ни wall_ids, ни wall_segments. Спуфинг model_version наверх не даёт обойти геометрическую проверку — вывод: ослабление гарда не создаёт находки Medium/High по целостности данных.
4. Сверены AC1-AC4 с существующей тестовой инфраструктурой tests_backend/test_wall_segment_model.py: фикстура test/fixtures/282-wall-identity-parity.json существует и уже используется (строка 36-46); паттерн «stored/previous → submitted/candidate → validate_wall_model_transition» уже используется в 4 существующих тестах (строки 184-298), включая ровно тот сценарий AC2/#314 (test_current_wall_model_independent_geometry_does_not_require_contour_ catalog_change, строка 226). AC1/AC2/AC3/AC4 доказуемы предложенным способом без дополнительных догадок об инфраструктуре.
5. Проверено, что test_stale_client_echoing_v8_catalog_gets_the_named_error (строка 210-223, old_model=9, new_model=9) и test_stale_client_round_trip_is_hydrated_but_structural_change_is_rejected (строка 184-207, new_model<8 ветка) остаются зелёными под новым условием new_model <= old_model — оба явно соответствуют AC3/AC4.
6. Проверен канон docs/WALL-THICKNESS.md — «canonical model v9 never writes compatibility open_spans or open_to» (строка 76), противоречий с ТЗ нет.
7. docs/SCOPE.md: это баг-фикс, восстанавливающий J6 («Keep the plan true as the home evolves» — drag/resize, merge/split), а не новая функция; решение владельца по направлению фикса уже зафиксировано в S2-analysis-комментарии 2026-08-26. Открытых продуктовых вопросов нет.

Находки

Нет. Ни одной High/Medium/Low.

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

• Соответствие §5 (лёгкий трек): сложность/риск, одна поверхность (validation.py), нет миграции конфига/новых полей/UX-контракта, нет влияния на touch/perf — подтверждено чтением кода, а не только заявлением автора оценки.
• Структура ТЗ в теле issue соответствует упрощённому шаблону §5: проблема · контракт · AC1…AC4 с доказательством · откат — все разделы на месте.
• Контракт («гард применяется только при new_model <= old_model») — однозначная булева формулировка, прямо переносимая в код без дополнительной интерпретации; не риторика, а точное условие.
• Посылка «устаревший клиент не может поднять model_version» проверена по фронтенд-коду, а не принята на веру.
• Отсутствие дыры в целостности данных при ослаблении гарда проверено по независимой схемной проверке _config_wall_segment_invariants.
• Каждый AC указывает способ доказательства (регрессионный тест, зелёные существующие тесты) и воспроизводим по существующей тестовой инфраструктуре проекта.
• Откат: ревертом одного коммита, правка не трогает данные (только валидацию записи) — корректно и достаточно для этого класса изменений.
• Ветка old_model >= 8 and new_model < 8 (легаси-клиент, AC4) явно не меняется — подтверждено чтением кода.

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

• Не запускал pytest tests_backend — на этапе spec кода фикса ещё нет, запускать нечего; это часть код-ревью следующего этапа.
• Не проверял вручную UI/тост «Обновите карточку» в браузере — это поведенческое доказательство, а не спецификационное; относится к код-ревью/смокам.
• Не выяснял в глубину, обрабатывает ли plan-optimizer.ts путь отдельно от обычной структурной записи в бэкенде — не требуется: бэкенд-валидация одна на все пути записи, и AC1 формулирует «любая структурная запись», что корректно покрывает и «Оптимизировать планы» без отдельного AC.

Вердикт

Зелёный. ТЗ технически обосновано, контракт однозначен и реализуем буквально, все AC проверяемы предложенным способом, открытых продуктовых вопросов нет, скоуп совпадает с job J6 из docs/SCOPE.md. Готово к разработке.