Integrate Antirion admin with FastAPI and htmx

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.
This commit is contained in:
2026-11-12 21:55:36 +03:00
parent 58cc8090a9
commit 88ac95dd19
260 changed files with 20395 additions and 320 deletions
+13 -9
View File
@@ -17,6 +17,8 @@ make test # или: pytest
Результат сборки: `OUT/<build_id>/` и симлинк `OUT/current`, который переключается атомарно. Неудачная сборка `current` не трогает.
Расширенный пример для проверки перед возможным переносом сайта — [examples/ai-studio](examples/ai-studio/README.md), также на схеме версии 1: услуги, сценарии, кейсы, обложки, связи и понятные схемы полей. Проверка: `site-engine validate examples/ai-studio`, сборка: `site-engine build examples/ai-studio --out /tmp/ai-studio-dist`, браузерная приёмка: `PYTHONPATH=src python scripts/qa_ai_studio.py`. `studio-site` остаётся базовой фикстурой; отдельный запуск нового примера описан в его README.
## Структура проекта
```
@@ -145,29 +147,31 @@ SITE_COOKIE_SECURE=0 uvicorn site_engine.web.app:create_app --factory --env-file
- **Без потерь.** Форма открывается из файла и отправляется обратно без изменений: у каждого блока примера, всех страниц и записей YAML остаётся тем же по смыслу. Неизвестные ключи не пропадают, привязки сохраняются.
- **Конфликты.** Если файл изменили в другом окне, правка получит 409, а чужие изменения не будут перезаписаны.
- **Проверка при сохранении.** Нельзя сохранить неизвестный фрагмент, несуществующий layout, блок в закреплённый регион, значение не того типа, `{{ }}` в данных, привязку к чужому корню. Пропуск обязательного поля не блокирует сохранение (ADR-003), но он виден в «Проверке страницы», и сборка релиза с ним не пройдёт; опубликованный сайт при этом не меняется.
- **Безопасность.** Каждый POST требует CSRF-токен и Origin своего хоста; id страниц, блоков и записей проверяются регулярным выражением и поиском в реестре, до пути на диске недоступны; предпросмотр отдаётся в `sandbox`-фрейме с CSP без скриптов; в аудит попадают id и тип действия, но не содержимое.
- **Безопасность.** Каждый POST требует CSRF-токен и Origin своего хоста; id страниц, блоков и записей проверяются регулярным выражением и поиском в реестре, до пути на диске недоступны; пассивное превью использует iframe без scripts, интерактивное — отдельный origin и только nonce bridge; в аудит попадают id и тип действия, но не содержимое.
Что работает иначе, чем можно ожидать:
- **Без JS.** Порядок блоков меняется кнопками ↑/↓, элементы списков добавляются через «пустую строку» формы. Скачать htmx и SortableJS в окружении без сети было нельзя, поэтому редактор целиком работает на обычных формах. Если положить `htmx.min.js` в `src/site_engine/web/admin/static/`, админка включит `hx-boost` сама (проверено только разметкой, с настоящим htmx не запускалось).
- **Первая правка файла переформатирует его YAML** в блочный стиль: `{id: b_1, fragment: hero}` станет несколькими строками. Смысл и порядок ключей сохраняются.
- **Обычные формы и локальный htmx.** Порядок блоков меняется кнопками ↑/↓, элементы списков добавляются через «пустую строку» формы. htmx 2.0.11 поставляется в `src/site_engine/web/admin/static/` и включает существующий `hx-boost`; источник, лицензия и SHA-256 — в [VENDOR.md](src/site_engine/web/admin/static/VENDOR.md). Без JS сохраняются обычные формы. CDN и Node-сборка не нужны; SortableJS пока не подключён. Конфигурация запрещает eval, скрипты из ответов и сторонние запросы, отключает сохранение HTML в localStorage и разрешает показ HTML-ошибок 4xx. Новый редактор использует HTML-фрагменты htmx, общий буфер в памяти и явный Save; без JS доступна обычная форма исходника.
Развитие админки описано в [001 — Antirion Rework](specs/001-antirion-admin/spec.md): htmx/Jinja → HTML UI → серверный API-клиент → типизированный JSON API FastAPI → сервисы. JSON API, общий буфер Конструктора/«Эксперта», ручной Save и интерактивное превью реализованы. Контракт, env и запуск второго процесса: [runtime.md](specs/001-antirion-admin/runtime.md); приёмка: [verification.md](specs/001-antirion-admin/verification.md).
- **Конструктор пересобирает YAML** после предупреждения: комментарии и форматирование могут измениться. «Эксперт» и переходы режимов без правок сохраняют точный исходник. «Применить к буферу» не пишет файл; «Сохранить документ» записывает весь документ с CAS, историей и аудитом. До Save исходник можно скачать.
- **Ассеты** выбираются по пути из подсказки, загрузки файлов в редакторе пока нет.
- **Блоки не переносятся между регионами**, только внутри своего списка.
- **Блоки перемещаются** кнопками ↑/↓ или перед указанным ID. Между регионами/слотами действует проверка схемы; циклы и изменение fixed-блоков запрещены.
- **Запись коллекции со «лишним» ключом**, которого нет в схеме, нельзя сохранить в статусе `published`, пока ключ не уберут из файла: так требует ADR-003.
## Что реализовано
| Этап | Состояние |
|---|---|
| M0 Контракт и прототип | Готово: формат файлов, модель блоков, load → validate → render, CLI, 15 фрагментов, сайт-пример |
| M1 Публикуемый движок | Частично: маршруты, ссылки, редиректы, sitemap, атомарная публикация, откат (`services/publish.py`), превью страницы через CLI. Нет: превью по токену, 404-страница из коробки, тема |
| M2 Коллекции, заявки, доступ | Частично: коллекции, display templates, запросы, формы (разметка, версия формы в релизе), **вход одного администратора с аудитом входов и обзорная страница админки**. Нет: роли, приём заявок, outbox, аудит правок |
| M0 Контракт и прототип | Готово: формат файлов, модель блоков, load → validate → render, CLI, 15 встроенных фрагментов, сайт-пример; отдельный steps поставляется с ai-studio |
| M1 Публикуемый движок | Частично: маршруты, ссылки, редиректы, sitemap, атомарная публикация, откат (`services/publish.py`), превью страницы через CLI. Превью по токену реализовано в 001; нет 404-страницы из коробки и системы публичных тем |
| M2 Коллекции, заявки, доступ | Частично: коллекции, display templates, запросы, формы (разметка, версия формы в релизе), **вход одного администратора с аудитом входов и обзорная страница админки**. Аудит Save/create/publish/rollback реализован; нет ролей, приёма заявок и outbox |
| M3 MCP и редактор | Готово: редактор страниц, блоков и записей на `ContentService`, предпросмотр, публикация и откат из админки. Нет: `patch_page`, changeset (rename, delete), MCP-сервера, перетаскивания, загрузки файлов |
| M4 | Не начат |
## Что проверено, а что нет
Тесты и сборка примера выполнялись в окружении без сети: ядро (`core/`, `build/`, `parsing/`, `storage/`, `services/`) и вся логика админки (`web/admin/handlers.py`, `editor.py`, `forms.py`, шаблоны, вход, CSRF, заголовки) запущены и покрыты 206 тестами, включая сквозные через HTML-формы. Тонкий FastAPI-адаптер `web/admin/routes.py` проверен на подставном модуле `fastapi`, а `web/app.py`, `db/`, `mcp/` и `Dockerfile` только компиляцией и чтением: FastAPI, SQLAlchemy и MCP SDK в окружении не было. Ядро намеренно не зависит от pydantic: ошибки должны нести путь к полю (`pages/index.md:regions.main[b_hero].props.title`), а валидация задаётся манифестами фрагментов. Pydantic нужен на границах API (web, mcp).
Приёмка 001 включает полную регрессию ядра/CLI/админки, настоящий FastAPI, JSON-контракт и ASGI-клиент, Chromium на двух origin, адаптивные экраны и установленный wheel без `design/`. Воспроизводимые команды, результаты и ограничения: [verification.md](specs/001-antirion-admin/verification.md). Docker/proxy deployment, БД и MCP-сервер не запускались. Ядро сохраняет dataclass; Pydantic используется на границе API.
## Соответствие журналу решений
@@ -178,7 +182,7 @@ SITE_COOKIE_SECURE=0 uvicorn site_engine.web.app:create_app --factory --env-file
| ADR-003: draft / release / live, версия формы в релизе | `validate_workspace` vs `validate_release`, `_forms/<id>@<версия>.json`, `switch_current` |
| ADR-004: `if_match`, блокировка сайта, история | `services/content.py`, `storage/locks.py`, `storage/history.py` |
| ADR-005: границы доверия | `SandboxedEnvironment`, Markdown без raw HTML, `safe_join`, токены темы, YAML без алиасов |
| ADR-006: 15 фрагментов, `editorial`, `requires` только `feature.*` | `builtin/fragments/`, `models.Page.editorial`, `render._feature_on` |
| ADR-006: 15 встроенных фрагментов, локальный steps в ai-studio, `editorial`, `requires` только `feature.*` | `builtin/fragments/`, `examples/ai-studio/fragments/steps/`, `models.Page.editorial`, `render._feature_on` |
## Как расширять