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

15 KiB
Raw Blame History

План 002 — Site Studio и Theme Manager

Дата: 2026-11-13. Основание — спецификация, выполнение — задачи, проверка текущего этапа — verification.md.

Этапы 4 и 5 выполнены последовательно по отдельным поручениям пользователя. Этап 4 принят; приёмка Theme Manager — отдельный шаг.

Этапы 2 и 3 взяты и выполнены вместе по прямому поручению пользователя. Их совместная приёмка — verification-stages-2-3.md; переход к этапу 4 остаётся отдельным решением.

Архитектурные решения

  • Каталог обнаруживает манифесты рекурсивно; идентичность фрагмента и категория — разные свойства. Сохранены глобальные ID и запрет затенения builtin.
  • Категория пути вычисляется в registry. API остаётся проекцией ядра; русские подписи и объединение прежних категорий относятся только к HTML-представлению.
  • Файловый theme.yaml — единственный реализованный формат темы с этапа 2. Это выбранное пользователем решение, без инфраструктуры миграции; прежний inline runtime отклоняется диагностикой.
  • Валидация/разрешение темы и ширины живут в ядре с dataclass. API использует Pydantic DTO, вызывает сервисы вне event loop и сохраняет существующие обработчики ошибок. Предпросмотр, CLI и build используют один resolver.
  • Theme Manager переносится из исходников Antirion. Моки и localStorage заменяются API; новый интерфейс и независимые frontend-алгоритмы темы не создаются.
  • Каждая стадия готовится отдельно для пользовательской приёмки. Запуск проекта с новым SITE_ROOT и коммиты examples в этот план не входят.

Этап 1 — Категории и каталог (реализован, ожидает приёмки)

  1. В загрузчике вычислить категорию из первого каталога для вложенного размещения, сохранив плоскую структуру и рекурсивный поиск.
  2. Загрузить optional preview.yaml, проверить envelope/props, объединить поверх inline preview по ключам, оставить плоскую форму API.
  3. Перенести 15 builtin по категориям, изменить только category в манифестах. Сверить ID и байты шаблонов/ресурсов.
  4. Показать категории в существующем каталоге, добавить поиск по коду и подписи, объединить legacy labels, сохранить описание/allow/ID. Синхронизировать фильтр после HTML swap.
  5. Проверить смешанный сайт и реальный путь login → HTML → внутренний API → transform/preview/save. Повреждённый preview должен быть виден в workspace/publish, отказ не меняет live.
  6. Проверить wheel вне checkout, браузер desktop/mobile и регрессии; обновить AGENTS/README и отчёт.

Выход: действующие сайты используют прежние ссылки на фрагменты; пользователь видит категории в добавлении блока. Ни тема, ни оформление публичных фрагментов на этой стадии не меняются.

Этап 2 — Ядро файловой темы и публикация (реализован, ожидает приёмки)

  1. Добавить dataclass-модель ThemeDocument/EffectiveTheme, валидатор и каталог immutable preset@version в runtime-пакете. Перенести значения и разрешённые шрифты из дизайн-JS, зафиксировать диапазоны из spec.
  2. Site читает theme.file; registry разрешает документ и добавляет диагностику в общий Report. Отсутствующая настройка использует minimal@1 в памяти; явная плохая ссылка и legacy tokens дают ошибку.
  3. Обновить конфигурации примеров/фикстур в исходниках под theme.yaml. Сохранять цвета существующих примеров через новые семантические/custom токены, не переписывая их страницы.
  4. Подключить effective tokens к bundle и preview через общий renderer. Токены применяются после defaults; CSS-потребители builtin используют согласованную таблицу переменных. Не менять палитру админки.
  5. Дополнить manifest релиза разрешённой темой и preset/version. Учитывать theme/preset/render resources при fingerprint; не перезаписывать исторический релиз другим результатом. Сохранять атомарный current и независимость rollback от workspace.
  6. Проверить воспроизводимость, все preset/Custom, контраст-warning, недопустимый ввод, сохранность старого live при ошибке и правильную тему после rollback. Набор пресетов и данные темы должны попадать в wheel.

Выход: CLI/build/preview читают один новый контракт и одинаково формируют оформление. API/UI управления темой добавляются на этапе 5.

Этап 3 — Ширина сайта и блока (реализован, ожидает приёмки)

  1. Добавить BlockLayout в модель, разрешённые ключи YAML, общий валидатор и resolver наследования. Явно проверить объекты и enum; числовой legacy container не включать.
  2. Передать layout через снимки, существующие операции блока, API DTO, формы и parse/serialize. Метаданные не должны теряться при редактировании props, добавлении, дублировании и переносе блока.
  3. Применять ширину к собственным корням и контейнерам фрагмента, исключая утечку правил в nested blocks. Сохранить sticky-header, anchors, slots и preview markers без нарушающих геометрию wrappers.
  4. Перенести контролы ширины инспектора из обновлённого дизайна и связать с transform. Обновление preview асинхронное; сохранить выделение/scroll и локальный выбор секции.
  5. Проверить global modes, пары внешней/внутренней ширины, responsive gutters и границы 699/700/1023/1024 px. Сверить Конструктор ↔ Эксперт, fixed/Display/slots и отсутствие overflow на 360 px.

Выход: штатный renderer и конструктор понимают layout из нового примера.

Этап 4 — Общие компоненты и examples/site-studio

  1. Сопоставить seed и текущие полноценные схемы по ST-01/02. Сохранить ID и проверенные названия/описания, перенести HTML/CSS компонентов из источника.
  2. Добавить builtin content/steps с title/items, исключив локальный дубликат ai-studio в том же обновлении исходников. Сохранить поддержку прежнего card_grid.variant: steps.
  3. Добавить data/entry_card и универсальный ref to: '*', value collection/slug: парсинг, валидация, resolver, выбор в формах, проверки published target. Фиксированные ref/refs не изменяются.
  4. Дополнить entry_header и form необязательными полями из spec. Перенести общие стили, связывая литералы дизайна с effective tokens, сохраняя исходное оформление при значениях seed.
  5. Создать новый examples/site-studio: данные/ассеты из seed, адаптированные Page/Entry/Collection/Display/Menu/Form/Redirect, layouts с engine hooks. Не копировать повторные builtin manifests или mini-renderer.
  6. Описать запуск отдельно от рабочего сайта. Проверить 13 опубликованных страниц, отсутствие draft booking в live, ссылки/ассеты/редиректы, формы без ложного успеха, отключённые коллекции и совместимость прежних примеров.
  7. Проверить публичные страницы и общие компоненты относительно design preview на desktop/mobile. Документировать различия из-за данных и штатных SEO/assets hooks; не заменять визуальную проверку HTTP 200.

Выход: отдельный пример проходит стандартный validate/build, общие компоненты сохраняют функциональные возможности.

Этап 5 — ThemeService, Theme Manager и onboarding

  1. ThemeService предоставляет get/list_presets/resolve/validate/save; OnboardingService — status/skip/restart. Подключить JSON и HTML endpoints из API-01 без обходов внутреннего API.
  2. API DTO: ThemeSnapshot, ThemeUpdate, ThemePreviewRequest, ThemeDiagnostics, OnboardingState. Snapshot содержит document/etag/effective_tokens/diagnostics/workspace_revision/live_build_id; ErrorEnvelope допускает текущий снимок темы при 409. If-match для создания — ABSENT.
  3. Save проходит через ContentService с точным разрешённым путём, SiteLock, CAS, проверку, историю, atomic write и аудит. Изменения после Save не публикуются. Конфликт и 5xx сохраняют пользовательский ввод; неожиданные ошибки коррелируются через request_id.
  4. Расширить существующий PreviewStore overlay темы без сохранения файлов сайта, сохранив CSP/origin/nonce/immutable snapshots. Стенд из дизайн-макета и фактическая страница используют один token resolver; ответы связаны с revision.
  5. Перенести исходные HTML/CSS/JS Theme Manager в существующий Antirion shell. Подключить четыре шага, reset/skip/repeat, YAML/export, диагностику, desktop/mobile и ссылки настройки. Сохранять рабочее состояние вкладки до явного Save; не переносить auto-localStorage или beforeunload.
  6. Состояние мастера хранить атомарно в SITE_STATE_DIR/theme-onboarding.json под блокировкой сайта; в нём нет canonical palette. Инициализацию различать по наличию настроенной темы/релиза, текущему admin разрешить как владельцу. Save завершает workflow, skip/restart независимы от live.
  7. Выполнить серверные проверки ETag/CSRF/доступа, сбои диска/аудита/сети, два одновременных редактора, рестарт, существующий/новый сайт, skip/repeat, publish/rollback и отсутствие потери правок.

Выход: экран из дизайна управляет настоящим файлом и превью, существующая публикация остаётся отдельным действием.

Общая проверка и передача этапов

После каждого функционального этапа: целевые unit/integration checks → штатные validate/build → реальный FastAPI и browser → installed wheel для новых ресурсов → отчёт с ограничениями → пользовательская приёмка.

Для нового Theme Manager обязательна сверка с оригиналом на 1440/1280/1024/768/390/360 px, клавиатура и фокус, отсутствие native dialogs, JS/CSP/HTTP-ошибок, горизонтального переполнения и изменения skin админки. Для общих компонентов повторить проверки старых примеров и функциональности больше трёх steps/items.

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

Изменения runtime требуют пересборки образа. Root examples не коммитятся, рабочий SITE_ROOT не переключается, live не публикуется автоматически. Завершение всей 002 отмечается только после выполнения и приёмки всех этапов.