diff --git a/docs/reviews/SPEC-REVIEW-217-r1.md b/docs/reviews/SPEC-REVIEW-217-r1.md new file mode 100644 index 00000000..97a06589 --- /dev/null +++ b/docs/reviews/SPEC-REVIEW-217-r1.md @@ -0,0 +1,130 @@ +# SPEC-REVIEW-217-r1 + +- **Issue:** #217 — Text-маркер: внешняя обводка стала эллипсом вместо капсулы +- **Артефакт ТЗ:** `docs/specs/217-text-shell-outline.md` +- **Ветка/SHA:** `issue/217-text-shell-outline` @ `fe33dea` +- **Трек:** обычный (не `small`) +- **Цикл:** r1/4 +- **Вердикт:** зелёный · High: 0 · Medium: 0 + +## Скоуп ревью + +Первый цикл — разбор полный. Проверялись: тело issue #217 и оба комментария +(аналитика, хендофф автора ТЗ), `docs/specs/217-text-shell-outline.md` +целиком, соответствие обязательным разделам §7.1 PROCESS.md, техническая +достоверность диагноза причины по фактическому коду, согласованность с +родительскими задачами #179 (нормативный дизайн-пакет) и #213 (контракты +размеров/inset/hover, которые #217 обязуется не трогать). + +## Как проверялось + +- `docs/SCOPE.md`, `AGENTS.md`, `PROCESS.md` — прочитаны целиком, требования + §2.4/§7.1/§12 применены к ТЗ. +- `docs/USER-GUIDE.ru.md` (разделы «Устройства», «Визуальные состояния + устройств») — сверена терминология («капсула», «shell», «полукруглые + торцы»). +- `docs/STYLING-HOOKS.md`, `docs/LIVE-TEXT.md` — проверены как возможные + канонические документы подсистемы; ни один не описывает геометрию внешней + рамки Text-маркера напрямую, канон для неё — принятый спек #213 + (`docs/specs/213-device-marker-geometry.md`), который ТЗ #217 и цитирует. +- `docs/specs/213-device-marker-geometry.md` — сверены §9.1 (inset/anchor + контракт) и §11 (hover всей capsule), на которые #217 ссылается как на + неизменяемую базу. +- `src/styles.ts` (строки 2040–2086), `src/device-face.ts` (строки 86–101) — + прочитаны, чтобы проверить точность «Подтверждённой причины» ТЗ по + фактическому коду, а не по пересказу автора. +- `demo/srv/reference/device-icons/Light/Text Default.svg` — открыт и разобран + как SVG (outer `` и внутренний ``), чтобы убедиться, что + stadium-контракт для внешней рамки действительно взят из нормативного + дизайн-пакета #179, а не додуман автором ТЗ. +- Существование файлов, упомянутых в §11/§14 ТЗ, проверено по факту: + `test/device-marker-polish-contract.test.mjs`, + `demo/smoke_device_icon_design.mjs`, `demo/smoke_device_preview_parity.mjs`, + `demo/smoke_static_icon.mjs`, `scripts/check-docs.mjs`. +- Прослежено, что `cardStyles` из `src/styles.ts` подключён во всех трёх + поверхностях (`houseplan-card.ts`, `space-card.ts`, `hp-device-preview.ts`), + что делает заявленный в ТЗ «shared device face without a second renderer» + технически достижимым для AC7 (surface/theme parity). + +Код не менялся и не проверялся на этапе реализации — на этапе `spec` его +ещё нет (issue в `S4-spec-review`); все находки касаются только текста ТЗ и +его соответствия существующему коду/дизайну. + +## Находки + +Нет находок High или Medium. + +**Low (снята с записью, не требует правки).** §2 ТЗ описывает форму словом +«stadium» — англицизм дизайн-жаргона, которого нет в +`docs/USER-GUIDE.ru.md`; там для того же объекта используется «капсула» / +«внешняя капсула» (строки 563–564, 836). Раздел «что человек увидит» по +§7.1 должен быть без терминов реализации, и «stadium» на грани этого +требования. Решение ревьюера: не блокирует и не требует цикла, потому что +(а) release note в §17 ТЗ и заголовок issue уже используют корректное +русское «капсульная форма» — расхождение не попадёт ни в changelog, ни в +UI; (б) «stadium» используется только как техническое уточнение геометрии +внутри ТЗ, рядом с явным описанием «торцы — полуокружности, между ними +прямой участок», которое самодостаточно и не требует термина. Автору +предложено при следующей правке ТЗ (если он будет) заменить слово на +«капсула», но это не является условием зелёного вердикта. + +## Проверка по существу (не только по форме) + +Дословно перепроверена «Подтверждённая причина» (§3 ТЗ) против кода: + +- `src/styles.ts:2049` — общий fallback `.device-shell-frame { border-radius: + 9999px; }` подтверждён. +- `src/styles.ts:2061-2062` — `.device-shell:not(.with-values) + .device-shell-frame { border-radius: 50%; }` подтверждён как источник + регрессии. +- `src/device-face.ts:96-101` — класс `text-shell` присваивается по + `presentation.valueText != null`, класс `with-values` — по + `hasSections` (badge либо legacy-метрики), это два независимых условия. + Text-only маркер (только `valueText`, без badge/legacy) получает + `text-shell` без `with-values` и поэтому действительно попадает под + круглый override — диагноз ТЗ точен, а не «догадка, выданная за факт». +- Комбинация `text-shell` + `with-values` (Text вместе с value-badge/legacy) + уже сегодня исключена из круглого override и не затронута регрессией; ТЗ + не утверждает обратного и не обязано отдельно оговаривать этот вариант. + +Референсный SVG (`Light/Text Default.svg`) прочитан как файл, не поверх +слов автора: внешний `` — сплошная stadium-обводка (два больших +дуговых торца, соединённые прямыми верхней/нижней границами), внутренний +`` — капсула с радиусом ровно в половину высоты. +Нормативный источник действительно однозначно задаёт stadium и для внешней +рамки, а не только для core — предположение №1 в §18 ТЗ подтверждено +файлом, а не принято на веру. + +## Проверка обязательных разделов §7.1 + +Все обязательные разделы присутствуют и содержательны: сценарий (§1) · что +человек увидит до/после (§2) · проблема (§3) · нормативные источники и +приоритет (§4) · scope/не-scope (§6/§7) · контракт поведения (§8) · UX (§9) · +данные/migration/i18n (§10) · архитектура (§11) · performance/security (§12) · +AC1…AC9, каждый с доказательством (§13) · план автотестов (§14) · риски (§15) · +откат (§16) · release-артефакты (§17). Продуктовые открытые вопросы +отсутствуют, а неизбежное техническое предположение (какой CSS-механизм +сузить: `9999px` vs height-derived) явно оставлено реализации в §18, +пункт 2, и корректно помечено как «может быть изменено ревьюером». + +Каждый AC1–AC9 однозначен, имеет названный способ доказательства +(`unit`/`browser smoke`/`golden`/«ревью кода»/`docs diff`) и проверяем не +только предъявлением, но и потенциальным падением (AC2 явно требует +documented mutant, AC4 — rect/inset assertions до/после). + +## Соответствие SCOPE.md + +Задача — исправление регрессии дизайн-системы #179, ранее принятой как +Core user job J5/J1 (видимая точность отображения устройства на плане). +Не расширяет продуктовый скоуп, не вводит новую функциональность, не +затрагивает «Out of scope» раздел SCOPE.md. + +## Что не проверялось + +- Реальная browser-геометрия (rendering) не запускалась — на этапе `spec` + кода ещё нет; проверка ограничена статическим чтением текущего `src/`. +- Golden/визуальные артефакты не создавались и не сравнивались — они + появятся в реализации и будут предметом code-review. +- Не проверялась производительность — на этой стадии нет кода для профиля; + §12 ТЗ корректно ограничивает изменение CSS-only geometry без новых + layers/observers, что снимает необходимость профиля уже на этапе ТЗ.