Files
flexly-cms/specs/001-antirion-admin/spec.md
T
phelex 88ac95dd19 Integrate Antirion admin with FastAPI and htmx
Add the shared document API, constructor and expert editors, isolated preview, and fragment catalog metadata with typed block IDs.

Include design references, specification 001, QA scripts, project guidance, and cached Docker dependency installation. Leave example sites for a separate commit.
2026-11-12 21:55:36 +03:00

31 KiB
Raw Blame History

001 — Antirion Rework: админка и редакторы

Дата: 2026-11-12. Статус: реализовано и проверено. Контракт и запуск — runtime.md, результаты приёмки — verification.md. Локальная библиотека htmx поставляется в runtime-пакете.

Связанные документы: технический план, задачи.

1. Цель и результат

Перенести оформление Antirion Rework на работающую админку Site Engine, затем развить редакторы страниц и записей: общий буфер Конструктора и «Эксперта», встроенный инспектор, контролируемое сохранение и интерактивное превью несохранённого документа.

Результат 001 — интерфейс, работающий с реальными файлами сайта и действующими операциями бэкенда. Сохранённый документ, несохранённый буфер редактора и опубликованный релиз имеют разные явно показанные состояния.

Реализация выполнена по этапам A–F. Статусы задач и привязка к фактическим проверкам ведутся в tasks.md; кандидаты 002–006 остаются следующей очередью.

2. Источники и приоритет

  1. Решения пользователя, перечисленные в разделе 3 этой спецификации.
  2. Действующие файловые контракты, реализация и тесты репозитория; журнал архитектурных решений.
  3. HTML/CSS выбранного варианта как эталон оформления и взаимодействий.
  4. Документы stage7 как проект развития с поправками из этого пакета.

Визуальные источники:

Экран Источник
Shell, обзор, страницы antirion-rework.html, design/assets/antirion-rework.css
Конструктор и «Эксперт» страницы builder-antirion.html, design/assets/builder.css
Коллекции и записи content-antirion.html, design/assets/content-editor.css
Публикация и история publication-antirion.html, design/assets/publication.css

JS прототипов описывает UX; его seed-данные, localStorage, browser codec и имитации публикации не являются контрактом бэкенда. При расхождении скриншота и исходного выбранного HTML/CSS приоритет имеет исходник. design/ сохраняется как визуальный эталон; уточнения stage7 выполняются отдельными задачами.

3. Зафиксированные решения пользователя

Решение Принятый вариант
Первый результат Оформить все существующие рабочие экраны и выполнить необходимые точечные доработки
Следующий приоритет Редакторы страниц и записей
Доступ Один администратор через существующую конфигурацию; пользователи и роли позднее
Сохранение Только по явной кнопке, без автозаписи файла после изменения поля
Превью редактора Интерактивное сразу в этапе развития редакторов, с отдельным origin
Оформление Antirion Rework; Rose Graphite и другие концепции не внедряются в 001
Взаимодействие UI и бэкенда htmx + Jinja; UI вызывает единый JSON API FastAPI через серверный клиент, по схеме flexly-estimator
Транспорт API В одном приложении httpx.ASGITransport, без сетевого соединения; API-ключи не передаются браузеру

Технические значения по умолчанию: светлая палитра при первом входе; предпочтение оформления хранится только как UI-настройка; срок токена превью — 10 минут. Изменяемый контент остаётся в файлах сайта.

4. Исходное состояние и расхождения со stage7

Область Уже существует Доработка в 001
Контент Page/Entry, YAML front matter, Markdown, коллекции и display Использовать текущую модель в новом UI
Композиция Layout, Fragment, регионы, слоты, fixed, явные ID, hidden/requires Дерево и инспектор без уплощения структуры
Значения Literal, Binding, LinkRef, Query; разрешение на сервере Единый буфер и операции Конструктора
Запись ContentService: ETag, блокировка сайта, история, атомарная запись Перенести прикладные операции из HTTP-обработчиков в сервисы
Валидация Workspace/release, проверки нового текста до записи Общая проверка Конструктора и «Эксперта»
Доступ Одна учётная запись, cookie, CSRF, ограничение входа, аудит Сохранить; передавать проверенного автора в новые сервисы
Конфликт 409 с текущим ETag, общая страница сообщения Сохранить ввод, показать версии и дать повторное сохранение после разрешения
Превью Рендер сохранённого документа без скриптов Временный рендер буфера, отдельное приложение и взаимодействие с деревом
Публикация Build сразу переключает current; сохранённые релизы и rollback Новое оформление существующих операций
HTTP-контракт FastAPI-адаптер, общий dispatch редактора, HTML-ответы; OpenAPI отключён Явные JSON-маршруты, Pydantic DTO, OpenAPI и HTML-адаптер над серверным API-клиентом

Обнаруженные несовместимости stage7, подлежащие документированию и исправлению:

  • Для collection_list.source нужен {query: {collection: ...}}; объект запроса без query не соответствует текущему контракту.
  • У richtext поле Markdown называется content, а не source.
  • Блоки используют hidden и requires; visibility не поддерживается.
  • Пример с layout: landing требует собственного layout; текущий сайт-пример содержит default.
  • Поля примера Entry должны соответствовать схеме services: title, tagline, summary, order и системным полям.
  • Текущая публикация доступна по /admin/publish; /admin/publication — предложение stage7.
  • В HTML-формах используются csrf и etag; параметр сервиса называется if_match.
  • ETag вычисляется по байтам файла, без добавления версии схемы. Ядро использует dataclass, а не Pydantic.
  • Наличие моделей SQLAlchemy не означает готовности пользователей, заявок, outbox или истории сборок в БД.
  • Новые ADR stage7 не должны переопределять существующие ADR с теми же номерами без явного сопоставления и сохранения истории.

Текущий CSP админки не объявляет frame-src при default-src 'none', что препятствует загрузке iframe в браузере. Ссылки /assets/... в текущем превью относятся к опубликованному сайту, поэтому не гарантируют отображение ассетов workspace. Обе проблемы входят в первый этап.

5. Объём 001

Этап A — рабочие экраны

Вход/выход, обзор, список и создание страниц, формы страницы и блока, операции с блоками, коллекции, список/создание/редактирование записей, существующее превью, публикация, история релизов, откат, ошибки и пустые состояния.

Рабочие маршруты и обычные формы сохраняются. Пока новые редакторы не готовы, пользователь сохраняет изменения существующими кнопками форм. На этом этапе оформление публикации соответствует текущей операции «собрать и опубликовать».

Этап B — редакторы

Общие сервисы, единый API-контракт и серверный клиент UI, буфер документа, дерево блоков, встроенный инспектор, режим «Эксперт», сохранение документа целиком, разрешение конфликтов и интерактивное превью.

Начальный режим страницы — «Конструктор». Для Entry Конструктор редактирует поля её коллекции; дерево блоков относится к Page, а display/fixed-блоки вывода Entry доступны для просмотра. Изменение display-кода из редактора записи не предоставляется.

Следующая очередь

Отдельные кандидаты релиза, diff с live, медиабиблиотека и загрузки, changeset/rename, редактирование меню/настроек, пользователи/RBAC, заявки/outbox и MCP описываются следующими спецификациями. В 001 не добавляются Node-сборка, новая структура всего Python-пакета или миграция канонического контента в БД.

Контракт интерфейса

Принята схема, проверенная по коду ../flexly-estimator/: web/client.py, web/deps.py, web/routes/estimates.py, api/routers/estimates.py. Переносится архитектурный подход; модели пользователей, БД и расчётов estimator не являются зависимостями CMS.

Браузер / htmx → UI-маршрут FastAPI → серверный API-клиент
    → JSON API FastAPI → прикладной сервис → файловое хранилище
    ← HTML-страница / фрагменты ← результат API

UI-маршруты возвращают страницы или HTML-фрагменты; /admin/api/v1/ возвращает JSON и не выбирает формат по HX-Request. Браузер отправляет формы с cookie и CSRF в UI, не получает внутренние credentials и не вызывает API напрямую. Прямой вызов сервисов из UI допустим только как переходное состояние этапа оформления существующих экранов; к завершению 001 операции контента, проверки, превью и публикации проходят через API-клиент. Проверки сессии и рендер шаблонов остаются ответственностью UI.

API задаёт единый контракт операций и данных. HTML-фрагменты дополнительно имеют собственный UI-контракт: DOM-цели, правила замены, сообщения об ошибках и revision. Общие сервисы остаются доступными CLI и будущему MCP напрямую.

6. Функциональные требования

ID Требование
FR-01 Общий shell воспроизводит навигацию, верхнюю панель, рабочую область и адаптивное поведение Antirion Rework.
FR-02 Экран показывает реальные данные. Действие без серверной реализации не выдаётся за доступную операцию; недоступное состояние объясняется.
FR-03 Списки страниц и записей поддерживают поиск по названию/ID/маршруту и фильтр статуса; список страниц также фильтруется по эффективному layout. Выбор показывает свойства и переход в редактор.
FR-04 Существующие формы сохраняют маршруты, имена полей, CSRF, контроль версии и работающие операции.
FR-05 Ответы 409/422 сохраняют ввод и показывают причину отказа.
FR-06 PageService и EntryService предоставляют чтение, создание, проверку и изменение документа независимо от HTTP-представления.
FR-07 Снимок документа содержит идентификатор, путь относительно сайта, исходник, модель, ETag и диагностику.
FR-08 Конструктор и «Эксперт» изменяют общий временный буфер. Проверка, преобразование и превью не записывают канонические файлы и историю их версий.
FR-09 «Сохранить» записывает весь документ одной операцией с проверкой версии, валидацией, историей и аудитом успешного изменения.
FR-10 Конструктор сохраняет регионы, слоты, ID, привязки, ссылки, запросы и Markdown; fixed-блоки layout доступны только для просмотра.
FR-11 YAML разбирает сервер. Ошибочный исходник остаётся в редакторе и не заменяет последнюю корректную модель.
FR-12 Переключение режимов сохраняет корректные правки. Ошибочный исходник не позволяет молча перейти к другой модели; внутренний переход с несохранёнными изменениями требует подтверждения в интерфейсе.
FR-13 При 409 доступны пользовательская и текущая серверная версии. Пользователь вручную объединяет правки либо явно принимает серверную версию; повторное сохранение использует актуальный ETag.
FR-14 Превью показывает буфер документа и соответствующие ассеты workspace до сохранения файла.
FR-15 Клик в превью выбирает блок без прокрутки; выбор в дереве прокручивает к невидимому блоку; обновление поля сохраняет положение и выделение.
FR-16 Интерактивное превью обслуживается отдельным origin, доступно по ограниченному токену и использует проверенные сообщения между окнами.
FR-17 Обычная публичная сборка не получает служебных атрибутов/скриптов редактора и сохраняет прежнюю семантику.
FR-18 Прикладные операции UI проходят через явный версионированный JSON API FastAPI; запросы, ответы и ошибки описаны Pydantic DTO и OpenAPI. Ядро сохраняет dataclass-модели.
FR-19 UI вызывает API через серверный клиент с ASGITransport в том же приложении. Проверенный автор и эпоха сессии сохраняются; API отклоняет анонимные, отозванные и поддельные внутренние credentials.
FR-20 htmx получает только HTML от UI. Ответы 409/422 и истечение сессии обрабатываются явно; JS редактора сохраняет буфер, revision и связь с превью при частичных обновлениях.

7. Модель данных и сохранения

  • Canonical Page — pages/**/*.md; Entry — content/<collection>/*.md. Идентичность документа определяется проверенным реестром и путём, а не произвольным путём из запроса.
  • Сохраняются типы значений, regions, slots, hidden, requires, editorial, Markdown и существующие статусы draft/published/archived.
  • Буфер содержит исходник, ETag сохранённой основы и последнюю корректную модель. Преобразование буфера не обновляет ETag основы.
  • Конструктор изменяет разобранный документ на сервере. Сериализация сохраняет смысл, порядок блоков и данные, которые текущая политика схемы допускает сохранять; поля не исчезают молча.
  • «Эксперт» сохраняет проверенный исходный текст. Конструктор использует текущую нормализацию YAML; это описано рядом с исходником, без отдельного предупреждения при правке. Исходник можно скачать. Нативные alert/confirm/prompt и beforeunload-диалоги не используются; подтверждения удаления, отмены и внутренних переходов с несохранёнными правками показываются в окнах интерфейса. Перезагрузка/закрытие вкладки не вызывает системного подтверждения.
  • Неполный draft допустим в пределах базовых требований текущей модели: например, Page по-прежнему требует корректный заголовок, но обязательные бизнес-поля фрагмента могут быть не заполнены.
  • Алиасы, дублирующиеся ключи YAML, недопустимая вложенность, Jinja-выражения в данных и попытки записи кода отклоняются с диагностикой. Действующие лимиты безопасного парсера сохраняются.
  • Переименование файла и изменение логического slug Entry через исходник запрещены в 001. Изменение route страницы остаётся существующей возможностью без обещания автоматического создания редиректа.
  • etag формы передаётся как if_match; его значение — sha256: и SHA-256 текущих байтов файла. После успешного сохранения клиент получает новый ETag.
  • При 409 новый ETag не подставляется в повторную отправку автоматически. Диалог конфликта сохраняет обе версии и требует явного действия пользователя.
  • Несохранённый исходник хранится в памяти вкладки; UI предлагает скачать его перед отказом от правок. Восстановление буфера после перезагрузки не обещается. LocalStorage допускается для темы/свёрнутой навигации, но не для канонического контента.
  • Аудит содержит автора, тип операции и идентификатор объекта; содержимое исходника, токены и секреты не записываются.

8. Интерактивное превью

Превью — временный производный результат. Его создание может писать артефакты в служебное состояние, но не изменяет canonical Page/Entry, историю файлов и live.

  • Отдельные явно заданные origin админки и превью; wildcard и совпадающие origin для интерактивного режима запрещены.
  • Отдельное приложение превью не имеет login/admin/API-маршрутов и не использует админскую cookie для авторизации.
  • Токен открывает один подготовленный снимок HTML и его ассеты, действует 10 минут и проверяется на каждом запросе. Выход администратора отзывает доступ через эпоху сессий. Токен одного снимка не открывает другой.
  • Превью содержит только разрешённый служебный скрипт взаимодействия. Скрипты сайта и произвольный исходник не получают права исполнения.
  • postMessage проверяет origin, source, тип сообщения, текущий снимок и существование блока. Отправка направляется точному origin.
  • Fixed/layout, display и редактируемые блоки имеют различимые области идентификаторов; совпадение локального ID не даёт возможности менять fixed-блок.
  • Скрытый блок или блок с выключенным feature остаётся в дереве с пояснением; превью не показывает его как публично видимый. Выбор такого блока не вызывает ошибочную прокрутку.
  • Удаление выбранного блока сбрасывает выбор на существующий соседний блок или свойства документа. Ответ старого запроса превью не заменяет более новое состояние.
  • Истечение токена требует повторной генерации из авторизованного редактора. Недоступность приложения превью сохраняет буфер и возможность редактировать/сохранить документ.

9. Качество и совместимость

ID Требование
NFR-01 Существующие URL, форматы файлов, основные команды CLI и поведение публикации/отката сохраняются.
NFR-02 Autoescape, санитайзер Markdown, safe paths, CSRF и защитные cookie сохраняются. CSP разрешает только необходимые ресурсы.
NFR-03 Проверяются ширины 1440, 1280, 1024, 768, 390 и 360 px; таблицы могут иметь внутреннюю прокрутку, весь экран не переполняется.
NFR-04 Управление доступно с клавиатуры, фокус видим, у полей и iframe есть подписи. Модальные окна удерживают фокус и возвращают его инициатору; учитывается reduced motion.
NFR-05 Установленный wheel содержит шаблоны, статику админки и служебные ресурсы превью. Работа не зависит от наличия каталога design на сервере.
NFR-06 Канонические файлы и live меняются только соответствующими явными операциями; ответы ошибок не показывают трассировки и секреты.

Для FR-18–FR-20 обязательны локальная закреплённая версия htmx с источником, лицензией и SHA-256, запрет eval/скриптов из фрагментов и запросов htmx к сторонним origin. OpenAPI выгружается воспроизводимо для проверки контракта; HTTP-доступ к схеме и документации требует административной авторизации. Анонимные Swagger/OpenAPI не включаются.

10. Приёмочные сценарии

ID Проверка и ожидаемый результат
AC-01 Вход → обзор → создание/редактирование Page/Block/Entry → reload: существующие операции работают в новом оформлении.
AC-02 Конструктор → «Эксперт» → Конструктор сохраняет ID, вложенность, привязки и Markdown; простой переход без правок не переформатирует исходник.
AC-03 Изменение поля/блока, validate и preview оставляют байты canonical-файлов, историю и current прежними; «Сохранить» фиксирует все правки документа.
AC-04 Ошибочный YAML, повтор ключа, неподдерживаемый блок или попытка изменить fixed не записывают файл; введённый текст остаётся в UI.
AC-05 Две вкладки читают один ETag; первая сохраняет, вторая получает 409 с сохранённым вводом и текущей версией; после ручного объединения сохраняет с новым ETag.
AC-06 Превью выбирает нужный вложенный/fixed-блок, соблюдает правила прокрутки и отображает последнюю версию буфера, включая ассеты workspace.
AC-07 Неверный/истёкший/отозванный токен, чужой снимок, поддельные origin/source/сообщения и traversal отклоняются; приложение превью не открывает admin/login.
AC-08 Успешная публикация переключает current; неудачная сохраняет live; откат сохраняет workspace. В UI отсутствует имитация ещё не реализованного кандидата.
AC-09 Основные экраны, ошибки, диалоги и редакторы проходят адаптивную и клавиатурную проверку на заданных размерах.
AC-10 Wheel содержит runtime-ресурсы; обычная сборка сайта проходит и не содержит служебной разметки/скриптов preview-режима.
AC-11 Реальный FastAPI проверяет запросы и ответы JSON API, единый формат ошибок и OpenAPI. HTML- и API-маршруты не смешивают форматы; UI вызывает API через ASGITransport с проверенным автором. Ошибки/отказ API отражаются в UI без обхода через прямую запись.
AC-12 Настоящий htmx загружает фрагмент, отправляет форму с CSRF, показывает 409/422, обрабатывает истечение сессии и согласованные обновления без потери буфера. Поддельные внутренние credentials и прежняя эпоха после logout не дают API-доступ; API-токенов нет в HTML и браузерных запросах.

Готовность требует исполнения сценариев через реальный FastAPI и браузер. Тесты обработчиков и QA прототипа не заменяют эту проверку.