Add the shared document API, constructor and expert editors, isolated preview, and fragment catalog metadata with typed block IDs. Include design references, specification 001, QA scripts, project guidance, and cached Docker dependency installation. Leave example sites for a separate commit.
121 lines
18 KiB
Markdown
121 lines
18 KiB
Markdown
# Работающий контракт 001
|
||
|
||
## Редактор и файлы
|
||
|
||
Начальный режим — Конструктор. «Применить к буферу» меняет исходник в памяти открытой вкладки; «Сохранить документ» записывает его целиком. Проверка и превью не создают историю контента и не меняют `current`. Публикация отдельно собирает и переключает релиз. В 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, issues, …}`; 409 дополнительно содержит submitted/current, 422 validation — неприменимый buffer либо диагностику. Лимит JSON-запроса — 1 MiB; source ограничен DTO и безопасным YAML-парсером. Неожиданная ошибка API возвращается без трассировки и секретов.
|
||
|
||
Схема и локальная страница документации доступны после входа: `/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 и совместимости; он валидирует переданный исходник и строит инспектор, без записи файла.
|
||
|
||
Инспектор применяет поля к текущему source после паузы 650 мс; Save/выбор блока/смена режима сначала применяют ожидающую форму. Такой POST transform проверяет и преобразует переданный source, затем обновляет HTML-проекцию; это не сохранение черновика. До явного 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`.
|