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

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

SHA материала: 69facb991882b336a8e4122abf7733faec56d5ba (после ребейза конвейером: fec74ff3 → 69facb99, поверх легло 1 коммит dev; предыдущего верхнего коммита в родословной ветки нет — это исходный ребейз перед первым циклом ревью, разбор полный).

Трек: trivial (§5.1). AC зафиксированы автором в теле issue при переводе в S5-ready:

1. бейдж HACS-Custom → HACS-Default (README.md, README.ru.md);
2. секция установки — вместо «⋮ → Custom repositories» обычный поиск «House Plan» в HACS; my-кнопка, перезапуск, добавление интеграции и заметка про Lovelace-ресурс сохраняются.

Класс изменения: C (документация), без кода — src/**, custom_components/**/*.py не тронуты.

Скоуп диффа

README.md       | 11 ++++++-----
README.ru.md    | 12 +++++++-----
docs/STATUS.md  |  2 +-
docs/TESTING.md |  2 +-
4 files changed, 15 insertions(+), 12 deletions(-)

Два коммита, оба с трейлерами Issue: #323 / User-Visible: no:

• 343af61a — README.md + README.ru.md: бейдж и секция установки;
• 69facb99 — попутно найденные устаревшие места: строка HACS в docs/STATUS.md (описывала очередь из 835 PR) и пункт установки в docs/TESTING.md (начинался с custom repository).

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

AC — по коду (docs), проверено чтением

• AC1 (бейдж). README.md:3 и README.ru.md:3 — HACS-Custom → HACS-Default, URL и alt-текст остались консистентны с прежним статичным shields.io-бейджем (не live-бейдж, разница только в тексте/подписи). Выполнено.
• AC2 (секция установки). README.md:88-95, README.ru.md:91-99 — шаги «⋮ → Custom repositories» / «добавьте URL» убраны, заменены на «найдите House Plan в поиске HACS и установите»; my-кнопка (my.home-assistant.io/.../hacs_repository), шаг перезапуска, шаг «Add integration → House Plan» и абзац про ручную регистрацию Lovelace-ресурса (resources: /houseplan_files/houseplan-card.js) сохранены дословно. Выполнено. Проверено чтением, не исполнением (docs-only, поведения карточки правка не касается).

hacs.json.name = "House Plan (card + storage)" — поиск по подстроке «House Plan» в HACS находит запись; формулировка в README не вводит пользователя в заблуждение.

Гейты — прогнаны

Гейт	Команда	Результат
Typecheck	npx tsc --noEmit	зелёный, без вывода
Unit-тесты	npm test	зелёный: 1358 объявлено, 1357 pass, 1 skipped, 0 fail
Build	npm run build	зелёный, dist/houseplan-card.js собран за 9.3s
Синхронность трёх копий бандла	git status --short после build	пусто — dist/, custom_components/houseplan/frontend/, demo/srv/assets/ не тронуты и не разошлись (класс D не менялся, дифф его и не затрагивал)

Три гейта прогнаны, потому что они всегда дешёвые и прогоняются в каждом раунде независимо от объёма диффа — их результат актуален именно для 69facb99, не унаследован.

Гейты — не прогонялись, и почему

• node scripts/check-docs.mjs — не нужен: диплом не трогает src/**, отпечаток скриншотов не может устареть от правки в README/STATUS/TESTING.
• npm run invariants -- --config … — геометрия, layout, толщина стен, marker.space, open_spans диффом не затронуты.
• Браузерные смоки (demo/smoke_*.mjs) — диплом не меняет ни одной видимой в карточке строки или поведения; node scripts/smoke-select.mjs не запускал, т.к. измененные символы — это markdown-текст README/STATUS/ TESTING, а не код/тесты, по которым инструмент ищет связи. Смоки рендерят demo/srv/demo.html, README/STATUS/TESTING в это дерево не попадают.
• npm run golden:verify — рендер, геометрия и стили не менялись.
• python -m pytest tests_backend -q — custom_components/**/*.py не тронут.
• Perf-профили — не названы в AC, geometry/perf-пути не задеты.

Находки

Medium — В СКОУПЕ задачи

M1. docs/USER-GUIDE.md и docs/USER-GUIDE.ru.md не обновлены и противоречат исправленному README.

Обе версии полного руководства (на которое README ссылается как на «Full user guide» / «Полное руководство», и куда RU-README прямо отправляет за «пошаговыми сценариями») в разделе «HACS» / «Установка через HACS» по‑прежнему учат добавлять репозиторий вручную:

docs/USER-GUIDE.md:82-83
1. Add `https://github.com/Matysh/houseplan-card` to HACS as a custom
   **Integration** repository.

docs/USER-GUIDE.ru.md:82
1. В HACS добавьте `https://github.com/Matysh/houseplan-card` как
   пользовательский репозиторий категории **Integration**.

Воспроизведение: пользователь читает README → видит «House Plan is in the HACS default catalog — no custom repository needed», переходит по ссылке «Full user guide» за подробностями → получает противоположную и устаревшую инструкцию (добавить custom repository вручную) в том же самом разделе «HACS». Это ровно та проблема, которую issue #323 ставит целью убрать («лишние шаги, которых больше не требуется»), просто в соседнем файле того же класса C.

Автор этой же ветки уже расширял скоуп за пределы «только README»: коммит 69facb99 правит docs/STATUS.md и docs/TESTING.md как «попутно найденные устаревшие места» — тот же тип дефекта (стале-упоминание custom-repository потока), тот же класс C. USER-GUIDE — тот же случай, не пойманный при том же самом sweep (вероятная причина: непрямое совпадение по тексту — «custom Integration repository» с жирным между словами в EN и строчная «пользовательский» без грепаемого «HACS-Custom» в RU, — оба ускользают от точного grep по фразе «custom repository»).

Без этой правки задача не решает заявленный сценарий полностью: у пользователя остаётся действующий (и более заметный, т.к. это «полное руководство») путь к устаревшей инструкции.

Что делать: привести шаг 1 в обоих docs/USER-GUIDE*.md к тому же виду, что и в README (поиск в HACS вместо добавления custom-repository), в рамках этого же issue — Medium в скоупе, отдельный issue не заводится (#202).

Других мест с той же формулировкой не нашлось (проверено grep -rniE "custom.{0,20}repositor|HACS-Custom|пользовательск\S*\s+репозитор" --include="*.md" ., исключая CHANGELOG и node_modules; docs/DEVELOPMENT.md, CONTRIBUTING.md чисты).

Проверено и корректно

• Бейдж и секция установки в обоих README согласованы между собой (EN/RU), порядок шагов и сохранённые фрагменты (my-кнопка, restart, add integration, YAML-ресурс) идентичны прежним, кроме заменённого шага.
• docs/STATUS.md HACS-строка и docs/TESTING.md install-чеклист приведены в соответствие факту (hacs/default#9004 merged 2026-08-25) без потери информации (post-merge checklist сохранён).
• Трейлеры Issue: #323 / User-Visible: no на обоих коммитах корректны: продукт (карточка/интеграция) не меняется, значит changelog не требуется.
• docs/CHANGELOG.md / docs/CHANGELOG.ru.md не тронуты — согласуется с User-Visible: no.
• Диплом не трогает dist/**, custom_components/houseplan/frontend/**, demo/golden/baselines/** (класс D) — верно для чисто текстовой правки.
• «Одно число — один источник»: числовых пользовательских величин дифф не вводит и не меняет, правило не применимо к этому диффу за вычетом M1, которое устройство ровно того же типа дефекта, но текстовое, а не числовое.

Чего не проверял (и осознанно)

• Живой поиск «House Plan» в HACS UI — недоступен в окружении ревьюера (нет запущенного HA/HACS-инстанса); утверждение принято по ссылке на hacs/default#9004 (merged, зафиксировано владельцем в чате 2026-08-27, процитировано в теле issue) и по hacs.json.name.
• Скриншоты/докс-фингерпринт — не проверялись, т.к. src/** не тронут и check-docs.mjs не применим (см. таблицу гейтов выше).
• Отсутствие меты типа (bug/feature/tech-debt) на issue #323 при наличии trivial — замечено (§5.1 требует тип bug в списке критериев короткого трека), но это принятое владельцем в S2-analysis решение (владелец лично перевёл в S5-ready и взял в работу), не предмет код-ревью и не блокирует; не выношу отдельной находкой.

Вердикт

High: 0. Medium: 1, в скоупе задачи (M1) — чинится в этом же issue. Полный набор AC доказан, но задача не закрывает сценарий целиком, пока второй документ с теми же инструкциями противоречит первому — поэтому вердикт жёлтый, а не зелёный, несмотря на 0 High.