5.5 KiB
Контракт и устройство 003
HTTP
JSON API:
POST /admin/api/v1/pages/{identity:path}/update;POST /admin/api/v1/collections/{collection}/entries/{identity}/update.
Совместимые aliases: /editor/pages/{identity:path}/update и /editor/entries/{collection}/{identity}/update внутри того же API prefix.
Пример тела:
{
"source": "---\ntitle: Главная\n...",
"etag": "<основание последнего чтения/сохранения>",
"revision": 12,
"operations": [
{
"type": "inspector",
"fields": {
"operation": ["block"],
"block_id": ["hero_home"],
"p.title": ["Новый заголовок"]
}
}
]
}
inspector.fields — полная успешная форма конкретного инспектора, включая operation/block_id и значения остальных его полей; пример выше сокращён. Значения представлены multimap для checkbox/list/requires. Это позволяет использовать единственный серверный parser схемы. Также принимаются существующие типизированные Action (metadata, entry_fields, block, add, delete, toggle, duplicate, move). Порядок операций существенен. До 100 операций на запрос; ограничения Buffer сохраняются: source до 524288 символов, revision ≥ 0, etag до 80 символов.
Пустой operations валидирует/рендерит исходник Expert без нормализации его байтов. ETag в update передаётся как основание будущего Save; CAS выполняется только при записи. Revision локальна вкладке и служит для сопоставления ответов, а не серверной версией сохранённого файла.
HTTP 200:
{
"snapshot": {"kind": "page", "id": "index", "source": "...", "etag": "...", "revision": 12, "model": {}, "schema": {}, "issues": [], "path": "pages/index.md"},
"preview": {"url": "...", "snapshot": "<32 hex>", "revision": 12, "interactive": false, "expires_at": 0, "html": "<!doctype html>...", "message": "..."},
"preview_error": null
}
При отказе preview: HTTP 200, принятый snapshot, preview: null и preview_error: {code, message, request_id, revision, issues}. При ошибке пакета: HTTP 422 и стандартный error: {code, message, request_id, buffer, issues} с исходной редакцией.
Браузер использует POST /admin/editor/pages/{identity}/update либо /admin/editor/entries/{collection}/{identity}/update. Передаёт FormData: csrf, JSON payload, selection, readonly, mode; заголовки Accept: application/json, HX-Request: true. Адаптер проверяет сессию/origin/CSRF и делает один AdminApi call. К JSON добавляется projection — серверный HTML без повторных скрытых копий исходника в каждой форме конструктора. Save использует тот же транспорт с прежним API save.
Полный контракт: OpenAPI.
Код
services/document_fields.py,document_actions.py— общий parser и нормализация операций, без зависимости от web.services/documents.py:update_buffer— Registry, пакет, диагностика, overlay;save_sourceсохраняет прежний ContentService/CAS.services/preview.py:render_document— renderer и защищённый snapshot на уже подготовленном Registry.web/api/{models,routes}.py— DTO и границы ошибок.web/admin/application.py— сессия/CSRF, AdminApi, серверная проекция.web/admin/static/editor.js— память вкладки, очередь, локальный выбор, применение проекции, Save/конфликт.web/admin/static/preview-update.js— общее обновление DOM;preview.js— проверенный bridge на отдельном origin.
При смене страницы состояние вкладки теряется; диалог интерфейса предлагает обработать несохранённые правки. Скачивание YAML остаётся доступным. localStorage и восстановление несохранённой редакции после перезагрузки не вводятся.
Запуск проверки
PYTHONPATH=src python -m unittest discover -s tests -p test_editor_updates.py -v
PYTHONPATH=src python scripts/qa_editor_updates.py
python scripts/verify_package_001.py --site examples/site-studio
site-engine export-openapi --out specs/001-antirion-admin/openapi.json
Для Chromium нужен установленный Playwright с channel chromium. Проверки работают на временных копиях сайта, обходят proxy для локального браузера и не меняют рабочие data/.env/live. После изменения Python/templates/static runtime в Docker требует пересборки образа.