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

CODE-REVIEW-378-r1

• Issue: #378 — «Значение + состояние»: выбор источника значения, как у бейджа
• Этап: код-ревью (PROCESS.md §2.7)
• Заход: r1 · блокирующих циклов израсходовано 0 из 4 до этого вердикта
• SHA материала: 552b78a134026f084593d5c76dcb55cba50088cd (git rev-parse HEAD сверен непосредственно перед подведением итогов)
• Диапазон: origin/dev...HEAD = 6e1d9364..552b78a1 (a851c8f9 ТЗ, ad9c6349 ревью ТЗ r1 — зелёный, 591f8f6a реализация, 552b78a1 docs screenshots после rebase)
• Спецификация: docs/specs/378-value-face-source.md, ревью ТЗ зелёное (docs/reviews/SPEC-REVIEW-378-r1.md)
• Вердикт: жёлтый · заход r1 · блокирующих циклов 1/4 · High: 0 · Medium: 1 → в задаче

Скоуп

Диапазон полный (первый заход код-ревью, дельты предыдущего раунда нет — предыдущий вердикт того же issue относился к этапу ТЗ, не к коду). Проверены все 10 AC ТЗ:

• src/device-value-badge.ts — общий resolveValueSource/formatter/failure-код, valueSourceWriteFields.
• src/device-presentation.ts — explicit-ветка resolveValue(), приоритет virtual, sourceSignature, fallbackReason/valueFullText.
• src/houseplan-editor-runtime.ts — селектор «Источник значения» в диалоге, draft/preview, reset на смену binding, rebind marker id.
• src/devices.ts, src/houseplan-card.ts, src/types.ts — поле конфига, rewriteMarkerControlReferences.
• custom_components/houseplan/validation.py — общая validate_source(), lossless-схема, delta-validation, marker-ref target/is_light.
• custom_components/houseplan/import_export.py — full/space export/import, drop/remap/virtualize, _transfer_dropped_marker_links maximum.
• scripts/model-invariants.mjs, scripts/smoke-links.mjs — новый инвариант ссылки и регистрация смока.
• demo/smoke_value_face_source.mjs — целевой browser smoke.
• Тесты: test/device-presentation.test.mjs, test/device-presentation-policy.test.mjs, test/devices.test.mjs, test/native-select-contract.test.mjs, test/fixtures/device-presentation-decisions.mjs, tests_backend/test_validation.py, tests_backend/test_ha_import_export.py.
• Документация: docs/ARCHITECTURE.md, docs/CONFIG-COMPATIBILITY.md, docs/DEVICE-PRESENTATION.md, docs/USER-GUIDE.md/.ru.md, docs/CHANGELOG.md/.ru.md, i18n en/ru/de/fr, docs/specs/README.md.

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

Дешёвые гейты уже подтверждены зелёным Validate на этом же SHA 552b78a1 (https://github.com/Matysh/houseplan-card/actions/runs/33270791009) — npx tsc --noEmit, npm test (1574 passed / 1 skipped, включая model-invariants.test.mjs на всех моделях проекта), npm run build, backend pytest (143 passed), no-new-any, bundle budget/sync не перегонялись повторно ревьюером.

Гейт	Статус	Как
npx tsc --noEmit, npm test, npm run build, backend pytest, no-new-any	не гонял повторно	зелёный Validate на точном SHA 552b78a1 (ссылка выше); код с тех пор не менялся
node scripts/check-docs.mjs	прогнал	Documentation checks passed (7 files, 10 external links)
node scripts/bundle-sync.mjs + сверка трёх копий бандла	прогнал	git status --short пуст после синка — dist/, custom_components/.../frontend и рабочая копия совпадают побайтово
node scripts/bundle-budget.mjs	прогнал	277948 B initial View при лимите 300000 B (что коррелирует с заявленными автором 277599 B; малая разница — среда/oxipng, бюджет не нарушен)
node scripts/smoke-select.mjs --base origin/dev --head HEAD	прогнал	прямое совпадение: smoke_cover_tap.mjs, smoke_value_face_source.mjs; зарегистрированная связь: smoke_cold_view_toggle.mjs; 31 слабая связь по общему имени _markerDialog — не прогонялись, см. «Чего не проверял»
demo/smoke_value_face_source.mjs	прогнал, зелёный, проверил, что умеет падать	мутация text: text ?? '—' → 'RAW' в device-value-badge.ts дала 5 честных провалов (preview42, plan42, static42, unavailableDash, recovered55); откат мутации восстановил зелёный прогон и чистое дерево
demo/smoke_cover_tap.mjs (прямое совпадение)	прогнал	все ключи true
demo/smoke_cold_view_toggle.mjs (зарегистрированная связь: resolvedLightSources)	прогнал	все ключи true
demo/smoke_device_preview_parity.mjs (слабая связь, но прямо про preview, который правит диф)	прогнал	все ключи true
npm run golden:verify (диф трогает рендер лица значения)	прогнал	78/78 сценариев passed, включая device-value-badge-positions-dark и все device-dialog-*
npm run invariants -- --config <…> на конкретном конфиге	не гонял отдельно	checkReferences() для marker.value_source уже покрыт model-invariants.test.mjs, часть зелёного npm test на всех моделях проекта
python -m pytest tests_backend -q	не гонял повторно	входит в зелёный Validate; изменения только в validation.py/import_export.py, оба покрыты новыми тестами, прочитанными построчно

Находки

Medium — AC2 не доказан golden-сценарием, как того явно требует принятое ТЗ

• Файл: docs/specs/378-value-face-source.md (AC2, «План автотестов», «Release-артефакты») vs фактический диапазон demo/golden/**
• Summary: ТЗ трижды явно требует golden-доказательство для видимого результата явного источника (cover.current_position = 42 → 42 %): в AC2 («unit + smoke + golden»), в плане автотестов («Golden-сценарий с cover 42 % и выбранным source принимается только через штатный reviewed Linux artifact») и в разделе Release-артефактов. Ни один файл demo/golden/** не тронут: git diff origin/dev...HEAD --stat -- demo/golden пуст, в demo/golden/matrix.mjs нет ни одного маркера с value_source. Автор сам зафиксировал это в handoff-комментарии: «Локальный golden на Windows дал неканонические renderer-различия, baseline не менялся и не принимался», но сценарий не был добавлен вовсе (даже без принятия эталона) — сравнивать боту было нечего, а не только «нечего принять».
• Failure scenario: будущий рефакторинг рендера .valtext/.valonly (шрифт, обрезка, цвет, позиционирование внутри капсулы) сможет сломать именно новый визуальный контракт «явный источник → 42 % вместо иконки» и пройти незамеченным: npm run golden:verify в этом PR прогнал 78 сценариев зелёным, но ни один из них не рендерит маркер с value_source, поэтому регресс такого рода этот гейт органически не ловит. Browser-smoke (demo/smoke_value_face_source.mjs) проверяет только textContent ('42 %' как строку), а не визуальную раскладку — разного рода поломки вёрстки капсулы через него не видны.
• Что делает находку Medium, а не High: функциональная корректность самого значения (форматирование, dash, восстановление, паритет рендереров, rebind, import/export) доказана unit+backend+smoke кодом, который умеет падать (см. таблицу выше) — рабочего дефекта в текущем поведении нет. Пробел — только в будущей защите от визуальной регрессии, для которой ТЗ явно назвало метод доказательства, а имплементация его не предоставила. Находка в скоупе задачи (тот же файл ТЗ, тот же issue), поэтому по правилу #202 отдельный issue не заводится: правится в этой же ветке.
• Что нужно: добавить сценарий в demo/golden/matrix.mjs (маркер cover с value_source: {kind: 'entity_attribute', entity_id: …, attribute: 'current_position'}, ожидаемое 42 %) и провести штатный Linux-цикл capture/accept через npm run golden:accept -- --reviewed на CI — именно так же, как в этом PR уже был принят docs screenshots артефакт (https://github.com/Matysh/houseplan-card/actions/runs/33270679280). Автор физически не может принять корректный baseline с Windows — это не повод пропустить шаг, а повод завести его через CI, как и было сделано для скриншотов документации в этой же ветке.

Low — index-таблица docs/specs/README.md нарушает сортировку по номеру issue

• Файл: docs/specs/README.md:113
• Summary: новая строка #378 вставлена между #90 и #94, хотя вся остальная таблица строго отсортирована по возрастанию номера issue (…, #90, #94, #101, #107, #113, …). Чисто косметическая непоследовательность, функционально ни на что не влияет (ссылка и путь верны).
• Решение ревьюера: снимается без правки — не блокирует и не входит в условия DoD; при следующей правке этого файла можно переставить строку.

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

• AC1 (список/сохранение). valueBadgeCandidates() используется как единственный источник кандидатов и для value badge, и для нового селектора; valueSourceWriteFields() — тот же паттерн touched/originalHas/original, что и у valueBadgeWriteFields() (auto = отсутствие поля). Доказано unit (test/device-presentation.test.mjs:920+ «persistence keeps untouched data») и smoke (candidatePresent, draftSourceExact, savedExact, reopenedExact, cancelKeptSource — все true, прогнано лично).
• AC2 (результат на всех рендерерах). resolveDevicePresentation() — единственная функция, которую вызывают preview, полный план и houseplan-space-card; sourceKey/text/fullText формируются один раз в resolveValueSource(). Smoke подтвердил побитовое совпадение preview42, plan42, static42, actionUnchanged (лично прогнано, зелёное). Golden proof отсутствует — см. находку Medium выше.
• AC3 (паритет formatter). resolveValueSource() — общая функция для badge и face; unit-тест «explicit cover position uses the exact value-badge formatter» сравнивает result.valueBadge.text === result.valueText и сверяет источник через valueBadgeCandidates() за тем же ключом.
• AC4 (legacy compatibility). Явный источник читается только если d.marker?.value_source truthy; auto-ветка (resolveValue() без explicitSource) байт-в-байт совпадает с прежним кодом путём climate/temp/ hum/ambiguous/no-state. Тест «explicit unavailable source… without auto fallback» отдельно прогоняет legacy-маркер без поля и получает valueText: null (не dash) — подтверждает, что явная и auto ветки не смешиваются. F09–F12 фикстуры device-presentation-policy.test.mjs не тронуты (только добавлен F18), npm test зелёный на этом SHA.
• AC5 (fail explicit). resolveValueSource(): failure выставляется ровно тогда, когда локальная переменная text осталась null; финальная сборка text: text ?? '—', fullText: text ?? unavailableText гарантирует их взаимоисключение — dash и диагностический код всегда идут вместе, а не вместо друг друга. Убедился мутацией (см. таблицу гейтов): без dash-веточки тест валится по пяти полям. fallbackReason больше не гасится наличием dash-текста (убрано условие !valueText) — специально для explicit-ветки, где текст '—' не null, но диагностика должна остаться видимой; для auto-ветки это изменение поведенчески нейтрально, там text и fallback всегда взаимоисключающи и без этого условия.
• AC6 (независимость). value_virtual-проверка (if (d.virtual) return) стоит раньше чтения value_source — приоритет сохранён кодом, а не только комментарием. lqiText подавляется и при valueBadge?.isLqi, и теперь при value.source?.kind === 'derived_lqi' — покрыто unit-тестом «derived sources share the plan graph and suppress duplicate LQI». Duplicate-hint в диалоге теперь сравнивает badgeSourceKey === innerValueSourceKey, где innerValueSourceKey берётся из единого previewPresentation.valueSource.sourceKey вместо ручной реконструкции — то же наблюдаемое поведение, один источник строки. Touch/pointer путь не тронут структурно (_clickDevice не менялся, только текст .valtext) — проверено чтением, не исполнением отдельного touch-смока; логика тапа общая для обоих устройств ввода.
• AC7 (конфиг и ссылки). Backend: validate_source() — общая функция для value_badge.source и value_source, коды ошибок отличаются префиксом, проверено построчно; delta-validation честно различает changed/unchanged через _matching_previous_marker (rename-tolerant, тест «marker reference and id rename are delta-safe»). Import/export: _drop_invalid_import_marker_links, _repair_target_space_refs, build_space_merge, create_export — все четыре точки reference seam обновлены параллельно уже существующим для value_badge; счётчик MAX_MARKERS * (MAX_CONTROLS + 2) корректно увеличен на 1 (было +1 для одного возможного badge-дропа на маркер, теперь +2 для badge и source). Frontend rebind: rewriteMarkerControlReferences() и _saveMarker() id-rename оба переписывают value_source.ref, тест devices.test.mjs это подтверждает.
• AC8 (preview/Cancel/binding). Смена binding (оба места: virtual-radio и выбор HA-сущности) добавляет valueSource: null, valueSourceTouched: true — единственная точка сброса, найдена и прочитана в обоих местах. Smoke bindingResetToAuto и cancelKeptSource подтверждают оба направления (сброс на смену binding, сохранение при незасейвленной смене source).
• AC9 (локализация/документация). i18n: 5 новых ключей + обновление marker.display_hint_value присутствуют идентично в en/ru/de/fr (сверено построчно диффом). Документация: ARCHITECTURE.md, CONFIG-COMPATIBILITY.md, DEVICE-PRESENTATION.md (новая строка F18 с корректной ссылкой на device-presentation-policy-value/presentation-row-contract, обе строки существуют как реальные тестовые id), USER-GUIDE.md/.ru.md, оба CHANGELOG — в одном коммите с поведением (591f8f6a), трейлер User-Visible: yes на месте. Docs screenshots пересчитаны после rebase на точном SHA 552b78a1 отдельным commit-only-docs коммитом с User-Visible: no — процессуально корректно.
• AC10 (гейты и бюджет). См. таблицу гейтов выше — все обязательные зелёные (частично по ссылке на Validate этого SHA, частично лично прогнаны).
• Трейлеры и процесс. Issue: #378 на каждом коммите класса A/B/C, User-Visible расставлен верно, CHANGELOG в том же коммите, что поведение, branch issue/378-value-face-source, rebase-конфликт (только сгенерированный бандл) разрешён и пересобран без orphan chunks — подтверждено побайтовой сверкой bundle-sync выше.

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

• Не прогонял 31 слабую связь smoke-select с общим именем _markerDialog (полный список — в выводе инструмента выше): диалог устройства используют почти все смоки этого файла не по существу дифа, специфичной для value_source логики в них нет. Решение — не прогонять, риск низкий.
• Не гонял npx tsc --noEmit, npm test, npm run build, python -m pytest tests_backend -q повторно — зелёный Validate на точном SHA 552b78a1 уже это доказал, код с тех пор не менялся.
• Не выполнял ручное тестирование в браузере (вне процесса, п. «оно вообще работает» закрыт код-ревью + автотестами + собственноручно прогнанными smoke/golden выше).
• Не проверял visual regression на конкретном golden-сценарии с явным value_source — он не существует (сама находка Medium).
• Полный performance-профиль не гонял: AC/риски не называют влияние на перф, а изменение — O(1) поиск по уже кэшированному графу; принято по чтению кода.