docs: review document for #691

Issue: #691 User-Visible: no
2026-09-29 03:09:36 +00:00 · 2026-09-28 12:56:39 +00:00
parent 20f17fee54
commit 3f17a1497d
2 changed files with 173 additions and 1 deletions
@@ -1,10 +1,11 @@
 # Индекс ревью

-Генерируется `node scripts/reviews-index.mjs` (#635) — не редактировать руками. Документов: 169, issue: 80. Вердикт: 🟢 зелёный · 🟡 жёлтый · 🔴 красный · ⚪ не распознан (свободная форма старых документов). H/M — число High/Medium по строке вердикта или заголовкам находок. Файлы — пути, названные в находках; ищите по имени файла: `grep form-kit INDEX.md`.
+Генерируется `node scripts/reviews-index.mjs` (#635) — не редактировать руками. Документов: 170, issue: 80. Вердикт: 🟢 зелёный · 🟡 жёлтый · 🔴 красный · ⚪ не распознан (свободная форма старых документов). H/M — число High/Medium по строке вердикта или заголовкам находок. Файлы — пути, названные в находках; ищите по имени файла: `grep form-kit INDEX.md`.

 | Issue | Документ | Этап · раунд | Вердикт | H | M | Находки | Файлы |
 |---|---|---|---|---:|---:|---|---|
 | #691 | [SPEC-REVIEW-691-r1.md](SPEC-REVIEW-691-r1.md) | spec · r1 | 🟡 жёлтый | 0 | 1 | направление edge-swipe не квантифицировано и не отмечено как допущение | `src/houseplan-card.ts` |
+| #691 | [SPEC-REVIEW-691-r2.md](SPEC-REVIEW-691-r2.md) | spec · r2 | 🟢 зелёный | 0 | 0 | — | — |
 | #689 | [SPEC-REVIEW-689-r1.md](SPEC-REVIEW-689-r1.md) | spec · r1 | 🟢 зелёный | 0 | 0 | — | — |
 | #688 | [SPEC-REVIEW-688-r1.md](SPEC-REVIEW-688-r1.md) | spec · r1 | 🟢 зелёный | 0 | 0 | — | — |
 | #688 | [CODE-REVIEW-688-r1.md](CODE-REVIEW-688-r1.md) | code · r1 | 🟢 зелёный | 0 | 0 | AC6 не покрывает спиральную лестницу и второй масштаб печати на уровне PDF-сцены | `test/pdf-scene.test.mjs` `test/stairs.test.mjs` `src/pdf/pdf-scene.ts` |
@@ -0,0 +1,171 @@
+# SPEC-REVIEW-691-r2
+
+- **Issue:** https://github.com/Matysh/houseplan-card/issues/691
+- **Этап:** `S4-spec-review` (ревью ТЗ, PROCESS.md §2.4)
+- **Трек:** полный (закреплено ещё в r1: «лёгкий трек: нет», P1, ценность
+  9/10, сложность и риск 7/10 — публичный touch-контракт View/kiosk с
+  несколькими конкурентами #449/#563/#578/#531).
+- **Материал:** тело issue #691, раздел `## ТЗ`, плюс комментарий (6)
+  «Правка по spec-review r1» — единственная правка после r1.
+- **Заход:** r2 · блокирующих циклов израсходовано 1 из 4
+- **Роль:** ревьюер ТЗ (не автор)
+
+## Скоуп ревью
+
+Тот же контракт, что в r1: разделение pan и edge-swipe в View/kiosk (48 px
+краевая зона, финальность owner) плюс расширение double-tap/double-click
+«Вписать всё» на room fill/label с задержкой одиночного room-fit на 350 мс.
+Автор внёс ровно одну правку — устранение Medium-находки r1 (не
+квантифицированная граница направления edge-swipe в §6 п.6). Правка
+локальна: три места текста (§6 п.6, §18, AC3), без изменения §1–5, §7–17,
+без новых продуктовых развилок и без кода (диапазон #691 по-прежнему пуст,
+см. ниже). Это укладывается в критерий «дельта локальна» PROCESS.md §2.10:
+не ребейз, не смена контракта, не новая подсистема — разбор ведётся по
+дельте, а не заново.
+
+**SCOPE-проверка** не повторяется: обоснование J1/`docs/TOUCH-SUPPORT.md`
+из r1 не затронуто правкой — наследуется без повторной проверки (см.
+раздел «Унаследовано из r1» ниже).
+
+## Как проверялось
+
+1. Получено тело issue #691 (`gh issue view --json body`) и все 7
+   комментариев (включая машинный вердикт r1 и авторский ответ на него).
+2. Найден и прочитан целиком документ предыдущего раунда
+   `docs/reviews/SPEC-REVIEW-691-r1.md` — единственная находка Medium,
+   её формулировка, смягчающее обстоятельство и требуемая правка
+   («число, либо явная запись в §18, что порог сохраняется без изменения»).
+3. Дельта объявлена сверкой кода: `git diff --stat 1751184b..20f17fee`
+   (1751184b — SHA материала r1, 20f17fee — текущий SHA) показывает только
+   `docs/reviews/INDEX.md` и добавление `docs/reviews/SPEC-REVIEW-691-r1.md`
+   — **исходный код (`src/**`) не менялся ни на строку** между r1 и r2.
+   Значит все построчные сверки кода из r1 (`_panLock`, `_swipeZone`,
+   `STAGE_TAP_DISTANCE_PX=8`, `|dx|>1.5·|dy|` на `src/houseplan-card.ts:6833`,
+   `DOUBLE_FIT_WINDOW_MS=350`, `planGestureOwnerFromPath()`,
+   `beginDoubleFitPointer()` на `src/room-fit.ts`) остаются верны без
+   повторного чтения файлов — они привязаны к байтам, которые не изменились.
+4. Дельта тела issue сверена по трём точкам, которые комментарий (6)
+   «Правка по spec-review r1» назвал явно, против текущего полного текста:
+   - §6 п.6 теперь гласит: «...при сохранённой действующей границе
+     горизонтального преобладания: `|dx| > 1,5 × |dy|` в правильном
+     inward-направлении. Равенство и всё, что ниже этой границы,
+     классифицируется как pan. ... Неверное направление или
+     pan-классификация финальны и не могут позже стать swipe.» — число
+     названо явно, граница (`=`) отнесена к `pan`, что и требовала находка.
+   - §18 «Принятые предположения» получил строку: «Порог clean tap и
+     первичной drag-классификации остаётся 8 px, граница edge-swipe
+     сохраняется `|dx| > 1,5 × |dy|`, окно double-fit — 350 мс.» — число
+     теперь в общем перечне с 48 px/8 px/350 мс, как просила находка.
+   - AC3 (§12) расширен: «Parameterized unit отдельно доказывает диагонали
+     на границе: `|dx| = 1,5 × |dy|` остаётся pan, минимальное превышение
+     при inward-направлении становится swipe.» — закрывает исходный пробел
+     r1 «AC2/AC3 тестируют только явно горизонтальный и явно вертикальный
+     drag, не саму границу».
+   Все три правки на месте, согласованы друг с другом (одно и то же число
+   `1,5`) и с §6 п.6 буквально.
+5. Проверено, что правка не вносит новой неоднозначности: «минимальное
+   превышение» в AC3 — стандартная формулировка граничного теста (тест
+   вправе взять любое значение строго выше порога), не требует
+   дополнительного числа — сам порог (`1,5`) уже назван, только сторона
+   `>`/`=` уточняется тестом. Смягчающее обстоятельство r1 («при сомнении
+   жест уходит в pan», не в switch) не изменилось — так и осталось в §6 п.6.
+6. Перечитаны §1–5 и §7–17 целиком на предмет незаявленных изменений —
+   текст идентичен r1 (сверено построчно с котировками r1-документа в его
+   разделе «Что проверено и корректно», где цитируются §6/§7/§9/§10/§15–18);
+   комментарий (6) автора прямо говорит «Другие разделы и продуктовые
+   решения не менялись» — подтверждено, а не принято на слово.
+7. Гейты (`tsc --noEmit`, `npm test`, `npm run build`, `check-docs.mjs`,
+   смоки, инварианты) не прогонялись: этап `spec`, `git diff
+   origin/dev...HEAD` для кода #691 по-прежнему пуст (см. п.3) — неприменимо
+   к тексту ТЗ, не пропущено.
+
+## Закрытие раунда r1
+
+| Находка r1 | Чем закрыта | Где это видно |
+| --- | --- | --- |
+| Medium: направление edge-swipe (§6 п.6) не квантифицировано и не отмечено как допущение — AC2/AC3 не тестируют саму границу | §6 п.6 явно называет `|dx| > 1,5 × |dy|` и относит равенство к `pan`; то же число добавлено в §18; AC3 получил parameterized-проверку ровно на границе и при минимальном превышении | Тело issue #691, §6 п.6 (предложения 2–3), §18 (последняя добавленная фраза), §12 AC3 (предложение 2) |
+
+## Унаследовано из r1
+
+- **Трек и приоритет** (полный трек, P1, ценность/сложность) — документ
+  `docs/reviews/SPEC-REVIEW-691-r1.md`, SHA материала `1751184b1247`, не
+  затронуто правкой r2.
+- **SCOPE-проверка** (J1, release-blocking touch-поверхность по
+  `docs/TOUCH-SUPPORT.md`, trailer `Touch editor: not exposed`) —
+  тот же документ, раздел «Скоуп ревью»; §4/§5 ТЗ не менялись.
+- **Построчная сверка кода** (`_panLock`, `_swipeZone`,
+  `STAGE_TAP_DISTANCE_PX`, `DOUBLE_FIT_WINDOW_MS`, `planGestureOwnerFromPath`,
+  `beginDoubleFitPointer`) — тот же документ, раздел «Как проверялось» п.4,
+  подтверждено актуальностью байт-в-байт (`git diff --stat` в п.3 выше).
+- **Обязательные разделы §7.1, внутренняя согласованность контракта §6/§7,
+  покрытие AC1–AC12, числовая согласованность 48/8/350** — тот же документ,
+  разделы «Как проверялось» п.3–6 и «Что проверено и корректно»; §1–5, §7–17
+  не менялись (подтверждено в п.6 выше).
+- **Риски, откат, release-артефакты, i18n** — тот же документ, раздел
+  «Что проверено и корректно», не затронуто правкой.
+
+## Находки
+
+Нет. Единственная находка r1 закрыта точечно и без побочных эффектов;
+новых находок в дельте и при контрольном перечитывании остального текста
+не обнаружено.
+
+## Что проверено и корректно
+
+- Правка r1→r2 точна: число `1,5` и отнесение равенства к `pan` появились
+  ровно в тех местах, которые требовала находка (§6 п.6, §18, AC3), и нигде
+  не противоречат друг другу или остальному тексту.
+- Правка не расширяет и не сужает скоуп, не открывает новых продуктовых
+  вопросов — комментарий (6) не содержит вопросов владельцу, только
+  фиксацию решения.
+- Исходный код между r1 и r2 не менялся (`git diff --stat 1751184b..20f17fee`
+  трогает только `docs/reviews/*`), поэтому все технические утверждения ТЗ
+  о текущем поведении кода остаются точными без повторной построчной сверки.
+- Документ ревью r1 (`docs/reviews/SPEC-REVIEW-691-r1.md`) присутствует в
+  дереве, использован как материал предыдущего раунда, ничего в нём не
+  противоречит текущему тексту issue.
+
+## Чего не проверял
+
+- Гейты (`tsc --noEmit`, `npm test`, `npm run build`, `check-docs.mjs`,
+  смоки, `golden:verify`, инварианты, performance) — не прогонял: этап
+  `spec`, кода для #691 по-прежнему нет (см. «Как проверялось» п.3, п.7).
+  Предмет код-ревью после реализации.
+- Не переоценивал заново разделы §1–5 и §7–17 построчно против кода/SCOPE —
+  они не входят в дельту r1→r2, а r1 уже проверил их полно (см.
+  «Унаследовано из r1»); перечитаны только на предмет необъявленных правок
+  (см. «Как проверялось» п.6), расхождений не найдено.
+- Не воспроизводил исходный баг вручную на touch-устройстве — как и в r1,
+  это диагностика по коду, подтверждённая построчным чтением, а не ручная
+  проверка на этапе spec.
+- Не искал новых записей в `docs/reviews/INDEX.md` сверх уже известной по
+  r1 — индекс обновляется шагом публикации, не ревьюером.
+
+## Вердикт
+
+Единственная находка r1 (Medium, не квантифицированная граница
+edge-swipe-направления в §6 п.6) закрыта точно и без побочных эффектов:
+число `|dx| > 1,5 × |dy|` явно названо в контракте, продублировано в
+«Принятых предположениях» §18 и получило собственную parameterized-проверку
+на границе в AC3. Между материалом r1 и текущим SHA (`20f17fee`) код не
+менялся ни на строку, поэтому все построчные сверки r1 остаются в силе.
+Остальные разделы ТЗ (§1–5, §7–17) не изменены и не требуют переразбора.
+Новых находок нет.
+
+Вердикт: зелёный · заход r2 · блокирующих циклов 1/4 · High: 0 · Medium: 0
+
+---
+
+---
+
+<!-- material-anchors: сгенерировано конвейером (#414) -->
+
+## Материал раунда
+
+- Ветка: `dev`, коммит `20f17fee5453` — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
+- Дерево материала: `83fad81b86c95ba0f05aee6c1e1ce7173205e205`
+  ```
+  git log --all --format='%H %T' | grep 83fad81b86c9
+  ```
+- Тело issue: `e8f3dd66a656bbca09f4f291c52632feb3ee16759c54dc9dcdd4e328aaf99b7b`
+- Вердикт конвейера: `green` · High 0