Files
flexly-cms/specs/002-site-studio-theme/verification-stage-5.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

11 KiB
Raw Blame History

Проверка этапа 5 — Theme Manager и onboarding

Дата: 2026-11-13. Этап реализован по разрешению пользователя после приёмки этапа 4. Подготовлен к отдельной пользовательской проверке; T069 и закрытие всей 002 остаются открытыми.

Результат

/admin/theme / «Дизайн сайта» и /admin/setup/theme предоставляют четыре шага исходного Antirion Theme Manager. Перенесены композиция/HTML/CSS/контролы из design/theme-studio-antirion.html и design/assets/theme-studio.{css,js}: шесть пресетов в исходном порядке, палитра, дополнительные цвета, роли/точки градиентов, пары и выбор шрифтов, scale/line/headingWeight, radius/spacing/shadow/button, контейнеры/gutters, desktop/mobile, YAML/export, reset/skip/repeat и собственные подтверждения.

Сохраняется принятый shell админки. CSS исходного экрана и необходимые button/chip-примитивы ограничены .theme-content. Стенд Hero/Buttons/Cards/Typography перенесён в серверный шаблон; рядом доступна реальная страница сайта. Оба используют core resolver/theme_css и immutable PreviewStore. Ширина внешнего окна передаётся как проверяемая viewport-метаинформация, чтобы исходные responsive-правила стенда не переключались из-за узкого изолированного iframe. Высота окна не пересоздаёт snapshot.

Backend: ThemeService, OnboardingService, восемь JSON endpoints, DTO и form/CSRF HTML adapter через AdminApi. Тема сохраняется через ContentService с точным путём, SiteLock/CAS, валидацией, историей, atomic write и аудитом. При первом Save добавляется ссылка из site.yaml. Ошибка после записи возвращает committed snapshot; 409 — current snapshot. Правки/preview не сохраняют файл; Save не публикует. Workflow хранится отдельно от палитры и переживает рестарт. Новому сайту предлагается setup, существующему — обычный обзор.

Серверные проверки

Полная регрессия: 359 unittest-тестов, успешно, без ошибок/пропусков. В этом этапе добавлен 21 тест в tests/test_theme_manager.py:

  • Snapshot, каталог и все шесть пресетов совпадают с core resolver; YAML формирует backend.
  • Validate, стенд и реальная страница не пишут canonical theme и workflow.
  • Два редактора, CAS/409/current, история и аудит; новый файл только с ABSENT.
  • Отдельный настроенный путь, его повторная проверка под блокировкой, запрет соседнего пути, site.yaml и symlink escape.
  • Ошибки типов/цветов/контейнеров, NaN, контраст как warning с допустимым Save.
  • Реальные ошибки записи и журнала: traceback/request_id, сохранность файла; committed snapshot при отказе аудита/workflow после записи.
  • Обычный отказ записи site.yaml восстанавливает первый файл при первоначальном сохранении.
  • Новый/существующий сайт, сайт с релизом без настройки, skip/restart/завершение и повторная инициализация сервиса/приложения.
  • Авторизация, отзыв сессии, CSRF/origin, отказ внутреннего API без прямого fallback к сервису.
  • Подпись/TTL/auth_epoch immutable preview и неизменность старого снимка после Save.
  • Save → publish → rollback: опубликованная версия и рабочая тема независимы.
  • Responsive-метаданные стенда и строгие границы viewport_width.

Регрессия исходного studio-site запускалась на извлечённой из HEAD временной базовой фикстуре с текущим контрактом темы. Пользовательский examples/studio-site/pages/index.md не переписывался ради тестов. Новый Site Studio проверялся на отдельной временной копии.

Браузер и исходный дизайн

scripts/qa_theme_manager_002.py: настоящий FastAPI, Chromium, отдельный static server оригинала, временная копия Site Studio. 9 групп приёмки, 96 сравнений компонентов: 4 шага × 6 ширин (1440/1280/1024/768/390/360) × 4 элемента. Сравниваются font-size, padding, border-radius заголовков, шагов, карточек/подзаголовков. Дополнительно сверяются responsive padding Hero и видимость его навигации с исходным стендом. Приложены парные полные снимки всех 24 состояний.

Проверены:

  1. Все шаги и Desktop/Mobile на шести ширинах без горизонтального переполнения.
  2. Все шесть пресетов, подтверждение замены, отсутствие автосохранения.
  3. Запоздавший ответ preview не заменяет новое состояние; выбор шага сохраняет тот же DOM iframe.
  4. Палитра/именованные цвета/градиенты/точки, шрифты, fluid/outline/нулевой gutter, overlay реальной страницы; клавиатура, замыкание фокуса, Escape.
  5. Серверный YAML/export текущих несохранённых значений.
  6. Невалидный ввод/восстановление; две реальные вкладки, конфликт, сохранность ввода, явное принятие основы и повторный Save без публикации.
  7. HTTP 500 с request_id и обрыв транспорта: видимая ошибка, ввод и сохранённый файл не теряются.
  8. Отмена перехода, повтор/пропуск мастера без перезаписи рабочей темы, сохранение workflow.
  9. Пассивный и отдельный origin preview с nonce bridge; сохранённый skin админки; отсутствие palette-localStorage.

Итог: 0 JS/CSP-ошибок, 0 native dialogs, 0 неожиданных HTTP-ошибок. Преднамеренные 422/409/500 учитываются отдельно. Это сверка перенесённых компонентов и поведения, а не заявление о попиксельном равенстве двух целых экранов: runtime использует существующий shell, настоящие данные/статусы, серверную диагностику и изолированный iframe. Типографика и отключённые градиенты стенда подчиняются общему контракту темы, включая headingWeight и однотонный fallback; жёстко заданные обходы прототипа не создают второй resolver.

Артефакты: /tmp/site-engine-manager-002/:

  • browser.json, browser.log, unittest.log, package.log;
  • manager-{width}-step{1..4}.png и source-{width}-step{1..4}.png;
  • preset-{minimal,dark,editorial,bold,natural,custom}.png;
  • manager-{width}-preview.png — видимое превью в viewport (Chromium может не рисовать находящийся вне экрана пассивный iframe в full-page снимке);
  • real-page-overlay.png, conflict-keeps-input.png, separate-origin.png.

Desktop и mobile снимки просмотрены визуально; проверен загруженный стенд внутри iframe.

Установленный пакет и контракт

scripts/verify_package_001.py --site examples/site-studio: wheel собран и установлен вне checkout, каталога design/ нет. Проверены все пресеты, штатная сборка, прежний конструктор/API/bridge, CSS/JS Theme Manager, серверный шаблон стенда, validate и отдельный preview origin. Runtime не читает исходники дизайна. Штатный CLI validate examples/site-studio: 0 ошибок, одно ожидаемое W_THEME_GRADIENT_CONTRAST. Ruff для изменённых Python и git diff --check проходят. OpenAPI обновлён штатным export-openapi.

Воспроизведение:

PYTHONPATH=src python -m unittest discover -s tests -p test_theme_manager.py -v
PYTHONPATH=src python scripts/qa_theme_manager_002.py
python scripts/verify_package_001.py --site examples/site-studio
site-engine export-openapi --out specs/001-antirion-admin/openapi.json

При пользовательском изменённом studio-site полный suite требует описанной выше базовой фикстуры, как на предыдущем этапе.

Границы передачи

Рабочие data/.env/SITE_ROOT, live, пользовательские design/ и docker-run.sh не менялись. Коммит/переключение примера/публикация не выполнялись. Для просмотра runtime на сервере нужна пересборка контейнера. Ручная серверная приёмка пользователем остаётся открытой.

Первый Save включает два отдельных atomic rename (theme.yaml и site.yaml) под одним SiteLock с восстановлением при обычном отказе. Это не общая crash-atomic транзакция нескольких файлов: при аварийном завершении процесса между rename может остаться несвязанный файл темы. Он не применяется без ссылки. Настроенная тема обновляется одним файлом. Отказ аудита/workflow после записи явно сообщает committed snapshot; запись не маскируется как неуспешная без последствий.