Integrate Content Editor and Publication workflow
This commit is contained in:
@@ -0,0 +1,70 @@
|
||||
# Этап 5: Publication и серверный контракт
|
||||
|
||||
Дата: 2026-11-17. Источники — `design/publication-antirion.html`, `design/assets/publication.css` и `publication.js`. Исходная композиция, таблица, инспектор, пять вкладок, карточки Workspace/Candidate/Live и диалоги перенесены в принятый shell. Mock-хранилище, выдуманные роли, симуляция сборок и ремонт демонстрационных данных исключены. Проверки — [verification-publication.md](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 не выдаёт это за подтверждённое сравнение.
|
||||
Reference in New Issue
Block a user