32 KiB
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. Источники и приоритет
- Решения пользователя, перечисленные в разделе 3 этой спецификации.
- Действующие файловые контракты, реализация и тесты репозитория; журнал архитектурных решений.
- HTML/CSS выбранного варианта как эталон оформления и взаимодействий.
- Документы 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 прототипа не заменяют эту проверку.