Files

71 lines
13 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Этап 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 не выдаёт это за подтверждённое сравнение.