# Контракт и устройство 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. Пример тела: ```json { "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: ```json { "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": "...", "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](../001-antirion-admin/openapi.json). ## Код - `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 и восстановление несохранённой редакции после перезагрузки не вводятся. ## Запуск проверки ```bash 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 требует пересборки образа.