Files
flexly-cms/AGENTS.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

17 KiB
Raw Blame History

AGENTS.md

Проект

  • Python 3.12+, пакет site_engine в src/. Публичный сайт — статический HTML из Markdown/YAML и Jinja2; FastAPI обслуживает админку, публикацию и статику.
  • Контент — файлы; сборка не зависит от SQLite. Конвейер: core/registry.py → core/validate.py → core/render.py → build/pipeline.py.
  • Контекст и архитектура: README.md, docs/TZ-site-engine-decisions.md (ADR-001…006). Часть ТЗ ещё не реализована; фактические возможности сверяй с кодом и тестами.

Куда подключать дизайн

  • Публичный сайт-пример: 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. Списки записей используют 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.

Правила интеграции

  • Админский дизайн переносить из выбранных design/antirion-rework.html и связанных editor/publication-макетов: сохранять разметку, CSS, иконки и сценарии, заменяя mock-данные API. Самостоятельное подобие макета недопустимо. Повторный перенос идёт по этапам; после каждого этапа пользователь проверяет результат до перехода к следующему.
  • Не использовать нативные alert/confirm/prompt и beforeunload-диалоги. Подтверждения действий показывать в модальных окнах интерфейса из дизайна. Пересборка YAML не требует отдельного подтверждения.
  • Сначала сопоставь секции макета с layouts, фрагментами и полями. Повторяющиеся секции выноси в компоненты, изменяемый контент оставляй в данных. Используй существующий стек; отдельную frontend-сборку вводи только под конкретную необходимость.
  • В layout сохраняй seo_head(), assets_head(), assets_body() и вызовы region(...); регионы объявляй в layout.yaml. Во фрагментах используй props и slots, ссылки выводи через |href, Markdown — через |md / |md_inline.
  • Новые props и варианты объявляй в fragment.yaml: по этой схеме работают валидация и формы редактора. Сохраняй явные ID блоков, привязки {bind: ...}, типизированные ссылки {page: ...} / {entry: ...} / {url: ...} и запросы {query: ...}. Jinja-выражения в данных запрещены.
  • Именования бери из design/: hero_home, services_list, benefits_grid, process_steps, cta_home — ID блоков, а hero, collection_list, card_grid, cta_banner — типы Fragment. При добавлении и дублировании генерируй ID как <fragment_id>_<5 случайных символов>, например richtext_81ay7; существующие ID сохраняй. Сохраняй это разделение, не добавляй префиксы тематики сайта к общим компонентам; расширения с отличающимся контрактом получают собственный универсальный ID.
  • В каталоге Fragment сохраняй name, description и категории из дизайна: «Список коллекций», «Текстовая секция», «Markdown body», «Карточки». Под названием показывай назначение из fragment.yaml:description, передаваемое через API; ID доступен для поиска и в title. section содержит свой текст и поддерживает слоты, richtext по умолчанию выводит page.body. Изменения builtin/API/шаблонов требуют пересборки Docker-образа; одного bind-mount сайта недостаточно.
  • В админских формах сохраняй action, method, имена полей, csrf, etag (параметр сервиса — if_match) и передачу ошибок. Запись контента проходит через ContentService: блокировка, проверка версии, валидация, история, атомарная запись.
  • Для нового UI HTML и JSON имеют отдельные маршруты. Серверный клиент вызывает API через httpx.ASGITransport; внутренние credentials не попадают в браузер, автор и эпоха проверяются на API-границе. Буфер/превью не сохраняют контент до явного Save.
  • Ошибки JSON API возвращай как error: {code, message, request_id, …} с корректным HTTP-статусом. Общая граница — web/error_handling.py: неожиданные исключения записываются со стеком в uvicorn.error, метод, путь и ID связывают HTML-запрос с внутренним API. Не добавляй в лог тело запроса, cookies и Authorization. В htmx ошибки HTTP/сети показываются через уведомление из дизайна; 5xx не должны заменять несохранённый исходник редактора. Проверка отказов — PYTHONPATH=src python scripts/qa_errors_001.py.
  • Сохраняй autoescape, санитайзер Markdown и CSP. JS для админки подключай внешним локальным файлом. Пассивное превью не исполняет скрипты. Интерактивное использует web/preview_app.py на отдельном origin, nonce bridge и защищённые immutable snapshots; JS сайта не запускается. Обычная сборка не получает служебную разметку.
  • Приём публичных форм пока возвращает HTTP 501; MCP и changeset — заготовки. Не показывай успешную отправку без работающего обработчика.
  • Проверяй мобильную и широкую версии, клавиатурную навигацию, фокус, подписи полей и контраст. Анимации учитывают prefers-reduced-motion.
  • Правь исходники. dist/, data/, .engine/ и .env — результат сборки, рабочие данные и секреты; не используй их как место для разработки дизайна.

Проверка

Установка зависимостей: python -m pip install -e '.[server,dev]' (extra mcp нужен только для работы с MCP).

Из корня репозитория:

PYTHONPATH=src python -m unittest discover -s tests -v
PYTHONPATH=src python -m site_engine.cli validate examples/studio-site
PYTHONPATH=src python -m site_engine.cli build examples/studio-site --out /tmp/studio-dist

Дополнительная приёмка 001: PYTHONPATH=src python scripts/qa_001.py, PYTHONPATH=src python scripts/qa_editor_001.py (нужен Playwright Chromium), PYTHONPATH=src python scripts/qa_selection_001.py (выбор секций и диалоги в обоих режимах превью), python scripts/verify_package_001.py; сравнение с исходным дизайном — scripts/qa_shell_001.py, scripts/qa_pages_001.py и scripts/qa_builder_001.py; экспорт контракта — site-engine export-openapi.

Это команды make test, make validate-example, make build-example без зависимости от make. Собранный сайт — /tmp/studio-dist/current/.

  • Пример сайта используется как фикстура тестов: изменения контента и разметки сверяй с соответствующими проверками. Для изменений поведения обновляй целевые тесты; для чистого CSS проверяй сборку и внешний вид в браузере.
  • Черновики могут быть неполными; релиз содержит только published. Ошибка сборки не должна менять текущий релиз, публикация и откат переключают current атомарно.
  • В отчёте перечисляй выполненные проверки и ограничения окружения; успешные тесты обработчиков не заменяют запуск FastAPI и проверку браузером.