Files
flexly-cms/specs/001-antirion-admin/publication-backend.md
T

13 KiB
Raw Blame History

Этап 5: Publication и серверный контракт

Дата: 2026-11-17. Источники — design/publication-antirion.html, design/assets/publication.css и publication.js. Исходная композиция, таблица, инспектор, пять вкладок, карточки Workspace/Candidate/Live и диалоги перенесены в принятый shell. Mock-хранилище, выдуманные роли, симуляция сборок и ремонт демонстрационных данных исключены. Проверки — verification-publication.md.

Сценарий

  1. Сохранить необходимые документы в редакторе. Несохранённые правки других вкладок не участвуют в сборке.
  2. «Проверить» выполняет настоящие workspace/release-проверки. Исходники и Live не меняются; результат помечается устаревшим при изменении входных файлов или renderer.
  3. «Собрать кандидата» строго проверяет и рендерит сайт в неизменяемый каталог релиза, сохраняя текущий Live. Отдельный предварительный запуск «Проверить» не обязателен: сборка сама выполняет строгую проверку.
  4. Во вкладке «Кандидат» доступны настоящий снимок страницы, сравнение зафиксированных исходников с базовым Live и журнал сборок. Просмотр не пересобирает сайт.
  5. «Опубликовать» открывает исходный диалог с комментарием. Подтверждение переключает current на выбранный снимок без повторного рендера. Комментарий обязателен, до 150 символов.
  6. «История» показывает существующие каталоги релизов. Перед откатом доступны реальные изменённые публичные файлы, маршруты/формы и подтверждение. Откат переключает Live, сохраняя workspace.

Поиск, фильтры, выбор документа и вкладки работают локально. Сетевые операции выполняются через fetch в фоне; переключение вкладок остаётся доступным, повторные изменяющие действия блокируются на время запроса. Сборка на сервере синхронная: долговечной очереди заданий и отмены задачи нет.

Один контракт FastAPI

Browser → /admin/publication/* (cookie, Origin, CSRF) → AdminApi/httpx.ASGITransport → /admin/api/v1/publication* → PublicationService. Браузер не получает внутренних credentials. Начальные данные передаются в скрытом textarea (tojson, чтение .value), который сохраняется при htmx swap с allowScriptTags:false; script-элементы для хранения этих данных не используются. Права и авторство берутся из проверенной сессии; отдельные API keys/scopes и RBAC пока не реализованы.

JSON API относительно /admin/api/v1 Назначение
GET /publication Реальное состояние, изменения, проверки, кандидат, история, сборки и журнал
POST /publication/validate Проверить workspace/release без записи контента
POST /publication/build Собрать кандидат без активации
GET /publication/candidate-diff Сравнить неизменяемый кандидат с его базовым релизом
GET /publication/compare?path=… Сравнить сохранённый файл workspace с частным снимком Live
GET /publication/document-history?path=… Существующие версии .engine/history, максимум 20; восстановления здесь нет
GET /publication/release?id=… Сравнить публичные файлы выбранного релиза и текущего Live перед откатом
POST /publication/preview {id, route} → защищённый пассивный снимок настоящего релиза
POST /publication/activate {id, expected_live, comment} → переключение проверенного кандидата
POST /publication/rollback {id, expected_live, comment} → переключение существующего исторического релиза

expected_live обязателен; до первой публикации передаётся null. HTML adapter читает состояние по /admin/publication/state; остальные названия операций совпадают. POST принимает FormData csrf и JSON-строку payload; ответ — JSON. Читающие операции — GET. Экран открыт по /admin/publish; без JavaScript доступна ссылка на обычную форму /admin/publish/legacy. Старые POST /admin/publish, API /publish, /rollback и CLI сохраняют прежний сценарий сборки с публикацией.

Разделение состояния и файлов

PublicationService не редактирует файлы сайта. Изменения документов остаются ответственностью ContentService с CAS/history/audit. Проверки, сборка и переключение выполняются под общим SiteLock; в build_site добавлен параметр activate=False, обычное значение остаётся True. Внешние писатели должны соблюдать тот же lock.

Служебные данные находятся только в SITE_STATE_DIR/publication/:

  • candidate.json: последний кандидат, базовый Live, хеш входных файлов и renderer, hash публичного output, время/автор/маршруты/диагностика;
  • releases/<build_id>.json: частный снимок входных файлов и происхождение релиза, комментарий/автор и факт активации;
  • validation.json: реальный результат последней проверки и fingerprint его входных данных;
  • builds.json: последние 40 результатов/ошибок сборки с ID запроса и кратким журналом стадий.

Список исходников охватывает pages, content, menus, assets, layouts, fragments, collections, display, data, forms, root site/theme/redirect YAML и настроенный файл темы. Для UTF-8 текста известных расширений до 512 КиБ сохраняется исходник; для остальных файлов — hash/размер. Скрытые и служебные каталоги исключены, symlink в исходниках отклоняется. Полный hash workspace консервативно инвалидирует кандидата и при изменении иных файлов, включая README; fingerprint renderer учитывает ресурсы движка.

Частные исходники, включая draft, не копируются в публичный dist или manifest. В релиз рендерятся только published. Статус published в файле не означает, что сохранённая редакция уже находится в Live.

Старые/CLI-релизы без частного снимка продолжают работать: маршруты, preview и откат доступны, сравнение исходников/автор/комментарий неизвестны и обозначены явно. Ретроспективно придумывать их нельзя. После первой публикации новым workflow сравнение станет доступно для этого релиза.

Кандидат сравнивается со своей зафиксированной базой, а не с текущими изменениями workspace. Последующие правки требуют новой сборки. Откат сравнивает реальные байты публичных файлов, включая manifest/assets. Никогда не публиковавшиеся кандидаты с известным происхождением через откат выбрать нельзя.

Конфликты, ошибки и безопасность

Перед активацией проверяются expected_live, актуальность ID кандидата, hash исходников/renderer/базового Live и неизменность собранных файлов. Нарушение актуальности — HTTP 409 release_conflict; повреждённый снимок/валидация — 422; отсутствующий релиз — 404. Отказ строгого рендера сохраняет прежние Live и кандидат.

JSON-ошибки: error: {code, message, request_id, …}. Непредвиденные ошибки и ошибки хранилища логируются со стеком и тем же ID. UI показывает сообщение, код и ID; 409 не закрывает подтверждение и не удаляет комментарий, автоматического повторного POST нет. Сеть и истёкшая сессия также видимы.

Если ошибка записи служебных данных/аудита произошла после сборки либо переключения, API отвечает 500 candidate_after_build или release_after_commit с committed_build. Сообщение различает «снимок создан, Live не переключён» и «Live уже переключён». UI перечитывает состояние перед повтором; указатель current остаётся источником истины. Переключение symlink атомарно, но несколько служебных JSON и audit не являются общей crash-atomic транзакцией.

Preview читает HTML/assets выбранного build ID, а не workspace, использует существующие TTL/epoch-токены и immutable snapshots. Скрипты удалены, script-src 'none' действует также на отдельном preview origin; iframe sandbox запрещает выполнение кода, формы и навигацию верхнего окна. Настроенный preview origin разрешён в frame-src всех страниц shell: CSP исходного документа сохраняется при htmx swap. Браузерные сценарии проверены с обеими конфигурациями origin.

Журнал показывает настоящие release-события из хвоста аудита: до 80 записей в последних 256 КиБ. Старый аудит не удаляется. Пароли, токены и тела запросов в журнал не добавляются.

Границы этапа

Новый workflow не удаляет кандидаты/релизы автоматически. Прежняя CLI-сборка сохраняет своё keep=5; если каталог уже удалён, API сообщает отсутствие, кандидат становится неактуальным. Политика retention и очистка частных снимков требуют отдельной работы.

Не добавлены durable jobs, реестр идемпотентных операций, changeset/recovery нескольких документов, согласование агентских изменений, RBAC, приём заявок или MCP. Публичные формы по-прежнему отвечают HTTP 501. Исторический релиз без provenance нельзя проверить по исходным входным файлам; UI не выдаёт это за подтверждённое сравнение.