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

SPEC-REVIEW-337-r1

• Issue: https://github.com/Matysh/houseplan-card/issues/337
• ТЗ: docs/specs/337-lazy-editor-chunk.md, commit 6e7ab6b7 (ветка issue/337-lazy-editor-chunk, HEAD detached)
• Трек: полный (обоснование в аналитике: производительность + несколько поверхностей/public asset contract — критерий §5 назван, small корректно отклонён)
• Этап: spec-review, заход r1, блокирующих циклов израсходовано 0/4
• Вердикт: зелёный

Скоуп

Задача переносит View/editor границу frontend в реальную модульную границу (src/editors/runtime/), делает multi-asset build/раздачу/CI/HACS-контракт и безопасно минифицирует статические CSS-литералы, чтобы initial View graph уложился в ≤256 000 B gzip. Данные/layout/геометрия/UX/touch policy не меняются, только: (а) до входа в редактор код редакторов не грузится, (б) при редкой ошибке загрузки чанка показывается новое локализованное сообщение, а View остаётся рабочим.

Проверка по docs/SCOPE.md: работа не добавляет функциональность — она инфраструктурно защищает J1/J6 (быстрый рабочий View для kiosk/tablet-персон, которые являются «the product» по SCOPE) и не задевает ни один пункт out-of-scope. Отдельный вопрос владельцу не нужен: видимое поведение не меняется, кроме двух явно описанных добавлений (индикатор ожидания, сообщение об ошибке), и автор прямо заявил в комментарии, что продуктовых вопросов нет — это соответствует действительности, разночтений о персоне/сценарии в ТЗ я не нашёл.

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

Ревью документа на этом этапе не имеет кода для гейтов (typecheck/test/build неприменимы — commit 6e7ab6b7 меняет только docs/specs/337-lazy-editor-chunk.md). Вместо этого каждое фактическое утверждение ТЗ, которое можно спутать с непроверенной догадкой, сверено с текущим репозиторием на HEAD:

Утверждение ТЗ	Проверка	Результат
dist/houseplan-card.js 1 353 147 B raw / 378 335 B gzip, src/houseplan-card.ts ≈1052 KiB, View+3 редактора в одном классе	wc -c src/houseplan-card.ts → 1 071 305 B (22 809 строк)	согласуется с заявленным порядком величины
custom_components/houseplan/__init__.py раздаёт один точный файл StaticPathConfig(FRONTEND_URL, ...) без auth	прочитан файл целиком	подтверждено; новый asset-route не вводит новый класс уязвимости — паритет с текущим
GUI config editor (houseplan-card-editor) сейчас eager	grep "import './editor'" в houseplan-card.ts:190 — статический импорт	подтверждено, AC11 закрывает реальный источник веса
Существующий mode-transition CSS-класс переиспользуется под loading surface	найден в plan.styles.ts/houseplan-card.ts, уже используется как de-emphasis coordinate	правдоподобно, а конкретная реализация прямо отнесена к §18 «принято предположительно»
«Старый браузер, способный исполнять текущий ESM bundle, способен исполнять native dynamic import» (§12)	tsconfig.json target es2021, без даунлевелинга; в коде 811 использований ?. и 110 ?? — уже требуется ES2020+ движок	верно: минимальный движок, способный распарсить нынешний бандл, уже новее движков без import() (Chrome 63/FF 67/Safari 11.1) — вычислено, не принято на веру
Ручная установка сегодня — это копирование папки custom_components/houseplan, а не одного JS (README.md:109-112, USER-GUIDE.ru.md:97-102)	прочитаны оба файла	подтверждено — multi-asset дерево не ломает существующий документированный manual-install путь; отдельный top-level houseplan-card.js GitHub-asset никогда не был этим путём
docs/specs/README.md/PROCESS.md §7.1 обязательные разделы	построчная сверка ТЗ §1–§18	все присутствуют по содержанию (см. ниже)
Трейлеры коммита 6e7ab6b7	git log -1 --format=%B	Issue: #337 / User-Visible: no, корректно — ТЗ не является пользовательским изменением
#34 (направление декомпозиции, на которое ссылается §7.1)	gh issue view 34	#34 сам в S3-spec, ещё не утверждён; его текущий целевой tree (editors/plan/, editors/devices/, editors/render/, …) и «безопасный порядок» (render-слои → диалоги → контроллеры, маленькими слайсами) не совпадают дословно с editors/runtime/ из #337

Дополнительно сверены обязательные разделы ТЗ (PROCESS.md §7.1): сценарий (§1) · что человек видит (§2) · проблема (§3) · скоуп/не-скоуп (§4–§5) · контракт поведения и UX (§6) · архитектурный контракт (§7) · модель данных и миграция (§12) · i18n (§11) · AC1…AC13 с доказательством (§13) · план автотестов (§14) · риски (§15) · откат (§16) · release-артефакты (§17) · блок «принято предположительно» (§18). Все присутствуют по существу, не только по названию.

Находки

Ничего в статусе High или Medium-в-скоупе, требующего возврата автору. Три наблюдения Low, ревьюер снимает их с записью (правка необязательна, вносить можно по желанию автора в этом же цикле без отдельного возврата):

1. houseplan-space-card не упомянута в границе runtime. У неё есть собственный GUI config editor (src/space-editor.ts, статически импортированный в space-card.ts:39, 93 строки/3.3 KB raw). ТЗ §7.1/§6.2.6 описывает границу и AC11 только для houseplan-card. Снято: вклад в gzip пренебрежимо мал (на два порядка меньше бюджета), «Обе карточки в одном файле» и обе регистрируются надёжно — п.6.1.1 это покрывает; не наблюдается риска для AC1/AC2. Если авторы решат вынести и его — не помешает, но не является требованием этого ТЗ.
2. Число/размер editor-чанков не ограничено. Формально ТЗ можно закрыть набором очень мелких чанков, что било бы по числу HTTP-запросов при первом входе в редактор, хотя раздел «Риски» уже фиксирует намерение «переносить законченными typed slices». Снято: нет продуктового контракта на задержку входа в редактор кроме «не выглядит зависшим» (150 ms порог, §15), а именно этим и ограничен риск.
3. Имя src/editors/runtime/ разойдётся с целевым деревом #34 (editors/plan/, editors/devices/, editors/decor/, render/, dialogs/ — сам #34 ещё в S3-spec, не утверждён). Это два разных среза: #34 — про читаемость и единственный источник состояния, #337 — про то, что статически не импортируется в entry; частичное совпадение целей не значит, что нужно ждать #34. Снято: §18 прямо относит имена внутренних модулей и форму typed host port к «принято предположительно, можно менять свободно» — реальной привязки к продукту нет, а сведение выполнимости и проверяемости ТЗ не страдает.

Ни одна из трёх не задевает выполнимость или проверяемость ни одного AC1…AC13, поэтому они не поднимаются выше Low и не создают жёлтый вердикт.

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

• Числовой бюджет непротиворечив: «250 KiB» (§4.2) и «256 000 B» (issue, AC1/§13) — один и тот же порог (250×1024=256000), никакого двойного источника значения нет.
• Каждый AC1…AC13 имеет явный, разный и проверяемый способ доказательства (unit/manifest-тест/Playwright-smoke/backend-тест/golden/статический гейт); ни один не сформулирован как «проверено ревьюером на глаз».
• Не-цели (§5) корректно исключают геометрию, config/layout, polyclip-ts, lazy i18n, backend API/SVG-вычисления и automatic idle-prefetch — согласуется с docs/SCOPE.md (никакой новый функционал сверх заявленной работы) и не противоречит docs/CONFIG-COMPATIBILITY.md (миграции нет, контракт не сформулирован — не нужен, раз stored data не меняется). docs/WALL-THICKNESS.md/CANVAS.md не затронуты (геометрия explicitly вне скоупа) — глубокая сверка с ними не требовалась.
• §6.4 (failure/retry/fingerprint) и §10 (fingerprint/cache) описывают ровно одну попытку retry, запрет auto-hard-reload и явную обработку mismatch — внутренне непротиворечиво и без недосказанных веток.
• Формулировки пользовательских сообщений (§6.2.3, §6.4.2) — новый текст, а не изобретённая замена существующей терминологии USER-GUIDE.ru.md: там нет готовой фразы под этот сценарий (grep пуст), так что это не нарушение правила «UI не говорит на языке разработчика».
• Блок «принято предположительно» (§18) корректно отделяет технические решения (имена модулей, формат manifest, реализация delayed-surface, механизм инвалидации manifest, gzip-параметры сборки, разбиение на коммиты) от того, что зафиксировано как продуктовое решение и менять нельзя (URL ресурса, отсутствие auto-reload, сохранение рабочего View при ошибке, отсутствие prefetch) — ровно то разделение, которого требует PROCESS.md §7.1.
• Трек и метка (S4-spec-review, полный трек) корректны для задачи со сложностью 9/10 и влиянием на public asset contract.

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

• Гейты npx tsc --noEmit / npm test / npm run build / bundle:sync / check-docs.mjs / инварианты геометрии — не запускал: на этом этапе нет продуктового кода, диапазон коммита r1 — один файл в docs/specs/. Они становятся обязательными на этапе код-ревью (§2.7), когда появится реализация.
• Достижимость бюджета ≤256 000 B самой декомпозицией — это инженерный риск, который ТЗ само называет негарантированным («если модульная декомпозиция не доводит граф до бюджета, задача не считается выполненной») и оставляет измеримым на этапе реализации; ревью ТЗ не может предсказать фактический результат code-splitting, только то, что критерий сформулирован проверяемо.
• Полное содержание docs/ARCHITECTURE.md, docs/DEVELOPMENT.md, docs/TOUCH-SUPPORT.md не перечитывалось построчно — сверены только фрагменты, релевantные конкретным утверждениям ТЗ (раздел «Как проверялось»); геометрия/touch/config не в скоупе задачи, поэтому глубокого разбора WALL-THICKNESS.md/CANVAS.md/CONFIG-COMPATIBILITY.md не требовалось.

Итог

ТЗ выполнимо и проверяемо, разделы полны, продуктовых вопросов владельцу нет и не появилось при ревью, скоуп соответствует docs/SCOPE.md. Три Low-находки сняты с записью выше. Статус — «Готово к разработке».