Files

5.5 KiB
Raw Permalink Blame History

Контракт и устройство 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 требует пересборки образа.