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

155 lines
25 KiB
Markdown
Raw 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.
# Работающий контракт 001
## Редактор и файлы
Начальный режим — Конструктор. «Применить к буферу» меняет исходник в памяти открытой вкладки; «Сохранить документ» записывает его целиком. Проверка и превью не создают историю контента и не меняют `current`. Новый экран публикации отдельно собирает кандидат, затем переключает его в Live; старые формы/CLI сохраняют build+publish. В Entry редактируются поля коллекции и Markdown; layout/display доступны для чтения.
«Эксперт» хранит точный исходник. Переход между режимами без правок не пересобирает YAML; сохранение без изменений сохраняет в том числе CRLF и комментарии. Конструктор предупреждает о пересборке YAML перед первой операцией. До неё можно скачать исходник. Неприменимый YAML остаётся в «Эксперте», последнее корректное дерево доступно для просмотра. В localStorage попадают только тема и ширина навигации; HTML-кеш htmx отключён.
При 409 доступны отправленная и серверная версии. Внесите слияние в «Эксперте», явно примите показанную серверную версию как основу, затем нажмите Save. Принятие основы не записывает файл. Повторный конфликт обрабатывается так же. При 422, сетевой ошибке или истечении сессии текст остаётся во вкладке и доступен для скачивания. После нового входа можно открыть документ и перенести скачанные правки. Закрытие браузера не является сохранением буфера.
## HTML и JSON
Обзор и список Page используют проекцию `Workspace`: страницы, проверки, `release` (current/built_at/routes) и `comparison_available`. `PageRow` включает изменённость файла относительно LIVE, время файла, SEO-описание, относящиеся к странице issues и наличие маршрута на LIVE. Фильтр `changed=true` у JSON `/pages` соответствует HTML-вкладке «Изменённые» (`changed=1`).
Новые сборки содержат `page_sources` — SHA-256 опубликованных файлов Page. Старый manifest без индекса означает неизвестное сравнение (`changed=null`), а не отсутствие правок. Сравниваются файлы Page; зависимости layout/fragment/assets/коллекций не входят в этот счётчик. Откат меняет базу сравнения вместе с `current`. Создание draft возвращает HTML UI в список с выбранной страницей; публикация остаётся отдельным действием.
```text
browser/htmx → /admin/... (HTML)
→ AdminApi/httpx.ASGITransport
→ /admin/api/v1/... (JSON, Pydantic)
→ PageService/EntryService → ContentService → files
```
Рабочий runtime подключает `AdminApplication`; прежние независимые `AdminHandlers`/`EditorHandlers` сохранены для совместимости. Контент, диагностика, списки, превью и публикация runtime проходят через API. Вход, cookie/CSRF и рендер HTML относятся к UI.
API принимает случайные credentials, существующие только на время серверного UI-запроса. На каждой API-границе исходная сессия повторно проверяется по подписи, сроку и epoch. Cookie браузера и поддельный Bearer не предоставляют API-доступ. Автор берётся из проверенного Principal, а не из тела запроса. Нет отдельного публичного ключа для браузера.
| JSON маршрут | Операция |
|---|---|
| `GET /admin/api/v1/site`, `GET /admin/api/v1/collections`, `GET /admin/api/v1/pages?q=&status=&layout=` | Страницы, коллекции, layouts, диагностика workspace/release |
| `GET /admin/api/v1/collections/{collection}/entries` | Записи коллекции |
| `POST /admin/api/v1/pages` | Создать draft Page |
| `POST /admin/api/v1/collections/{collection}/entries` | Создать draft Entry |
| `GET /admin/api/v1/pages/{identity}/source` | Снимок Page; вложенные ID поддерживаются |
| `GET /admin/api/v1/collections/{collection}/entries/{identity}/source` | Снимок Entry |
| `POST …/{identity}/validate, transform, save, preview` | Общий исходник, ETag основы, revision; transform имеет типизированное действие |
| `GET /admin/api/v1/assets/{asset}` | Защищённые workspace-ассеты прежнего превью |
| `GET /admin/api/v1/preview/{snapshot}/html, assets/{asset}` | Защищённый неизменяемый снимок |
| `GET /admin/api/v1/releases` | Реальные релизы и current |
| `POST /admin/api/v1/publish, rollback/{build_id}` | Сборка с публикацией / откат current |
HTML-операции нового редактора: `/admin/editor/pages/{id}/{operation}` и `/admin/editor/content/{collection}/{slug}/{operation}`. Ответы — HTML; `X-Editor-Revision` позволяет отклонить устаревший результат. Старые `/admin/pages/…/meta`, `/blocks/…`, `/add`, `/content/…` и `/publish` продолжают принимать прежние формы.
Предусмотренные планом `/admin/api/v1/editor/pages/…`, `/admin/api/v1/editor/entries/{collection}/…` и `GET/POST /admin/api/v1/entries/{collection}` также поддерживаются. Create возвращает 201, rollback доступен и как `POST /admin/api/v1/rollback` с `build_id` в JSON.
Снимок содержит kind/id/path/source/etag/model/schema/issues/revision; результат превью — URL, snapshot, expires_at и revision. ETag — `sha256:` от исходных байтов; проверка актуальной схемы и CAS выполняются под одним SiteLock вместе с history/atomic write. Изменение code/layouts/schemas через content scope запрещено, в том числе через symlink/traversal. Ошибка аудита после записи возвращает признак committed с сохранённым снимком и не выдаётся за отклонённый Save.
Ошибки API имеют `error: {code, message, request_id, issues, …}` с соответствующим HTTP-статусом; 409 дополнительно содержит submitted/current, 422 validation — неприменимый buffer либо диагностику. Лимит JSON-запроса — 1 MiB; source ограничен DTO и безопасным YAML-парсером. Неожиданная ошибка API возвращается без трассировки и внутренних путей.
Пример ответа HTTP 500 на `/admin/api/v1/publish`:
```json
{
"error": {
"code": "storage_error",
"message": "Ошибка доступа к файлам сервера. Проверьте права и свободное место. Проверьте текущую версию перед повтором операции.",
"request_id": "c4a857fd62774d688c5135d104ce3a51"
}
}
```
`X-Request-ID` присутствует в ответах приложения; ID сохраняется при внутреннем вызове API. Коды: `internal_error` — неожиданное исключение; `storage_error` — ошибка файловой системы; `request_validation`/`validation` — запрос/контент; `conflict` — несовпадение версии; `preview_unavailable` — недоступный snapshot. Серверный клиент преобразует отказ транспорта в HTTP 503 `api_unavailable`, некорректный ответ — в HTTP 502 `invalid_api_response`.
Неожиданные исключения пишутся через `logger.exception` в `uvicorn.error`: `request_failed request_id=… method=POST path=/admin/api/v1/publish code=storage_error`, затем traceback с исходным исключением и местом ошибки. Обработанные HTTP-ошибки дают `request_error` со статусом и кодом. Тело запроса, Authorization, cookies и query string не добавляются в эти записи. В Docker смотреть `docker logs --since 10m flexly-cms`; ID из интерфейса позволяет найти соответствующий стек.
HTML UI показывает сообщение, код и ID запроса. На публикации ошибку видно и без JavaScript; htmx показывает постоянное уведомление, которое закрывается пользователем. Подготовленная страница ошибки может заменить boosted-страницу; исходник документа при 5xx не заменяется. Отказ сети и timeout также видимы, автоматического повтора мутаций нет. Если после ошибки публикации недоступен список релизов, исходная ошибка операции сохраняется.
Проверка отказов на временной копии сайта: `PYTHONPATH=src python scripts/qa_errors_001.py`. Сценарий проверяет UI 500, общий ID с traceback, мобильное уведомление, сохранность несохранённого исходника при серверном и сетевом сбое и восстановление Save/Publish после устранения сбоя. Выход — `/tmp/cms-errors-qa/`; браузер — `QA_BROWSER=firefox`, каталог — `QA_ERRORS_OUT=/tmp/cms-errors-firefox`.
Схема и локальная страница документации доступны после входа: `/admin/api/v1/openapi.json`, `/admin/api/v1/docs`; сокращённые `/admin/api/openapi.json`, `/admin/api/docs` также работают. Воспроизводимый экспорт без секретов и работающего сайта:
```bash
site-engine export-openapi --out specs/001-antirion-admin/openapi.json
```
Эталон экспорта — [openapi.json](openapi.json). Экспорт с той же версией зависимостей даёт одинаковый JSON.
## Отдельное превью
Требуются два разных точных origin без завершающего `/`. Схема/host/порт сравниваются как origin; разный регистр или явный default port не делают origin разными. HTTP разрешён только на loopback, production требует HTTPS.
Пример локального запуска после установки `.[server,dev]`, с уже настроенными `SITE_ADMIN_LOGIN`, `SITE_ADMIN_PASSWORD_HASH`, `SITE_SECRET_KEY`:
```bash
export SITE_ROOT=/absolute/path/to/test-site
export SITE_DIST=/absolute/path/to/test-dist
export SITE_STATE_DIR=/absolute/path/to/test-state
export SITE_ADMIN_ORIGIN=http://127.0.0.1:8000
export SITE_PREVIEW_ORIGIN=http://127.0.0.1:8001
export SITE_COOKIE_SECURE=0
uvicorn site_engine.web.app:create_app --factory --host 127.0.0.1 --port 8000 --no-access-log
# Во втором терминале с теми же env:
uvicorn site_engine.web.preview_app:create_preview_app --factory --host 127.0.0.1 --port 8001 --no-access-log
```
Перед запуском на рабочем сайте сделайте резервную копию site, dist и state. Для разработки используйте отдельную копию сайта без рабочего `.engine`; QA-скрипты создают такую копию автоматически. Они не меняют права и секреты рабочего примера.
Отдельный процесс превью читает только подготовленные снимки и `auth_epoch` из общего state. Ему не нужен workspace или dist; state можно смонтировать read-only. Не подключайте admin-приложение на preview-origin. Пример с образом из текущего Dockerfile (env-файл содержит те же ключи и внешние HTTPS-origin):
```bash
docker run --rm --name cms-admin -p 8181:8000 --env-file .env \
-v "$PWD/data:/data" flexly-cms
docker run --rm --name cms-preview -p 8182:8000 --env-file .env \
-e SITE_STATE_DIR=/data/state -v "$PWD/data/state:/data/state:ro" flexly-cms \
uvicorn site_engine.web.preview_app:create_preview_app --factory --host 0.0.0.0 --port 8000 --no-access-log
```
Reverse proxy направляет каждый внешний origin в соответствующий процесс. Отключите query strings в access logs proxy для `/s/`; приложение также маскирует `token` в uvicorn access logs. Реальный Docker/proxy deployment не выполнялся при приёмке 001.
Токен подписан отдельным purpose-key, привязан к immutable snapshot, revision, документу/сессии и epoch; TTL — 600 секунд. Проверяется на каждом HTML/asset-запросе, после logout недействителен. Снимок содержит копию ассетов workspace (до 50 MiB), включая защищённые CSS-зависимости. Symlink и traversal отклоняются. Последние 20 снимков документа/сессии сохраняются; просроченные/отозванные и оставшиеся после сбоя незавершённые снимки очищаются при старте и создании следующего снимка (незавершённые — после TTL). Если превью больше не запрашивается, файлы могут оставаться на диске до следующего создания, но обслуживаться после TTL не будут.
Iframe отдельного origin имеет `allow-scripts allow-same-origin`; CSP разрешает только nonce bridge, CSS/изображения/шрифты снимка. JS сайта не подключается, inline-скрипты сайта блокируются. Сообщения проверяются по точному origin, source, типу, snapshot, revision и адресу блока `(scope, owner, id)`. Клик превью не прокручивает страницу, дерево прокручивает к невидимому блоку, последующие обновления восстанавливают viewport/selection. Скрытые блоки не появляются искусственно.
Если обе origin-переменные отсутствуют, редактор работает с превью на административном origin: iframe с `allow-same-origin`, без scripts, CSP `script-src 'none'` и защищённые снимки/ассеты. Выбор секций в обе стороны работает и здесь: родительская админка обрабатывает клики по служебным маркерам и выделяет блок в DOM iframe, проверяя точный URL снимка, iframe/document, revision и адрес блока `(scope, owner, id)`. Код внутри превью не исполняется. Поле API `interactive` обозначает наличие bridge отдельного origin, а не возможность выбрать секцию. При частично заданной или небезопасной конфигурации основное приложение также использует режим без scripts; отдельное приложение превью требует корректные два origin.
## Проверки
```bash
python -m unittest discover -s tests -q
PYTHONPATH=src python scripts/qa_001.py
PYTHONPATH=src python scripts/qa_editor_001.py
python scripts/verify_package_001.py
```
Для браузерных скриптов установите Chromium: `python -m playwright install chromium`. Результаты текущей приёмки, ссылки на тесты и ограничения приведены в [verification.md](verification.md).
## Конструктор Page после этапа 3
Оригинал UI — `design/builder-antirion.html`; runtime не зависит от наличия `design/`. Поведение и визуальные адаптации перечислены в [design-transfer.md](design-transfer.md).
HTML-проекция содержит серверные шаблоны инспектора для всех блоков. Чистый выбор секции локально обновляет дерево/инспектор/выделение и прокрутку превью: без POST, изменения source/revision, нового снимка или замены iframe. Клик по секции превью выбирает её без дополнительной прокрутки. HTML `/select` остаётся для форм без JS и совместимости; он валидирует переданный исходник и строит инспектор, без записи файла.
После 003 инспектор отправляет один stateless POST update после паузы 200 мс; запрос объединяет изменения, проверку и preview. Save и смена режима дожидаются очереди. Чистый выбор секции остаётся локальным. Запрос не сохраняет черновик; контракт и очередь описаны в ../003-background-editor/runtime.md. До явного Save контент не записывается. «Текущая редакция» — память открытой вкладки, без серверного autosave/recovery; `status: draft` — статус файла, исключающий его из релиза. Ошибка формы сохраняет ввод и блокирует последующую запись до исправления. Переходы режимов сохраняют исходные байты. Структурные правки пересобирают YAML без отдельного подтверждения. Для исходника доступны сравнение/отмена, поиск, скачивание и явное форматирование через существующий metadata transform без записи.
Нативные `alert`/`confirm`/`prompt` и `beforeunload`-диалоги не вызываются. Удаление/отмена и внутренний переход с несохранёнными правками подтверждаются в окнах интерфейса; Escape отменяет действие, фокус возвращается к инициатору. При перезагрузке или закрытии вкладки системного подтверждения нет; несохранённая редакция теряется.
API `Add` принимает `props`, `BlockAction` — `type: duplicate`. Дублирование копирует поддерево, генерирует новые ID и снимает anchors копий. Ограничения регионов/слотов/циклов/типов остаются серверными. Schema передаёт manifest preview/defaults, choices и названия страниц; клиент не выдумывает значения. HTML-действия проходят прежний серверный API-клиент, credentials остаются на сервере.
Переключатель Live в редакторе пока отключён с объяснением. Рабочее превью остаётся настоящим временным снимком, а успешная проверка структуры не заменяет проверку релиза. Сохранение не выполняет publish. Компонентная и сквозная проверка: `PYTHONPATH=src python scripts/qa_builder_001.py` и `PYTHONPATH=src python scripts/qa_editor_001.py`.
## Content Editor после этапа 4
UI `/admin/content/{collection}/{id}` использует оригинальные Content templates/CSS и общую очередь 003. Состав backend-доработок и точные границы: [content-backend.md](content-backend.md); машиночитаемый контракт — [openapi.json](openapi.json). Начальный preview — настоящая карточка `entry_card`, переключатель Page рендерит display/layout. Live/Page читает immutable release; Live/Card показывает отсутствие такого артефакта. Старый manifest без Entry hashes/routes не выдаёт неизвестное сравнение за отсутствие изменений.
Дополнительная приёмка: `PYTHONPATH=src python -m unittest discover -s tests -p test_content_editor.py -v`, `PYTHONPATH=src python scripts/qa_content_001.py`, `python scripts/sync_content_design.py --check`, `python scripts/verify_package_001.py --site examples/site-studio`. Браузерный сценарий использует временный Site Studio и два режима preview; исходный дизайн открывается отдельно. Отчёт — [verification-content.md](verification-content.md).
## Publication — повторный этап 5
`GET /admin/publish` — оригинальный экран с реальными изменениями, проверками, кандидатом, историей и журналом. Проверить → собрать → preview/diff → опубликовать с комментарием; сборка и отмена подтверждения не переключают Live. При правке входных файлов/renderer/базового Live кандидат устаревает. Публикация требует `{id, expected_live, comment}`, откат — выбранный release и expected_live. Workspace при откате не меняется.
Browser fetch → `/admin/publication/*` → серверный AdminApi → `/admin/api/v1/publication*` → PublicationService. Локальные вкладки/поиск/выбор не делают POST. Несохранённые данные других вкладок не участвуют в сборке; состояние релизов в localStorage не хранится. История/сравнение берутся из настоящих файлов и частного `SITE_STATE_DIR/publication/`, старые релизы без provenance имеют неизвестное сравнение.
Все маршруты/ошибки/ограничения — [publication-backend.md](publication-backend.md), результаты — [verification-publication.md](verification-publication.md). На сервере нужен новый wheel/пересборка образа; `design/` для runtime не требуется. Дополнительных env или миграции БД нет, SITE_STATE_DIR должен оставаться приватным постоянным каталогом.