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

# CODE-REVIEW-348-r1

- **Issue:** #348 — i18n: добавить полную немецкую локализацию интерфейса
- **Ветка / SHA на момент ревью:** `issue/348-german-localization` · `837acec7475270c657962f7480d61559908d824c`
- **ТЗ:** `docs/specs/348-german-localization.md`, ревью ТЗ зелёное (`docs/reviews/SPEC-REVIEW-348-r1.md`)
- **Заход:** r1 · блокирующих циклов израсходовано 0/4
- **Материал:** `git log --oneline origin/dev..HEAD` (4 коммита) и `git diff origin/dev...HEAD` (52 файла)

Ветка перед ревью была ребейзнута конвейером на `origin/dev` (только doc/asset-конфликты
в сгенерированных деревьях, разрешённые пересборкой). Merge-base с `origin/dev` совпадает
с текущим `origin/dev` tip — это первый настоящий разбор кода задачи, полный, не по
дельте (§7.2, §2.10 к этому раунду неприменим: цикл первый).

## 1. Скоуп

Четыре коммита:

1. `f2024fae` docs: specify German localization — ТЗ (класс C, `User-Visible: no`)
2. `60c68376` docs: review document for #348 — артефакт ревью ТЗ (класс C, `User-Visible: no`)
3. `d0a3077d` feat: add complete German localization — вся продуктовая правка
   (класс A/B/D, `User-Visible: yes`, оба changelog в этом же коммите)
4. `837acec7` fix: keep locale gate within view budget — правка после первого
   упора в initial-View budget (класс A/B/D, `User-Visible: no`, обоснованно: только
   внутреннее объединение двух WeakSet-трекеров в один, видимого поведения не меняет)

Трейлеры на всех четырёх корректны (`Issue: #348`, ровно один `User-Visible:`),
`User-Visible: yes` идёт вместе с правкой обоих `docs/CHANGELOG*.md` в одном коммите
(`d0a3077d`). Ветка `issue/348-german-localization` соответствует номеру issue.

## 2. Как проверялось — таблица гейтов

| Гейт | Команда | Результат |
|---|---|---|
| Typecheck | `npx tsc --noEmit` | green, 0 ошибок |
| Unit/tooling | `npm test` | green — 1457 тестов, 1456 pass, 1 skipped, 0 fail (`npm run inventory` подтверждает те же 1457) |
| Build + bundle sync | `npm run build && npm run bundle:sync` | green; `cmp dist/houseplan-card.js custom_components/houseplan/frontend/houseplan-card.js` — идентичны; `diff -rq dist/houseplan-assets custom_components/houseplan/frontend/houseplan-assets` — пусто |
| Budget | `npm run bundle:budget` | green — initial View **255 986 / 256 000 B** gzip (запас всего 14 B, см. находку L2 ниже), lazy editor 131 831 B, lazy locale 21 875 B |
| Docs fingerprint | `node scripts/check-docs.mjs` | green — «Documentation checks passed (7 files, 10 external links)» |
| Smoke-selector | `node scripts/smoke-select.mjs --base origin/dev --head HEAD` | НЕОПРЕДЕЛЁННОСТЬ — инструмент не подтвердил связь с `smoke_german_locale.mjs` вопреки записи в `scripts/smoke-links.mjs`; прогнал целевой смок напрямую, т.к. он назван в AC3-AC5 |
| Целевой smoke | `node demo/smoke_german_locale.mjs` | green — все 8 assertions (см. §3) |
| golden:verify | `npm run golden:verify` (полный набор — визуальный diff во многих файлах i18n) | 129 passed, 2 `missing-baseline` — новые German-сцены (ожидаемо, приёмка эталонов не входит в код-ревью), **4 `different` + 3 `missing-baseline`** на НЕ-немецких сценах — см. §4, подтверждено не багом этой задачи |
| Backend | `python -m pytest tests_backend -q` | **не прогнан** — в этом окружении нет `pytest`/`.venv-backend`; продуктовый `.py`-код не менялся (только новый `custom_components/houseplan/translations/de.json`), его key/placeholder-парность с `en`/`ru` доказана Node-тестом (`test/i18n.test.mjs`, «backend dictionaries preserve the English structure and placeholders»), прошедшим в `npm test` |
| `git diff --check` | `git diff --check origin/dev...HEAD` | green |
| Model invariants | — | не применимо: diff не трогает геометрию, `layout`, `marker.space`, `open_spans` или толщину стен |

## 3. AC — разбор

- **AC1 (полный key set).** `npm test` → `i18n: every registered dictionary carries the
  English key set`, `i18n: registry matches frontend and backend locale files`,
  `i18n: backend dictionaries preserve the English structure and placeholders`,
  `i18n: placeholders match between languages`, `i18n: every literal help call has body
  and full aria keys in both languages` — все green против реального `de.json` (загружен
  через `ensureLanguage`/`dictionaryFor`, не мимо registry). **Доказано автотестом.**
- **AC2 (locale resolution).** `test/i18n.test.mjs` покрывает `de`, `de-DE`, `de-AT`,
  `de-CH`, explicit `de`, неизвестную locale → `en`. **Доказано автотестом**, тест умеет
  падать: изменил ожидание `de-CH → de` на `en` локально — тест красный, вернул обратно.
- **AC3 (нет смешанного UI).** `demo/smoke_german_locale.mjs` проверяет `btn.save`,
  `btn.cancel`, `space.header`, `lang="de"` на живом `houseplan-card` (View + device
  dialog через `deviceLightControls`). Wiring в `editor.ts`/`space-editor.ts`/
  `space-card.ts` — идентичный трёхстрочный паттерн (`languageRenderGate` + тот же
  `LANGUAGE_RUNTIME`), **проверено чтением, не исполнением**: браузерным смоком покрыт
  только `houseplan-card`, три остальные корневые поверхности (space-card, оба GUI
  editors) — нет. Риск низкий (общая функция, общий runtime, никакой специфики на
  поверхность), но это не автотест.
- **AC4 (без flash).** Cold-путь доказан и юнитом (`LanguageRuntime`/`languageRenderGate`
  в `test/i18n-runtime.test.mjs`), и браузером (`germanColdFrameIsNeutral`,
  `germanCopyCommitsAtomically`). Warm-путь (существующий закоммиченный кадр + смена
  языка на уже смонтированном элементе) доказан юнитом на фейковом хосте и **проверен
  чтением** механизма `noChange` (`node_modules/lit-html`: top-level `render()` явно
  бейлится на `noChange`, значение возвращается прямо из `LitElement.render()` и
  доходит до него без директивы-обёртки — путь корректен), но ни один браузерный тест не
  проверяет его на реальном, уже отрисованном компоненте (`replaceWithGermanCard` в смоке
  всегда создаёт новый элемент, то есть всегда cold). Не блокирую (механизм подтверждён
  чтением библиотеки), отмечаю как L3.
- **AC5 (без deadlock).** Юнит `test/i18n-runtime.test.mjs` — dedupe, retry-once,
  warn-once, fingerprint mismatch — против generic `LanguageRuntime`. Продакшн-синглтон
  `LANGUAGE_RUNTIME`/`settleGerman()` в `src/i18n/registry.ts` — независимая ручная
  реализация того же контракта (см. L1), но её ровно эти сценарии — dedupe
  (`germanLoadsExactlyOnce`, `secondCardReusesPageLocale`), bounded retry
  (`failureRetriesExactlyOnce === 2`), fallback (`failureFallsBackAndUnblocks`),
  warn-once (`failureWarnsOnce`) — прогнаны и зелёные в `demo/smoke_german_locale.mjs`
  против настоящего собранного бандла с перехватом сети (delay/abort). **Доказано.**
- **AC6 (perf/budget).** `npm run bundle:budget` — initial View 255 986/256 000 B,
  German полностью в `lazyLocaleFiles`, EN/RU остаются в initial графе без обращения к
  `de-*.js` (подтверждено смоком: `englishColdViewDoesNotRequestGerman`). **Доказано.**
- **AC7 (доставка).** `dist/houseplan-assets.json`/`custom_components/.../houseplan-assets.json`
  содержат `lazyLocaleFiles: ["houseplan-assets/de-*.js"]` отдельно от
  `lazyEditorFiles`/`lazyOnboardingFiles`; `test/bundle-assets.test.mjs` покрывает и роль,
  и retry-URL подстановку. **Доказано автотестом.**
- **AC8 (layout/a11y).** **Не доказано автоматизированно** — см. Medium-находку M1.
  Golden-сцены для German существуют в `demo/golden/matrix.mjs`
  (`device-dialog-desktop-de`, `german-view-mobile-light`), но у них по канону ещё нет
  эталона (`missing-baseline`, приёмка — предрелизный шаг, не код-ревью), а обещанного
  ТЗ (§11) smoke-измерения переполнения нет вовсе.
- **AC9 (EN/RU compatibility).** `npm test` green (1456/1457), `demo/smoke_german_locale.mjs`
  подтверждает EN не запрашивает de-чанк. Единственная содержательная правка
  рендер-контракта — добавление `!this.hass` в раннюю проверку `space-card.ts`/
  `space-editor.ts` (было только `!this._config`) — **проверено чтением**: в реальном
  жизненном цикле Lovelace/демо-стенда `hass` приходит одновременно с `config`, до этой
  правки язык вообще нельзя было определить без `hass` для gate; риск регрессии низкий,
  автотеста на этот конкретный переход нет.
- **AC10 (документация).** Оба changelog, `CONTRIBUTING.md`, `docs/ARCHITECTURE.md`,
  `docs/TESTING.md`, `docs/USER-GUIDE.md`/`.ru.md`, `docs/specs/README.md` — все правки
  на месте, ссылка на #348 есть, `check-docs.mjs` зелёный. **Доказано.**

## 4. Находки

### Medium (в скоупе — возврат автору, отдельный issue не заводится)

**M1. AC8 не имеет обещанного в ТЗ smoke-доказательства «нет overflow».**
`docs/specs/348-german-localization.md` §11 прямо обещает: «German 390 px golden: …
отсутствие overflow измеряется smoke, а не только глазами». Немецкие строки
систематически длиннее английских — это явный риск, названный в самом ТЗ (раздел 13).
Прогнал существующий обобщённый смок `demo/smoke_dialog_footer_width.mjs` — единственный
инструмент в проекте, который уже умеет мерить ширину футера диалога по языкам — и он
**не был расширен на `'de'`** (`for (const language of ['en', 'ru'])`, `grep -n "'de'"`
пусто). Новый `demo/smoke_german_locale.mjs` (единственный файл, где вообще встречается
`'de'` среди `demo/smoke_*.mjs`) не содержит ни одного измерения ширины/scroll/overflow
(`grep -n "scrollWidth\|clientWidth\|getBoundingClientRect\|overflow"` — пусто). Golden-
сцены для German существуют, но у них ещё нет эталона, и даже после приёмки golden — это
визуальное сравнение «на глаз» между эталоном и кадром, а не измеренный порог, который
явно обещан текстом ТЗ. Итог: до пре-релизного golden-принятия у AC8 нет ни одного
пройденного автоматического доказательства «German не ломает layout» — заявленный в
собственном плане тестов инструмент не построен.
*Воспроизведение:* `grep -n "'de'" demo/smoke_dialog_footer_width.mjs` → нет вхождений;
`grep -n "overflow\|scrollWidth\|clientWidth" demo/smoke_german_locale.mjs` → нет
вхождений.
*Как чинится в скоупе:* добавить `'de'` в цикл языков `smoke_dialog_footer_width.mjs`
(тривиально — тот же формат вызова, что уже есть для en/ru) **или** добавить в
`smoke_german_locale.mjs` явную метрику (например `scrollWidth <= clientWidth`) на
представительном диалоге при 390 px. Любой из двух вариантов закрывает находку.

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

**L1.** `src/i18n/language-runtime.ts` определяет полноценный переиспользуемый класс
`LanguageRuntime` (dedupe/cache/bounded-retry/fingerprint), который юнит-тестируется в
`test/i18n-runtime.test.mjs`, но в продакшене **не используется** — `src/i18n/registry.ts`
реализует тот же контракт вручную и отдельно (`settleGerman`, `germanPending`,
`germanFailed`), жёстко привязанным к одному языку `de`. Дублирование логики без общего
источника истины. Реальный риск снят: production-объект `LANGUAGE_RUNTIME` покрыт
end-to-end браузерным `demo/smoke_german_locale.mjs` (dedupe/retry/fallback/warn-once —
все проверены против настоящего бандла), поэтому не блокирую, но при добавлении
четвёртого языка стоит либо удалить неиспользуемый класс, либо действительно завести его
в `registry.ts` вместо копии логики.

**L2.** Initial View budget после follow-up-коммита — **255 986 / 256 000 B gzip**, запас
14 байт из 256 000. Гейт `bundle:budget` корректно упадёт при малейшей будущей регрессии,
это не дефект задачи, но подушка настолько мала, что практически любая следующая правка
`houseplan-card.ts` потребует новой чистки. Не в скоупе #348 — фиксирую как риск для
следующего изменения.

**L3.** `scripts/bundle-manifest.mjs`: классификация `editorRoots`/`onboardingRoots`/
`localeRoots` сменилась с «всё, что не onboarding — editor» на позитивный список (роль
модуля **или** regex имени файла). Проверил на реальном `dist/houseplan-assets.json` — все
4 текущих dynamic root корректно попадают ровно в одну применимую категорию, живого
дефекта нет. Но конструкция теперь «тихо роняет» будущий пятый тип lazy-root, если он не
совпадёт ни с одной ролью/regex: он останется в `lazyFiles`, но не попадёт ни в
`lazyEditorFiles`, ни в `lazyOnboardingFiles`, ни в `lazyLocaleFiles`, без ошибки. Не
блокирую (это гипотетический будущий случай, не изменяет корректность на этом diff'е).

**L4.** Удалённые из `en.json`/`ru.json` ключи (`title.add_device`, `title.show_all`,
`title.markup_opening`, `marker.preview.demo_activity/demo_notice`, `confirm.merge_rooms`,
`toast.contour_min_edges`, `room.split_header`, `space.orientation`/`orient.*`,
`space.temp_min/max`, `devbar.add/show_all`, `tap.cover`, `confirm.tap_cover`,
`editor.lang_en/ru`) проверены построчным grep по `src/**`, `test/**`, `demo/**` — кроме
одного случая, все действительно мертвы в текущем коде (уже заменены на другие ключи в
более ранних, не связанных с #348 коммитах `dev`). Исключение: `title.add_device`
по-прежнему встречается как строковый литерал в **не тронутом этой задачей** смоке
`demo/smoke_editor_tabs.mjs:168` (`c._t('title.add_device')` внутри assertion
`headerCleanInDev`). Сам ассерт не падает (проверяет отсутствие селектора, а буквальный
ключ-заглушка никогда не совпадёт), но проверяет уже не то, что задумано — тихая деградация
чужого теста. Это застарелая проблема самого `smoke_editor_tabs.mjs` (девбар давно
переехал на `device_inbox.*`, комментарий в тесте уже ссылается на другой issue, #29),
#348 её не создаёт, а лишь убирает последний живой символ. Вне скоупа задачи, оставляю с
записью, не для отдельного issue (стоимость правки — одна строка, но правка чужого файла
не входит в #348).

## 5. Отдельно проверено и не является находкой этой задачи

**Golden-регрессии `geometry-devices-editor-dark`, `device-dialog-mobile-ru`,
`toggle-entity-dialog-mobile-ru`, `device-ripple-color-popover-mobile-ru` (`different`) и
`device-inbox-desktop-en-light`, `device-inbox-desktop-ru-dark`,
`device-inbox-narrow-ru-dark` (`missing-baseline`).** Первая реакция — заподозрить, что
German-изменение сломало рендер девбара (просмотр diff-картинки `geometry-devices-
editor-dark` показал наложенный друг на друга текст на месте кнопок «Add» / «Hidden and
disabled», которые в актуальном коде уже заменены на единую кнопку `device_inbox.*`).
Проверил происхождение: смёрджил рабочий `origin/dev` (`3c6b473c`, тот самый единственный
коммит, на который конвейер перебазировал ветку) в отдельный `git worktree`, собрал его
изолированно (тот же `node_modules`) и прогнал `golden:verify` — **тот же самый набор**
`different`/`missing-baseline` воспроизводится один-в-один на чистом `dev`, без единого
коммита этой задачи. Причина — более ранний, не связанный с #348 коммит
`cab8d128 feat: add device lifecycle catalog`, у которого golden-эталоны ещё не приняты
(отсюда и `--expect-new`-инфраструктура в этой же ветке dev, #350). Это дефект,
существовавший в `dev` до открытия #348, эта задача его не создаёт и не обязана чинить;
не заводится и как отдельный issue этим ревью — он либо уже отслежен по своей задаче, либо
всплывёт на приёмке golden, где и положено фиксировать пробелы `--expect-new`.

**Обратная связь ТЗ ↔ инфраструктура #62.** `LANGUAGE_REGISTRY`, `resolveLanguageCode`,
typed lazy/eager entry — используются ровно так, как описано в принятом ТЗ; сверено с
исходным API #62 по факту (не по слову автора).

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

- **`python -m pytest tests_backend -q`** — не прогнан: в этом окружении нет `pytest`/
  `.venv-backend`. Продуктовый Python не менялся (только `custom_components/houseplan/
  translations/de.json`); его структурная/placeholder-парность с `en`/`ru` доказана
  Node-тестом, HA-специфичный backend translation API (загрузка через реальный HA) —
  предрелизный/CI-гейт по канону (AGENTS.md: «Windows не может запустить полный HA-
  harness», здесь его тоже нет).
- **`npm run golden:accept`** — не запускал: не входит в код-ревью по канону (принятие
  эталонов — предрелизный шаг с полным Linux CI артефактом).
- **Полный набор `demo/smoke_*.mjs` (196 файлов)** — не прогонял целиком: диффа
  недостаточно широк (`smoke-select.mjs`: 29 изменённых символов, порог «широкого» — 39),
  прогнал только AC-named `smoke_german_locale.mjs` плюс изучил (без прогона)
  `smoke_dialog_footer_width.mjs`, `smoke_editor_tabs.mjs` для находок M1/L4.
- **Браузерные проверки `houseplan-space-card`, GUI editor `houseplan-card`, GUI editor
  `houseplan-space-card` в German** — не прогонял (нет смока, нацеленного именно на них);
  заменил чтением идентичного паттерна wiring (AC3, AC4 выше).
- **Performance-профили** — не запускал: ни ТЗ, ни AC не называют profiler/perf-путь
  затронутым сверх bundle-budget, который прогнан.

## 7. Вердикт

High: 0. Medium: 1, в скоупе задачи (M1) — возврат автору, отдельный issue не заводится.
Low: 4, приняты с записью (L1–L4), правки не требуют.

**Жёлтый.** AC1–AC3, AC5–AC7, AC9, AC10 доказаны; AC4 доказан для критического (cold)
пути и обоснован чтением для warm-пути; AC8 — единственный AC, чьё собственное ТЗ
обещало smoke-измерение переполнения, а получил только (ещё не принятый) golden-эталон.
Это конкретный, дешёво устранимый пробел, а не признак нерабочей реализации в целом.