Files
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

110 lines
23 KiB
Markdown
Raw Permalink 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 — Site Studio: категории фрагментов, тема и Theme Manager
Дата: 2026-11-13. Статус: этапы 1–5 реализованы; пользователь принял этап 4 и разрешил этап 5. Theme Manager подготовлен к отдельной пользовательской приёмке; вся 002 ещё не закрыта. Связанные документы: [план](plan.md), [задачи](tasks.md), [проверка этапа 1](verification.md), [проверка этапов 2–3](verification-stages-2-3.md), [runtime](runtime.md), [проверка этапа 4](verification-stage-4.md), [проверка этапа 5](verification-stage-5.md).
## 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-ошибок, потерянных правок и нативных диалогов. Снимки и ограничения среды прикладываются к отчёту каждого этапа.