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

SPEC-REVIEW-423-r1

• Issue: https://github.com/Matysh/houseplan-card/issues/423
• Этап: ТЗ на ревью (PROCESS.md §2.4)
• Заход: r1 · блокирующих циклов израсходовано 0 из 4
• Материал: ветка issue/423-v170-polish, SHA 7102994dc669e789951f3a1906bf07152239f99d (docs: specify v1.70 support polish)
• ТЗ: docs/specs/423-v170-polish.md (420 строк, ссылка issue ↔ ТЗ на месте в обе стороны)

Скоуп ревью

Полный трек, первый заход. Проверялись: полнота обязательных разделов §7.1, однозначность и доказуемость AC1–AC12, отсутствие догадок, выданных за факт, и фактическое соответствие текста ТЗ реальному состоянию кода — websocket_api.py, support_transport.py, houseplan-editor-runtime.ts, houseplan-card.ts, i18n, bundle-budget, benchmark-файлы, docs/specs/043-private-support-report.md (контракт Help & feedback, на который #423 ссылается), USER-GUIDE.ru.md.

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

Ревью — не код-ревью: продуктового кода в диффе нет (только docs/specs/423-v170-polish.md + строка в docs/specs/README.md, User-Visible: no). Дешёвые гейты на этом SHA не гонялись отдельно — Validate на 7102994d зелёный (ссылка в задаче на ревью), а диффа в src/**/custom_components/** нет, значит typecheck/test/build/check-docs.mjs не могли измениться этим коммитом. node scripts/process-gate.mjs прогнан вручную — «гейт пройден, предупреждений 0».

Каждое фактическое утверждение ТЗ о текущем коде и цифрах сверено чтением исходников на HEAD, а не принято на слово:

Утверждение ТЗ	Где проверено	Результат
_support_repairs() матчит только broken_plan_*	websocket_api.py:249-256	подтверждено
filename_token[:32] в multipart, token.slice(0,12) в browser download	support_transport.py:61, houseplan-editor-runtime.ts:9307	подтверждено
_build_snapshot() (executor, до 8 МиБ) выполняется до prune/count/limit	websocket_api.py:2158-2202	подтверждено; там же обнаружен смежный баг: old_token того же draft удаляется до проверки лимита (строки 2196-2202) — если проверка после этого проваливается, старый пригодный preview уже потерян. Спецификация фиксирует именно это в контракте §3 и рисках («Неудачный refresh уничтожает старый preview»)
строгое _haIntegrationVersion !== CARD_VERSION в трёх местах	houseplan-editor-runtime.ts:9206, 9326, 9395	подтверждено, ровно три места
config/get не отдаёт capability-поле сейчас	websocket_api.py:1224-1242	подтверждено; топ-level словарь ответа не зависит от space_id/fields/marker_fields — добавление support_api как top-level поля действительно не подчиняется projection, вход AC5 корректен
43 английские строки support.*	src/i18n/en.json, python3 -c "..." подсчёт по факту	подтверждено, ровно 43
Initial View baseline 291046 B gzip	dist/houseplan-assets.json → initialViewGzipBytes	подтверждено побайтово; текущий бюджет scripts/bundle-budget.mjs — 300000, запас 8954 Б (ТЗ округляет до «9,5 КБ» — не расходится по существу)
demo/benchmark_backdrop_decode.mjs создаёт page напрямую, без watchPage/reportPageErrors	сам файл, chromium.launch()+newPage() без импорта из serve.mjs	подтверждено; проверены и остальные восемь demo/benchmark_*.mjs — три идут через launch() из serve.mjs (уже получают watchPage изнутри, serve.mjs:139), пять не создают Playwright page вовсе. backdrop_decode — единственный нарушитель, объём AC9 не занижен и не завышен
§7.2 ТЗ #43 уже требует «family + count» из translation_key	docs/specs/043-private-support-report.md:257-272	подтверждено; технический источник (translation_key, regex, длина 64) — новое техническое решение #423, корректно записанное в «Принятые предположения», не противоречит #43
§8.3 ТЗ #43 уже держит место под {short-id} в имени файла	docs/specs/043-private-support-report.md:375-384	подтверждено, #423 не меняет форму заявленного контракта, только источник short-id
.github/workflows/docs-screenshots.yml действительно имеет разъехавшиеся строки (Capture/гейт)	сам файл, строки ~80/99	подтверждено; #422 (S6-in-progress, ещё не смержен) уже владеет этим пунктом — ссылка корректна, дублирования правки нет
Единственный вызывающий async_submit_report — websocket_api.py:2299	grep по всему backend	подтверждено; удаление параметра filename_token не задевает скрытых вызовов

Продуктовая рамка (§7.1, два первых раздела)

Сценарий и «что человек увидит до и после» присутствуют, отвечают на оба обязательных вопроса: персона — Home admin (единственная персона с can_write, которая видит форму поддержки, docs/SCOPE.md), поверхность — диалог «Помощь и обратная связь» в шапке, момент — сразу после обновления карточки/интеграции через HACS, когда браузер может держать старый bundle. «До»/«после» сформулированы без терминов реализации: форма скрывается при любом несовпадении релиза → форма доступна при совместимом support_api, независимо от номера релиза; имя файла перестаёт называть capability-токен. Это ровно то отличие, которое обязано увидеть ТЗ, а не техническая деталь.

Продуктовый вопрос Q1 и его закрытие

Автор корректно вынес владельцу продуктовый (а не технический) вопрос: как трактовать несовпадение версий карточки/интеграции — по номеру релиза или по capability API (что человек видит: форма показана или скрыта). Вопрос задан одним комментарием с default и альтернативой, issue помечен blocked поверх S3-spec, как требует §7.1. blocked снят, и в финальном ТЗ зафиксирован явный выбор («Владелец подтвердил default: protocol capability важнее равенства product versions») в разделе «Принятые предположения». Отдельного текстового ответа владельца отдельной репликой в этом issue не видно — но это соответствует установленной практике репозитория: то же самое устройство переписки видно в #406 («Q1–Q4 приняты по defaults из issue») и в §4 самого ТЗ #43 («Решения владельца» перечислены без дословной цитаты). Не поднимаю это в находку — это системное свойство процесса этого репозитория, а не дефект конкретного ТЗ.

Критерии приёмки

AC1–AC12 пронумерованы, у каждого — однозначная формулировка и явный способ доказательства (unit/backend/smoke/i18n+bundle/build manifest/review/ diff). Ни один не описывает желаемый результат без наблюдаемого признака:

• AC1–AC4 (repair families, filename, двухфазная quota) проверяемы backend-тестами на конкретных структурах данных, включая новый инвариант «старый token того же draft не удаляется до финальной успешной проверки» — прямое исправление найденного при проверке смежного бага.
• AC5–AC6 (capability contract) единообразны: один supportApiCompatible(value) используется в трёх путях, что устраняет реальный источник несогласованности (сейчас — три независимые проверки, один текст).
• AC7–AC8 (lazy i18n, bundle) привязаны к измеренному факту (291046 Б, 43 строки), не к общему «уменьшить» — числа проверяемы npm run bundle:sync + dist/houseplan-assets.json, повторный расчёт не нужен по гейт-политике.
• AC9 (benchmark guard) — прямое расширение уже существующего в кодовой базе паттерна (test/smoke-harness-contract.test.mjs, issue #404/#407/#421, demo/guard/guard_report_page_errors.mjs); контракт и --guard-probe сформулированы так же, как уже принятый прецедент для смоков.
• AC10 фиксирует границу с #422 отрицательным условием («workflow не меняется»), что проверяется тривиальным diff.
• AC11–AC12 — стандартные гейты и документация/changelog.

«План отрицательной проверки» покрывает по одному конкретному способу сломать каждый из шести пунктов и что должно покраснеть — формально это не раздел «план автотестов» из §7.1, но содержательно эквивалентен и даже избыточен: у каждого AC есть отдельная строка «Доказательство», плюс раздел «Затрагиваемые файлы» перечисляет точные тестовые файлы. Тот же паттерн («План отрицательной проверки» вместо/вместе с «план автотестов») уже принят ревью #421 без отдельной находки — не поднимаю здесь вторично.

Single source (числа, показанные пользователю)

Единственное новое/изменённое число, видимое пользователю, — short-id в имени скачиваемого/пересылаемого файла. Контракт §2 ТЗ явно фиксирует один источник: и frontend (preview.sha256.slice(0,12)), и backend (attachment_sha256[:12]) берут префикс одного и того же уже вычисленного и уже показанного пользователю SHA-256 (диалог показывает полный SHA-256 текстом) — второго независимого вычисления нет. Требование docs/specs/README.md/task про «одно число — один источник» выполнено предположением, а не совпадением: ТЗ прямо называет это в разделе Security («SHA short-id не добавляет новую информацию»).

Не-скоуп и границы

Не-скоуп корректно исключает: смену package v1/схемы, смену лимитов 3/3 и TTL, передачу сырых Repair id, новый negotiation-эндпоинт, вынос немедленной локали целиком, правку docs-screenshots.yml (владеет #422). Все шесть пунктов проверяемого аудита (а/б/в/г/д/ж) покрыты контрактом; пункт (е) корректно и единственно исключён со ссылкой на #422, который на этом SHA ещё не смержен (S6-in-progress, blocked) — ссылка не «дублирует уже готовое», а действительно устраняет двойную правку одного участка файла из двух задач параллельно.

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

• Обязательные разделы §7.1 присутствуют все, под ожидаемыми заголовками — сценарий, что человек увидит, проблема, скоуп/не-скоуп, контракт, UX, модель данных/миграция, i18n, AC, план (в форме «отрицательной проверки»), риски, откат, release-артефакты.
• DoR-пункты (§2.5), проверяемые на этапе спека, закрыты явно: compatibility per CONFIG-COMPATIBILITY.md решена корректно («runtime capability, не persisted config, миграции нет» — поле действительно не персистится ни в одном сторе); touch описан («один predicate для touch/desktop/keyboard»); производительность названа числами, а не общими словами; откат описан по каждому из шести пунктов отдельно.
• Технические решения (regex translation_key, источник short-id, одновременный перенос всех четырёх локалей) записаны явным блоком «Принятые предположения» — ревьюер может оспорить, но ни одно не выдано за факт о существующем поведении.
• Все файловые пути, номера строк и цифры в ТЗ, проверенные выше, совпадают с фактическим деревом на HEAD.

Находки

Нет ни одной находки уровня High или Medium — ни в скоупе, ни вне скоупа.

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

• Реализуемость AC3/AC4 «без store loads/executor build» как именно будет доказана backend-тестом (мокать внутреннюю функцию или считать side-effect) — техническая деталь реализации, не предмет ТЗ-ревью; будет видно на код-ревью.
• Полный текст будущей русской формулировки support.update_required — ТЗ фиксирует смысл («обновите карточку и интеграцию до совместимых версий»), а не точный текст на четырёх языках; это нормально для ТЗ, финальный текст — предмет code review/i18n-тестов.
• Тяжёлые гейты (golden, полный smoke-набор, invariants, performance_smoke, backend HA harness) — не запускал: диффа в src/**/custom_components/** нет, диффа в геометрии/config нет, AC этой задачи их не называют на этапе ТЗ. Они относятся к этапу код-ревью после реализации.

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

SHA: 7102994dc669e789951f3a1906bf07152239f99d
Дерево: docs/specs/423-v170-polish.md (blob новый в этом коммите)
Поиск при протухании SHA:
  git log --all --find-object=$(git rev-parse 7102994d:docs/specs/423-v170-polish.md) -- docs/specs/423-v170-polish.md

---

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

• Ветка: issue/423-v170-polish, коммит 7102994dc669 — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
• Дерево материала: 69763043f0c176779743a040107b9e115862ef2d

  git log --all --format='%H %T' | grep 69763043f0c1
  

• ТЗ docs/specs/423-v170-polish.md, блоб 3a0e7b78a9f8a01f3f54e4a6182dba04badecfae

  git log --all --find-object=3a0e7b78a9f8a01f3f54e4a6182dba04badecfae -- docs/specs/423-v170-polish.md