Files

74 lines
5.5 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Контракт и устройство 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 требует пересборки образа.