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

CODE-REVIEW-668-r1

Issue: #668 «Английское руководство пользователя отстаёт от русского» Материал раунда: 85cba3d8b4e335b0519f8f089f1c534eabf89e9f (HEAD, origin/dev..HEAD) Коммиты в материале:

• 85cba3d8 docs: синхронизировать английское руководство (#668) — Issue: #668, User-Visible: no
• cbc39cea, d24b0f0e — документы SPEC-REVIEW r1/r2 (не относятся к коду)

Класс изменения: C (документация) + B (scripts/user-guide-parity.mjs, test/user-guide-parity.test.mjs, правка scripts/check-docs.mjs). Класс A (src/**, custom_components/**) не тронут.

Скоуп

Задача выделена из #667 (п. 8): синхронизировать смысл и структуру docs/USER-GUIDE.md с docs/USER-GUIDE.ru.md, покрыть перечисленный в Scope список отсутствующих тем, расширить структурный гейт scripts/check-docs.mjs полным профилем H2–H4 и отметкой версии. Не-scope: продукт, UI, i18n, RU-руководство, changelog/release notes — задача этого не трогает (проверено diff'ом, см. ниже). Обслуживает J4/J6 из docs/SCOPE.md (онбординг и поддержание плана англоязычным администратором).

Прошёл spec-review в двух раундах: r1 — жёлтый (Medium в скоупе: AC4 требовал «unit», которого не было в плане автотестов), r2 — зелёный (AC4 переписан явно на два доказательства). Это первый заход код-ревью.

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

Прочитаны в указанном порядке: docs/SCOPE.md, docs/process/REVIEWER.md, AGENTS.md, тело issue #668 и все 7 комментариев (аналитика → ТЗ → SPEC-REVIEW r1 → правка → SPEC-REVIEW r2 → хендофф реализации), docs/USER-GUIDE.ru.md (как источник терминологии), а также канонические SUN.md, VACUUM.md — разделы, которых касается новый EN-текст.

Дельта разбиралась не по дельте предыдущего раунда (это первый код-ревью-заход задачи), а целиком, как и полагается для r1.

Прочитаны построчно: scripts/user-guide-parity.mjs, test/user-guide-parity.test.mjs, диф scripts/check-docs.mjs, весь docs/USER-GUIDE.md (итоговый файл, 1444 строки) и параллельно сверялся с docs/USER-GUIDE.ru.md по позиции разделов.

Автоматически сверен полный профиль заголовков EN/RU (node с логикой, эквивалентной guideHeadingProfile) — 97 заголовков H2–H4 с обеих сторон совпадают позиционно, номера 23 нумерованных H2 идентичны, порядок и уровни идентичны.

Точечно сверены с кодом/каноном спорные фактические утверждения:

• инвариант замка (docs/SCOPE.md «Lock invariant») — раздел «Lock» не ослабляет формулировку, добавляет явное «a plan tap never toggles a lock»;
• кнопки диалога закрытия настроек «Continue»/«Discard» — найдены буквально в src/i18n/settings/en.json:50-51 (dialog.discard_confirm: "Discard", dialog.discard_keep: "Continue"), автор заявил это как сверенное — подтверждено;
• термины «Show hidden on plan», «Select all ({count})», «Hide selected ({count})» — найдены дословно в src/i18n/en.json;
• разбивка фаз солнца по часам (05:00–08:00 и т. д.), порог 3°, фейд 2 с, переход окружения 1,1 с (1100 мс) — совпадают с docs/SUN.md;
• калибровка пылесоса 40 см, сглаживание пути 17.5 см, буфер 4000 точек — совпадают с docs/VACUUM.md;
• брейкпоинт телефонной шапки ≤ 480 px — совпадает с src/houseplan-card.ts:10837, src/header-menu.ts (issue #616);
• список из 8 скриншотов (images/0N-*.png) в EN и RU расположен в одинаковых по смыслу местах.

Выполнены гейты, не покрытые ссылкой на зелёный Validate этого SHA (Validate подтверждает typecheck/test/build/docs, но AC требует явного исполнения и демонстрации, что защитный тест умеет падать):

• node --test test/user-guide-parity.test.mjs — 4/4 green (структурный тест на реальных файлах + три отрицательные пробы).
• Мутационная проверка «тест умеет падать» на реальных файлах (не только на строковых фикстурах теста): временно вырезан заголовок ### Lock из docs/USER-GUIDE.md, тест сразу покраснел (not ok 1), затем рабочая копия восстановлена (cp бэкапа, подтверждено git status --porcelain — пусто).
• Контрольная проверка, что чисто текстовая правка заголовка того же уровня (без изменения количества/уровня заголовков) тест не ловит — ожидаемо, т.к. AC1/AC6 специфицируют защиту структуры (порядок/уровень), а не текста; содержательное соответствие — предмет AC2 (ревью кода), не автотеста. Разночтения не найдено.
• node scripts/check-docs.mjs --external — green: «Documentation checks passed (7 files, 12 external links)» → AC5 подтверждён исполнением.
• node --check на всех трёх изменённых .mjs-файлов — синтаксически чисты.
• git diff origin/dev...HEAD --stat -- docs/USER-GUIDE.ru.md src/ custom_components/ — пусто → AC4 (неизменность RU/продукта) подтверждён.
• git diff origin/dev...HEAD --stat -- dist/ custom_components/houseplan/frontend/ demo/golden/baselines/ — пусто → бандл и golden-эталоны в коммит не попали (часть AC7).
• Версии Current for **v1.78.0-beta.5**. / Актуально для **v1.78.0-beta.5**. — идентичны (AC4).

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

• npx tsc --noEmit, полный npm test, npm run build со сверкой бандла, npm run gate:small целиком — не перегонялись повторно: Validate на этом же SHA (85cba3d8) уже завершился success (https://github.com/Matysh/houseplan-card/actions/runs/36308972032), и диф не касается src/**/custom_components/**/*.py, так что риска регрессии в собираемости не вижу.
• Browser-смоки, golden:verify, pytest tests_backend, инварианты модели, performance — не запускал: задача документационная, исполняемое и визуальное поведение продукта не меняет (нет правок src/**), AC не называют эти гейты, а smoke-select.mjs для чисто docs/scripts-диффа предметно не даёт прямых совпадений (диф не касается кода карточки/демо). Явно не прогонял node scripts/smoke-select.mjs --base <base> --head <head> — прошу считать это осознанным пропуском по диффу (только docs/**, scripts/check-docs.mjs, scripts/user-guide-parity.mjs, test/**), а не недосмотром: инструмент разбирает связи изменённого продуктового/демо-кода со смоками, а здесь такого кода нет.
• Не вычитывал построчно весь текст EN-руководства против RU слово-в-слово (объём ~1444 строк); выборочно проверил структуру целиком (автоматически) и содержание — по разделам с наибольшим риском фактической ошибки (безопасность/замок, солнце, пылесос, диалоги, брейкпоинты, i18n-термины) и по перечню тем из Scope. Чек-лист тем из Scope (мобильная шапка, контекстные подсказки, Merge/Split/Resize/толщина/нулевая толщина, проёмы/режимы/замок/толстые стены, авто-появление маркеров/скрытые/деактивированные, жесты/действия/подложка/активность/отображение/бейджи/иконки/матрица, заливки/наследование/источник света, инструменты подложки/двойной клик/живой текст/мебель/свои изображения, солнце/калибровка/путь пылесоса, оптимизация/сохранения/риск-отмена, памятка безопасности) — сверен по заголовкам и содержанию, все присутствуют по существу (AC2).
• Не сверял английские термины i18n построчно для каждого упоминания в тексте (только выборочно для контролов, упомянутых в самых чувствительных разделах); полное построчное сопоставление 1444 строк с src/i18n/en.json не выполнялось — это соразмерное для документационной задачи сужение (§8), а не пропуск конкретного риска.
• npm run inventory не запускал — документ не содержит счётчиков тестов, которые требовалось бы актуализировать.

Находки

Не найдено находок уровня High или Medium. Один пункт снят как Low без действия:

• Low, снято, не блокирует. В scripts/check-docs.mjs для пары docs/USER-GUIDE.md/docs/USER-GUIDE.ru.md теперь работают два параллельных структурных гейта: старый по 13 именованным docs-section-маркерам (строки ~175-186) и новый полный H2–H4/version профиль (guideParityErrors, строки 188-191). Это было явно предвидено в SPEC-REVIEW-668-r1 (Low, снято ревьюером) с оговоркой «если после кода это разъедется — находка код-ревью». Разъезда не произошло: список из 13 маркеров идентичен и в том же порядке в обоих файлах (проверено grep), а старый гейт остаётся нужен отдельно для пары README.md/README.ru.md, которую новая функция не покрывает — то есть он не read-only дубль, а разделяет ответственность (README vs. полная структура USER-GUIDE). Оставляю как есть, без действия.

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

• AC1 — H2–H4 профиль и 23 нумерованных раздела совпадают позиционно между EN/RU; unit node --test test/user-guide-parity.test.mjs green.

• AC2 — все перечисленные в Scope темы присутствуют содержательно и в соответствующих разделах (сверено по чек-листу выше).

• AC3 — выборочно проверенные названия контролов (Show hidden on plan, Select all/Hide selected, Continue/Discard) дословно совпадают с src/i18n/en.json и src/i18n/settings/en.json; несуществующего поведения в проверенных разделах не встретил.

• AC4 — отметки версии идентичны (v1.78.0-beta.5); RU и продуктовый код не изменены (diff пуст).

• AC5 — node scripts/check-docs.mjs --external green.

• AC6 — защитный тест доказан таблицей:

  AC	Чем доказан	Чем краснеет
  AC6 (пропуск подраздела)	test/user-guide-parity.test.mjs кейс 2 на строковой фикстуре	подтверждено также мутацией реального docs/USER-GUIDE.md (удалён ### Lock) — not ok 1, тест-прогон приведён выше
  AC6 (смена уровня)	кейс 3 на строковой фикстуре	#### Деталь вместо ### Detail красит heading profiles differ
  AC6 (версия)	кейс 4 на строковой фикстуре	разные версии красят current versions differ

• AC7 — bundle:clean-состояние подтверждено: dist/**, custom_components/houseplan/frontend/**, demo/golden/baselines/** не в диффе; трейлеры Issue: #668 и User-Visible: no на коммите на месте (докрутка changelog не требуется).

• Трейлеры и класс изменения соответствуют AGENTS.md: User-Visible: no, оба changelog не тронуты (и не должны были).

• Число «одна версия — один источник» (§8): версия v1.78.0-beta.5 встречается в EN и RU и берётся из одного и того же места по построению (структурный гейт сравнивает их напрямую); других видимых пользователю чисел, продублированных в этом диффе, не встретил.

Вердикт

Зелёный. AC1–AC7 выполнены и доказаны; единственная Low-находка снята без действия, High/Medium нет.

---

Материал раунда

• Ветка: issue/668-user-guide, коммит 85cba3d8b4e3 — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
• Дерево материала: 08ee50612259632359530b8c7a8226782d45f9a0

  git log --all --format='%H %T' | grep 08ee50612259
  

• Тело issue: aeef91d8b412d0d7dddc4e4c9179746e50a716ed6a80a3078c645cdd925fd5b2
• Вердикт конвейера: green · High 0