# 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//{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//` — `fragment.yaml` (поля/слоты), `template.html.j2`, `style.css`, необязательный `script.js`. Общие стили — `builtin/base.css`, токены — `site.yaml:theme.tokens` (например, `color.primary` → `--color-primary`). - Компоненты конкретного сайта добавляй в его `fragments//`. ID плоские и уникальные: встроенные фрагменты нельзя затенять. Для особого дизайна используй новый ID и обновляй ссылки на него в блоках; изменения встроенных компонентов влияют на все сайты. - Изображения, шрифты и прочие файлы сайта — `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`. ## Правила интеграции - Админский дизайн переносить из выбранных `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 как `_<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 и проверку браузером.