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

SPEC-REVIEW-42-r1

• Issue: #42 «[HP-ENG-01] измеряемое инженерное качество backend»
• Этап: ТЗ на ревью (PROCESS.md §2.4), полный трек (метки: P2, tests, tech-debt, S4-spec-review; small отсутствует)
• Артефакт ТЗ: docs/specs/042-backend-engineering-quality.md, ревизия 2 (коммит 582d673a, docs-only, класс C)
• Заход: r1 (документов SPEC-REVIEW-42-*.md в репозитории не найдено — первый заход подтверждён)
• Ревьюер: свежая сессия, без контекста написания ТЗ

Скоуп проверки

ТЗ описывает одну ступень из пяти блоков: tooling-фундамент (pyproject + requirements_test), ruff narrow, mypy strict на растущем allowlist, coverage-механизм в CI с baseline-файлом, и формализация WS ERROR_CODES + JSON-details + локализованный fallback (единственная видимая пользователю часть). Дифф этого раунда — только сам файл ТЗ (177 добавлено / 58 удалено), продуктовый код не тронут.

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

Ревью ТЗ на этом этапе — не код-ревью: гейты typecheck/test/build и браузерные смоки к докс-диффу неприменимы (класс C, ноль файлов src/** или custom_components/**/*.py в этом коммите). Вместо этого перепроверялись фактические утверждения ТЗ по текущему коду dev — то, что обычно и выдаёт догадку, поданную как факт:

• python3 -m ruff check custom_components/houseplan --select E,F,B,I --target-version py313 --statistics → 333 (E501 291, B023 17, I001 13, F401 6, E731 2, F841 2, B905 2) — совпадает с цифрами ТЗ дословно;
• custom_components/houseplan/quality_scale.yaml → ровно 4 todo: test-coverage, docs-troubleshooting, docs-examples, strict-typing — совпадает с заявлением владельца в issue;
• docs/USER-GUIDE.md §22 Troubleshooting существует (строка 1034), docs/USER-GUIDE.ru.md раздела «Troubleshooting»/«Устранение неполадок» не содержит вовсе — совпадает;
• grep -c '"backup.error\.' src/i18n/en.json → 26 ключей — совпадает;
• .github/workflows/mutation-gate.yml:67 действительно дублирует строку pip install pytest voluptuous pytest-homeassistant-custom-component home-assistant-frontend из validate.yml — совпадает;
• прочитан весь путь ошибки на фронте (src/houseplan-card.ts:9497-9536 _errText, src/houseplan-editor-runtime.ts:8002-8010 _backupErrorText) и все точки эмиссии send_error (custom_components/houseplan/ websocket_api.py, 54 вызова) плюс классы с публичным .code (validation.py, junction_limits.py, import_export.py) — см. находку Medium 1.

Не запускался: npm run typecheck/test/build, check-docs, model-invariants, браузерные смоки, pytest tests_backend, mypy/coverage прогон — см. «Чего не проверял».

Находки

Medium 1 (в скоупе) — AC5 не покрывает коды, эмитируемые не литералом в send_error(...)

Файл: docs/specs/042-backend-engineering-quality.md, раздел «5. WS error contract + доки» и «AC5».

Формулировка ТЗ: «ERROR_CODES ⊇ все коды send_error (скан исходника): каждый литерал send_error(...)-кода ∈ ERROR_CODES». Как метод верификации это подразумевает статический скан аргументов вызовов send_error(...) на литеральные строки.

Почему это не выполнимо как написано. Как минимум четыре класса ошибок несут код не литералом внутри send_error(...), а через err.code, прочитанный в обработчике (websocket_api.py:189 send_error(msg_id, err.code, err.message); :1370 и :1747 send_error(msg["id"], err.code, str(err))):

• validation.py:43-54 OpeningPassageError.code = "invalid_passage_fields" и validation.py:63-72 PartitionOpeningJambMarginError.code = "invalid_partition_opening_jamb_margin" — это ровно те два кода, вокруг которых построен весь блок 5 (JSON-details). Скан по литералам send_error(...) их не найдёт — они читаются из атрибута класса, а не передаются строкой в месте вызова;
• validation.py:57-60 PartitionOpeningHostError.code = "invalid_partition_opening_host" и validation.py:81-84 WallModelClientOutdatedError.code = "wall_model_client_outdated" — то же;
• validation.py:35-40 MarkerControlError.__init__(self, code, message) — код передаётся аргументом конструктора; часть литеральна ("duplicate_marker_control", "marker_control_self", "invalid_value_badge" и др., validation.py:824-968), часть собрана f-строкой из prefix с ровно двумя значениями (validation.py:818: "value_badge" / "value_source") → value_badge_marker_missing, value_source_marker_missing, value_badge_marker_not_light, value_source_marker_not_light (validation.py:847,849);
• junction_limits.py:56 JunctionLimitError.code = f"junction_limit_{rule}" — rule пробегает конечное множество ключей П1–П4 (junction_limits.py:427-430), но опять не литерал внутри send_error(...).

Итого не меньше дюжины уже существующих кодов — включая оба кода, ради которых написан блок 5 — невидимы для скана, читающего только литералы в send_error(...). Реализация AC5 «в лоб» даст зелёный контракт-тест, который ничего не доказывает для этих кодов: они не попадут в ERROR_CODES, останутся без ключа backup.error.<code>, и _errText продолжит показывать сырой e.message (houseplan-card.ts:9528) ровно для того класса ошибок, который issue называет проблемой. Это технический, не продуктовый вопрос (какой метод верификации использовать), поэтому решаю его в вердикте, а не выношу владельцу.

Как чинится в скоупе: AC5/раздел 5 должны явно назвать способ, которым скан достаёт коды из err.code — либо (а) перечислить классы-источники (OpeningPassageError, PartitionOpeningHostError, PartitionOpeningJambMarginError, WallModelClientOutdatedError, MarkerControlError, JunctionLimitError, ImportFailure) и извлекать их code-литералы/шаблоны статическим разбором модуля, либо (б) явно сузить AC5 до кодов-литералов в send_error(...) и отдельно перечислить раскрытые f-строкой/классом семейства как «покрыты общим локализованным fallback по коду, без выделенного ключа» — тогда _errText/_backupErrorText обязаны фактически падать в этот fallback для них, а не в сырой e.message (что снова упирается в порядок проверок в _errText, см. Medium 2).

Medium 2 (в скоупе) — раздел «i18n» (обязателен по PROCESS.md §7.1) отсутствует; повторное использование err.code не зафиксировано

Файл: тот же, ТЗ целиком — раздела с заголовком «i18n» нет ни одного.

DoR §2.5 требует «i18n: ключи en + ru перечислены». Блок 5 обещает: «неизвестный код → общий локализованный текст + код» — но не говорит, это НОВЫЙ ключ или переиспользование существующего.

Проверка кода показывает, что подходящий ключ уже есть и уже переведён: src/i18n/en.json:338 "err.code": "code {code}", src/i18n/ru.json:338 "код {code}" (де/фр тоже переведены). Реальная причина текущего дефекта не в отсутствии такого ключа, а в порядке проверок внутри _errText (houseplan-card.ts:9528: if (e.message) return e.message; стоит РАНЬШЕ ветки err.code) — значит для любой ошибки, где бэкенд шлёт одновременно код и message, независимо от известности кода, сейчас показывается сырое английское message. AC6 («неизвестный код → локализованный fallback») не сможет быть проверен юнит-тестом однозначно, пока ТЗ не решит: (а) переиспользуется err.code/err.unknown без новых ключей — тогда раздел i18n тривиален («новых ключей нет, порядок проверок в _errText меняется на code-first») — либо (б) вводится новый текст — тогда нужны конкретные en+ru строки. Без явного выбора ревьюер кода не сможет сверить AC6 с намерением автора, а автор рискует написать тест под собственную догадку, которую я не смогу отличить от решения.

Как чинится в скоупе: добавить короткий раздел «i18n» с явным решением (рекомендация — вариант (а), ключ уже есть и уже переведён на 4 языка) и одной строкой описать смену порядка проверок в _errText (code-first → message → error → JSON).

Low (снимаю с записью, не блокирует)

Разделы «UX» и «Модель данных и миграция», формально обязательные по PROCESS.md §7.1 как отдельные заголовки, в файле не оформлены как таковые — их содержание фактически присутствует, но разбросано («Что человек увидит до и после» покрывает UX: новых диалогов/интеракций нет, меняется только текст; «DoR-примечания» закрывает миграцию: единственное затронутое поле — формат message двух кодов, обратная совместимость на одну бету). Контент по существу верный и достаточный, поэтому не поднимаю до Medium — прошу консолидировать при следующей правке ради дословного соответствия §7.1, но это не требует нового цикла ради одного этого пункта.

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

• Сценарий и «что человек увидит до и после» — на месте, продуктовые, без терминов реализации; соответствуют J-рядам SCOPE.md лишь косвенно (инженерное качество — не отдельная строка core user jobs), но решение вести эту работу и её ценностная оценка (3/10 пользователю, 9/10 разработке) уже приняты владельцем в комментариях issue — не переоткрываю;
• Скоуп/не-скоуп разделены явно, «следующая ступень» зафиксирована текстом, а не памятью;
• Контракт поведения: код и структура успешных ответов не меняются; единственное видимое изменение — формат message двух кодов на JSON, риск для рассинхронизированной пары фронт/бэк одной беты назван и обоснован явно, а не спрятан;
• AC1–AC4, AC6, AC7 — однозначны, у каждого назван способ доказательства (CI/локально/юнит), и по каждому видно, как тест умеет упасть (AC1 — «подмена baseline на большее число», AC2 — «удаление homeassistant из шага установки», AC4 — «контракт-тест падает при сужении списка», AC6 — м1/м2 мутанты в разделе «План автотестов»);
• Риски называют главный поведенческий риск (B023-фиксы) и версийный разъезд (3.10 песочница / 3.13 CI) без сокрытия;
• Откат — git revert, без потери данных, явно;
• Release-артефакты — оба changelog, ARCHITECTURE.md, USER-GUIDE.ru §Troubleshooting — названы;
• Принятые предположения — присутствуют отдельным блоком, включая ту же идею про backup.error.<code> как общее пространство кодов, которую находка Medium 2 просит явно продолжить в раздел i18n;
• порог coverage 90→95 сознательно вынесен в отдельные trivial-issues — разумно, механизм этой ступени уже будет их принудительно проверять.

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

• npx tsc --noEmit, npm test, npm run build + сверка копий бандла, node scripts/check-docs.mjs, node scripts/model-invariants.mjs — диф этого раунда состоит из одного файла docs/specs/042-*.md (класс C), в src/** и custom_components/**/*.py изменений нет; прогон гейтов кода на неизменном коде не даёт сигнала по существу ТЗ и не входит в предмет ревью ТЗ (PROCESS.md §2.4 против §2.7);
• браузерные смоки, golden:verify, pytest tests_backend, performance — та же причина, плюс на этом этапе AC не привязаны к конкретному коду, который можно было бы прогнать;
• фактическое покрытие 89.1% и «pure 240/0» из измерений владельца — не переснимал (нужен рабочий HA-harness/pytest-cov, которых в песочнице нет и установка которых для разового замера ушла бы за рамки ревью ТЗ). Считаю косвенным подтверждением точное совпадение независимо перепроверенных ruff-цифр (333/291/17/13/6/2/2) — метод измерения автора доверия заслуживает;
• осуществимость конкретного стартового allowlist mypy strict (const, projection, coordinate_canonicalization, frontend_asset_manifest, junction_limits, plans + часть validation/wall_segment_model/ geometry_migration) — ТЗ само откладывает точный финальный список «по факту зелени» в handoff, это законное «assumed, решается в реализации», не спец-пробел.

Итог

Механизм в целом обоснован и предметен — почти все числа и ссылки в ТЗ проверяются на HEAD dev дословно, что необычно хорошо для спека такого объёма. Возврат — по двум находкам Medium в скоупе задачи: AC5 нужно дотянуть до кодов, приходящих через err.code (включая оба флагманских кода блока 5), и явно решить/записать пункт i18n. Обе решаются добавлением текста в тот же файл, без пересмотра архитектуры и без нового цикла владельца.