Files
flexly-cms/specs/002-site-studio-theme/verification.md
T
phelex 0d171915d7 Add Site Studio themes and Theme Manager
Support categorized fragments, theme presets, block widths, and server-backed theme editing with onboarding and preview.

Include Site Studio, design sources, specification and verification reports; remove the legacy studio-site example.
2026-11-13 14:04:49 +03:00

45 lines
8.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Проверка 002 — этап 1: категории фрагментов
Дата: 2026-11-13. Реализация этапа 1 подготовлена к пользовательской приёмке. Следующие этапы — тема, ширина блоков, перенос публичных компонентов, отдельный Site Studio и Theme Manager — этим отчётом не закрываются.
Это отчёт состояния на момент завершения этапа 1. Последующая реализация темы и ширины описана отдельно в [проверке этапов 2–3](verification-stages-2-3.md); актуальный контракт — [runtime.md](runtime.md).
## Реализованное поведение
- Обнаружение рекурсивное, по `fragment.yaml`; имя каталога не подменяет ID манифеста. Плоское, категоризированное и смешанное размещение работают одновременно.
- Для вложенного фрагмента категория — первый каталог относительно `fragments/`, для плоского — YAML `category` или `misc`. Путь имеет приоритет над YAML, дополнительная вложенность категорию не меняет. Допустимы произвольные категории сайта.
- Все 15 builtin разложены по шести категориям: `content` (6), `data` (2), `forms` (1), `marketing` (3), `media` (1), `system` (2). Их ID, шаблоны, CSS и JS сохранены; побайтовое сравнение перемещённых шаблонов и ресурсов с HEAD прошло. `columns` и `page_header` сохранены.
- API продолжает отдавать строку `schema.fragments[id].category` и плоский словарь `preview`. Ссылки на фрагменты остаются без префиксов категорий; повторные ID запрещены.
- Необязательный соседний `preview.yaml` имеет форму `{name?: string, props: object}`. Его `props` переопределяют inline preview по ключам; отсутствующие значения берутся из defaults полей. `name` из preview не меняет имя фрагмента. Некорректные файлы дают диагностику с путями, а не исключения из `.get()` при рендере формы.
- В каталоге видны категория, название и назначение. Поиск учитывает ID, название, описание, код категории и прежнюю русскую подпись. Прежние категории объединяются со стандартными только при отображении: исходное значение API и файла сохраняется.
- Добавление блока и предпросмотр не записывают страницу. Явное сохранение, ETag, CSRF, ограничения регионов/слотов и формат новых ID сохранены.
## Выполненные проверки
1. Полный набор Python-проверок: **288 тестов, 0 ошибок, 0 падений, 0 пропусков**. Фикстура `examples/studio-site` взята из HEAD во временный каталог, поскольку рабочий `pages/index.md` изменён пользователем; исходный пример не менялся. Машиночитаемый результат: `/tmp/site-engine-fragments-002/unittest.json`, подробный лог — `unittest.log` в том же каталоге.
2. Новые проверки ядра: **23 теста** для обнаружения, приоритета категории, глобальных ID, дубликатов, preview и его диагностики. **7 интеграционных тестов** используют самостоятельную временную файловую модель и настоящую цепочку login → HTML → внутренний API, включая экранирование пользовательских категорий, диагностику повреждённого preview в workspace/JSON/HTML и сохранность опубликованного релиза при отказе.
3. Валидация текущего `examples/ai-studio`: **0 ошибок, 0 предупреждений**. Штатная сборка: **14 страниц** в `/tmp/site-engine-fragments-002/ai-studio-dist/current/`.
4. Проверка упаковки: wheel содержит все файлы вложенных builtin. Установка wheel во временный каталог и запуск FastAPI вне checkout прошли: статика, шаблоны, API, изолированное превью и bridge работают без каталога `design/`.
5. Браузер: настоящий FastAPI и отдельный preview origin, Chromium 158, **1440×960 и 390×844**, **8 групп приёмки**. Проверены категории, русские подписи, поиск, пустая выдача, ограничения региона/слота, клавиатурный фокус, sidecar defaults с `false`/`0`, добавление/превью без записи, согласованность активного фильтра после HTML swap, явное сохранение/повторное открытие, CSS вложенных и плоских фрагментов в опубликованном бандле. Неожиданных JS-ошибок, нативных диалогов и передачи внутренних credentials браузеру нет.
6. Проверены Ruff для изменённого Python-кода и `git diff --check`.
Браузерный отчёт и скриншоты находятся в `/tmp/site-engine-fragments-002/`: `report.json`, `catalog-desktop.png`, `mobile.png`. При проверке ответы runtime `builder-adapter.css` и `builder.js` сравниваются с текущими исходниками; их SHA-256 записывается в отчёт. Скриншоты просмотрены: категории видимы, горизонтального переполнения каталога нет.
## Воспроизведение
```bash
PYTHONPATH=src python -m unittest discover -s tests -p 'test_fragment_catalog*.py' -v
PYTHONPATH=src python scripts/qa_fragments_002.py
PYTHONPATH=src python -m site_engine.cli validate examples/ai-studio
PYTHONPATH=src python -m site_engine.cli build examples/ai-studio --out /tmp/ai-studio-dist
PYTHONPATH=src python scripts/verify_package_001.py
```
Браузерный сценарий самостоятельно получает базовую фикстуру через `git archive HEAD`, не читая и не изменяя рабочий `examples/studio-site/pages/index.md`. Обычные команды полной проверки и `verify_package_001.py` используют рабочий пример: при наличии пользовательских изменений его результаты могут отличаться. Для описанной проверки установленного wheel использовалась временная копия актуальных `src/`, `pyproject.toml`, `README.md` и базовая фикстура из HEAD.
## Развёртывание и приёмка
Рабочий `SITE_ROOT`, файлы сайта и исходники `design/` не переключались и не менялись. Коммиты и публикация на сервер не выполнялись. Изменения builtin, загрузчика и админки требуют пересборки Docker-образа; bind-mount каталога сайта их не обновляет.
После установки новой сборки открыть конструктор → «Добавить блок»: проверить подписи шести категорий, фильтрацию и существующие локальные фрагменты. Далее этап 1 принимает пользователь; переход к ядру темы выполняется после этой приёмки согласно согласованному плану.