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

SPEC-REVIEW-397-r1

• Issue: https://github.com/Matysh/houseplan-card/issues/397
• ТЗ: docs/specs/397-device-position-echo.md (класс A, полный трек — задета логика синхронизации layout/optimistic locking, попадает под критерий "public contracts")
• Заход: r1 · блокирующих циклов израсходовано 0 из 4 (эта проверка потратит один, см. вердикт)
• SHA ревью: 83692e79 (docs: #397 spec — correct the fingerprint line number)

Скоуп

Issue не помечен small → полный трек, ТЗ обязано жить в docs/specs/. Файл на месте, создан и поправлен коммитами 9fcbb646 и 83692e79, оба User-Visible: no, Issue: #397 — трейлеры корректны для чисто документационного изменения (класс C, часть DoD этапа ТЗ).

Диф этого раунда — только docs/specs/397-device-position-echo.md (174 строки

• 1 правка номера строки). Продуктовый код (src/**) не тронут — это ожидаемо для этапа "ТЗ на ревью": код появится после S5-ready.

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

Ревью читает ТЗ против текущего состояния src/houseplan-card.ts и src/device-position-history.ts на этом SHA — не верит утверждениям на слово, перепроверяет построчно.

1. Прочитаны docs/SCOPE.md, AGENTS.md, PROCESS.md §2.4/§7.1/§7.2.
2. Прочитано тело issue #397 (комментариев нет).
3. Прочитан канонический документ подсистемы — спека #74 (docs/specs/074-device-position-undo.md), сверена формулировка AC10 (строка 254): "Own echo/reconnect same-content сохраняют stack, отличный remote content очищает" — дословно совпадает с тем, как ТЗ #397 её цитирует.
4. Каждая строчная ссылка ТЗ проверена чтением исходника на этом SHA:
   • _persistDevicePlacement, src/houseplan-card.ts:5226-5258 (для сравнения — ниже return; идёт ветка _persistLocalLayout() до закрывающей скобки ~5261, ТЗ обрывает диапазон чуть раньше конца функции — не искажает суть, см. Low ниже);
   • подтверждено: строка 5230 пишет this._layout = applyDevicePlacement(this._layout, deviceId, placement) сырым placement, строка 5244 канонизирует this._layout[deviceId] в локальную pos, строка 5248 отправляет pos на сервер, но pos не кладётся обратно в _layout — фиксация отпечатка на 5253 считается по нежеканоническому _layout. B3 воспроизводится буквально;
   • для контраста: _persistLayout (debounced writer, :4959-4980, вызывается из _savePos, :5316-5323) правильно пишет канонический pos обратно в _layout (:4967) до отправки — это именно тот старый паттерн, на который ссылается ТЗ как на v1.69.0:4776. Он используется для позиций подписей комнат (rl_*, только через houseplan-editor-runtime.ts:10854), не для маркеров устройств — граница скоупа в ТЗ («не в скоупе» не called out явно, но по факту верна: чужой путь не задет и не сломан);
   • _reloadLayoutOnly (:4904-4948): подтверждено, сравнение на :4928 идёт с contentFingerprint(this._layout) — текущим (нежеканоническим) слепком, а не с сохранённым _layoutContentFingerprint;
   • _adoptStructuralResponses (:4203-4269): подтверждено, сравнение на :4249 идёт с this._layoutContentFingerprint — зафиксированным на :5253 по нежеканоническому слепку;
   • demo/smoke_device_position_history.mjs:235-237: подтверждено, строка 235 (serverLayout = structuredClone(c._layout)) перезаписывает уже корректно смоделированный по проводу serverLayout (строится из message.pos на :38-49, канонический с самого начала) локальной копией клиента — именно та подмена, которую описывает M1. Проверка :237 зелёная независимо от состояния кода.
5. Сверена типизация/сборка на этом SHA (Validate не найден зелёным):
   • npx tsc --noEmit → чисто, без вывода;
   • npm test → 1655 tests, pass 1654, fail 0, skipped 1 (существующий известный skip, не связан с #397);
   • npm run build → собрался (dist создан за 15.9s). Эти три гейта проверяют текущее состояние дерева, не содержимое этого ТЗ: на этом этапе продуктовый код ещё не менялся, так что зелёный результат подтверждает только то, что база, от которой стартует реализация, не сломана — он не может ни подтвердить, ни опровергнуть корректность плана.

Обязательные разделы (PROCESS.md §7.1)

Все пункты присутствуют: сценарий · что человек увидит до/после · проблема · скоуп/не-скоуп · контракт поведения · UX · модель данных и миграция · i18n · критерии приёмки · план автотестов · риски · откат · release-артефакты. Сценарий называет персону (хозяин/Home admin), поверхность (редактор плана, фон работы карточки) и момент (reconnect/вторая вкладка/перезапуск HA) — в одном месте с явным продуктовым "до/после" без терминов реализации. Это закрывает J6 SCOPE.md ("Keep the plan true as the home evolves" — drag/resize, multi-client sync, optimistic locking), хотя ТЗ не называет строку J6 явно.

Утверждений о поведении, которое существует только в голове автора и подано как факт без пометки "предположение", не найдено — каждое техническое утверждение о текущем коде (B3, M1) проверено построчно и совпадает буквально (см. выше). Раздел рисков документирует два технических решения (порядок записи против гонки с _sentPos, условие «писать только при отличии» против лишнего ре-рендера) с митигацией — по факту это и есть блок «принято предположительно», просто не выделен формальным заголовком; не блокирует.

Находки

Medium (в скоупе) — AC7 и половина AC5 не имеют способа доказательства

PROCESS.md §7.1 требует критерии приёмки "с указанием доказательства"; §2.5 для DoR — то же самое пофакторно (unit/backend/smoke/golden/"ревью кода").

• AC7 ("Позиции, отправленные и ещё не подтверждённые (_sentPos), продолжают побеждать ответ сервера при слиянии — поведение _reloadLayoutOnly в этой части не меняется.") не имеет ни фразы "Доказательство: …", ни строки в разделе "План автотестов". Риски упоминают эту гонку как митигацию ("AC7 фиксирует существующее поведение слияния"), но это не тест, а намерение. Существующий смок demo/smoke_layout_sync.mjs:87 проверяет только что _sentPos дренируется после ответа сервера, не что он побеждает отличающийся ответ при мердже в _reloadLayoutOnly. Ни один из текущих тестов эту ветку не покрывает — проверено грепом _sentPos/_reloadLayoutOnly по test/ и demo/smoke_*.mjs. Правка B3 меняет ровно тот код (_persistDevicePlacement, окружение _sentPos.set), который граничит с этой веткой слияния — риск регрессии реален и явно того типа, что #102 уже стоил продукту (правка по соседнему замечанию ломает AC, который никто не проверяет).
• AC5, вторая половина ("эхо удаления историю не чистит"), тоже без доказательства. Юнит-план (test/device-position-persist.test.mjs, пункт 2) доказывает только запись/отпечаток для ветки удаления — то есть первую половину AC5 ("локальный ключ удалён до фиксации отпечатка"). Ни один из трёх браузерных смоков в плане (пункты 4–6) не воспроизводит сценарий «удалить → _reloadLayoutOnly() с честным сервером, ответившим тем же удалением → canUndo остаётся true» — все три про перемещение (перемещение → …), не про удаление. Существующий смок уже умеет удалять позицию и катать undo/redo (demo/smoke_device_position_history.mjs:185-221, сценарий "auto-positioned marker round-trips through delete/update"), но там нет шага reload/reconnect после удаления — сценарий AC5 просто не собран.

Почему это Medium, не Low: обе непроверенные ветки лежат ровно там, где работает фикс B3 (запись в _sentPos, порядок записи в _layout до/после отправки) — это тот класс изменений, где локальная правка по одному замечанию способна тихо сломать соседний, никем не тестируемый инвариант. Без явного теста код-ревью не сможет отличить "починили и не сломали AC7/AC5-эхо" от "починили и сломали" иначе как чтением, а чтение уже один раз ошиблось на похожей логике (#102).

Что чинить: добавить в "План автотестов" минимум по одному пункту на каждую ветку — например смок 7 "удаление → честный reload с тем же удалением → canUndo === true" (AC5) и смок 8 (или юнит с моком hass.callWS, если воспроизвести гонку в браузерном смоке дороже) "_sentPos победил при _reloadLayoutOnly, даже когда сервер вернул другое значение для того же устройства" (AC7); проставить "Доказательство: …" у обеих строк AC.

Low — обрыв диапазона строк для _persistDevicePlacement

ТЗ цитирует функцию как src/houseplan-card.ts:5226-5258; фактическое тело функции (включая ветку _persistLocalLayout() без серверного хранилища и закрывающую скобку) простирается примерно до :5261. Диапазон не искажает ни один вывод ТЗ — код до 5258 покрывает всю ветку с багом — не блокирует, автор может поправить попутно или оставить.

Low — отсутствует фраза "Доказательство" у AC3

AC3 не содержит явного "Доказательство: …", но раздел "План автотестов" закрывает это пунктом 5 браузерного смока с явной пометкой "(AC3)" — по факту доказательство названо, просто не в самой строке AC. Не блокирует, чисто стилистическая непоследовательность с AC1/AC2/AC4.

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

• Обязательные разделы §7.1 присутствуют полностью, в правильном порядке, продуктовые "сценарий"/"что человек увидит" отвечают на оба вопроса без терминов реализации.
• Технический разбор B3 и M1 воспроизведён построчно на текущем SHA, а не принят на веру: все номера строк, имена функций и цитаты кода совпадают буквально с содержимым src/houseplan-card.ts и demo/smoke_device_position_history.mjs.
• Граница скоупа корректна: путь _savePos/_persistLayout (используется только для позиций подписи комнаты, rl_*, вызывается из houseplan-editor-runtime.ts:10854) уже пишет канонический ответ обратно и багом не затронут — ТЗ справедливо его не трогает.
• Цитата AC10 ТЗ #74 сверена с docs/specs/074-device-position-undo.md:254 — дословное совпадение.
• Модель данных/миграция, i18n, откат — корректно описывают отсутствие изменений формата и нулевой миграционный риск для точечной правки в две строки исходника плюс одну строку фикстуры.
• Release-артефакты: изменение поведения (Undo/Redo больше не гаснет без причины) верно помечено как User-Visible, требующее правки обоих changelog — соответствует правилу AGENTS.md о трейлере.
• AC1, AC2, AC4, AC6 однозначны и имеют названный, воспроизводимый способ доказательства с прослеживаемой связью AC ↔ пункт плана автотестов / мутант.
• Гейты npx tsc --noEmit, npm test (1654/1655 pass, 1 known skip), npm run build зелёные на этом SHA — база для будущей реализации не сломана (см. оговорку в разделе "Как проверялось": эти гейты не проверяют содержимое самого ТЗ, продуктовый код ещё не менялся).

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

• node scripts/check-docs.mjs — не прогонялся: диф не трогает src/** (только docs/specs/397-*.md), отпечаток скриншотов документации не мог устареть от этого изменения.
• npm run invariants -- --config … — не прогонялся: диф не меняет геометрию, layout-структуру, marker.space или open_spans; формат данных ТЗ прямо заявляет неизменным.
• demo/smoke_*.mjs (браузерные смоки) — не прогонялись: продуктовый код не менялся на этом SHA (это ревью ТЗ, а не кода), смокам нечего проверять, запускать их сейчас означало бы тестировать dev, а не эту задачу. scripts/smoke-select.mjs по той же причине не вызывался — нет диффа в src/**/demo/**, который можно было бы сопоставлять со смоками. Инструмент отложен до этапа код-ревью, когда появится реализация.
• npm run golden:verify, python -m pytest tests_backend -q, performance-профили — не прогонялись: рендер/геометрия/стили/слои и custom_components/**/*.py этим ТЗ не затронуты (нет кода вообще), и ни один AC не называет perf-путь.
• npm run bundle:sync / bundle:budget — не прогонялись: dist/** — генерируемый класс D, этот диф в него не пишет.

Вердикт

Один High не найден. Один Medium в скоупе этой же задачи (незакрытый пункт "План автотестов" для AC5/AC7) — по правилу #202 чинится тем же автором в том же issue, отдельный issue не заводится. Два Low — не блокируют, исправить по вкусу автора.

Жёлтый. Возврат в "ТЗ в работе": дополнить план автотестов пунктами, доказывающими вторую половину AC5 и весь AC7, проставить фразы "Доказательство: …" у AC3/AC5/AC7, по желанию поправить диапазон строк _persistDevicePlacement.