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

58 lines
17 KiB
Markdown
Raw 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.
# 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. Самостоятельное подобие макета недопустимо. Повторный перенос идёт по [этапам](specs/001-antirion-admin/design-transfer.md); после каждого этапа пользователь проверяет результат до перехода к следующему.
- Не использовать нативные `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).
Из корня репозитория:
```bash
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 и проверку браузером.