Files
flexly-cms/specs/003-background-editor/spec.md
T

7.2 KiB
Raw Blame History

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/.