Add the shared document API, constructor and expert editors, isolated preview, and fragment catalog metadata with typed block IDs. Include design references, specification 001, QA scripts, project guidance, and cached Docker dependency installation. Leave example sites for a separate commit.
12 KiB
12 KiB
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,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 и обновляй ссылки на него в блоках; изменения встроенных компонентов влияют на все сайты. - Изображения, шрифты и прочие файлы сайта —
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. Самостоятельное подобие макета недопустимо. Повторный перенос идёт по этапам; после каждого этапа пользователь проверяет результат до перехода к следующему. - Не использовать нативные
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. - Сохраняй 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 и проверку браузером.