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

# SPEC-REVIEW-348-r1

- **Issue:** https://github.com/Matysh/houseplan-card/issues/348
- **Этап:** spec (PROCESS.md §2.4)
- **Заход:** r1 (первый и единственный документ ревью на этот issue)
- **Ветка / SHA материала:** `issue/348-german-localization` @ `2e650a02`
  (один коммит `docs: specify German localization` поверх `dev`@`918fc9e2`)
- **Трек:** полный (обоснование в S2-analysis корректно: несколько
  поверхностей, новый языковой/loading UX-контракт, влияние на perf budget
  и touch — критерии §5 не проходят одновременно)
- **Вердикт: зелёный**

## Скоуп ревью

Диф `origin/dev..origin/issue/348-german-localization` — только класс C:

```
docs/specs/348-german-localization.md | 385 +++++++++++++++++++++++++
docs/specs/README.md                  |   1 +
```

Продуктового кода нет, гейты code-уровня (`typecheck`/`test`/`build`) к
предмету ревью неприменимы — это ревью текста ТЗ, а не кода. Ниже —
раздел «Гейты и проверки» с тем, что фактически было прогнано для проверки
технических утверждений документа.

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

Ревью состязательное: документ прочитан целиком, каждое проверяемое
техническое утверждение сверено с реальным состоянием `origin/dev`, а не
принято на слово автора.

1. **Зависимость #62.** Проверено `gh issue view 62` — `S8-merged`, то есть
   инфраструктура (typed registry, locale resolution, parity gates) уже в
   `dev`, а не гипотетическая. Прочитан `src/i18n/registry.ts`: `LANGUAGE_REGISTRY`,
   `resolveLanguageCode` (exact → primary → fallback), `languageOptions` —
   контракт locale resolution, который ТЗ обещает не менять, действительно
   существует в описанном виде.
2. **Бюджет initial View.** Число «255 910 B gzip из 256 000 B» — не
   принято на веру: собран бандл с `origin/dev` (`npm run build` +
   `node scripts/bundle-budget.mjs`), результат:
   `initial View: 255910 B gzip`, `lazy editor: 131779 B gzip` — **точное
   совпадение** с ТЗ, включая экстремально узкий запас (90 B). `INITIAL_VIEW_GZIP_BUDGET
   = 256_000` подтверждён в `scripts/bundle-budget.mjs`.
3. **Классификация lazy-групп в манифесте.** Прочитан
   `scripts/bundle-manifest.mjs`: сейчас ровно два динамических класса
   (`lazyOnboardingFiles` по имени чанка, всё остальное — `lazyEditorFiles`).
   Требование ТЗ добавить третий класс `lazyLocaleFiles` — реальное изменение
   этого файла, и он прямо назван в §12 «Затронутые файлы» — не забыт.
4. **Прецедент lazy-loading + bounded retry.** Найдены
   `EDITOR_RETRY_ASSET_TOKEN` / `ONBOARDING_RETRY_ASSET_TOKEN` в
   `scripts/bundle-manifest.mjs` и рабочие `await import('./houseplan-editor-runtime')`
   / `import('./houseplan-onboarding-runtime')` в `src/houseplan-card.ts`, а
   также браузерный тест `demo/smoke_lazy_editor_chunk.mjs` с перехватом
   маршрута (`page.route`). План §6 (dedupe, page-lifetime cache, bounded
   retry, fail-open English, fingerprint) и план тестов AC4/AC5 (задержанный
   импорт, provoked failure) — не фантазия, а расширение уже работающего в
   продукте паттерна на новый субъект (locale вместо editor/onboarding).
5. **Терминология и реальность строк.** Проверены по `src/i18n/en.json`
   ключи, стоящие за глоссарием ТЗ: `markup.partition` → «Partition»,
   `markup.column` → «Column», `space.zero_wall_style` → «Zero-thickness
   walls», `decor.fill` → «Fill», `space.glow_enabled`/`marker.glow_radius_label`
   → «Glow» и т.д. — термины глоссария не изобретены, они соответствуют
   реальным строкам продукта. Сверено с `docs/USER-GUIDE.ru.md`: «Space» →
   «Пространство» в действующей русской терминологии, немецкое «Bereich» не
   противоречит смыслу.
6. **Мёртвые legacy-ключи.** `editor.lang_en` / `editor.lang_ru` в
   `src/i18n/en.json` существуют и не встречаются больше нигде в `src/*.ts`
   и `test/*.mjs` — заявление §7 «доказанно неиспользуемые» подтверждено
   поиском, а не принято на слово.
7. **Backend translations.** `custom_components/houseplan/translations/en.json`
   реально содержит только `config`/`options`/`issues` — соответствует §3.1
   («config flow, options flow и repair issue»).
8. **CONFIG-COMPATIBILITY.md** не упоминает `language` вовсе — подтверждает
   заявление ТЗ «`language` остаётся строковым полем без изменения schema и
   миграции», а не пропуск темы.
9. **390 px как канонический touch-viewport.** Подтверждено по
   `demo/smoke_*.mjs` (`card_controls`, `color_picker`, `gear_tabs`,
   `plan_picker` и др. используют `width: 390`) — ссылка ТЗ на этот размер
   в §8 не выдумана.
10. **Существование release-артефактов.** `docs/USER-GUIDE.md`,
    `docs/USER-GUIDE.ru.md`, `docs/TESTING.md`, оба `CHANGELOG*.md`
    существуют — §12/§15 указывают на реальные файлы.
11. **Обязательные разделы §7.1 PROCESS.md.** Сценарий (§1), что человек
    увидит до/после (§2), скоуп/не-скоуп перевода (§3), контракт поведения
    (§4–9), модель данных и миграция (§5, §14 — «миграция не нужна»),
    AC1…AC10 с доказательством (§10), план автотестов (§11), риски (§13),
    откат (§14), release-артефакты (§15) — присутствуют по существу, не
    только по заголовку.

## Находки

Ни одной находки уровня High или Medium. Два Low-замечания, оба решением
ревьюера **сняты без правки** (документ остаётся годным для DoR), с записью
причины ниже — как того требует §12 PROCESS.md («Оставили в тексте ревью»
не считается закрытием, поэтому обе оставлены явной записью, а не
формулировкой «доработать»).

### L1 — de-CH унаследует «ß», хотя стандартная швейцарская орфография его не использует

`docs/specs/348-german-localization.md`, §4 правило 3 («Используются
настоящие ä, ö, ü, ß…») применяется к единственному словарю `de`, на который
по §5 резолвится и `de-CH`. Реальный швейцарский стандартный немецкий не
использует «ß» вовсе (пишет «ss»), поэтому носитель de-CH увидит
орфографически нетипичный для своего региона текст.

**Почему не блокирует.** Это решение — прямое следствие уже принятого на
этапе S2-analysis и не оспоренного владельцем "safe default" — «de-DE/de-AT/de-CH
используют общий de» (единый словарь для регионов был явно объявлен и принят
молчанием владельца по §2.2 до написания ТЗ). Требовать от одного словаря
одновременно двух орфографий — уже отдельная, более крупная задача
(региональные варианты внутри одного языка), а не пробел этого ТЗ. Дефект
не функциональный: интерфейс остаётся читаемым, AC2 (locale resolution)
не страдает.

**Решение ревьюера:** снято с записью. Если в будущем швейцарские
пользователи укажут на несоответствие, это отдельный issue на региональный
вариант орфографии, не возврат текущего ТЗ.

### L2 — явного блока «принято предположительно, поменять свободно» в конце документа нет

PROCESS.md §7.1 предписывает собирать не-продуктовые технические решения
в отдельный блок в конце ТЗ, чтобы ревьюер мог их оспорить одним взглядом.
В этом документе такие решения (устройство page-lifetime cache, форма
dedupe, retry policy, разбиение ролей в manifest) разбросаны по §6–§7 как
формулировки контракта, а не собраны отдельным блоком.

**Почему не блокирует.** По содержанию все технические решения либо прямо
привязаны к проверяемому AC (AC4, AC5, AC6, AC7 — это не «свободно
меняемые предположения», а часть контракта, который тестами и будет
доказываться), либо повторяют уже работающий в проекте паттерн
(editor/onboarding lazy-loading, retry-asset token). Оспаривать в них
нечего — ревью выше по каждому пункту нашло реальное покрытие, а не догадку.
Форматное требование не задевает проверяемость ТЗ.

**Решение ревьюера:** снято с записью, правка не нужна.

## Что проверено и признано корректным

- Классификация трека (полный) и перечисление нарушенных критериев §5 в
  S2-analysis — соответствует содержанию задачи.
- Зависимость #62 реально `S8-merged`, её API (`LANGUAGE_REGISTRY`,
  `resolveLanguageCode`, `languageOptions`) совпадает с тем, что ТЗ обещает
  расширить, а не заменить.
- Locale resolution matrix (§5) не меняет существующую политику exact →
  primary → English — подтверждено чтением `resolveLanguageCode`.
- Заявленный текущий bundle budget (255 910 / 256 000 B gzip) — точное,
  а не приблизительное число; проверено сборкой.
- План тестов (AC1–AC10) — для каждого назван реалистичный, уже
  прецедентный на проекте способ доказательства (unit registry-parity,
  Playwright semantic smoke, delayed-import smoke по образцу
  `smoke_lazy_editor_chunk.mjs`, bundle-manifest unit).
- Не-скоуп (§3.2) корректно исключает контент, который карточка принципиально
  не переводит нигде (имена HA-сущностей, значения, README) — согласовано
  со SCOPE.md («мы не редактируем реестр HA», «UI, не документация»).
- Откат (§14) не требует миграции данных — подтверждено отсутствием
  `language` в CONFIG-COMPATIBILITY.md.
- Оба changelog, оба User Guide, TESTING.md существуют как файлы — release
  artifacts (§15) указывают на реальные, а не гипотетические цели правки.
- Открытых продуктовых вопросов действительно не осталось: все пять
  дефолтов, которые ТЗ фиксирует как решённые (native label, единый словарь
  для de-*, отсутствие перевода HA-контента, English fallback, отсутствие
  регрессии EN/RU), были явно объявлены и приняты по правилу «молчание —
  согласие» ещё в S2-analysis, до написания ТЗ — это соответствует
  предписанному в PROCESS.md порядку (продуктовые вопросы решаются пачкой,
  с дефолтом, не в спеке задним числом).

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

- **Гейты `typecheck`/`test`/`build`/`bundle:budget` на самой ветке
  задачи** — diff ветки не содержит кода (только `docs/specs/**`), гейты
  этого рода проверяют код, а не текст ТЗ; прогон дал бы тот же результат,
  что и на `dev`, и ничего не доказал бы про качество спецификации. Вместо
  этого сборка `dev` использована лишь как источник факта (текущий
  bundle budget), см. пункт 2 «Как проверялось».
- **`node scripts/check-docs.mjs`** — diff не касается `src/**`, условие
  запуска (PROCESS.md §8) не выполнено.
- **Смоки, golden, backend pytest** — нет кода для прогона; они появятся
  только на этапе реализации и будут предметом код-ревью.
- **Точный итоговый размер lazy-loader кода** (риск «Loader превышает
  initial budget даже без словаря», §13 ТЗ) — не проверяем и не можем
  проверить на этапе спецификации: кода ещё нет. Риск в документе назван
  явно, с мерой («только доказанная очистка мёртвых i18n keys, budget не
  повышается») и с проверкой через AC6 (bundle-manifest/budget unit) —
  этого достаточно для DoR; если реализация не уложится, это остановит
  код-ревью, а не проходит на этом этапе незамеченным.
- **Ручной аудит немецкого перевода на естественность/грамматику** —
  вне полномочий этого ревью (ревьюер ТЗ не носитель и не переводчик);
  проверена структура контракта (glossary, правила капитализации,
  placeholders, no-English-fallback gate), а не текстовое качество
  конкретных строк, которых на этапе ТЗ ещё и не существует (кроме
  примеров таблицы §4).

## Унаследовано из предыдущего раунда

Неприменимо — это первый и единственный заход (r1), лимит циклов ТЗ на
полном треке (4) не тронут.

## Итог

ТЗ полное, проверяемое, все десять AC имеют названный способ доказательства,
технические утверждения документа сверены с реальным состоянием репозитория
и не являются догадками, выданными за факт. Продуктовые вопросы закрыты
корректно на этапе аналитики. Два Low-замечания сняты с записью причины.
Задача готова к переходу в `S5-ready`.