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

CODE-REVIEW — issue #256 — заход r1

Скоуп задачи: houseplan/config/get и houseplan/layout/get получают необязательные параметры проекции (space_id, fields, marker_fields / space_id), не меняя ответ по умолчанию. Лёгкий трек (small), ТЗ — в теле issue. Заход первый: git log --oneline origin/dev..HEAD даёт один коммит (a952f5f), это полный разбор, дельты по предыдущим раундам нет.

Диапазон материала: git diff origin/dev...HEAD — 3 файла, +269/−5: custom_components/houseplan/projection.py (новый, 95 строк), правки custom_components/houseplan/websocket_api.py (+41/−5), tests_backend/ test_projection.py (новый, 138 строк, 11 тестов).

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

Прочитаны в порядке из инструкции: docs/SCOPE.md, AGENTS.md, тело issue #256 и оба комментария (спека и отчёт автора), PROCESS.md §2.7/§2.10/§4. Изменение не трогает видимое поведение (User-Visible: no, подтверждено диффом — нет правок в docs/CHANGELOG*), поэтому docs/USER-GUIDE.ru.md и канонические документы подсистем не задействованы: меняется только серверный WS-протокол для диагностических клиентов, UI не тронут.

Гейты — что прогнал сам и с каким результатом

Гейт	Команда	Результат
Typecheck	npx tsc --noEmit	чисто, exit 0
JS-тесты	npm test	1136/1136, 0 fail
Сборка + сверка бандла	npm run build, затем diff dist/houseplan-card.js custom_components/houseplan/frontend/houseplan-card.js	сборка ок; diff пустой (файлы идентичны) — ожидаемо, диффа в src/** нет
Backend pure-тесты (новые)	python3 -m pytest tests_backend/test_projection.py -v (после pip3 install --user pytest pytest-asyncio, песочница не имела pytest)	11/11 passed
Backend pure-подмножество целиком	python3 -m pytest tests_backend -q --ignore=tests_backend/test_coordinate_canonicalization.py --ignore=tests_backend/test_validation.py	51 passed — совпадает с числом, заявленным автором
Дисциплина «тест умеет падать»	вручную сломал keep = {"id", *names} → {*names} в копии projection.py, перезапустил test_projection.py: 4 теста упали (потеря id), включая test_marker_fields_keep_id_even_when_not_asked и test_markers_survive_unexpected_entries. Отдельно занулил условие раннего возврата (if False: return config) — упали 2 теста инварианта идентичности (test_no_parameters_change_nothing, test_empty_or_malformed_lists_mean_no_projection). Оба раза файл восстановлен из бэкапа, git status чист	тесты не ватные
node scripts/smoke-select.mjs --base origin/dev --head HEAD	—	«Исполняемого frontend-диффа нет (src/**/*.ts не тронут). Browser-smoke этим диффом не выбираются — выбирать нечего.»

Полный вывод git status --short после всех экспериментов — пусто, рабочее дерево осталось чистым.

Что не прогонял и почему

• node scripts/check-docs.mjs — не прогонял. Условие запуска — diff трогает src/**; этот diff src/** не трогает (подтверждено и git diff --stat, и выводом smoke-select.mjs). Отпечаток документации считается по src/**, изменение в него не входит.
• npm run invariants -- --config <...> — не прогонял. Diff действительно упоминает layout и marker.space, но только как ключи фильтрации при чтении — ни один путь записи (config/set, layout/set, plan/optimize) не тронут, хранимый документ проекция не мутирует (проверено чтением и тестами test_no_parameters_change_nothing, is CONFIG/is LAYOUT). Инварианты модели (#254) — про целостность хранимых данных; здесь модель не меняется, поэтому гейт неприменим, а не пропущен.
• golden:verify, browser-смоки — не прогонял; рендер, геометрия и стили не затронуты, smoke-select.mjs подтверждает: выбирать нечего.
• HA-харнесс (test_ha_websocket.py и соседние) — не прогонял. В песочнице нет homeassistant (тот же пробел независимо воспроизведён на origin/dev — test_coordinate_canonicalization.py/test_validation.py падают с ModuleNotFoundError и там, это не регрессия задачи). Проводка двух обработчиков (ws_config_get, ws_layout_get) разобрана чтением, не исполнением — см. AC2/AC4 ниже; фактический прогон харнесса — за CI.
• hassfest/HACS — манифест не менялся, гейт неприменим.
• Perf-профили — не названы в AC, путь не относится к чувствительным к перфу (проекция — плоская фильтрация словаря/списка на чтении, O(n) от размера уже загруженного документа).
• Одно число — один источник — неприменимо: изменение не добавляет и не меняет пользовательскую величину, это диагностический протокол, не UI.

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

1. config/get без параметров — ответ прежний. Доказано тестом test_no_parameters_change_nothing (проверяет тождество объекта is CONFIG, не только равенство) и чтением кода: ws_config_get строит config ровно как раньше, вызывает project_config(config, space_id=None, fields=None, marker_fields=None), а та при всех трёх None возвращает входной объект без копии (projection.py:56-58). Тест умеет падать — проверено (см. таблицу гейтов).
2. space_id возвращает одно пространство, markers/settings не урезаны. Доказано test_space_id_narrows_spaces_only и test_unknown_space_returns_empty_list_not_an_error. Плюс чтением: project_config трогает только ключ spaces, остальные ключи копируются как есть (dict(config)).
3. marker_fields: ["binding","space"] оставляет id+два поля. Доказано test_marker_fields_keep_id_even_when_not_asked (сверка точного словаря) и разрушающим экспериментом выше (тест ловит потерю id).
4. layout/get с space_id — только позиции этого пространства. Доказано test_layout_space_filter. Проводка в ws_layout_get — проверено чтением, не исполнением: project_layout(data.get("layout", {}), space_id=msg.get("space_id")) подставлена на место прежнего data.get("layout", {}), rev/can_optimize_undo/undo_kind считаются из config_data/data, которые проекции не касаются — инвариант «флаги считаются до проекции» не может быть задет этой правкой хотя бы потому, что строки, их вычисляющие, физически не изменены (diff это подтверждает).

Инвариант 2 из ТЗ («rev, can_write, virtual_lights, can_optimize_undo, undo_kind не зависят от проекции») — проверено чтением: в ws_config_get virtual_lights считается до вызова project_config, из непроецированного config; can_write/can_optimize_undo/undo_kind используют data/ config_data, не config. Порядок операций в диффе это гарантирует структурно, не только по намерению.

Инвариант 3 («проекция только для чтения») — проверено чтением: ни один из трёх обработчиков записи (config/set, layout/set, plan/optimize) не импортирует и не вызывает projection.py — grep по diff и по текущему websocket_api.py подтверждает единственную точку импорта.

Инвариант 4 (неизвестное имя поля — не ошибка; неизвестный space_id — пустой список) — доказано test_unknown_space_returns_empty_list_not_an_error, test_unknown_marker_field_adds_nothing.

Разобрано и корректно

• Проекция не мутирует исходный документ: project_config делает dict(config) (мелкое копирование) и никогда не пишет в config[...] до этого; spaces/ markers заменяются новыми списками/словарями, а не редактируются на месте. Подтверждено и тестами (CONFIG == original после вызова), и разрушающей проверкой не потребовалось — код тривиально проверяем чтением.
• Порядок применения фильтров (space_id → marker_fields → fields) корректен даже в комбинации «fields не включает markers, но marker_fields задан»: marker_fields спроецирует markers до того, как fields вырежет сам ключ markers — лишняя работа, не баг.
• Решение «пустой список = отсутствие проекции, а не проекция в ноль полей» автор явно пометил как оспоримое. Он не наблюдаем ни одной персоной (доступен только диагностическим клиентам, не описан в AC) — это техническое решение в духе PROCESS.md §7 («решай и записывай»), а не догадка, выданная за продуктовый факт. Принимаю: альтернатива (пустой список = «убрать все поля») не более очевидна и нигде не запрошена.
• id всегда добавляется в marker_fields — соответствует AC3 буквально и сопровождается тестом и комментарием, объясняющим «почему».
• Схемы vol.Optional/vol.All(...vol.Length(...)) на space_id (1–200 символов), fields/marker_fields (список строк 1–100 символов, максимум 50 элементов) — разумные защитные пределы, симметричные между config/get и layout/get.
• Загрузка модуля в тестах по пути (importlib.util.spec_from_file_location), а не через пакет — повторяет приём из test_virtual_lights.py и обосновано тем же #135; сам projection.py не импортирует ничего, кроме typing, что и позволяет тесту работать без homeassistant. Подтверждено эмпирически: test_projection.py собрался и прошёл в песочнице без HA/voluptuous, тогда как соседние файлы, тянущие пакет, — нет.
• Трейлеры коммита a952f5f: Issue: #256, User-Visible: no — корректно, изменение не даёт пользователю ничего нового, changelog обоснованно не тронут.
• Продуктовая рамка не нарушена: docs/SCOPE.md не содержит прямого пункта под диагностические WS-параметры, но задача явно заведена самим ревью (аудит инфраструктуры 2026-08-23) и принята владельцем на уровне issue — скоуп решён на входе, пересматривать на этапе кода нечего.

Находки

Нет находок High или Medium. Ниже — то, что рассмотрено и сознательно не поднято до находки:

• Low, не блокирует, не правлю: порядок space_id→marker_fields→ fields в project_config иногда строит markers-проекцию, которую тут же выбрасывает fields-фильтр (см. выше). Чисто эффективность на маленьких документах (максимум пара сотен маркеров), не корректность. Не стоит цикла ревью.
• Рассмотрел как потенциальную Medium-находку: решение «пустой список = нет проекции» могло быть продуктовым вопросом («хочу узнать только rev, без конфигурации вообще»), а не техническим. Отклоняю как находку: ни один реальный клиент (карточка, диагностика) не отправляет пустой список сегодня, случай гипотетический, вариант автора не хуже альтернативы, и не наблюдаем ни одной из трёх персон продукта — чисто внутренний контракт диагностического API. Не эскалирую владельцу: это не вопрос «что видит пользователь».

Вердикт

Все 4 AC доказаны автотестами, тесты проверены на способность падать. Оба инварианта совместимости (байт-в-байт без параметров; rev/флаги считаются до проекции) проверены и чтением, и тестами. Запись не затронута. Гейты, соразмерные объёму задачи (typecheck, JS-тесты, build+bundle-сверка, pure backend-тесты), зелёные; неприменимые гейты названы с обоснованием.

Зелёный.