docs: review document for #323

Issue: #323
User-Visible: no

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

@@ -0,0 +1,176 @@
+# 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.