# 001 — Antirion Rework: админка и редакторы Дата: 2026-11-12. Статус: реализовано и проверено. Контракт и запуск — [runtime.md](runtime.md), результаты приёмки — [verification.md](verification.md). Локальная библиотека htmx поставляется в runtime-пакете. Связанные документы: [технический план](plan.md), [задачи](tasks.md). ## 1. Цель и результат Перенести оформление Antirion Rework на работающую админку Site Engine, затем развить редакторы страниц и записей: общий буфер Конструктора и «Эксперта», встроенный инспектор, контролируемое сохранение и интерактивное превью несохранённого документа. Результат 001 — интерфейс, работающий с реальными файлами сайта и действующими операциями бэкенда. Сохранённый документ, несохранённый буфер редактора и опубликованный релиз имеют разные явно показанные состояния. Реализация выполнена по этапам A–F. Статусы задач и привязка к фактическим проверкам ведутся в `tasks.md`; кандидаты 002–006 остаются следующей очередью. ## 2. Источники и приоритет 1. Решения пользователя, перечисленные в разделе 3 этой спецификации. 2. Действующие файловые контракты, реализация и тесты репозитория; [журнал архитектурных решений](../../docs/TZ-site-engine-decisions.md). 3. HTML/CSS выбранного варианта как эталон оформления и взаимодействий. 4. [Документы stage7](../../design/docs/stage7/README.md) как проект развития с поправками из этого пакета. Визуальные источники: | Экран | Источник | |---|---| | Shell, обзор, страницы | [antirion-rework.html](../../design/antirion-rework.html), `design/assets/antirion-rework.css` | | Конструктор и «Эксперт» страницы | [builder-antirion.html](../../design/builder-antirion.html), `design/assets/builder.css` | | Коллекции и записи | [content-antirion.html](../../design/content-antirion.html), `design/assets/content-editor.css` | | Публикация и история | [publication-antirion.html](../../design/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](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. ```text Браузер / 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//*.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 прототипа не заменяют эту проверку.