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

23 KiB
Raw Blame History

002 — Site Studio: категории фрагментов, тема и Theme Manager

Дата: 2026-11-13. Статус: этапы 1–5 реализованы; пользователь принял этап 4 и разрешил этап 5. Theme Manager подготовлен к отдельной пользовательской приёмке; вся 002 ещё не закрыта. Связанные документы: план, задачи, проверка этапа 1, проверка этапов 2–3, runtime, проверка этапа 4, проверка этапа 5.

1. Цель и источники

Перенести новый файловый пример design/examples/site-studio/ на штатный движок, обновить общие фрагменты, добавить категории, файловую тему, ширину секций и полноценный Theme Manager. Сохранить схему версии 1 и существующую архитектуру: браузер/htmx → HTML UI → внутренний JSON FastAPI → сервисы → ядро/файлы.

Источники оформления и поведения:

  • Theme Manager — design/theme-studio-antirion.html, design/assets/theme-studio.css и theme-studio.js.
  • Настройки ширины в конструкторе — обновлённый design/assets/builder.js и соответствующий Antirion-макет.
  • Публичный сайт — design/examples/site-studio/: шаблоны, стили, контент и подготовленные превью.
  • Контекст — design/docs/stage7/07_THEME_MANAGER.md, 08_CONTAINER_LAYOUT.md, THEME_MANAGER_QA.md и ADR-007.

Разметка, CSS, композиция, контролы и сценарии Theme Manager переносятся из исходников. Замена mock-данных и хранилища на API не является поводом для самостоятельного редизайна. Браузерный прототип не заменяет сервисы, валидацию и публикацию.

2. Исходное состояние

Новый seed содержит 9 ручных страниц, 8 записей, 15 фрагментов, 5 layouts и 13 HTML-страниц автономного превью. Собственные проверки seed и контейнеров проходят. Штатные проверки workspace и release CMS до переноса обнаруживают суммарно 137 ошибок со встроенными фрагментами, включая 13 повторных ID; без builtin остаются 44 ошибки. Это исходная сверка, а не критерий совместимости после реализации.

Загрузчик уже рекурсивно ищет fragment.yaml, но категория бралась только из YAML. Отдельный preview.yaml, Block.layout и внешний theme.yaml прежде не использовались. Темы работали через site.yaml.theme.tokens. Changeset, публичный приём заявок и расширенный RBAC не являются готовыми сервисами.

3. Фрагменты и каталог

FR-01. Одновременно поддерживаются плоское fragments/<folder>/fragment.yaml и категоризированное fragments/<category>/<folder>/fragment.yaml размещение, в том числе смешанное в одном сайте. Поиск рекурсивный; каталог без манифеста не становится фрагментом. Повреждённый найденный манифест даёт диагностику.

FR-02. ID берётся из fragment.yaml:id, не из пути. Он глобально уникален, одинаково адресуется из Page, Display, Layout и slots. Категория не входит в ID. Дублирование builtin и локальных ID запрещено и возвращает E_FRAGMENT_DUP.

FR-03. Если путь каталога фрагмента относительно fragments/ содержит не менее двух компонентов, категория — первый компонент. Иначе применяется YAML category или misc. Каталог имеет приоритет над YAML; дополнительная вложенность не меняет категорию. Это правило одинаково для builtin и компонентов сайта. Дополнительные категории допустимы.

FR-04. Встроенные фрагменты размещаются так:

Категория Фрагменты этапа 1
content card_grid, columns, disclaimer, faq, richtext, section
data collection_list, entry_header
forms form
marketing cta_banner, hero, page_header
media image
system site_header, site_footer

На этапе 1 меняется размещение и категория; шаблоны и ресурсы сохраняются. На этапе публичных компонентов добавляются общие steps и entry_card; columns и page_header остаются.

FR-05. Соседний preview.yaml необязателен: {name?: string, props: object}. props переопределяют inline fragment.yaml:preview по верхним ключам; затем формы используют defaults полей. Значения false, 0 и явно заданные пустые значения не теряются. Имя preview не переименовывает фрагмент. API сохраняет плоский словарь Fragment.preview. Неверный YAML, форма envelope, неизвестные props и неверные типы дают диагностику с путём; ссылки в образце не разрешаются во время загрузки каталога.

FR-06. Каталог сохраняет название и описание под ним, добавляет видимую категорию, поиск по ID/названию/описанию/категории и фильтры. Стандартные подписи: Контент, Данные, Формы, Маркетинг, Медиа, Системные; misc — Прочее. Неизвестные категории показываются по имени. API отдаёт исходную вычисленную категорию; только UI объединяет прежние русские подписи с новыми группами. «Компоновка» относится к content, «Первый экран»/«Конверсия» — к marketing, «Каркас» — к system. Остальные прежние подписи сопоставляются одноимённым категориям.

FR-07. Ограничения allow региона/слота продолжают действовать независимо от фильтра. Фильтр и подсвеченная кнопка согласованы после обновления HTML. Добавление, выбор секции и preview не создают сохранённый черновик; запись страницы происходит только по Save. Формат новых ID остаётся <fragment_id>_<5 случайных символов>.

4. Принятое решение по теме

TH-01. Для реализации 002 выбран файловый вариант ADR-007: site.yaml.theme.file: theme.yaml, отдельный документ {schema: 1, preset, preset_version, overrides}. Это решение пользователя уточняет Proposed ADR в исходниках дизайна; сами исходники дизайна не переписываются. Переход сразу на новый контракт: механизм миграции и совместимость с inline theme.tokens не создаются. Старый формат получает явную диагностику. Конфигурации примеров и фикстур обновляются в исходниках вместе с реализацией.

TH-02. Отсутствие настройки темы у нового сайта означает безопасный preset minimal@1 без автоматической записи. Целевой файл по умолчанию — корневой theme.yaml; новые примеры задают ссылку явно. Явная ссылка на отсутствующий/некорректный файл диагностируется. Чтение и запись не выходят за root сайта.

TH-03. Preset definitions minimal, dark, editorial, bold, natural, custom версии 1 переносятся из дизайна в пакет приложения. Опубликованные определения неизменяемы. Сервер вычисляет effective tokens через валидируемое глубокое объединение preset и overrides. Custom сохраняет полный набор overrides. Клиент получает каталог с сервера, отдельной канонической копии пресетов в JS/SQLite нет.

TH-04. Типизированный контракт включает восемь colors.*, type.pair/heading/body/scale/line/headingWeight, ui.radius/container/spacing/shadow/button, custom_colors и gradients. Числовые ограничения и списки берутся из исходного дизайна: scale 0.85–1.3, line 1.3–1.9, radius 0–24 px, spacing 0.8–1.4; shadow none/soft/medium, button solid/outline. Heading weight — целое 100–900. Шрифты — системные стеки из разрешённого каталога дизайна; pair может быть custom при ручном выборе. Произвольные CSS, URL, Jinja и JS не принимаются.

TH-05. Семантические цвета — HEX #RRGGBB. Дополнительных именованных цветов не более 24; имя [a-z][a-z0-9_]{1,31}, без конфликтов зарезервированных токенов. Градиенты выключены по умолчанию, не более 12 linear definitions, угол 0–360, 2–5 stop с HEX и строго возрастающими позициями 0–100. Применение именованных цветов и градиентов адресное; отключение градиентов возвращает однотонные fallback.

TH-06. Неверный контракт блокирует сохранение/сборку. Недостаточный контраст — предупреждение в редакторе и публикации, а не блокировка релиза. Минимальные проверки: основной текст на background/surface и muted на surface; для градиентов диагностика не обещает полную проверку произвольного изображения или композиции.

TH-07. Общий resolver ядра используется CLI, сервисами, API, preview и build. Ядро остаётся без обязательного Pydantic; API DTO не дублируют алгоритм разрешения. CSS темы не перекрывается более поздними значениями по умолчанию. Админка не наследует публичные токены.

5. Ширина сайта и блоков

WD-01. overrides.ui.container — объект: mode: boxed|fluid|full, max_width — целое 720–1920 px, gutter.desktop/tablet/mobile — целые 0–96 px. Breakpoints: desktop ≥1024, tablet 700–1023, mobile <700. Старый числовой container не является поддерживаемым production-форматом.

WD-02. Block.layout содержит только section_width и content_width, значения inherit|boxed|fluid|full. Отсутствующий объект: hero, cta_banner, site_header, site_footer получают full/inherit; остальные — inherit/inherit. Явное inherit разрешается в глобальный mode. Ошибки не заменяются молча безопасными значениями.

WD-03. Внешняя ширина управляет фоном секции, внутренняя — её содержимым. Boxed ограничен max_width и gutter, fluid сохраняет gutter без max_width, full заполняет доступную ширину без gutter. Внешняя секция ограничивает внутреннее содержимое. Вложенные блоки, сетки и sticky-header не ломаются от служебных wrappers или CSS предков.

WD-04. Layout одинаково работает в Page, Display, fixed-блоках и вложенных slots. Инспектор использует контролы дизайна. Конструктор/Эксперт, изменение props, добавление, дублирование, сохранение и повторное открытие сохраняют layout. Не теряются выделение и scroll preview; выбор блока не требует сетевого запроса.

6. Общие фрагменты и Site Studio

ST-01. Оформление общего builtin переносится из seed с сохранением возможностей: типизированные actions/links/query, bindings, slots, неограниченные тремя элементами списки. Сопоставление: heading → title; card1…3/step1…3/FAQ → items; button/buttonUrl → actions; collection/sort/limit → source.query; Markdown body → {bind: page.body} / {bind: entry.body}. Нужные статические подписи из дизайна становятся данными, а не захардкоженными текстами всех сайтов.

ST-02. entry_header получает необязательные summary, image и image_alt, сохраняя title/meta. form получает необязательные title/description, сохраняя ссылку form. steps использует существующий контракт title/items из ai-studio. entry_card использует title и обязательный entry типа ref с to: '*', значение collection/slug. Фиксированные ref/refs сохраняют прежний контракт slug + to; универсальный ref проверяет collection, slug и доступность публикации. Встроенный каталог форм редактора даёт соответствующий выбор записей.

ST-03. Рабочий результат размещается отдельно в examples/site-studio/. Данные и статусы из seed сохраняются, схемы адаптируются к CMS: полные fields/of/options/to, SEO bindings, ID страниц в меню, существующий формат redirects, поля формы с key. Выключенные courses/posts описываются согласованно с features/requires. Намеренно неполный draft booking не входит в релиз и не мешает публикации остальных материалов.

ST-04. Layout использует seo_head(), assets_head(), assets_body() и region(). Не создаётся второй renderer или новая template API из mini-renderer. Повторные определения builtin из seed не копируются. При добавлении общего steps локальный дубликат ai-studio заменяется использованием builtin в том же изменении исходников; его контент и ID блоков сохраняются.

ST-05. Формы переносятся как схема и оформление. Приём/хранение заявок, Telegram, outbox и новая модель ролей не входят в 002. Существующий HTTP 501 показывается честно, ложного успеха нет. Новый пример должен проходить штатные validate/build, воспроизводить 13 страниц seed и не выводить черновики в live.

7. Theme Manager, API и сохранение

UI-01. Переносится исходный Antirion Theme Manager: четыре шага, шесть карточек, палитра/дополнительные цвета/градиенты, типографика, токены и ширина, Desktop/Mobile, YAML/export, reset/skip/repeat, собственные dialogs и toast. Исходные HTML/CSS/JS остаются эталоном. Нативные alert/confirm/prompt/beforeunload из переносимого runtime исключены; frontend-сборка не добавляется.

API-01. JSON API под /admin/api/v1: GET /theme, GET /theme/presets, PATCH /theme, POST /theme/preview, POST /theme/validate, GET /theme/onboarding, POST /theme/onboarding/skip, POST /theme/onboarding/restart. HTML: GET /admin/theme, GET /admin/setup/theme, POST /admin/theme/save|preview|validate, POST /admin/setup/theme/skip|restart. HTML runtime использует серверный API-клиент; прямого обхода сервисов нет.

API-02. Snapshot темы содержит document, etag, effective_tokens, diagnostics, workspace_revision и live_build_id. PATCH передаёт полный document, if_match и revision; для отсутствующего файла используется существующий ABSENT. Preview передаёт документ и revision без записи; запоздалый ответ не заменяет новое состояние. Не добавляется скрытый auto-draft или canonical localStorage.

API-03. Save использует ThemeService и ContentService с ограничением на целевой файл: SiteLock → reread/CAS → полная проверка → история → atomic_write → аудит. Конфликт 409 возвращает текущий ThemeSnapshot и сохраняет пользовательский ввод. Ошибки используют общий {error:{code,message,request_id,…}}, диагностические пути и логирование неожиданных исключений со стеком. UI показывает ошибку и не теряет введённую тему при 5xx/сети.

UI-02. Preview использует серверный resolver и существующее изолированное preview-хранилище/origin. Стенд Hero/Buttons/Cards/Typography сохраняет композицию исходника; его токены формирует backend. Preview страницы строится тем же штатным renderer с overlay темы. Скрипты сайта в preview не исполняются; служебные токены не попадают в браузерный API-клиент.

UI-03. В текущем single-admin режиме admin выполняет роль владельца. Состояние мастера хранится в SITE_STATE_DIR/theme-onboarding.json, отдельно от палитры. Новый сайт без настроенной темы и релиза получает setup при первом входе; существующий сайт с темой/релизом не получает принудительный redirect. Skip сохраняется между сессиями, успешный Save завершает настройку, Repeat открывает первый шаг без перезаписи рабочей темы. Перезапуск сервера не сбрасывает workflow.

8. Публикация, границы и приёмка

RL-01. Save изменяет только workspace. Build использует зафиксированную разрешённую тему, включает CSS и сведения preset/version/tokens в артефакт. Отпечаток сборки учитывает тему, preset definitions и используемые ресурсы рендера; одинаковый старый build_id не используется для перезаписи исторического релиза с другим оформлением. Rollback возвращает готовый релиз, не перезаписывая рабочую тему.

AC-01. Приёмка идёт по этапам плана; следующий функциональный этап начинается после пользовательской приёмки предыдущего. Готовая документация не означает готовую функциональность. Рабочий SITE_ROOT не переключается автоматически; root examples/ не включается в коммиты. Исходники дизайна и пользовательские данные не перезаписываются.

AC-02. Проверки включают ядро, API/сервисы, установленный wheel, реальные FastAPI/preview процессы, сравнение с источниками в браузере и текущие регрессии. Theme Manager проверяется на 1440, 1280, 1024, 768, 390, 360 px: все действия, desktop/mobile, клавиатура/фокус, диалоги, отсутствие переполнения, JS/CSP-ошибок, потерянных правок и нативных диалогов. Снимки и ограничения среды прикладываются к отчёту каждого этапа.