195 lines
32 KiB
Markdown
195 lines
32 KiB
Markdown
# 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/<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 прототипа не заменяют эту проверку.
|