Make editor updates asynchronous with unified preview API
This commit is contained in:
@@ -0,0 +1,10 @@
|
||||
# План реализации 003
|
||||
|
||||
1. **Общий сервисный контракт.** Вынести разбор типизированных полей и операций из HTML-адаптера в сервисный слой, сохранить совместимость прежних форм/маршрутов. Добавить пакетный update с одной загрузкой Registry и откатом всего пакета при ошибке.
|
||||
2. **Единый запрос.** Добавить DTO и update для страниц/записей. Рендерить preview на подготовленном overlay; независимо вернуть ошибку preview. HTML-адаптер делает один вызов AdminApi и добавляет серверную проекцию интерфейса.
|
||||
3. **Очередь браузера.** Хранить источник/ETag/revision и несогласованные формы в памяти; сериализовать запросы, объединять ввод, сохранять новые изменения поверх ответов. Выбор секции выполнять локально.
|
||||
4. **Сохранение DOM.** Оставлять активный инспектор при правках свойств, точечно обновлять строки списков. Структурные изменения применять по серверным шаблонам. Сохранять iframe/Document при обновлении HTML, поддержать пассивный и отдельный origin.
|
||||
5. **Save и отказы.** Дождаться очереди перед Save, сохранить CAS и явное разрешение конфликта. Не терять новые правки во время Save. Показывать JSON-ошибки и сохранять последнее пригодное preview.
|
||||
6. **Приёмка.** Серверные проверки одного Registry/API-вызова, отказов и отсутствия записей; браузер с задержками, списками, конфликтом, Expert и записями; wheel вне checkout; OpenAPI и документация.
|
||||
|
||||
Дизайн экрана, схема 1 и опубликованный сайт не меняются. Производительность больших документов и объём preview HTML остаются зависимыми от полного серверного рендера; дальнейшая оптимизация требует отдельных измерений.
|
||||
@@ -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 требует пересборки образа.
|
||||
@@ -0,0 +1,43 @@
|
||||
# 003 — Фоновое редактирование конструктора
|
||||
|
||||
Дата: 2026-11-13. Статус: реализовано, готово к проверке пользователем.
|
||||
|
||||
## Проблема и принятое решение
|
||||
|
||||
Каждое изменение инспектора вызывало последовательные transform и preview, повторные чтения сайта и замену инспектора. Ввод и выбор секции зависели от завершения запросов. Одинаковый исходник передавался повторно.
|
||||
|
||||
Рабочая редакция остаётся только в памяти открытой вкладки до явного Save. Серверных сессий редактирования, автосохранения контента и нового хранилища черновиков не добавляем. `status: draft` остаётся статусом документа; preview snapshots — отдельные защищённые временные артефакты.
|
||||
|
||||
Браузер отправляет один stateless POST update: исходник один раз, основание ETag, локальную revision и пакет операций. Backend применяет операции, валидирует документ и рендерит preview с одним Registry. PATCH с одним изменённым значением потребовал бы хранения несохранённой основы на сервере; выбранная модель обходится без такого состояния.
|
||||
|
||||
## Поведение интерфейса
|
||||
|
||||
- Текст собирается с debounce 200 мс; select, checkbox и выбор значения через picker планируют отправку сразу.
|
||||
- Запросы выполняются последовательно. Пока сервер отвечает, пользователь продолжает ввод и переключает секции; накопленные правки идут следующим пакетом на основе принятого результата.
|
||||
- Выбор секции в дереве и preview локален. Инспектор берётся из актуальной серверной проекции с наложением ещё не отправленных значений.
|
||||
- Обычное изменение свойства сохраняет активные input/textarea/select, фокус и каретку. Нет блокировки инспектора через inert/readOnly. Структурные операции и изменение схемы/layout могут пересобрать инспектор.
|
||||
- Заполнение последней пустой строки списка добавляет следующую без замены активного поля. Подтверждённое удаление перенумеровывает пути строк; более новый пакет не повторяет уже принятое удаление.
|
||||
- Preview использует настоящий серверный HTML. Обновление сохраняет iframe и его Document, прокрутку и выбранную секцию. Содержимое head/body заменяется; это не дифф отдельных фрагментов. Первичная загрузка и восстановление iframe используют защищённый snapshot URL.
|
||||
- Поддерживаются пассивный iframe и отдельный preview origin с доверенным bridge. В preview по-прежнему можно выбрать секцию.
|
||||
- Save дожидается очереди и сохраняет зафиксированную редакцию через существующий CAS. Ввод во время Save остаётся более новой несохранённой редакцией. Save не публикует.
|
||||
- При 409 показываются серверная и локальная версии и явное принятие основы. Автоматического повторного Save нет.
|
||||
|
||||
## Ошибки и безопасность
|
||||
|
||||
Невалидный пакет не применяется частично: API возвращает исходную редакцию и диагностику с HTTP 422. Введённые значения остаются в браузере; Save не обходит ошибки. Ошибка preview возвращается отдельно от уже принятых правок: последнее успешное preview остаётся видимым.
|
||||
|
||||
Ошибки транспорта, авторизации, CSRF и сервера видны в уведомлении интерфейса. Неожиданные исключения пишутся со стеком и request_id; исходник, cookies и credentials не добавляются в журналы. Нативные диалоги не используются.
|
||||
|
||||
Сохраняется цепочка browser → HTML adapter → AdminApi → JSON FastAPI → services/core. Нет обхода API и внутренних credentials в браузере. Контент записывает только ContentService при Save, с CAS/блокировкой/историей/аудитом. Update может создать временный preview snapshot, но не меняет canonical content или live.
|
||||
|
||||
Обновление preview удаляет scripts, обработчики on*, nonce, srcdoc, base и служебные meta/preload для скриптов. HTTP CSP исходного iframe сохраняется. Bridge проверяет origin, source, текущие snapshot/revision и параметры следующего снимка. JS публичного сайта не запускается.
|
||||
|
||||
## Критерии готовности
|
||||
|
||||
1. Одиночное изменение свойства — один POST update, без transform/preview POST.
|
||||
2. Один Registry на применение пакета и preview; нет записи контента до Save.
|
||||
3. При искусственной задержке 2 секунды ввод и выбор секции работают; максимум один update в полёте, новые правки не теряются.
|
||||
4. Списки, metadata, типизированные поля/привязки, вложенные блоки, Expert и редактор записи сохраняют штатный контракт.
|
||||
5. iframe/Document сохраняются, preview соответствует последней локальной revision; старые ответы не перезаписывают новый ввод.
|
||||
6. Видимы отказы preview/сети/валидации; работают восстановление и CAS-конфликт двух вкладок.
|
||||
7. Проходят серверная регрессия, Chromium в обоих режимах preview и smoke установленного wheel без design/.
|
||||
@@ -0,0 +1,16 @@
|
||||
# Задачи 003
|
||||
|
||||
- [x] T001 Вынести общий parser FormData/полей и form_action из web в services, оставить совместимые импорты.
|
||||
- [x] T002 Реализовать пакетный update с одним Registry и применением overlay без записи контента.
|
||||
- [x] T003 Добавить update DTO/JSON endpoints страниц и записей, отдельный preview_error.
|
||||
- [x] T004 Подключить HTML-адаптер к одному API-вызову, добавить компактную серверную проекцию и JSON auth/CSRF errors.
|
||||
- [x] T005 Реализовать очередь в памяти вкладки, debounce и объединение форм, защиту нового ввода от старых ответов.
|
||||
- [x] T006 Убрать блокировку/замену активного инспектора при обычных изменениях; локально выбирать секции.
|
||||
- [x] T007 Добавлять пустые строки списков без потери каретки, перенумеровывать удалённые строки и новые отложенные правки.
|
||||
- [x] T008 Обновлять существующий iframe/Document через серверный HTML в обоих режимах preview, сохранить выбор и прокрутку.
|
||||
- [x] T009 Сохранить явный Save/CAS, ввод во время Save и диалог конфликта; не добавлять автосохранение/публикацию.
|
||||
- [x] T010 Показывать validation/network/preview/server errors без потери ввода; сохранять traceback/request_id.
|
||||
- [x] T011 Добавить серверные и браузерные проверки, провести регрессию и визуальную проверку desktop/mobile.
|
||||
- [x] T012 Проверить установленный wheel без checkout/design, обновить OpenAPI и спецификацию.
|
||||
|
||||
Проверка пользователем на сервере после пересборки контейнера остаётся отдельной приёмкой. Коммит и развёртывание не выполняются этой задачей.
|
||||
@@ -0,0 +1,60 @@
|
||||
# Проверка 003
|
||||
|
||||
Дата: 2026-11-13. Реализация подготовлена к пользовательской проверке после пересборки контейнера.
|
||||
|
||||
## Результат
|
||||
|
||||
Один update заменяет последовательные transform и preview. Подтверждены один внутренний API-вызов и один Registry на пакет с рендером. Рабочая редакция остаётся в памяти вкладки, запись контента выполняется явным Save с прежним CAS. Ввод/переключение секций не блокируются; новые изменения продолжают очередь на принятой редакции. В обычном сценарии сохраняются активное поле, iframe и Document. Списки получают новую пустую строку; удаление корректно учитывается даже при более новом вводе во время ответа.
|
||||
|
||||
## Сервер
|
||||
|
||||
**371 unittest-тест прошёл** в полной регрессии. В `tests/test_editor_updates.py` добавлено **12 тестов**:
|
||||
|
||||
- один AdminApi call и Registry для нескольких операций с preview, компактная проекция без скрытых повторов source;
|
||||
- отсутствие записи canonical content/history/live при update;
|
||||
- сохранение исходных комментариев/байтов Expert при пустом пакете;
|
||||
- общие типизированные поля, привязки, вложенные блоки и ширина;
|
||||
- отказ всего пакета при ошибке последующей операции;
|
||||
- сохранность исходника при ошибочных формах/YAML;
|
||||
- независимый отказ preview: принятый snapshot, traceable error, traceback без исходника;
|
||||
- HTTP 500 для неожиданного отказа сервиса;
|
||||
- HTTP 500 и журналирование ошибки серверной проекции вместо маскировки как невалидного ввода;
|
||||
- явный Save и реальный CAS/409;
|
||||
- JSON-ошибки auth/CSRF/DTO;
|
||||
- overlay записи и компактный HTML-адаптер записи; неоднозначное направление move отклоняется отдельной проверкой.
|
||||
|
||||
Счётчик 12 относится к методам тестов: некоторые проверяют несколько связанных условий. После финального удаления повторов source из проекций целевые 12 тестов запускались отдельно.
|
||||
|
||||
Существующие тесты используют удалённый `examples/studio-site`. Полная регрессия запускалась на **временной** базовой фикстуре из коммита `231490b`, через подмену `tests/helpers.EXAMPLE` перед unittest discovery. В ней старый inline theme мигрирован в `site.yaml:theme.file: theme.yaml` и отдельный schema 1 minimal@1 с `overrides.colors.primary: '#0b5fff'`, `overrides.custom_colors.hero_dark: '#14213d'`. Остальной контент архивной фикстуры сохранён. Это ограничение тестовой инфраструктуры: обычный discover без такой фикстуры пока не воспроизводит полный успешный прогон. Удалённые примеры не возвращались в репозиторий. Новые тесты имеют собственную фикстуру; браузер проверяет текущий Site Studio.
|
||||
|
||||
## Chromium
|
||||
|
||||
`scripts/qa_editor_updates.py`: настоящий FastAPI, временная копия `examples/site-studio`, Chromium без proxy. **13 групп сценариев в каждом из двух режимов preview — 26 проверок**:
|
||||
|
||||
1. Один POST на свойство, тот же активный input, iframe и Document.
|
||||
2. Добавление строки списка без потери фокуса; удаление и перенумерация при более новом вводе во время задержки.
|
||||
3. Удаление scripts/nonce/onload из обновляемого HTML; bridge отклоняет чужой snapshot.
|
||||
4. Искусственная задержка 2 секунды: продолжение ввода, мгновенное переключение секций, изменения в нескольких инспекторах, максимум один update одновременно.
|
||||
5. Невалидное число не теряется, Save блокируется, исправление восстанавливает preview.
|
||||
6. Отказ preview сохраняет принятую редакцию и последнее успешное preview; последующее обновление работает.
|
||||
7. Обрыв транспорта сохраняет поля, повторное редактирование восстанавливает очередь.
|
||||
8. Save дожидается update; ввод во время задержанного Save остаётся несохранённым.
|
||||
9. Две реальные вкладки, CAS-конфликт и явное принятие основы.
|
||||
10. Expert → конструктор → невалидный YAML → восстановление той же корректной редакции.
|
||||
11. Каталог, добавление/дублирование/удаление блоков через диалог дизайна.
|
||||
12. Отмена правок, mobile 390 px без горизонтального переполнения, screenshots 390/1440 px.
|
||||
13. Фоновое изменение записи коллекции с настоящим preview.
|
||||
|
||||
**0 JavaScript-ошибок, 0 native dialogs.** Намеренно вызванные validation/409/preview/network errors проверяются отдельно; traceback QA preview failure в журнале ожидаем.
|
||||
|
||||
Desktop/mobile screenshots просмотрены визуально. Стили/композиция экрана сохраняют существующий перенос дизайна; CSS дизайна не менялся.
|
||||
|
||||
Артефакты: `/tmp/site-engine-editor-updates/browser.json`, `builder-{passive,bridge}-{1440,390}.png`; журналы — `/tmp/editor-updates-{browser,regression,tests,package}.log`. Время input → применение preview измеряется внутри браузера, включая debounce 200 мс. В контрольном прогоне: **513 мс passive, 547 мс bridge**. Это локальные измерения на Site Studio, не гарантия задержки на рабочем сервере. Серверная часть transform+render при отдельном замере — медиана около 249 мс. Ранее отдельные transform/preview и дополнительные чтения суммарно занимали около секунды серверной работы.
|
||||
|
||||
## Пакет и статические проверки
|
||||
|
||||
`scripts/verify_package_001.py --site examples/site-studio`: wheel собран и установлен вне checkout/design. Проверены сборка сайта, штатные пресеты, templates/static, новый preview-update.js, фоновый update с одним API call без записи контента и bridge на отдельном origin, существующий Theme Manager.
|
||||
|
||||
OpenAPI обновлён в `specs/001-antirion-admin/openapi.json`. Ruff для изменённых Python, синтаксис изменённых JS и `git diff --check` проходят. `preview.js` содержит серверный placeholder конфигурации; его реальное исполнение проверяет Chromium в отдельном origin.
|
||||
|
||||
Команды целевой приёмки — в [runtime.md](runtime.md). Рабочие данные, .env, live, design/ не менялись. Развёртывание и коммит не выполнялись. После пересборки образа пользователь проверяет конструктор на своём сервере.
|
||||
Reference in New Issue
Block a user