Files

32 KiB
Raw Permalink 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 — рабочие экраны

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

Рабочие маршруты и обычные формы сохраняются. Пока новые редакторы не готовы, пользователь сохраняет изменения существующими кнопками форм. При первом переносе оформление публикации соответствовало операции «собрать и опубликовать». Повторный этап 5 уточняет этот контракт: проверка → сборка неизменяемого кандидата → просмотр/diff → отдельное переключение Live с CAS; см. publication-backend.md.

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

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

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

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

На повторном этапе 5 по разрешению пользователя в 001 включены реальные кандидаты релиза, diff с Live и проверка expected_live. Расширенный release workflow (durable jobs, безопасные повторы/реестр операций, retention и reviewed changeset), медиабиблиотека и загрузки, 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. Сборка кандидата не переключает Live; публикация проверяет его актуальность и expected_live без повторного рендера.
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 прототипа не заменяют эту проверку.