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.
This commit is contained in:
2026-11-13 14:04:49 +03:00
parent 231490bb7c
commit 0d171915d7
408 changed files with 11812 additions and 550 deletions
+6 -3
View File
@@ -9,12 +9,15 @@
## Куда подключать дизайн
- Публичный сайт-пример: `examples/studio-site/`. Каркас — `layouts/<id>/{layout.yaml,layout.html.j2}`, композиция страниц — `pages/*.md` (включая подкаталоги), страницы записей коллекций — `display/*.yaml`; схемы коллекций — `collections/`, записи — `content/`.
- `examples/ai-studio/` — расширенный кандидат на замену примера, схема остаётся 1: services/scenarios/cases, общие встроенные фрагменты и локальные `entry_cover`, `benefits`, `related`, `steps`. Списки записей используют `collection_list`, отдельного `catalog` нет. `columns` — контейнер со слотами, `steps` — отдельный компонент «Этапы» из дизайна; прежний `card_grid.variant: steps` поддерживается для совместимости. Локальные ID не должны дублировать встроенные. Контракт и отдельный запуск — его `README.md`; проверка — `PYTHONPATH=src python scripts/qa_ai_studio.py`. Базовую фикстуру и рабочий SITE_ROOT не переключать без задачи на перенос.
- Встроенные компоненты: `src/site_engine/builtin/fragments/<id>/` — `fragment.yaml` (поля/слоты), `template.html.j2`, `style.css`, необязательный `script.js`. Общие стили — `builtin/base.css`, токены — `site.yaml:theme.tokens` (например, `color.primary` → `--color-primary`).
- Компоненты конкретного сайта добавляй в его `fragments/<id>/`. ID плоские и уникальные: встроенные фрагменты нельзя затенять. Для особого дизайна используй новый ID и обновляй ссылки на него в блоках; изменения встроенных компонентов влияют на все сайты.
- `examples/ai-studio/` — расширенный кандидат на замену примера, схема остаётся 1: services/scenarios/cases, общие встроенные фрагменты и локальные `entry_cover`, `benefits`, `related`. Списки записей используют `collection_list`, отдельного `catalog` нет. `columns` — контейнер со слотами, `steps` — общий builtin-компонент «Этапы» из дизайна; прежний `card_grid.variant: steps` поддерживается для совместимости. Локальные ID не должны дублировать встроенные. Контракт и отдельный запуск — его `README.md`; проверка — `PYTHONPATH=src python scripts/qa_ai_studio.py`. Базовую фикстуру и рабочий SITE_ROOT не переключать без задачи на перенос.
- Новый независимый публичный пример `examples/site-studio/` переносит разметку/CSS из `design/examples/site-studio/` без локальных дублей builtin и mini-renderer. `entry_card.entry` — ref с `to: '*'`, значение collection/slug; редактор предлагает опубликованные записи включённых коллекций. Fixed ref/refs сохраняют slug + to. `collections/*.yaml:requires` ограничивает публикацию и queries через feature.<имя>, как у courses/posts. Формы сохраняют HTTP 501 с видимым сообщением.
- Встроенные компоненты: `src/site_engine/builtin/fragments/<category>/<id>/` — `fragment.yaml` (поля/слоты), `template.html.j2`, `style.css`, необязательный `script.js`. Категории: `content`, `data`, `forms`, `marketing`, `media`, `system`. Тема — `site.yaml:theme.file` → `theme.yaml` (`schema: 1`, `preset`, `preset_version`, `overrides`); inline `theme.tokens` отклоняется. Resolver/валидация/CSS — `core/theme.py`, immutable пресеты из дизайна — `builtin/themes/v1/`. Без настройки темы используется minimal@1 в памяти. Общие стили — `builtin/base.css`, затем стили фрагментов, вычисленные токены и `builtin/containers.css`.
- Ширина блока — отдельный `layout: {section_width, content_width}`, значения `inherit|boxed|fluid|full`. Отсутствующий layout у hero/cta_banner/site_header/site_footer означает full/inherit, у остальных inherit/inherit; явный inherit берёт глобальный mode темы. `core/block_layout.py` и `layout_marks.py` применяют ширину к корням и собственным `.f-container`/`.container`, не к контейнерам вложенных блоков. Для независимой ширины фона и текста шаблон должен иметь внешний корень и внутренний контейнер; не оборачивай sticky-header общим служебным div. Контролы инспектора перенесены из design; изменение до Save остаётся в памяти вкладки.
- Компоненты сайта ищутся рекурсивно по `fragment.yaml`: работают `fragments/<id>/` и `fragments/<category>/<id>/`. Во вложенном размещении категория — первый каталог относительно `fragments/`, в плоском — `category` из YAML или `misc`. ID берётся из манифеста, остаётся плоским и уникальным; встроенные фрагменты нельзя затенять. Опциональный `preview.yaml:props` переопределяет inline `fragment.yaml:preview` по ключам; затем используются defaults полей. Для особого дизайна используй новый ID и обновляй ссылки на него в блоках; изменения builtin влияют на все сайты.
- Изображения, шрифты и прочие файлы сайта — `assets/`. Сборщик копирует их в релиз и объединяет CSS/JS использованных фрагментов в общие бандлы с хешами; порядок фрагментов в бандле — по ID, а не по расположению на странице.
- Админка — отдельный интерфейс: `src/site_engine/web/admin/templates/` и `static/`; runtime — `application.py`, серверный клиент — `api_client.py`, формы — `forms.py`, HTTP-адаптер — `routes.py`; `handlers.py` отвечает за вход/статику, `editor.py` сохраняется для совместимости. Работают HTML-формы с локальным htmx; версия, источник и хеш — `static/VENDOR.md`.
- Направление развития — `specs/001-antirion-admin/{spec,plan,tasks}.md`: браузер/htmx → HTML UI → серверный API-клиент → JSON FastAPI → сервисы. API `/admin/api/v1/` реализован в `web/api/` с Pydantic DTO; ядро сохраняет dataclass. Runtime UI не обходит API при ошибке. Контракт/запуск — `specs/001-antirion-admin/runtime.md`, результаты — `verification.md`.
- Новый перенос — `specs/002-site-studio-theme/{spec,plan,tasks}.md`: этапы 1–5 реализованы, контракт — `runtime.md`, результаты проверок — `verification.md` и `verification-stages-2-3.md`. Отдельный `examples/site-studio/` перенесён на штатный renderer (13 опубликованных страниц); проверка — `scripts/qa_site_studio_002.py`, отчёт — `verification-stage-4.md`. Theme Manager реализован: `/admin/theme`, `/admin/setup/theme`, ThemeService/OnboardingService, snapshot/ETag/CAS и серверный preview overlay. Источники Theme Manager — `design/theme-studio-antirion.html` и `design/assets/theme-studio.css` / `theme-studio.js`; сохраняй исходную композицию и сценарии. Runtime заменяет mock-хранилище API: edits только в памяти вкладки, явный Save, никакого localStorage с палитрой. CSS экрана ограничен theme-content, sample и страница живут в immutable iframe. Workflow — SITE_STATE_DIR/theme-onboarding.json; существующий сайт не перенаправляется. Проверка — scripts/qa_theme_manager_002.py, отчёт — verification-stage-5.md. Первый Save создаёт файл темы и ссылку через ContentService.update_files под одной блокировкой; каждая запись atomic, обычный отказ второго файла откатывает первый, но это не crash-atomic транзакция нескольких файлов. При ошибке после commit API возвращает committed snapshot; не повторяй запись вслепую. Manifest релиза фиксирует документ/effective tokens темы; build fingerprint учитывает ресурсы движка. Исторический каталог релиза не перезаписывается, rollback не меняет workspace.
## Правила интеграции