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