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

CODE-REVIEW-443-r1

• Issue: https://github.com/Matysh/houseplan-card/issues/443
• Ветка: issue/443-vacuum-route-polish
• Материал: git diff origin/dev...HEAD, HEAD = 1e5f33aa6413cb68659d5d1dcdb2b374a7404bda
• ТЗ: docs/specs/443-vacuum-route-polish.md, ревью ТЗ зелёное на r2 (docs/reviews/SPEC-REVIEW-443-r2.md)
• Заход: r1 (первый код-ревью цикл этой задачи)

Скоуп диффа

Один коммит поведения cebd20a9 (fix: polish vacuum map routes) плюс promotion-коммит 1e5f33aa (пересборка бандла и канонических скриншотов). Три независимых правки, всё согласно контракту ТЗ §1–§4:

1. map_routes authority — src/vacuum-routes.ts::effectiveRoutes(), custom_components/houseplan/vacuum_routes.py::effective_routes(): условие Array.isArray(x) && x.length → Array.isArray(x), отдельно на frontend и backend.
2. Single-space export — custom_components/houseplan/import_export.py: kept_routes or None → kept_routes (пустой список пишется как есть).
3. Группа «Пространство удалено» — src/editors/vacuum-maps-section.ts: разбиение routes на validRows/missingRows, отдельная секция с локализованным заголовком; src/i18n/support/{en,ru,de,fr}.json, src/styles/dialogs.styles.ts.
4. Vacuum-only render snapshot — src/render-device-snapshot.ts (vacuumDevices subset, заморожен), src/houseplan-card.ts (_renderVacuumDevices getter и новый call site _renderVacuums(this._renderVacuumDevices, …)).

Плюс тесты/мутанты (test/vacuum-routes.test.mjs, test/render-device-snapshot.test.mjs, test/isometric-contract.test.mjs, tests_backend/test_vacuum_routes.py, tests_backend/test_ha_import_export.py, scripts/mutation-gate.mjs, demo/smoke_vacuum_route_draft.mjs) и документация (docs/VACUUM.md, docs/CONFIG-COMPATIBILITY.md, docs/USER-GUIDE.ru.md, оба changelog) — все пять release-артефактов, названных ревью ТЗ, на месте.

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

Дешёвые гейты подтверждены на этом SHA, не перегонялись. Validate зелёный на точном 1e5f33aa (https://github.com/Matysh/houseplan-card/actions/runs/33802298798): джобы frontend (typecheck/unit/mutation-gate/bundle:sync), backend (pytest в HA), golden, performance_smoke, все 3 шарда smoke, docs, provenance, process-gate, hassfest, hacs — все success, я сверил через gh run view --json jobs лично, не только со слов автора.

Отдельно проверены с сохранением headSha:

• полный performance-прогон (7 профилей, включая large-house 60/200) — 33802485595, headSha = 1e5f33aa…, success;
• каноническая съёмка документации — 33802095608, success (на SHA промежуточного дерева 1fd042d9, откуда получены новые PNG, зафиксированные затем в promotion-коммите 1e5f33aa; сам docs job Validate подтверждает fingerprint против финального дерева отдельно и тоже зелёный).

Гейты, которые прогнал сам ревьюер (дёшево, воспроизводимо):

Гейт	Команда	Результат
smoke-select	node scripts/smoke-select.mjs --base origin/dev --head HEAD	6 прямых совпадений: smoke_cold_view_vacuum, smoke_controls, smoke_glow_fail_dark, smoke_glow_geometry_resilience, smoke_vacuum_firstuse, smoke_vacuum — все входят в полный набор, уже прогнанный зелёным в Validate (3/3 шарда)
no-new-any	node scripts/no-new-any.mjs --base origin/dev --head HEAD	«Новых any нет» (83 добавленные строки в 5 файлах)

Не прогонял: npx tsc --noEmit, npm test, npm run build — покрыты Validate на этом же SHA (условие задачи: не гонять то, что уже зелёное на точном SHA). npm run model-invariants не запускался — дифф не трогает рёбра комнат, записи толщины, layout, marker.space (сравнивается route.space, поле маршрута робота, не геометрия) или open_spans; гейт неприменим. python -m pytest tests_backend -q не гонял отдельно — покрыт зелёным backend-job Validate на этом SHA. Полный golden:capture/локальный HA-harness не запускал — канон Linux CI зелёный на точном SHA, второй прогон ничего не добавляет.

Разбор по AC

AC1 (единая route authority). test/vacuum-routes.test.mjs добавляет explicit empty routes remain authoritative over legacy calibration — три состояния: absent (legacy), null (legacy), [] (пусто, без legacy). Защитный AC, доказан таблицей «чем краснеет»:

AC	Чем доказан	Чем краснеет
AC1 (frontend)	node --test --test-name-pattern="explicit empty routes remain authoritative" test/vacuum-routes.test.mjs	мутант vacuum-empty-routes-revive-legacy-frontend возвращает explicit.length, гейт красный (проверено по определению мутанта в scripts/mutation-gate.mjs:384-396, сам mutation-gate job зелёный в Validate — значит применённая мутация действительно ловится)
AC2 (backend)	tests_backend/test_vacuum_routes.py::test_explicit_empty_routes_remain_authoritative	мутант vacuum-empty-routes-revive-legacy-backend (то же условие в Python)
AC3 (export)	tests_backend/test_ha_import_export.py::test_issue_443_space_export_preserves_explicit_empty_routes — экспортирует marker с explicit routes, полностью отфильтрованными по space, и уцелевшей legacy calibration; проверяет map_routes == [], effective_routes(...) == [] после round-trip	мутант vacuum-space-export-drops-empty-authority возвращает kept_routes or None

Читкой подтверждено: writeRoutes() в vacuum-maps-section.ts:129 (explicit ? (vacuum.map_routes ?? null) : null) при map_routes: [] берёт пустой массив как базу (![] есть false в JS — ветка convertLegacyRoutes не выполняется), то есть UI-редактирование поверх уже-пустого explicit-состояния не оживляет legacy при следующей записи. Отдельного unit на этот конкретный путь нет, но demo/smoke_vacuum_route_draft.mjs:50-72 стартует именно с map_routes: [] и успешно проводит через него draft-flow — риск низкий, тот же explicit-флаг, что доказан AC1/AC2.

AC2 (backend parity). См. таблицу выше; TS и Python проверяют одну и ту же четырёхстрочную матрицу independently, значения совпадают (absent/null → 1 маршрут, [] → 0).

AC3 (export). См. таблицу; дополнительно assert document["transfer"]["dropped_marker_links"] == 1 — счётчик не подменяется побочно.

AC4 (группа «Пространство удалено»). Контракт §3 — не защитный AC (расположение/текст/группировка), доказательство обычным сравнением достаточно. demo/smoke_vacuum_route_draft.mjs:150-192 (часть полного зелёного smoke-прогона в Validate) проверяет: ровно одна группа ([data-hp="vacuum-route-missing-group"]), заголовок "Deleted space", валидные строки идут первыми и не входят в группу, три missing-строки отсортированы по идентичности (missing-a,missing-b,missing-z — по map_id→source, а не по space, соответствует §3.2), каждая строка группы сохраняет <select> и обе кнопки (edit/delete остаются доступны), warning (.warn) не исчезает, заголовок читаем в light и dark темах. Pending draft рендерится отдельно от validRows/missingRows (vacroute.pending вне обеих групп) — контракт #441 не нарушен.

AC5 (renderer получает только роботов). test/render-device-snapshot.test.mjs — vacuumDevices содержит только устройство с фактом vacuum:<id>, переиспользует тот же клонированный элемент (snapshot.vacuumDevices[0] === snapshot.devices[1]), заморожен (Object.isFrozen, push бросает TypeError). Call site подтверждён структурным свидетелем: test/isometric-contract.test.mjs:37 требует буквальное вхождение _renderVacuums(this._renderVacuumDevices, view, space.id) в src/houseplan-card.ts — до правки строка была _renderVacuums(this._renderDevices, …), то есть тест механически падает при откате call site, не только при откате subset-логики. Проверено чтением: _captureRenderDeviceSnapshot() (houseplan-card.ts:4776-4822) итерирует this._devices (полный ростер, не отфильтрованный по текущему пространству) и кладёт facts.set('vacuum:'+id, …) для каждого _isVacDev(device) — то есть subset действительно содержит всех роботов плана, а не только текущего этажа, что и требует AC6.

AC6 (межэтажное и snapshot-поведение). Существующий mutation-тест vacuum-overlay-back-to-the-dock-space-filter (scripts/mutation-gate.mjs:423) обновлён на новый call site (find теперь ищет _renderVacuumDevices) и по-прежнему требует падения smoke_vacuum_multifloor при подмене на current-space devs. space-card.ts (второй, статический card) не вызывает _renderVacuums вовсе — никакой параллельный call site не остался непереключённым.

Слабое место: мутант ловит подмену на devs (устройства текущего пространства), но не ловит гипотетический откат _renderVacuumDevices → this._renderDevices (полный ростер всех этажей) — такой откат не сломал бы ни один функциональный тест, только регрессировал бы производительность к исходной проблеме (в). Эту дыру закрывает не mutation-gate, а структурный witness isometric-contract.test.mjs:37: он проверяет точную подстроку _renderVacuumDevices, поэтому откат к _renderDevices уронит и его. Тест умеет падать — проверено чтением diff (до правки эта точная строка не существовала).

AC7 (производительность). Full performance run зелёный на точном SHA, включает large-house 60/200 (см. «Как проверялось»). Structural witness — тот же isometric-contract.test.mjs:37 плюс render-device-snapshot.test.mjs, подтверждающий V < N состав subset. Новый latency-бюджет не вводился — согласовано ТЗ и не оспаривается ревью.

AC8 (совместимость и документация). docs/VACUUM.md, docs/CONFIG-COMPATIBILITY.md, docs/USER-GUIDE.ru.md обновлены текстуально верно (сверено чтением — формулировки описывают ровно новое поведение, не больше и не меньше). Оба changelog правлены в том же коммите cebd20a9, что и поведение (User-Visible: yes) — правило §10.2.4 соблюдено. i18n: все четыре словаря (en/ru/de/fr) получили vac.route_missing_space_group, test/i18n.test.mjs обновлён на keys.length === 78 — тест самих ключей проверяет полноту, я прочитал все четыре файла и подтвердил перевод присутствует и осмыслен.

Одно число — один источник

Дифф не вводит и не показывает пользователю новую числовую величину дважды: меняется правило чтения списка (authority) и группировка строк, оба — не числа. Проверять нечего.

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

• Frontend/backend parity по всей 4-строчной матрице authority (AC1/AC2), включая отрицательные мутанты на обеих сторонах.
• Export не теряет explicit empty (AC3), включая проверку effective_routes после round-trip и неизменности счётчика dropped_marker_links.
• Группировка потерянных маршрутов: единственная группа, стабильный порядок, строки остаются редактируемыми/удаляемыми, warning сохранён, light/dark читаемость (AC4).
• Vacuum-only snapshot: immutable subset, реюз тех же клонированных строк, верный call site, подтверждено чтением что capture обходит весь ростер, а не только текущее пространство (AC5/AC6).
• writeRoutes() в редакторе корректно трактует уже-пустой explicit массив как базу без отката к legacy-конверсии (проверено чтением).
• i18n-словари всех 4 языков и test/i18n.test.mjs согласованы.
• Документация (VACUUM.md, CONFIG-COMPATIBILITY.md, USER-GUIDE.ru.md) и оба changelog обновлены в том же коммите, что и поведение.
• no-new-any — новых any нет (проверено лично).
• Все дорогие гейты (typecheck/unit/build/mutation/backend/golden/performance/ docs/smoke×3) зелёные на точном HEAD SHA 1e5f33aa — подтверждено запросом к самому workflow run, а не только по ссылке из хендоффа.

Находки

Находок нет. High: 0, Medium: 0, Low: 0.

Единственное отмеченное выше наблюдение (мутация не покрывает гипотетический откат _renderVacuumDevices → _renderDevices) не поднимается до Low: реальный свидетель (структурный тест на точную подстроку call site) уже существует и доказанно падает при этом откате — это другой инструмент (source-match, не mutation-gate), но не пробел в покрытии.

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

• Не запускал npx tsc --noEmit, npm test, npm run build, npm run bundle:sync, node scripts/mutation-gate.mjs --check, npm run golden:verify, python -m pytest tests_backend -q, performance-профили и node scripts/check-docs.mjs лично — все подтверждены зелёными на точном SHA 1e5f33aa в трёх названных прогонах CI, которые я сверил через gh run view (headSha, jobs, conclusion), а не принял на слово из хендоффа.
• Не запускал node scripts/model-invariants.mjs — дифф не касается геометрии (рёбра комнат, толщина, layout, marker.space, open_spans); гейт не применим по критерию задачи.
• Не проводил ручного тестирования в браузере (в этом процессе такой фазы нет); AC4/AC5/AC6/AC7 разобраны по коду и по прогону named browser smokes/perf runs в CI.
• Не проверял 6 «прямых совпадений» smoke-select индивидуально локально — они часть полного набора, уже зелёного во всех 3 шардах Validate на этом SHA; повторный локальный прогон не добавил бы информации.

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

• SHA ветки на момент вердикта: 1e5f33aa6413cb68659d5d1dcdb2b374a7404bda (сверено git rev-parse HEAD непосредственно перед выводом).
• Дерево материала: вывод git diff origin/dev...HEAD на этом SHA.
• Validate CI: https://github.com/Matysh/houseplan-card/actions/runs/33802298798 (headSha подтверждён равным 1e5f33aa…).

---

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

• Ветка: issue/443-vacuum-route-polish, коммит 1e5f33aa6413 — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
• Дерево материала: 9606928137c6ead0bada1645f26c70ca819dd342

  git log --all --format='%H %T' | grep 9606928137c6
  

• ТЗ docs/specs/443-vacuum-route-polish.md, блоб eb5bc721764abebb38a642cf9e450f52c6e608d7

  git log --all --find-object=eb5bc721764abebb38a642cf9e450f52c6e608d7 -- docs/specs/443-vacuum-route-polish.md