From 5a703ef562b327768b24cdb3d942512470e58b98 Mon Sep 17 00:00:00 2001 From: "claude[bot]" <209825114+claude[bot]@users.noreply.github.com> Date: Fri, 28 Aug 2026 00:24:41 +0000 Subject: [PATCH] docs: review document for #337 Issue: #337 User-Visible: no --- docs/reviews/SPEC-REVIEW-337-r1.md | 140 +++++++++++++++++++++++++++++ 1 file changed, 140 insertions(+) create mode 100644 docs/reviews/SPEC-REVIEW-337-r1.md diff --git a/docs/reviews/SPEC-REVIEW-337-r1.md b/docs/reviews/SPEC-REVIEW-337-r1.md new file mode 100644 index 00000000..9b85d3e9 --- /dev/null +++ b/docs/reviews/SPEC-REVIEW-337-r1.md @@ -0,0 +1,140 @@ +# 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-находки +сняты с записью выше. Статус — «Готово к разработке».