houseplan-card/docs/reviews/CODE-REVIEW-43-r2.md

# CODE-REVIEW-43-r2

- Issue: [#43](https://github.com/Matysh/houseplan-card/issues/43) — Диалог помощи и обратной связи с обезличенным support report
- Ветка: `issue/43-help-feedback`
- SHA ревью: `0e0ca3d4dc38851555a825b9481817642d8647a9`
- Заход: r2 (второй код-ревью) · блокирующих циклов израсходовано **1/4** (r1 был жёлтым — потратил цикл; зелёный вердикт цикла не образует, §4/#227)
- Вердикт: **зелёный** · High: 0 · Medium: 0

## 1. Скоуп раунда

Это второй заход, разбор — по дельте (§2.10 PROCESS.md). Предыдущий вердикт
(r1, жёлтый) получен на SHA `1ba5363038055b3f3442b62a761161d05c6d03c7`
(документ `docs/reviews/CODE-REVIEW-43-r1.md`, SHA явно назван в самом
документе). Дельта:

```
git diff 1ba53630..0e0ca3d4
```

3 коммита сверх r1: `ffddc383` (fix: satisfy validation gates), `40d63080`
(docs: review document — публикация r1, генерирует конвейер, не автор),
`0e0ca3d4` (test: cover help and feedback browser flows).

Продуктовый код изменён только в двух местах, и оба — рефакторинг типов без
изменения поведения:

- `src/houseplan-editor-runtime.ts` (+28/−17): `response: any` → `response: unknown`
  с явным сужением через промежуточный `payload`-объект в `_buildSupportPreview`
  и `_submitSupport`. Логика чтения полей (`text`, `size`, `token`, `sha256`,
  `report_id`, …) идентична строка в строку — только тип входа сузился.
- `src/support-feedback.ts` (+4/−3): `options.language as any` → typed
  `readonly string[]`, `(value as any).code` → `(value as {code?:unknown}).code`.
  Тоже чистое сужение типа, не логики.

`custom_components/houseplan/**/*.py` в дельте не тронут вообще (проверено
`git diff --stat 1ba53630..HEAD -- custom_components/` — только сгенерированные
`frontend/**`). Единственная правка бэкенда — 158 новых строк тестов в
`tests_backend/test_support_package.py`, сам `support_package.py` не менялся.

Остальное — тесты и инфраструктура: новый `demo/smoke_support_feedback.mjs`
(270 строк), 6 golden-сцен в `demo/golden/matrix.mjs` + ветка `dialog === 'support'`
в `demo/golden/harness.mjs`, обновлённый `demo/smoke_general_settings.mjs`,
новый мутант в `scripts/mutation-gate.mjs`, обновлённый `docs/images/screenshots.json`
(отпечаток скриншотов).

Дельта локальна: контракт поведения не менялся, новая подсистема не задета,
объём (≈390 строк не считая бандла) на порядок меньше исходной задачи
(+7023/−411 в r1). Полный повторный разбор не требуется — §2.10.

## 2. Закрытие раунда r1

| Находка r1 | Чем закрыта | Где это видно |
|---|---|---|
| **M1.** `check-docs` красный — устаревший `sourceFingerprint` скриншотов | `docs/images/screenshots.json` обновлён (`sourceFingerprint`/`sourceSha256` во всех сценах: `7faa6c2e…` → `7e950337…`) коммитом `ffddc383` | Лично прогнал `node scripts/check-docs.mjs` на HEAD `0e0ca3d4` → `Documentation checks passed (7 files, 10 external links)` |
| **M2.** Ни одного браузерного смока/golden-сцены для диалога Help & Feedback | Новый `demo/smoke_support_feedback.mjs` (режимы view/plan/devices/decor, kiosk, read-only, EN/RU, старый backend, validation/focus, preview/SHA/download exact bytes, success/429/timeout/unknown, retry с тем же idempotency key, 320×760 и 760×320, touch-target 44px) + 6 golden-сцен в `matrix.mjs` (`support-desktop-empty-light-en`, `support-desktop-preview-dark-en`, `support-phone-validation-light-ru`, `support-phone-success-dark-en`, `support-relay-error-light-en`, `support-tablet-preview-dark-ru`) + ветка `dialog === 'support'` в `demo/golden/harness.mjs`, оба коммитом `0e0ca3d4` | Лично прогнал `node demo/smoke_support_feedback.mjs` на свежем бандле — все 18 полей `true`, `OK`. Лично прогнал `node scripts/mutation-gate.mjs --id=support-timeout-claims-success` — `чистый прогон` + `тест покраснел, как обязан`, `поймано 1 из 1`: смок реально умеет падать на мутанте §14.4 (ложный success на timeout). Лично прогнал `node demo/golden/run.mjs --mode=capture --scenario=<каждая из 6>` — все 6 строятся без ошибки (`missing-baseline`, не `error`; baseline умышленно не принят до предрелизного визуального ревью, это по процессу, не пропуск). `test/golden-matrix.test.mjs` получил новый тест «issue 43 support dialog has the six reviewed responsive states», зелёный в `npm test` |
| **M3.** `no-new-any` красный — 4 новых `any` без обоснования | Все 4 типизированы (см. §1) коммитом `ffddc383` | Лично прогнал `node scripts/no-new-any.mjs --base origin/dev --head HEAD` на HEAD `0e0ca3d4` → `Новых any нет` |

Все три Medium закрыты предметно — не косметика вокруг находки, а именно то,
что было названо (актуальный отпечаток вместо любого другого фикса; смок и
golden именно для нового диалога, а не для соседней фичи; типизация именно тех
четырёх строк).

## 3. Унаследовано из r1

Без повторной проверки в этом раунде — код на этих участках дельта не
затронула, полный разбор см. `docs/reviews/CODE-REVIEW-43-r1.md`
(SHA `1ba53630`):

- Allowlist-проекция `support_package.py`: 8 `_project_*`-функций строят новый
  `dict`, не мутируя исходник (§7.3). Сам файл в дельте не менялся —
  дельта только добавила тесты поверх него (см. §5).
- Авторизация и владение токеном на всех трёх WS-командах
  (`_check_write`/`may_write`, сверка `preview.get("owner")`).
- Транспорт: фиксированный HTTPS-хост, без редиректов, таймауты 5/20с, статус
  мапится на закрытый список кодов до чтения тела.
- Relay `scripts/support-relay/**`: не менялся дельтой, 36/36 тестов,
  инварианты против подмены `X-Forwarded-For` (живой пентест владельца при
  ревью ТЗ r3-r5).
- «Одно число — один источник» для preview/download/submit (§2.6 r1) —
  цепочка байт/хеш не менялась.
- Деградация на старом backend (`compatible = _haIntegrationVersion === CARD_VERSION`).
- AC15 (нулевое влияние на `diagnostics.py`/`import_export.py`/`validation.py`).
- Трейлеры и changelog коммита `1e2e0fa6` (Issue/User-Visible, оба changelog
  в одном коммите) — не пересматривались, дельта changelog не трогает.
- Low-находки r1 (L1 единицы Caddyfile, L2 порядок проверки CPU/лимита, L3
  `_support_repairs()` без sentinel-теста, L4 неиспользуемые i18n-ключи
  `backup.error.support_*`) — сняты решением ревьюера r1 с записью, дельта их
  не касается, повторно не поднимаю.
- Ограничение проверки бэкенда: полный HA-харнесс (`test_ha_websocket.py` и
  т.д.) в r1 не поднимался (нет закреплённой версии Python 3.14/phcc в
  песочнице ревьюера) — то же ограничение действует и здесь, оно не связано с
  дельтой (AC9/AC10 остаются «проверено чтением», не автотестом с моей
  стороны, как и в r1).

## 4. Как проверялось в этом раунде

Дешёвые гейты гоняются в каждом раунде (§2.10); прогнаны лично на HEAD
`0e0ca3d4`, зелёного Validate CI на этом SHA нет — обязанность ревьюера (см.
задание раунда).

| Гейт | Команда | Результат |
|---|---|---|
| Типы | `npx tsc --noEmit` | зелёный, 0 ошибок |
| Юнит/интеграционные | `npm test` | 1725 тестов: 1724 passed, 1 skipped, 0 failed — совпадает с числом из хендоффа автора |
| Сборка + сверка бандла | `npm run build && cmp dist/houseplan-card.js custom_components/houseplan/frontend/houseplan-card.js` | идентичны |
| Три копии бандла | `npm run bundle:sync` | `git status` чист после — `dist`, `custom_components/.../frontend`, `demo/srv/assets` синхронны |
| Docs-контракт (диапазон меняет `src/**`) | `node scripts/check-docs.mjs` | `Documentation checks passed (7 files, 10 external links)` — M1 закрыт |
| Новый `any` | `node scripts/no-new-any.mjs --base origin/dev --head HEAD` | `Новых any нет` — M3 закрыт |
| process-gate | `node scripts/process-gate.mjs --range origin/dev..HEAD --issues` | «гейт пройден, предупреждений 0», 18 коммитов |
| Выбор смоков | `node scripts/smoke-select.mjs --base origin/dev --head HEAD` | 6 изменённых файлов `src/**`, 37 «прямое совпадение»; `demo/smoke_support_feedback.mjs` назван прямым совпадением по символам `_closeSupportDialog, _config, _downloadSupportPreview, _editorRuntime, _haIntegrationVersion, _submitSupport` — ровно то, что и требовалось запустить |
| Целевой смок (новый, M2) | `node demo/smoke_support_feedback.mjs` | все 18 проверок `true`, `OK` |
| Целевой смок (изменённый, About moved out) | `node demo/smoke_general_settings.mjs` | все проверки `true`, `OK`, включая новую `aboutMovedOut: true` |
| Мутационный гейт нового смока | `node scripts/mutation-gate.mjs --id=support-timeout-claims-success` | `ok чистый прогон` + `ok тест покраснел, как обязан` → `поймано 1 из 1` — смок доказуемо умеет падать (дисциплина §2.7/§18) |
| Golden-сцены (существование/сборка) | `node demo/golden/run.mjs --mode=capture --scenario=<id>` для всех 6 новых сцен | все 6 строятся без ошибки (`missing-baseline`, не `error`) |
| Бэкенд-тесты дельты | `pip install pytest voluptuous` (без пина, как в r1) → `python -m pytest tests_backend/test_support_package.py -q` | `14 passed` (10 старых + 4 новых: reject non-mapping, rich-projection sentinel, projection helpers fail-closed, size-limit-after-projection) |

## 5. Разбор по AC, чьё доказательство дельта задевает

Обозначения как в r1: **PASS/тест** — автотест, умеющий падать (см. §4);
**PASS/чтение** — проверено чтением; **∅** — не переоценивался, см. §3.

| AC | Было (r1) | Стало (r2) | Почему изменилось |
|---|---|---|---|
| AC1 | PASS/чтение | **PASS/тест** | `smoke_support_feedback.mjs`: порядок кнопок (`afterSettings` = `.support-button` идёт после `mdi:cog-outline`), неизменность режима/zoom/выбора при открытии для всех 4 режимов, `kioskHidden`, `readonlyAbsent` — все `true` |
| AC2 | PASS/тест+чтение | PASS/тест+чтение (усилено) | Логика не менялась (тест `test/support-feedback.test.mjs` не в дельте); новый смок добавляет DOM-уровень: `aboutAndEnglishGuide`/`russianGuide`/`oldBackendDegrades` — `true`. `smoke_general_settings.mjs` подтверждает `aboutMovedOut: true` — блок не задвоен |
| AC3 | PASS/тест | PASS/тест (усилено) | `freshDefaults`, `freshAfterSuccess` — новый черновик пуст при каждом открытии/после успеха, чекбокс не сохраняется, теперь и на уровне браузера, не только unit |
| AC4 | PASS/тест | PASS/тест (усилено) | `openIsLocal`: открытие диалога не увеличивает счётчик `houseplan/support/*`-вызовов до включения чекбокса |
| AC5, AC9, AC10 | PASS/тест(+чтение) | ∅ (логика не менялась) | Единственная правка смежного кода — сужение `any → unknown` в `_buildSupportPreview`/`_submitSupport`; путь чтения полей (`payload.text`, `payload.token`, …) идентичен построчно старому `response?.text` и т.д. — проверил диффом, поведение при `response` не-объектом (`undefined`) то же самое (`{}` фоллбэк даёт те же `''`/`NaN`, что и `?.`) |
| AC6, AC7, AC8 | PASS/тест | ∅, но с дополнительным покрытием | `support_package.py` не менялся; `tests_backend/test_support_package.py` получил 4 новых теста, включая структурный `test_rich_plan_projection_preserves_safe_structure_and_drops_unknown_values` (сеет `poly`/`walls`/`markers`/`decor` с частично некорректными формами и секретными полями, проверяет точный спроецированный результат) — прогнал сам, 14/14 зелёных. Это усиление доказательства, не обязательное по находкам r1, но не создаёт риска: тесты только добавляют строгости |
| AC13 | PASS/чтение | **PASS/тест** | Смок покрывает success/`support_rate_limited`/`support_unavailable` (timeout)/`unknown_command`, ретрай с тем же `idempotencyKey` (4 запроса с одним и тем же ключом), сохранение черновика при ошибке. Мутационный гейт `support-timeout-claims-success` подтверждает, что смок красный на реальной регрессии — не просто зелёный тест-пустышка |
| AC14 | PASS/чтение, UNVERIFIED по заявленному способу | **PASS/тест** (touch/layout), golden-candidate (не baseline) | `touchTarget` (≥44×44), `noHorizontalOverflow`, `phonePortrait`/`phoneLandscape` (320×760, 760×320 без клиппинга) — реальный браузерный рендер, не чтение TS. 6 golden-сцен покрывают desktop/phone/tablet × light/dark по именам состояний из §14.2 ТЗ; baseline умышленно не принят (процесс требует полного Linux CI артефакта для приёмки — это предрелизный шаг, не код-ревью) |
| AC11, AC12/12a, AC15, AC16, AC17 | PASS | ∅ | Relay, backend-модули diagnostics/import_export/validation, i18n-независимость и lazy-импорт дельтой не задеты — код идентичен r1 |

## 6. Находки этого раунда

Ничего блокирующего. Одна наблюдение уровня Low, снимаю с записью, не
блокирует:

**L5 (новая, Low).** Старый `demo/smoke_general_settings.mjs` проверял в
реальном DOM точные атрибуты About-ссылок (`href`, `target=_blank`,
`rel=noopener`) и точный текст версии (`Houseplan Card v${BUNDLE_VERSION}`) —
эта проверка выпала при переносе About в новый диалог: замена,
`aboutAndEnglishGuide` в `smoke_support_feedback.mjs`, проверяет только
количество `.aboutlink` (`=== 2`) и суффикс `href` guide-ссылки, не точные
`href`/`target`/`rel` GitHub/Telegram-ссылок и не текст версии. Не блокирую:
разметка статична (`src/houseplan-editor-runtime.ts:9387-9397`, атрибуты
захардкожены в шаблоне), риск молчаливого дрейфа без сопутствующей правки кода
практически нулевой, а `test/support-feedback.test.mjs` (не в этой дельте)
уже проверяет текстом, что `gs.about_version` не задвоен. Стоит вернуть
точную проверку атрибутов при следующей правке этого смока, отдельного issue
не требует.

## 7. Что проверено и корректно (в дополнение к §3)

- Три Medium из r1 закрыты предметно, не декларативно — по каждой лично
  воспроизвёл зелёный результат на HEAD этого раунда (см. таблицу §2 и §4).
- Новый смок доказуемо способен упасть: мутационный гейт `support-timeout-claims-success`
  красит именно `demo/smoke_support_feedback.mjs`, а не абстрактный юнит —
  снимает риск «зелёный тест ничего не проверяет», который прямо назван в
  документации самого `mutation-gate.mjs`.
- Рефакторинг типов (`any` → `unknown`/сужение) не меняет поведение: логика
  чтения полей идентична, `npm test` (1724/1724 незменившихся зелёных) и
  целевые смоки подтверждают эквивалентность.
- Три копии бандла синхронны, `git status` чист после `bundle:sync` —
  класс D не расходится с классом A.
- Трейлеры всех трёх коммитов дельты корректны (`Issue: #43`,
  `User-Visible: no` — оправданно, видимого поведения дельта не меняет,
  changelog не тронут).
- `process-gate --issues` зелёный, 0 предупреждений на 18 коммитах диапазона.

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

- **Полный HA-харнесс** (`test_ha_websocket.py` целиком) — то же ограничение
  песочницы, что и в r1 (нет закреплённой Python 3.14/`pytest-homeassistant-custom-component==0.13.357`);
  дельта не меняет ни один файл, который этот харнесс покрывал бы иначе, чем
  уже покрыто в r1. AC9/AC10 остаются на «проверено чтением».
- **`npm run invariants`** — диапазон не меняет геометрию/`layout`/толщину
  стен ни в r1, ни в дельте; неприменимо, не пропуск.
- **`golden:verify`/приёмка эталонов** — 6 новых сцен собираются без ошибки,
  но baseline не принимался: это предрелизный шаг (§8 PROCESS.md,
  `npm run golden:accept -- --reviewed` только по полному Linux CI
  артефакту), не обязанность код-ревью. Локальный `golden:verify` на всей
  матрице не гонял — большинство существующих сцен в этой песочнице дают
  `different` уже на `origin/dev` (другой Chromium/шрифты), это фон, не
  регрессия дельты, и полный прогон — предрелизная, а не ревью-обязанность.
- **Полный набор `demo/smoke_*.mjs`** (213 файлов) — не оправдано: дельта не
  меняет ничего, что затрагивало бы несвязанные поверхности; `smoke-select.mjs`
  подтверждает совпадения только на общих символах для остальных 36 файлов
  (типовой фон, тот же вывод, что и в r1).
- **Relay `scripts/support-relay/**`** — не в дельте, не перепрочитывал
  повторно (r1 уже перечитал этот код заново как часть первого код-ревью, а
  не принял на веру со спек-ревью).

## 9. Итог

Все три Medium-находки r1 закрыты предметно, каждая — воспроизведённым
зелёным результатом на HEAD этого раунда, а не заявлением автора. Дельта не
меняет продуктовую логику (только сужение типов и добавление тестов/смоков/
golden-сцен), поэтому полный повторный разбор всех 17 AC не требовался —
переоценены только AC1/AC2/AC3/AC4/AC13/AC14, чьё доказательство дельта
затронула, остальные унаследованы из r1 без изменений в коде, который их
доказывает. Новый браузерный смок дополнительно подтверждён мутационным
гейтом — это не пустой зелёный тест. High-находок нет, Medium-находок нет,
одно Low-наблюдение снято с записью в этом же документе.

Вердикт: зелёный · заход r2 · блокирующих циклов 1/4 · High: 0 · Medium: 0