Make editor updates asynchronous with unified preview API

This commit is contained in:
2026-11-13 15:18:56 +03:00
parent 0d171915d7
commit 3562194d92
30 changed files with 2445 additions and 748 deletions
+73
View File
@@ -0,0 +1,73 @@
# Контракт и устройство 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": "<!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](../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 требует пересборки образа.