Integrate Antirion admin with FastAPI and htmx
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.
This commit is contained in:
@@ -0,0 +1,144 @@
|
||||
# Повторный перенос дизайна 001
|
||||
|
||||
Дата: 2026-11-12. Основание — замечания пользователя о несоответствии оформления и поведения оригинальной вёрстке. Функциональные проверки прежней реализации не подтверждали точность переноса дизайна; визуальная приёмка 001 открыта повторно.
|
||||
|
||||
## Порядок работы и проверки
|
||||
|
||||
Каждый этап передаётся пользователю на проверку. Следующий этап начинается после его проверки. Во всех этапах исходные HTML/CSS/JS из `design/` задают композицию, размеры, иконки и поведение; адаптация подключает реальные данные и действия через существующий FastAPI-контракт. Демонстрационные роли, проверки и публикации не переносятся как фиктивные рабочие функции.
|
||||
|
||||
| Этап | Что переносим | Источник | Проверка пользователя |
|
||||
|---|---|---|---|
|
||||
| 1. Общий каркас | Sidebar, группы и пункты навигации, логотип, верхняя панель, быстрый поиск, профиль, темы, сворачивание, мобильное меню | `antirion-rework.html`, `assets/antirion-rework.css`, `assets/antirion-rework.js`: sidebar/topbar/command | Принят пользователем; разрешён этап 2 |
|
||||
| 2. Обзор и страницы | Композиция обзора, счётчики, поиск/фильтры, выбор строки, правый инспектор, создание страницы в модальном окне | Те же исходники: overview/pages/rows/inspector/new | Принят пользователем; разрешён этап 3 |
|
||||
| 3. Редактор страниц | Заголовок с действиями, дерево слева, превью в центре, инспектор справа, Конструктор/Эксперт, каталог блоков, поля и переключения | `builder-antirion.html`, `assets/builder.css`, `assets/builder.js` | Подготовлен к проверке пользователя |
|
||||
| 4. Контент и записи | Выбор коллекции, список записей, редактор по схеме, превью, вкладки и режим Эксперт | `content-antirion.html`, `assets/content-editor.css`, `assets/content-editor.js` | Ожидает этап 3 |
|
||||
| 5. Публикация и завершение | Композиция публикации/истории/отката, рабочие состояния и подтверждения; итоговая сверка всех экранов, входа, ошибок и пустых состояний | `publication-antirion.html`, `assets/publication.css`, `assets/publication.js` | Ожидает этап 4 |
|
||||
|
||||
Возможности следующей очереди (candidate/diff, RBAC, медиа и прочие) требуют отдельного действующего контракта; их ограничения фиксируются при переносе соответствующего экрана.
|
||||
|
||||
## Этап 1 — принят пользователем
|
||||
|
||||
- Оригинальный `antirion-rework.css` включён в runtime побайтово; его SHA-256 и происхождение SVG записаны в `static/VENDOR.md`. Рабочий пакет не зависит от наличия `design/`.
|
||||
- Shell использует оригинальные классы и композицию, SVG paths и параметры штриха. Старые общие стили кнопок/полей/ссылок вынесены из области каркаса; адаптация native dialog/ссылок находится отдельно в `shell.css`.
|
||||
- Sidebar сохраняет группы WORKSPACE/CONFIGURATION и исходный порядок пунктов, включая положение «Медиа». Счётчик страниц получен через API. Будущие разделы недоступны и подписаны в title.
|
||||
- Topbar показывает реальный host, текущий раздел, быстрый поиск, статус публикации, тему и профиль. Несуществующий релиз не показан как LIVE. Полный реальный ID доступен в title; длинный timestamp/hash сокращается визуально, чтобы сохранить мобильную компоновку.
|
||||
- Поиск открывается кнопкой и Ctrl/Cmd+K; фильтрует разделы и реальные страницы по названию/URL/файлу. Переход на страницу выбирает её в списке, как в оригинале. Закрытие — кнопкой, Esc или фоном; фокус возвращается вызывающему элементу.
|
||||
- Окно профиля показывает действующего администратора и настоящую POST-форму выхода с CSRF. Демо-переключателя ролей нет: в текущем бэкенде один администратор.
|
||||
- Сворачивание, адаптивная узкая панель, темы и мобильное меню сохраняют исходные breakpoints/классы. Настройки хранятся локально; документы и credentials туда не попадают. Мобильное меню удерживает клавиатурный фокус и блокирует фон.
|
||||
- CSS/JS имеют URL с хешем содержимого. htmx не переносит inline `style` при settle: CSP остаётся строгой.
|
||||
|
||||
Содержимое экранов (таблицы, формы, редакторы, публикация) ещё требует переноса на следующих этапах. Их предыдущий внешний вид не считается принятым вместе с каркасом.
|
||||
|
||||
## Свидетельства проверки этапа 1
|
||||
|
||||
```bash
|
||||
PYTHONPATH=src python scripts/qa_shell_001.py
|
||||
PYTHONPATH=src python scripts/qa_001.py --out /tmp/site-engine-shell-general
|
||||
PYTHONPATH=src python -m unittest discover -s tests -q
|
||||
python scripts/verify_package_001.py
|
||||
```
|
||||
|
||||
`qa_shell_001.py` поднимает настоящий uvicorn на временной копии сайта и открывает оригинал отдельно в Chromium. Для сравнения каркаса в оригинале подставляются только те же подписи сайта/host/счётчика/профиля/статуса. Контент страницы, CSS и layout оригинала не заменяются.
|
||||
|
||||
Сопоставляются координаты, размеры, шрифт, padding, цвет и фон 11 элементов каркаса на 1440/1280/1024/768/390/360 px в обеих темах (12 наборов сравнения). Дополнительно проверяются реальные переходы htmx, поиск и пустая выдача, сохранение сворачивания, профиль/выход, мобильный фокус/закрытие и индикатор настоящего опубликованного релиза. С длинным build ID проверяются также 600/430/421 px. В журнал попадают JS-исключения, ошибки console/CSP и HTTP ≥400.
|
||||
|
||||
Артефакты: `/tmp/site-engine-shell-001/` — `report.json`, парные `runtime-*.png`/`reference-*.png`, `collapsed.png`, `command.png`, `command-mobile.png`, `mobile-menu.png`, `live-release.png`.
|
||||
|
||||
Дополнительная регрессия: 239 тестов OK; прежний браузерный сценарий — 8 экранов/60 проверок ширины; установленный wheel без `design/` работает. Эти результаты подтверждают совместимость, но не закрывают визуальную приёмку остальных экранов.
|
||||
|
||||
Статус: этапы 1–2 приняты пользователем. Этап 3 подготовлен к проверке; этапы 4–5 ожидают её результата.
|
||||
|
||||
## Этап 2 — принят пользователем
|
||||
|
||||
- Обзор сохраняет оригинальные headline, overview-stage, live-панель, ribbon и две колонки изменений/проверок. Статус релиза, время сборки, ошибки и предупреждения получены из API. До первой публикации отображается отдельное состояние. Последние изменения показывают время файлов, без выдуманного автора.
|
||||
- Список сохраняет исходные toolbar, tabs, workbench, размеры колонок, выделение строки, правый инспектор, миниатюру и действия. Поиск работает по названию/URL/файлу; layout и вкладки пересекаются с запросом. Выбор строки меняет инспектор, кнопка «Редактор» отдельно открывает существующий редактор. Выбор сохраняется при фильтрации и сбросе, URL поддерживает Back/Forward.
|
||||
- Поиск обновляет только результаты и сохраняет фокус ввода. Выбор Desktop/Mobile миниатюры сохраняется при переключении строки. Информация, детали и создание используют исходные `.dialog`, `.field`, `.copyline`, `.dialog-actions` с native dialog, Escape/фоном и возвратом фокуса.
|
||||
- Создание вызывает настоящий API: новая страница — draft, допускается вложенный ID, после успеха остаёмся в списке с выбранной новой страницей. Открытие/отмена ничего не записывают. При 409/422 окно остаётся открытым с ошибкой и введёнными значениями. Обычные GET/POST работают без JavaScript.
|
||||
- Оригинальный CSS по-прежнему побайтово совпадает с `design/assets/antirion-rework.css`. `pages.css` адаптирует семантические ссылки и переносит исходные inline-размеры под CSP; старые общие стили изолированы от перенесённых экранов.
|
||||
|
||||
### Данные и ограничения
|
||||
|
||||
`PageRow` дополнен `changed`, `description`, `updated_at`, `issues`, `on_live`; `Workspace` — типизированным `release` и `comparison_available`. JSON-фильтр `/pages?changed=true` и HTML-вкладка используют одну проекцию. Credentials остаются на сервере.
|
||||
|
||||
Для настоящего сравнения файлов Page новые `manifest.json` сохраняют `page_sources`: SHA-256 только опубликованных файлов страниц. Черновые пути и исходники в публичный manifest не попадают. После редактирования/возврата исходных байтов и отката сравнение следует активному релизу. В существующих релизах без индекса сравнение неизвестно: UI показывает «—» и объяснение; перепубликовывать автоматически не нужно. Это сравнение файлов Page, а не полный dependency diff сайта: изменения layout, fragment, коллекций или assets отдельно этим счётчиком не охватываются.
|
||||
|
||||
Миниатюра сохраняет композицию исходного mock и показывает настоящий заголовок/литеральное SEO-описание; полный рендер страницы доступен в редакторе. Дублирование в деталях отключено с пояснением: такого действия в API пока нет. Новые действия редактора и публикации относятся к этапам 3–5.
|
||||
|
||||
### Проверки этапа 2
|
||||
|
||||
```bash
|
||||
PYTHONPATH=src python scripts/qa_pages_001.py
|
||||
PYTHONPATH=src python scripts/qa_shell_001.py
|
||||
PYTHONPATH=src python scripts/qa_editor_001.py
|
||||
PYTHONPATH=src python -m unittest discover -s tests -q
|
||||
python scripts/verify_package_001.py
|
||||
```
|
||||
|
||||
`qa_pages_001.py` поднимает настоящий uvicorn на временной копии и открывает оригинал отдельно в Chromium. В оригинале для сравнения заменяются подписи headline/ribbon и данные/число строк таблицы; исходные компоненты и CSS не заменяются. Проверяются 24 набора: overview/pages × light/dark × 1440/1280/1024/768/390/360 px. Сверяются шрифты, padding, цвета, ширины и положение устойчивых компонентов; вертикальные размеры зависимых от реальных текстов областей записываются в отчёт. Это компонентная сверка и скриншоты, а не утверждение о побайтовом совпадении изображений с разными данными.
|
||||
|
||||
Браузер проверяет выбор мышью/клавиатурой, фильтры/сброс/пустую выдачу/историю, фокус поиска, миниатюру, диалоги, настоящие draft и 409/422, отсутствие публикации при создании, значения после publish/edit/revert и неизвестное сравнение старого релиза, GET/POST без JS. Неожиданных JS/console/CSP/HTTP-ошибок нет. Артефакты: `/tmp/site-engine-pages-001/` — `report.json`, парные скриншоты overview/pages, окна и `pages-live.png`.
|
||||
|
||||
Регрессия: 244 теста OK; каркас — 12 наборов сравнения/6 сценариев; редактор — 25 сквозных сценариев. Wheel установлен вне checkout без `design/`; новые CSS/JS и страницы доступны. Общая проверка экранов — 8 экранов/60 проверок ширины.
|
||||
|
||||
|
||||
## Этап 3 — результат для проверки
|
||||
|
||||
Источник — `builder-antirion.html` и `assets/builder.{css,js}`. Сохранены исходные классы, SVG paths/stroke, три панели, toolbar превью, вкладки дерева/карты источников, инспектора, каталог и редактор исходника. Принятый shell остаётся общим. `builder-design.css` — побайтовая копия исходника; `builder.css` автоматически добавляет ограничивающие редактором обычные селекторы через `:where`, сохраняя декларации, media queries и специфичность document root. Зависимости от браузерного `@scope` нет. Семантические HTML/htmx/CSP-адаптации находятся отдельно в `builder-adapter.css` и `builder.js`. Проверяемое воспроизведение: `python scripts/sync_builder_design.py --check`; хеши — `static/VENDOR.md`.
|
||||
|
||||
### Поведение
|
||||
|
||||
- Дерево показывает настоящие регионы, вложенные блоки/слоты, ID, скрытие и условия. Layout-блоки выбираются в read-only инспектор; изменять/перемещать/дублировать их нельзя. Карта источников показывает реальные literal/bind/query/типизированные ссылки из props.
|
||||
- Поля строятся по схемам фрагментов. Простые поля сохраняют исходные `.field`/`.tiny-source`, списки, группы, link и query используют существующий типизированный парсер. Сложные поля не заменены плоским mock-эквивалентом. Файлы и ref выбираются из реальных choices, literal/bind сохраняются различимыми значениями.
|
||||
- Чистый выбор секции локально переключает дерево и серверную HTML-проекцию инспектора; POST и блокировки интерфейса нет. Как в оригинале, дерево выделяет и прокручивает секцию в основном окне, клик по самой секции выбирает её в дереве и инспекторе. Снимок и iframe при выборе сохраняются. Это работает и без отдельного preview-origin: родительская админка управляет служебными маркерами в iframe без scripts; CSP остаётся `script-src 'none'`. Bridge другого origin сохраняет проверки origin/source/snapshot/revision/адреса блока.
|
||||
- Правки инспектора применяются к текущей редакции после паузы 650 мс и обновляют настоящее превью. Кнопки Save, выбор другого блока и смена режима сначала применяют ожидающие поля. Фокус, caret и прокрутка инспектора/дерева восстанавливаются. Кнопка «Применить изменения» доступна отдельно.
|
||||
- При 422 сохраняются актуальные значения input/textarea/select/checkbox, а не старые HTML-атрибуты. Ошибка останавливает следующий Save/переход; исправленные значения можно отправить повторно. 401/сетевая ошибка не очищают исходник.
|
||||
- Каталог сохраняет поиск/категории и фильтрует реально допустимые фрагменты для региона/слота с учётом allow-паттернов. Клик вставляет блок с `preview`/default из настоящего manifest и выбирает новый ID. Ошибка оставляет окно с введёнными полями. Отдельного обязательного шага настройки перед каждой вставкой нет.
|
||||
- Выше/ниже, drag-and-drop, скрытие, удаление и дублирование вызывают API transform. Дублируется всё поддерево с новыми ID; anchor копий снимаются, чтобы не получить повтор. После удаления выбирается соседний блок. Подтверждения удаления/отмены используют исходную модальную композицию; Escape отменяет действие.
|
||||
- Desktop/Tablet/Mobile сохраняются при обновлении iframe. Клик настоящего превью выбирает блок, дерево прокручивает превью, обновление сохраняет viewport. Один iframe переносится между панелями Конструктора/Эксперта; перед htmx-заменой инспектора он сохраняется вне заменяемой области. Публичный HTML и JS сайта не получают служебных изменений.
|
||||
- В «Эксперте» перенесены файлы слева, codebox/гаттер/подсветка/статусная строка по центру, превью и проверки справа; responsive использует исходный `.expert-layout`. Есть поиск, Ctrl/Cmd+F, Ctrl/Cmd+Enter, Ctrl/Cmd+S, скачивание, реальное сравнение с последней загруженной/сохранённой версией, отмена и явное серверное форматирование. Обычное переключение режимов не сериализует исходник; CRLF сохраняется до содержательной правки.
|
||||
|
||||
### Архитектура и границы
|
||||
|
||||
«Текущая редакция» в переключателе превью — изменения в памяти вкладки. Transform/validate/preview обрабатывают переданный source без записи контента; файл записывается только по «Сохранить документ», с прежними CAS/ETag, валидацией, историей и аудитом. Серверное автосохранение и восстанавливаемые draft-сессии не добавлены. `status: draft` остаётся статусом файла/участия в релизе. Продуктовые подписи используют «Нет несохранённых изменений», «Применить изменения», «Предпросмотр».
|
||||
|
||||
Контракт дополнен `BlockAction.type: duplicate`, `Add.props`; schema включает настоящие manifest preview/defaults и названия страниц. Сохранение неполного документа по-прежнему допускается по ADR-003; готовность к публикации проверяет release validation. Успешная проверка структуры не выдаётся за проверку полного релиза. Сохранение не публикует сайт.
|
||||
|
||||
Отдельного предупреждения о пересборке YAML при правках нет; пояснение остаётся рядом с исходником. Нативные `alert`/`confirm`/`prompt` и `beforeunload`-диалоги запрещены. Подтверждения удаления, отмены правок и внутренних переходов используют окна интерфейса, Escape отменяет действие и возвращает фокус. Перезагрузка/закрытие вкладки не вызывает системного подтверждения; несохранённая редакция при этом теряется.
|
||||
|
||||
Тёмный режим использует утверждённые токены `antirion-rework.css`; палитра Rose не перенесена. Live-переключатель недоступен с объяснением: контракт просмотра опубликованного снимка в редакторе ещё отсутствует. Обратный поиск usages, developer/RBAC, demo server и симуляция 409 из прототипа не показаны как работающие возможности. Настоящий 409 обрабатывается через сравнение двух исходников, явное принятие ETag основы и отдельное сохранение.
|
||||
|
||||
### Проверки этапа 3
|
||||
|
||||
```bash
|
||||
python scripts/sync_builder_design.py --check
|
||||
PYTHONPATH=src python scripts/qa_builder_001.py
|
||||
PYTHONPATH=src python scripts/qa_selection_001.py
|
||||
PYTHONPATH=src python scripts/qa_editor_001.py
|
||||
PYTHONPATH=src python scripts/qa_shell_001.py
|
||||
PYTHONPATH=src python scripts/qa_pages_001.py
|
||||
PYTHONPATH=src python scripts/qa_001.py
|
||||
PYTHONPATH=src python -m unittest discover -s tests -q
|
||||
python scripts/verify_package_001.py
|
||||
```
|
||||
|
||||
Chromium открывает оригинал отдельно от настоящего приложения на временной копии сайта. Конструктор: 12 наборов сравнения (2 темы × 6 ширин 1440/1280/1024/768/390/360), сверяются ширины колонок, шрифты/отступы компонентов, исходные светлые фоны. Для тёмной темы используется утверждённая палитра shell; это не сравнение с Rose. Эксперт: 6 сравнений шрифта/padding исходника, колонок на desktop и переноса инспектора на tablet; парные скриншоты оригинала. Это компонентная сверка при разных настоящих данных, не заявление о попиксельном совпадении всего экрана.
|
||||
|
||||
12 браузерных групп проверяют переключение режимов до первой операции сервера с восстановлением превью/toolbar, автообновление/фокус/caret, немедленное применение перед выбором/Save, 422 с сохранённым вводом и остановкой Save, исправление и выбор настоящего изображения, viewport, binding, дублирование/отмену удаления/выбор соседа, каталог/вставку, drag-and-drop, явную запись без publish, форматирование без записи, Expert/diff/reset/фокус и карту источников. Проверяется и нижняя граница панелей на desktop: перенос кнопок не увеличивает документ за пределы viewport. Сквозная регрессия редактора — 25 сценариев, включая два origin, запрет JS сайта, границы сообщений, CRLF, две вкладки/409, сессию, сеть и Save без JS.
|
||||
|
||||
Полная регрессия — 248 тестов OK. Прежние shell/pages — 12/24 набора и 6/6 групп; общая проверка — 8 экранов/60 ширин. Установленный wheel работает без `design/`, включая новые CSS/JS/шаблоны; CLI validate/build на изолированной копии — 0 ошибок/предупреждений, 7 страниц. Артефакты: `/tmp/site-engine-builder-001/` (`report.json`, `constructor-*.png`, `expert-dark-*.png`, `reference-*.png`), `/tmp/site-engine-builder-general/`, `/tmp/site-engine-001-editor-qa/`.
|
||||
|
||||
Этап 3 передаётся пользователю на проверку. Этапы 4–5 в этой итерации не переносились.
|
||||
|
||||
### Исправление по скриншоту пользователя
|
||||
|
||||
На `http://10.10.0.44:8181` выполнена проверка напрямую без прокси, с настоящим входом. В Chromium исходные CSS загружались и применялись; в Firefox 142.0.1 воспроизведён распавшийся интерфейс из `data/Screenshot_198.png`: `CSSScopeRule` отсутствует, `.builder` имеет `grid-template-columns: none`, одновременно видны оба режима. Причина — игнорирование браузером всего `@scope`, а не HTTP-ошибка загрузки CSS.
|
||||
|
||||
`builder.css`, `builder-adapter.css` и изоляция старого редактора в `admin.css` используют обычные селекторы с `:where`. Генератор сохраняет исходные декларации и media queries, новые at-rules требуют явной поддержки генератором. Дополнительно исправлены всплытие `document:state`, порядок переноса iframe относительно изменения классов и расчёт оставшейся высоты под фактической шапкой. При fallback-переносе iframe отправка bridge-команд ждёт проверенное `preview:ready`, чтобы не писать во временный `about:blank` до загрузки другого origin.
|
||||
|
||||
Исправленные ресурсы проверены на настоящем сервере подменой файлов только в тестовой вкладке: 42 комбинации переключений/тем/ширин в Chromium и Firefox, переходы htmx и каталог; отдельно — страница «Услуги» при 1673 × 948 из скриншота. Серверная сборка и рабочий контент при этом не менялись. Артефакты: `/tmp/cms-live-inspect/` — `firefox-constructor.png` до исправления, `services-firefox-fixed.png` после, `fixed-report.json` / `firefox-fixed-report.json`.
|
||||
|
||||
Для постоянного прогона другого браузера `qa_builder_001.py` поддерживает `QA_BROWSER=firefox`, необязательный `QA_BROWSER_EXECUTABLE` и отдельный `QA_BUILDER_OUT`. Нужны совместимые версия Playwright, браузер и его системные библиотеки.
|
||||
|
||||
### Выбор секций и подтверждения
|
||||
|
||||
`scripts/qa_selection_001.py` прошёл в Chromium 158 и Firefox 142; проверяет два режима превью — административный origin без scripts и bridge отдельного origin: дерево → выделение/прокрутка/инспектор, превью → дерево/инспектор, фиксированные блоки только для чтения, ноль POST при чистом выборе, неизменный iframe/снимок/source, отсутствие записи файла и публикации. Повторные правки после локального выбора передают текущий source. Проверяются отмена перехода через селектор/ссылку/выход, подтверждённый переход/выход из Entry, Escape, перезагрузка без системного диалога. Любой нативный диалог проваливает прогон. Артефакты: `/tmp/site-engine-selection-001/` и `/tmp/site-engine-selection-firefox-001/`.
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,274 @@
|
||||
# Технический план 001 — Antirion Rework
|
||||
|
||||
Дата: 2026-11-12. Статус: функциональная реализация проверена, визуальная приёмка открыта повторно. [Порядок переноса оригинальной вёрстки с проверкой пользователя](design-transfer.md). Действующие маршруты и запуск — [runtime.md](runtime.md); этот документ сохраняет этапы и обоснование архитектуры.
|
||||
|
||||
Основание: [спецификация](spec.md). Учёт выполнения: [задачи](tasks.md).
|
||||
|
||||
## 1. Подход и границы
|
||||
|
||||
Выполнить два последовательных результата: сначала новое оформление существующей админки, затем сервисы и общий буфер редакторов с интерактивным превью. Контрольные точки обязательны перед переходом к следующему результату.
|
||||
|
||||
Сохранить `core/`, `parsing/`, `storage/`, `services/`, `web/`, dataclass-модели и файловые контракты. Развивать существующие модули без переименования всего пакета в слои из предложенной структуры stage7.
|
||||
|
||||
Один администратор остаётся в `AuthService`; контекст автора создаётся на сервере. SQLite/RBAC, новый release pipeline и MCP не являются зависимостями 001.
|
||||
|
||||
Принять подход flexly-estimator: браузер/htmx → HTML UI FastAPI → серверный API-клиент → JSON API FastAPI → прикладные сервисы. `web/admin/api_client.py` предоставляет методы предметных операций; транспорт — `httpx.AsyncClient` с `ASGITransport(app=...)`. Сетевой порт для внутреннего вызова не требуется, но авторизация, сериализация и валидация FastAPI выполняются. Lifespan инициализирует зависимости один раз в основном приложении; ASGITransport не запускает его повторно.
|
||||
|
||||
Пока выполняется оформление этапа B, допускается действующий прямой вызов сервисов из старых обработчиков. Этапы C–D переводят чтение данных и операции контента, превью и публикации на API-клиент. Аутентификация UI, загрузка локальной статики и рендер шаблонов остаются в UI. CLI и будущий MCP могут обращаться к сервисам напрямую. Отдельное развёртывание UI/API не требуется для 001; клиент изолирует транспорт для будущего расширения.
|
||||
|
||||
## 2. Аудит и документация — этап A
|
||||
|
||||
Сопоставить stage7 с `core/models.py`, `core/values.py`, `core/registry.py`, `core/draft_check.py`, `services/content.py`, `services/publish.py`, `web/admin/editor.py` и текущими тестами. В stage7 пометить каждую возможность как реализованную, доработку 001 или следующую очередь.
|
||||
|
||||
Исправить примеры Page/Entry относительно схем сайта-примера: query wrapper, `richtext.content`, доступный layout и поля коллекции. При проверке примеров использовать временную копию сайта, а не рабочие данные. Сопоставить номера ADR и сохранить историю предложений. Не объявлять все предложенные ADR принятыми автоматически.
|
||||
|
||||
Проверить актуальность AGENTS.md: HTML использует `etag`, сервис — `if_match`; принято направление htmx → UI → JSON API. Эти сведения уже зафиксированы. Описание интерактивного превью обновить после его реализации, сохранив требования к безопасности.
|
||||
|
||||
Подготовить изолированное окружение через доступный `uv`, установить extras `server,dev` и средства browser QA. Выполнить исходные проверки и сохранить вывод. Если установка или тест недоступны, записать конкретную причину без объявления проверки успешной.
|
||||
|
||||
**Выход:** актуальная матрица расхождений, проверяемые примеры, исходные результаты тестов, визуальные эталоны по выбранным HTML/CSS.
|
||||
|
||||
## 3. Оформление рабочих экранов — этап B
|
||||
|
||||
### 3.1. Runtime-ресурсы и шаблоны
|
||||
|
||||
Разместить CSS/JS в `src/site_engine/web/admin/static/`, общие Jinja-компоненты и шаблоны — в `web/admin/templates/`. Согласовать токены Antirion из shell, builder и publication; стили отдельных экранов ограничить их контейнерами, чтобы правила таблиц и форм не конфликтовали.
|
||||
|
||||
Общие компоненты: shell, боковое меню, верхняя панель, заголовок, статус, таблица, поле формы, диагностика, пустое состояние, диалог и уведомление. JS подключать внешним локальным файлом; inline event handlers и inline-стили прототипа перенести в разрешённые механизмы.
|
||||
|
||||
Светлая палитра — исходная; предусмотренное Antirion переключение светлой/тёмной палитры реализовать общими токенами. Хранить только UI-предпочтение. Скругления/палитру Rose Graphite не переносить.
|
||||
|
||||
Сохранить обычные формы и полноценную навигацию до внедрения новых редакторов. Статические ресурсы выдаются по allowlist с корректными MIME. Уточнить package-data для вложенных partials и будущих ресурсов превью; установленный пакет не читает `design/`.
|
||||
|
||||
`static/htmx.min.js` версии 2.0.11 уже перенесён побайтно из flexly-estimator; источник, лицензия 0BSD и SHA-256 находятся в `static/VENDOR.md`. Для обновления проверять новый дистрибутив и обновлять запись; установка Node и загрузка CDN в runtime не нужны. Эта поставка не закрывает задачи нового редактора или API.
|
||||
|
||||
### 3.2. Представления и данные
|
||||
|
||||
Последовательно перенести вход, обзор, списки, формы Page/Block/Entry, публикацию, сообщения и пустые состояния. У входа нет отдельного прототипа: использовать те же токены и компоненты формы без копирования shell защищённого раздела.
|
||||
|
||||
Данные получать из Registry и действующих сервисов. Добавить эффективный layout, файл, число блоков, статусы и current build. Поиск/фильтры реализовать через GET-параметры `q`, `status`, `layout` (последний только для Page). Неверные значения фильтра не расширяют доступ и отображаются как ошибка запроса. Выбранный объект идентифицируется по проверенному ID; отсутствие выбора даёт пустой инспектор.
|
||||
|
||||
Счётчики «изменено относительно live», diff, время/автор релиза показываются только при наличии реальных данных. В 001 не вычислять их из вымышленных seed-моделей или времени изменения файлов. Новые разделы прототипа до реализации получают объяснение недоступности, без маршрутов фиктивного CRUD.
|
||||
|
||||
`/admin/publish` продолжает выполнять существующие publish/rollback. Добавить подтверждение действия и реальные состояния успеха/ошибки. Кандидат релиза не появляется до спецификации 002.
|
||||
|
||||
### 3.3. Исправления интеграции
|
||||
|
||||
- Для существующего iframe явно добавить `frame-src 'self'`, сохранив ограничения `frame-ancestors` админки и sandbox превью.
|
||||
- Для пассивного превью предоставить авторизованную раздачу ассетов workspace из разрешённого `assets/` с safe path, nosniff и ограничивающим CSP. Обновить URL в preview-рендере и CSS, включая вложенные ссылки ресурсов; публичная сборка сохраняет `/assets/...`.
|
||||
- Поддержать бинарные ответы ассетов, не декодируя изображение как текст.
|
||||
- При 422 повторно отрисовывать переданные значения; при 409 сохранить пользовательские поля и предоставить текущую версию без автоматического повторного POST.
|
||||
|
||||
**Контрольная точка B:** AC-01, AC-08, AC-09 и упаковочная часть AC-10. Оформление не блокируется отсутствием отдельного preview origin: на этом этапе используется безопасное пассивное превью.
|
||||
|
||||
## 4. Прикладные сервисы и запись — этап C
|
||||
|
||||
### 4.1. Разделение ответственности
|
||||
|
||||
| Слой | Ответственность |
|
||||
|---|---|
|
||||
| UI-роутер | Request/FormData, cookie, Origin/CSRF, вызов серверного API-клиента |
|
||||
| Обработчик UI | Сбор представления и partials из DTO API, статусы/редиректы, введённые значения |
|
||||
| API-клиент UI | Преобразование полей формы в JSON DTO, внутренний авторизованный вызов, разбор DTO/ошибок |
|
||||
| JSON API FastAPI | Явные маршруты и Pydantic DTO, проверенный автор, HTTP-коды и общий формат ошибок; без Jinja и HX-веток |
|
||||
| PageService / EntryService | Проверенный объект, создание/чтение, операции буфера, validation, сохранение и аудит |
|
||||
| ContentService / storage | Разрешённый путь, один lock, CAS, история, атомарная запись |
|
||||
| Core | Схемы, разбор/разрешение значений, дерево, валидация и рендер |
|
||||
|
||||
Добавить `services/pages.py`, `services/entries.py` и общий модуль результатов редактора при необходимости. Формы `p.*` остаются представлением; прикладной сервис получает разобранные значения и не зависит от Request или Jinja.
|
||||
|
||||
UI-роутеры, использующие AsyncClient, выполняются как `async def` и ожидают API-клиент. Из прежнего EditorHandlers выделить сборку представлений из DTO; не запускать отдельный event loop на каждый вызов и не выполнять вложенный синхронный HTTP-запрос к тому же uvicorn-процессу.
|
||||
|
||||
### 4.2. Внутренние контракты
|
||||
|
||||
Использовать dataclass-результаты, сохраняя существующий Report/Issue:
|
||||
|
||||
| Контракт | Обязательные данные |
|
||||
|---|---|
|
||||
| DocumentSnapshot | Тип Page/Entry, логический ID, относительный путь, исходник, модель, ETag, Report |
|
||||
| EditorContext | Проверенный Principal, IP/источник операции для аудита; создаётся адаптером |
|
||||
| BufferResult | Текущий исходник, последняя корректная модель или диагностика ошибки, ETag основы, номер редакции UI |
|
||||
| SaveResult | Сохранённый снимок и новый ETag |
|
||||
| ConflictResult | Переданный исходник, ETag основы и текущий серверный снимок |
|
||||
| PreviewResult | URL ограниченного снимка, срок действия, номер редакции UI |
|
||||
|
||||
Общие возможности сервисов: `get`, `create`, `validate_source`, `transform_buffer`, `save_source`. PageService также применяет операции с блоками; EntryService проверяет поля коллекции. Превью использует тот же разобранный документ/Report, а не отдельный browser codec.
|
||||
|
||||
### 4.3. Транзакционная граница одного файла
|
||||
|
||||
В ContentService добавить операцию обновления с владельцем блокировки. Под одним SiteLock: проверить путь → перечитать байты → проверить if_match/ABSENT → загрузить актуальную схему → подготовить изменение → проверить → сохранить предыдущую версию → atomic_write. Отдельная точка входа записывает уже подготовленный исходник через тот же цикл.
|
||||
|
||||
Не вызывать публичный `write`, повторно захватывающий SiteLock, из участка с уже удерживаемой блокировкой. Старый интерфейс ContentService сохранить или адаптировать совместимо с тестами и текущими вызовами.
|
||||
|
||||
При отказе до записи история и канонический файл не меняются. Аудит успешной операции формируется сервисом однократно, без второго события из старого обработчика. Ошибки журналирования не маскировать под успешное завершение; клиенту не предлагать слепой повтор с прежним ETag после уже состоявшейся записи.
|
||||
|
||||
**Выход:** JSON API вызывает общие сервисы, старый UI переводится на API-клиент; существующие тесты сохраняют семантику, два писателя не теряют изменения.
|
||||
|
||||
### 4.4. JSON-контракт и внутренний клиент
|
||||
|
||||
Разместить API-роутеры, схемы и зависимости в `src/site_engine/web/api/`; HTML-маршруты остаются в `web/admin/`. Добавить `httpx` в extra `server`, поскольку это runtime-зависимость API-клиента, а не только средство тестирования. Ядро и сервисные результаты остаются dataclass; Pydantic-модели на HTTP-границе явно преобразуются в них и обратно. Использовать `response_model` или аннотированные модели ответов, а не произвольные dict.
|
||||
|
||||
Префикс API — `/admin/api/v1/`. UI сохраняет существующие URL и префикс `/admin/editor/` для HTML-фрагментов. Объявить API- и UI-маршруты до существующего catch-all редактора и до раздачи публичного сайта. Не подменять JSON на HTML при наличии HX-Request.
|
||||
|
||||
| Операция | JSON API |
|
||||
|---|---|
|
||||
| Обзор и доступные коллекции | `GET /admin/api/v1/site`, `GET /admin/api/v1/collections` |
|
||||
| Списки/создание документов | `GET/POST /admin/api/v1/pages`, `GET/POST /admin/api/v1/entries/{collection}` |
|
||||
| Снимок Page | `GET /admin/api/v1/editor/pages/{id}/source` |
|
||||
| Буфер Page | `POST /admin/api/v1/editor/pages/{id}/{transform,validate,save,preview}` |
|
||||
| Снимок Entry | `GET /admin/api/v1/editor/entries/{collection}/{slug}/source` |
|
||||
| Буфер Entry | `POST /admin/api/v1/editor/entries/{collection}/{slug}/{transform,validate,save,preview}` |
|
||||
| Релизы и текущая публикация | `GET /admin/api/v1/releases` |
|
||||
| Текущие publish/rollback | `POST /admin/api/v1/publish`, `POST /admin/api/v1/rollback` |
|
||||
|
||||
Фигурная группа действий обозначает отдельный явный маршрут для каждого действия. Вложенные ID Page с `/` поддерживаются и проверяются по Registry; маршрут не принимает произвольный файловый путь. Списки принимают те же q/status/layout, что UI. Create возвращает 201 и DocumentSnapshot; чтение/transform/validate/save/preview — 200 с соответствующим DTO. Publish/rollback возвращают фактический результат действующих сервисов без нового candidate pipeline.
|
||||
|
||||
DTO запросов буфера: `source`, `etag`, `revision`; transform дополнительно содержит дискриминированное типизированное `action`. `revision` — неотрицательное целое, возвращаемое без изменения, `etag` — прежний непрозрачный маркер версии. Схемы запрещают неизвестные служебные поля; пользовательские props проверяет действующая схема фрагмента/коллекции. В JSON не передаются csrf, Principal или произвольный путь записи.
|
||||
|
||||
Ответы соответствуют DocumentSnapshot/BufferResult/SaveResult/ConflictResult/PreviewResult из раздела 4.2. Модель документа передаёт только сериализуемые разрешённые данные, включая типы значений и дерево; Python-объекты и пути вне сайта не выдаются. Ошибка имеет форму `error: {code, message, issues, revision}`; issue содержит code, message и field/path, если применимо. Для 409 дополнительно передаются `submitted_source`, `base_etag`, `current` (DocumentSnapshot). Для ошибок схемы запроса и предметной валидации использовать один envelope, сохраняя различимые коды.
|
||||
|
||||
HTTP-статусы: 401 — нет действительных внутренних credentials, 403 — запрещённая операция, 404 — объект отсутствует, 409 — конфликт, 422 — недопустимый запрос/документ. Недопустимый буфер validate возвращает 422 с диагностикой; валидный неполный draft — 200 с предупреждениями. Ошибки 5xx не содержат трассировки; UI сохраняет введённые данные, сообщает о сбое и не выполняет альтернативную запись напрямую.
|
||||
|
||||
Pydantic-схемы служат источником OpenAPI. Добавить воспроизводимую выгрузку схемы для CI; доступ к HTTP-схеме `/admin/api/v1/openapi.json` и документации `/admin/api/v1/docs` разрешить только проверенной админской сессии. Скрытие docs не заменяет авторизацию API. Тесты проверяют маршруты, модели успешных ответов, envelope ошибок и версию контракта; не требуется отдельная сборка TypeScript-клиента.
|
||||
|
||||
### 4.5. Автор и авторизация между UI и API
|
||||
|
||||
UI сначала проверяет действующую cookie, Origin и CSRF, включая validate/transform/preview без канонической записи. API принимает только серверные credentials, связанные с проверенным администратором, сессией и auth epoch. Наличие /admin в URL или заголовка HX-Request не даёт доступа; одна cookie браузера не авторизует JSON API.
|
||||
|
||||
Внутренние токены создаёт сервер после проверки сессии, хранит в памяти процесса и ограничивает сроком этой сессии. ASGITransport вызывает тот же экземпляр приложения. Logout/изменение эпохи и истечение сессии проверяются на API-границе, не только в UI; после перезапуска прежние внутренние токены недействительны. Клиент передаёт авторизованный audit-контекст; login/epoch/IP нельзя брать из полей формы или копировать из произвольных входящих заголовков. Токены, cookie и исходник не попадают в журналы запросов.
|
||||
|
||||
API-ключ не включается в HTML, JS, URL или browser storage. В 001 не добавлять внешние API-ключи, scopes или настройки внешнего деплоя UI: это отдельное развитие. Файловые операции и рендер остаются синхронными; JSON-адаптер выполняет их в пуле потоков, не блокируя event loop вложенного ASGI-вызова.
|
||||
|
||||
## 5. Буфер и редакторы — этап D
|
||||
|
||||
### 5.1. Жизненный цикл
|
||||
|
||||
```text
|
||||
GET документа → source + base_etag + корректная модель
|
||||
→ изменение поля / исходника
|
||||
→ server validate/transform → новый буфер, прежний base_etag
|
||||
→ preview → временный результат, прежний base_etag
|
||||
→ явное Save → CAS + validation + history + write
|
||||
→ новый source + новый base_etag, буфер отмечен сохранённым
|
||||
```
|
||||
|
||||
Состояния UI: сохранён, есть несохранённые правки, проверяется, ошибка исходника, сохраняется, конфликт. Полнота для публикации показывается отдельно от допустимости сохранения draft. Проверка без правок не меняет dirty-состояние.
|
||||
|
||||
При переключении режима валидный source становится представлением той же модели. Невалидный source остаётся в «Эксперте»; доступны исправление, скачивание текста и явный отказ от правок. Без пользовательского действия не возвращать другую версию документа. При внутреннем переходе к другому документу подтверждать потерю несохранённых правок через окно интерфейса. Не использовать нативные alert/confirm/prompt и beforeunload-диалоги; отдельного подтверждения пересборки YAML нет.
|
||||
|
||||
### 5.2. HTTP-интерфейс
|
||||
|
||||
Существующие страницы `/admin/pages/{id}` и `/admin/content/{collection}/{slug}` сохраняются. В новом редакторе GET-параметр `mode=constructor|expert` задаёт представление; значение по умолчанию — constructor.
|
||||
|
||||
Добавить внутренние endpoints под отдельным префиксом, чтобы вложенный ID Page не конфликтовал с прежней адресацией:
|
||||
|
||||
| Действие | Page | Entry |
|
||||
|---|---|---|
|
||||
| Получить исходник | `GET /admin/editor/pages/{id}/source` | `GET /admin/editor/entries/{collection}/{slug}/source` |
|
||||
| Изменить буфер | `POST /admin/editor/pages/{id}/transform` | `POST /admin/editor/entries/{collection}/{slug}/transform` |
|
||||
| Проверить | `POST /admin/editor/pages/{id}/validate` | `POST /admin/editor/entries/{collection}/{slug}/validate` |
|
||||
| Сохранить | `POST /admin/editor/pages/{id}/save` | `POST /admin/editor/entries/{collection}/{slug}/save` |
|
||||
| Подготовить превью | `POST /admin/editor/pages/{id}/preview` | `POST /admin/editor/entries/{collection}/{slug}/preview` |
|
||||
|
||||
Это HTML-маршруты UI. Каждый вызывает одноимённую операцию JSON API из раздела 4.4 через серверный клиент; UI не обращается к Registry/ContentService для выполнения этих операций. Все POST UI требуют существующие сессию, проверку источника и `csrf`, включая операции без записи. Общие поля формы: `source`, `etag`, `revision` (номер изменения в UI); transform также передаёт типизированное действие и его значения. ID с `/` разбирается как логический ID Page и сверяется с реестром на API/сервисной границе до доступа к файлу.
|
||||
|
||||
Типы transform: метаданные Page, поля/статус/Markdown Entry, props/настройки блока, add/delete/toggle/move блока. Для перемещения использовать ID и `before`/`after` внутри указанного региона/слота; сохранять проверку allow, fixed, предельной вложенности и отсутствия циклов. Кнопки порядка остаются доступны с клавиатуры; drag-and-drop не является отдельным требованием 001.
|
||||
|
||||
HTML-ответы UI: 200 — partials и актуальное состояние буфера; успешный Save — сохранённое состояние (для полной формы допустим 303); 409 — панель сравнения с обеими версиями; 422 — исходник и диагностика. Остальные коды сохраняют смысл действующей админки. JSON API предназначен серверному клиенту UI; анонимный/внешний API не открывается.
|
||||
|
||||
Частичные ответы включают согласованные дерево, инспектор, исходник, диагностику и статус. Каждому ответу соответствует revision; устаревшие ответы игнорируются. Отправка Save блокирует конкурирующее повторное нажатие, но отказ сети сохраняет буфер и позволяет проверить серверную версию перед повтором.
|
||||
|
||||
### 5.3. Реализация UI и конфликтов
|
||||
|
||||
Использовать поставленную локальную версию htmx с лицензионным уведомлением. Настройки `allowEval=false`, `allowScriptTags=false`, `selfRequestsOnly=true`, `includeIndicatorStyles=false`, `historyCacheSize=0` задавать без inline JS, не использовать inline hx-on. История htmx не должна сохранять HTML с контентом/CSRF в localStorage. Разрешить подстановку ожидаемых 409/422: htmx по умолчанию их не подставляет. UI задаёт HX-Retarget/HX-Reswap для области диагностики или панели конфликта, а не заменяет редактор общей страницей ошибки. Сбой 5xx/сети сохраняет буфер и отображается внешним JS.
|
||||
|
||||
Для истёкшей сессии UI возвращает HX-Redirect на вход при htmx-запросе и 303 при обычной навигации. Нельзя молча заменить инспектор HTML-формой входа; перед потерей dirty-буфера предложить скачивание исходника. После Save обновлять состояние редактора без обязательного полного перехода страницы, который используется в estimator. Основные операции сохранения доступны обычной формой; интерактивное превью требует JS.
|
||||
|
||||
Небольшой внешний JS-модуль отвечает за буфер, debounce/порядок запросов, защиту от устаревших revision, dirty-состояние, фокус/выделение и postMessage превью. htmx отвечает за отправку форм и подстановку согласованных HTML-фрагментов, в том числе OOB для дерева/статуса при необходимости. Буфер не пересоздаётся при замене инспектора.
|
||||
|
||||
Сохранить текущие лимиты YAML; запретить повтор ключа вместо молчаливой перезаписи SafeLoader. Валидатор исходника использует те же ограничения, что Конструктор. Не допускать изменение Entry.slug или запись по пути из тела формы. Неподдерживаемый ключ не отбрасывается для получения формально успешного сохранения.
|
||||
|
||||
409 не меняет буфер и base_etag. Панель сравнивает пользовательский текст с текущим source; действия — принять серверную версию либо вручную объединить и явно подтвердить использование новой основы. После этого повторный Save снова проходит CAS; третье изменение на сервере вновь даёт 409.
|
||||
|
||||
**Контрольная точка D:** AC-02–AC-05. Проверять Page с вложенными слотами и привязками, а также Entry со схемой коллекции и Markdown.
|
||||
|
||||
## 6. Интерактивное превью — этап E
|
||||
|
||||
### 6.1. Конфигурация и развёртывание
|
||||
|
||||
Добавить проверяемые полные URL-origin `SITE_ADMIN_ORIGIN` и `SITE_PREVIEW_ORIGIN`: схема, host и необязательный порт без пути/query/fragment. Для интерактивного режима оба обязательны и различаются. В production использовать HTTPS; локально допустим HTTP на loopback.
|
||||
|
||||
Локальный пример: admin `http://localhost:8000`, preview `http://localhost:8001`. Production-пример: `https://cms.example.com` и `https://preview.example.com`. Origin включает порт; CORS-доступ к админке для preview не открывать.
|
||||
|
||||
Добавить отдельную фабрику приложения превью, запускаемую вторым uvicorn-процессом или отдельным контейнером того же образа. Она читает только подготовленные артефакты и необходимые параметры проверки токена/эпохи, без подключения admin router. Preview-контейнеру достаточно read-only доступа к каталогу подготовленных снимков и auth epoch; исходники сайта и возможность их записи ему не требуются.
|
||||
|
||||
При неполной конфигурации новые редакторы сохраняют возможность работы и пассивное превью; интерактивный режим показывает недоступность с причиной конфигурации. Для закрытия этапа E требуется рабочая проверка на двух origin.
|
||||
|
||||
### 6.2. Снимок и токен
|
||||
|
||||
В авторизованном основном приложении разобрать буфер, наложить документ на временное представление Registry и отрендерить HTML. Копирование изменённой Page/Entry в канонический каталог для превью запрещено. Подготовить необходимые ассеты и зависимые CSS-ресурсы из workspace в служебном `SITE_STATE_DIR/preview/`.
|
||||
|
||||
Снимок после выдачи URL неизменяем. Он содержит HTML, ассеты, карту разрешённых блоков, revision, срок и служебные данные авторизации. Токен — криптографически случайный идентификатор с подписью; подпись использует отдельный производный ключ, отличный от назначения подписи сессий. Срок — 600 секунд, токен привязан к одному снимку и текущему auth epoch.
|
||||
|
||||
Проверять доступ к HTML и каждому ассету. Токены/исходники не записывать в аудит и диагностические сообщения; журнал доступа к preview должен маскировать токен в URL. Удалять просроченные/незавершённые артефакты при обслуживании основным приложением и при запуске. Ограничить число сохранённых снимков одного документа одной сессии последними 20; удалённый снимок корректно отвечает отказом доступа, редактор может запросить новый.
|
||||
|
||||
### 6.3. Браузерная изоляция
|
||||
|
||||
В iframe использовать sandbox `allow-scripts allow-same-origin` только при гарантированно отдельном origin. Это сохраняет проверяемый origin сообщений; сочетание этих разрешений для same-origin превью запрещено. Формы, popups и top navigation не разрешаются.
|
||||
|
||||
CSP preview: разрешён только служебный скрипт с nonce, собственные подготовленные изображения/шрифты и стили рендера; код сайта не включается в JS-бандл превью. `frame-ancestors` ограничен SITE_ADMIN_ORIGIN, `form-action 'none'`, `base-uri 'none'`, `Referrer-Policy: no-referrer`, `Cache-Control: no-store`, nosniff. `X-Frame-Options: SAMEORIGIN` на cross-origin preview не переносится. Админка разрешает frame-src только собственный origin для пассивного превью и настроенный preview origin.
|
||||
|
||||
### 6.4. Маркировка и протокол
|
||||
|
||||
Добавить явный preview-mode Renderer, по умолчанию выключенный. Идентификатор блока включает область page/layout/display, владельца и локальный block ID. Маркировка не добавляет контейнеров, меняющих layout. Для fixed/display-блока действие выбора возвращает read-only инспектор.
|
||||
|
||||
Минимальные сообщения:
|
||||
|
||||
| Направление | Типы | Назначение |
|
||||
|---|---|---|
|
||||
| Preview → admin | ready, select, viewport | Готовность, выбранный блок, положение/размер viewport |
|
||||
| Admin → preview | highlight, navigate, restore | Выделение, переход по выбору дерева, восстановление позиции |
|
||||
|
||||
Сообщение содержит ID снимка, revision и разрешённый идентификатор блока, если нужен. Обе стороны проверяют origin, source окна, структуру, текущий снимок и допустимый тип. Не использовать wildcard targetOrigin. Предварительный обмен ready инициируется preview в известный admin origin.
|
||||
|
||||
При refresh сохранить viewport через служебный скрипт; после ready нового снимка восстановить положение и выделение. Навигацию к новому месту выполнять для явного выбора/добавления/перемещения, а не на каждое изменение поля. Учитывать reduced motion. Ответ предыдущей revision не заменяет свежую.
|
||||
|
||||
**Контрольная точка E:** AC-06, AC-07 и публичная часть AC-10/FR-17.
|
||||
|
||||
## 7. Проверки и поставка — этап F
|
||||
|
||||
| Уровень | Обязательная проверка |
|
||||
|---|---|
|
||||
| Существующие тесты | Ядро, сборка, routes, auth, редактор, формы, история, конфликты и упаковка |
|
||||
| Сервисы | Общая валидация, один lock без deadlock, CAS двух писателей, отказ без записи/истории, аудит один раз |
|
||||
| Буфер | Page/Entry round-trip, вложенные слоты, refs/query, ошибки YAML/дубли, режимы, сохранение всего документа |
|
||||
| JSON API | Реальные маршруты и Pydantic request/response, OpenAPI, envelope ошибок, недействительные credentials/epoch, проверенный автор, UI использует ASGITransport без обхода API |
|
||||
| HTTP/UI | Реальный FastAPI: cookie/CSRF/Origin, старые и новые маршруты, вложенные ID, HTML отдельно от JSON, 409/422 с вводом, binary assets |
|
||||
| Preview security | Два origin, срок/подпись/эпоха токена, подмена снимка, traversal/symlink, spoofed messages, отсутствие admin/login |
|
||||
| Browser | Настоящий htmx: partial swap, CSRF, 409/422, HX-Redirect и отсутствие API-ключа; dirty-buffer, конфликт, selection/scroll, быстрые правки, истечение токена, недоступность preview |
|
||||
| Visual/accessibility | Заданные ширины, клавиатура, focus, диалоги, статусы, палитры, reduced motion |
|
||||
| Packaging/build | Wheel, запуск из установленного пакета, CLI validate/build и отсутствие служебного preview-кода в публичном HTML |
|
||||
|
||||
Команды существующей проверки после подготовки окружения, из корня репозитория:
|
||||
|
||||
```bash
|
||||
PYTHONPATH=src python -m unittest discover -s tests -v
|
||||
PYTHONPATH=src python -m site_engine.cli validate examples/studio-site
|
||||
PYTHONPATH=src python -m site_engine.cli build examples/studio-site --out /tmp/studio-dist
|
||||
```
|
||||
|
||||
HTTP/browser-проверки добавляются как воспроизводимые dev-команды; файлы тестов и зависимости включить в документацию. Сохранять снимки/логи QA отдельно от канонического сайта. В отчёте различать выполненные, упавшие и недоступные проверки. Результаты выполненной приёмки приведены в [verification.md](verification.md), действующий контракт и запуск — в [runtime.md](runtime.md).
|
||||
|
||||
Этап B можно проверять и принимать до новых редакторов. Этап D принимается после сервисов C; завершение 001 требует E и F. Контентная миграция и миграция БД для 001 не нужны. Перед первым реальным сохранением новой версией редактора сделать резервную копию тестируемого сайта; deployment сначала проверить на его копии.
|
||||
|
||||
## 8. Следующая очередь спецификаций
|
||||
|
||||
| Номер | Направление | Доработка и результат приёмки |
|
||||
|---|---|---|
|
||||
| 002 | Релизы | Разделить build/publish; immutable candidate, manifest/hashes, diff, expected_live под общей блокировкой, безопасные повторы; сбой не меняет live, rollback не затирает workspace |
|
||||
| 003 | Медиа, структура, настройки | Безопасная загрузка, файловые metadata, where-used, changeset с recovery до rename, меню/redirect/site/data/theme; перенос каталога не теряет метаданные |
|
||||
| 004 | Доступы и журнал | Пользователи, разрешения, миграции SQLite, сессии и audit UI; отказ прав проверяется сервисом, а не видимостью кнопки |
|
||||
| 005 | Заявки и outbox | Версия формы, submission+outbox одной транзакцией, Telegram/retry, PII grants; сбой доставки не теряет заявку и rollback сохраняет совместимость |
|
||||
| 006 | MCP | Те же сервисы и ошибки, узкие scopes, TTL/revoke, draft-only; отсутствие publish grant исключает публикацию |
|
||||
|
||||
Это очередность отдельных работ. Их контракты и задачи не считаются реализованными или полностью специфицированными пакетом 001.
|
||||
@@ -0,0 +1,442 @@
|
||||
{
|
||||
"date": "2026-11-12",
|
||||
"unit_tests": 248,
|
||||
"responsive": {
|
||||
"widths": [
|
||||
[
|
||||
"overview",
|
||||
1440
|
||||
],
|
||||
[
|
||||
"overview",
|
||||
1280
|
||||
],
|
||||
[
|
||||
"overview",
|
||||
1024
|
||||
],
|
||||
[
|
||||
"overview",
|
||||
768
|
||||
],
|
||||
[
|
||||
"overview",
|
||||
390
|
||||
],
|
||||
[
|
||||
"overview",
|
||||
360
|
||||
],
|
||||
[
|
||||
"pages",
|
||||
1440
|
||||
],
|
||||
[
|
||||
"pages",
|
||||
1280
|
||||
],
|
||||
[
|
||||
"pages",
|
||||
1024
|
||||
],
|
||||
[
|
||||
"pages",
|
||||
768
|
||||
],
|
||||
[
|
||||
"pages",
|
||||
390
|
||||
],
|
||||
[
|
||||
"pages",
|
||||
360
|
||||
],
|
||||
[
|
||||
"page",
|
||||
1440
|
||||
],
|
||||
[
|
||||
"page",
|
||||
1280
|
||||
],
|
||||
[
|
||||
"page",
|
||||
1024
|
||||
],
|
||||
[
|
||||
"page",
|
||||
768
|
||||
],
|
||||
[
|
||||
"page",
|
||||
390
|
||||
],
|
||||
[
|
||||
"page",
|
||||
360
|
||||
],
|
||||
[
|
||||
"block",
|
||||
1440
|
||||
],
|
||||
[
|
||||
"block",
|
||||
1280
|
||||
],
|
||||
[
|
||||
"block",
|
||||
1024
|
||||
],
|
||||
[
|
||||
"block",
|
||||
768
|
||||
],
|
||||
[
|
||||
"block",
|
||||
390
|
||||
],
|
||||
[
|
||||
"block",
|
||||
360
|
||||
],
|
||||
[
|
||||
"collections",
|
||||
1440
|
||||
],
|
||||
[
|
||||
"collections",
|
||||
1280
|
||||
],
|
||||
[
|
||||
"collections",
|
||||
1024
|
||||
],
|
||||
[
|
||||
"collections",
|
||||
768
|
||||
],
|
||||
[
|
||||
"collections",
|
||||
390
|
||||
],
|
||||
[
|
||||
"collections",
|
||||
360
|
||||
],
|
||||
[
|
||||
"entries",
|
||||
1440
|
||||
],
|
||||
[
|
||||
"entries",
|
||||
1280
|
||||
],
|
||||
[
|
||||
"entries",
|
||||
1024
|
||||
],
|
||||
[
|
||||
"entries",
|
||||
768
|
||||
],
|
||||
[
|
||||
"entries",
|
||||
390
|
||||
],
|
||||
[
|
||||
"entries",
|
||||
360
|
||||
],
|
||||
[
|
||||
"entry",
|
||||
1440
|
||||
],
|
||||
[
|
||||
"entry",
|
||||
1280
|
||||
],
|
||||
[
|
||||
"entry",
|
||||
1024
|
||||
],
|
||||
[
|
||||
"entry",
|
||||
768
|
||||
],
|
||||
[
|
||||
"entry",
|
||||
390
|
||||
],
|
||||
[
|
||||
"entry",
|
||||
360
|
||||
],
|
||||
[
|
||||
"publish",
|
||||
1440
|
||||
],
|
||||
[
|
||||
"publish",
|
||||
1280
|
||||
],
|
||||
[
|
||||
"publish",
|
||||
1024
|
||||
],
|
||||
[
|
||||
"publish",
|
||||
768
|
||||
],
|
||||
[
|
||||
"publish",
|
||||
390
|
||||
],
|
||||
[
|
||||
"publish",
|
||||
360
|
||||
],
|
||||
[
|
||||
"constructor-dark",
|
||||
1440
|
||||
],
|
||||
[
|
||||
"constructor-dark",
|
||||
1280
|
||||
],
|
||||
[
|
||||
"constructor-dark",
|
||||
1024
|
||||
],
|
||||
[
|
||||
"constructor-dark",
|
||||
768
|
||||
],
|
||||
[
|
||||
"constructor-dark",
|
||||
390
|
||||
],
|
||||
[
|
||||
"constructor-dark",
|
||||
360
|
||||
],
|
||||
[
|
||||
"expert-dark",
|
||||
1440
|
||||
],
|
||||
[
|
||||
"expert-dark",
|
||||
1280
|
||||
],
|
||||
[
|
||||
"expert-dark",
|
||||
1024
|
||||
],
|
||||
[
|
||||
"expert-dark",
|
||||
768
|
||||
],
|
||||
[
|
||||
"expert-dark",
|
||||
390
|
||||
],
|
||||
[
|
||||
"expert-dark",
|
||||
360
|
||||
]
|
||||
],
|
||||
"screens": [
|
||||
"overview",
|
||||
"pages",
|
||||
"page",
|
||||
"block",
|
||||
"collections",
|
||||
"entries",
|
||||
"entry",
|
||||
"publish"
|
||||
],
|
||||
"console_errors": []
|
||||
},
|
||||
"editor": {
|
||||
"checks": [
|
||||
"site_scripts_blocked",
|
||||
"feature_hidden_not_rendered",
|
||||
"separate_origin_preview",
|
||||
"fixed_readonly_inspector",
|
||||
"preview_to_tree",
|
||||
"constructor_no_write",
|
||||
"unsaved_preview",
|
||||
"workspace_asset",
|
||||
"tree_scroll_and_viewport_restore",
|
||||
"mode_roundtrip",
|
||||
"explicit_save",
|
||||
"two_tab_conflict_explicit_rebase",
|
||||
"invalid_expert_preserved",
|
||||
"entry_buffer_save",
|
||||
"exact_crlf_source",
|
||||
"stale_preview_rejected",
|
||||
"network_error_preserves_buffer",
|
||||
"message_boundaries_checked",
|
||||
"forged_messages_rejected",
|
||||
"no_content_storage",
|
||||
"publish_public_html",
|
||||
"rollback_preserves_workspace",
|
||||
"ordinary_form_without_js",
|
||||
"session_expiry_download",
|
||||
"internal_credentials_never_in_browser"
|
||||
],
|
||||
"js_errors": []
|
||||
},
|
||||
"stage7": {
|
||||
"errors": 0,
|
||||
"warnings": 0,
|
||||
"built_pages": 7
|
||||
},
|
||||
"wheel": "installed outside checkout, design/ absent; API, templates, static, separate preview passed",
|
||||
"visual_acceptance": {
|
||||
"status": "reopened_after_user_review",
|
||||
"plan": "design-transfer.md",
|
||||
"current_stage": "3_page_builder",
|
||||
"stage_status": "ready_for_user_review",
|
||||
"stage_1": "accepted_by_user",
|
||||
"other_screens": "stages_4_to_5_pending",
|
||||
"browser_report": "/tmp/site-engine-builder-001/report.json",
|
||||
"component_comparisons": 12,
|
||||
"browser_flow_groups": 12,
|
||||
"themes": [
|
||||
"light",
|
||||
"dark"
|
||||
],
|
||||
"widths": [
|
||||
1440,
|
||||
1280,
|
||||
1024,
|
||||
768,
|
||||
390,
|
||||
360
|
||||
],
|
||||
"shell_regression": "/tmp/site-engine-shell-001/report.json",
|
||||
"shell_comparisons": 12,
|
||||
"shell_flows": 6,
|
||||
"editor_regression_checks": 25,
|
||||
"unexpected_browser_errors": [],
|
||||
"stage_2": "accepted_by_user",
|
||||
"expert_component_comparisons": 6,
|
||||
"regression_test_count": 248,
|
||||
"pages_regression": "/tmp/site-engine-pages-001/report.json",
|
||||
"pages_comparisons": 24,
|
||||
"pages_flow_groups": 6
|
||||
},
|
||||
"builder": {
|
||||
"browser": {
|
||||
"name": "chromium",
|
||||
"version": "158.0.8127.18"
|
||||
},
|
||||
"comparisons": 12,
|
||||
"expert_comparisons": 6,
|
||||
"flows": [
|
||||
"pristine_mode_roundtrip_restores_preview_and_toolbar",
|
||||
"invalid_fields_retained_save_stopped_correction_and_real_asset_picker",
|
||||
"auto_apply_focus_caret_preview_and_selection_flush",
|
||||
"device_retained_after_preview_refresh",
|
||||
"binding_picker_preserves_typed_source",
|
||||
"duplicate_selects_new_id_delete_is_memory_only",
|
||||
"catalog_filters_click_inserts_schema_defaults_no_file_write",
|
||||
"drag_drop_real_reordering",
|
||||
"save_flushes_pending_fields_without_publish",
|
||||
"explicit_server_format_does_not_save_file",
|
||||
"expert_source_diff_reset_dialog_focus",
|
||||
"data_map_and_binding_inspector"
|
||||
],
|
||||
"js_errors": [],
|
||||
"artifacts": "/tmp/site-engine-builder-001"
|
||||
},
|
||||
"builder_firefox": {
|
||||
"browser": {
|
||||
"name": "firefox",
|
||||
"version": "142.0.1"
|
||||
},
|
||||
"comparisons": 12,
|
||||
"expert_comparisons": 6,
|
||||
"flows": [
|
||||
"pristine_mode_roundtrip_restores_preview_and_toolbar",
|
||||
"invalid_fields_retained_save_stopped_correction_and_real_asset_picker",
|
||||
"auto_apply_focus_caret_preview_and_selection_flush",
|
||||
"device_retained_after_preview_refresh",
|
||||
"binding_picker_preserves_typed_source",
|
||||
"duplicate_selects_new_id_delete_is_memory_only",
|
||||
"catalog_filters_click_inserts_schema_defaults_no_file_write",
|
||||
"drag_drop_real_reordering",
|
||||
"save_flushes_pending_fields_without_publish",
|
||||
"explicit_server_format_does_not_save_file",
|
||||
"expert_source_diff_reset_dialog_focus",
|
||||
"data_map_and_binding_inspector"
|
||||
],
|
||||
"js_errors": [],
|
||||
"artifacts": "/tmp/site-engine-builder-firefox-001"
|
||||
},
|
||||
"live_style_check": {
|
||||
"direct": true,
|
||||
"server_modified": false,
|
||||
"content_modified": false,
|
||||
"chromium_checks": 42,
|
||||
"firefox_checks": 42,
|
||||
"screenshot_page": "/admin/pages/services/index",
|
||||
"artifacts": "/tmp/cms-live-inspect"
|
||||
},
|
||||
"selection": {
|
||||
"chromium": {
|
||||
"runs": [
|
||||
{
|
||||
"interactive_bridge": false,
|
||||
"selection_posts": 0,
|
||||
"no_file_write": true,
|
||||
"navigation_modals": true,
|
||||
"native_dialogs": [],
|
||||
"errors": []
|
||||
},
|
||||
{
|
||||
"interactive_bridge": true,
|
||||
"selection_posts": 0,
|
||||
"no_file_write": true,
|
||||
"navigation_modals": true,
|
||||
"native_dialogs": [],
|
||||
"errors": []
|
||||
}
|
||||
],
|
||||
"browser": {
|
||||
"name": "chromium",
|
||||
"version": "158.0.8127.18"
|
||||
}
|
||||
},
|
||||
"firefox": {
|
||||
"runs": [
|
||||
{
|
||||
"interactive_bridge": false,
|
||||
"selection_posts": 0,
|
||||
"no_file_write": true,
|
||||
"navigation_modals": true,
|
||||
"native_dialogs": [],
|
||||
"errors": []
|
||||
},
|
||||
{
|
||||
"interactive_bridge": true,
|
||||
"selection_posts": 0,
|
||||
"no_file_write": true,
|
||||
"navigation_modals": true,
|
||||
"native_dialogs": [],
|
||||
"errors": []
|
||||
}
|
||||
],
|
||||
"browser": {
|
||||
"name": "firefox",
|
||||
"version": "142.0.1"
|
||||
}
|
||||
},
|
||||
"artifacts": [
|
||||
"/tmp/site-engine-selection-001",
|
||||
"/tmp/site-engine-selection-firefox-001"
|
||||
],
|
||||
"deployed_to_user_server": false,
|
||||
"fixture": "isolated copy; unreadable working pages/index.md replaced with Git HEAD version; workspace unchanged"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,120 @@
|
||||
# Работающий контракт 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`.
|
||||
@@ -0,0 +1,194 @@
|
||||
# 001 — Antirion Rework: админка и редакторы
|
||||
|
||||
Дата: 2026-11-12. Статус: реализовано и проверено. Контракт и запуск — [runtime.md](runtime.md), результаты приёмки — [verification.md](verification.md). Локальная библиотека htmx поставляется в runtime-пакете.
|
||||
|
||||
Связанные документы: [технический план](plan.md), [задачи](tasks.md).
|
||||
|
||||
## 1. Цель и результат
|
||||
|
||||
Перенести оформление Antirion Rework на работающую админку Site Engine, затем развить редакторы страниц и записей: общий буфер Конструктора и «Эксперта», встроенный инспектор, контролируемое сохранение и интерактивное превью несохранённого документа.
|
||||
|
||||
Результат 001 — интерфейс, работающий с реальными файлами сайта и действующими операциями бэкенда. Сохранённый документ, несохранённый буфер редактора и опубликованный релиз имеют разные явно показанные состояния.
|
||||
|
||||
Реализация выполнена по этапам A–F. Статусы задач и привязка к фактическим проверкам ведутся в `tasks.md`; кандидаты 002–006 остаются следующей очередью.
|
||||
|
||||
## 2. Источники и приоритет
|
||||
|
||||
1. Решения пользователя, перечисленные в разделе 3 этой спецификации.
|
||||
2. Действующие файловые контракты, реализация и тесты репозитория; [журнал архитектурных решений](../../docs/TZ-site-engine-decisions.md).
|
||||
3. HTML/CSS выбранного варианта как эталон оформления и взаимодействий.
|
||||
4. [Документы stage7](../../design/docs/stage7/README.md) как проект развития с поправками из этого пакета.
|
||||
|
||||
Визуальные источники:
|
||||
|
||||
| Экран | Источник |
|
||||
|---|---|
|
||||
| Shell, обзор, страницы | [antirion-rework.html](../../design/antirion-rework.html), `design/assets/antirion-rework.css` |
|
||||
| Конструктор и «Эксперт» страницы | [builder-antirion.html](../../design/builder-antirion.html), `design/assets/builder.css` |
|
||||
| Коллекции и записи | [content-antirion.html](../../design/content-antirion.html), `design/assets/content-editor.css` |
|
||||
| Публикация и история | [publication-antirion.html](../../design/publication-antirion.html), `design/assets/publication.css` |
|
||||
|
||||
JS прототипов описывает UX; его seed-данные, localStorage, browser codec и имитации публикации не являются контрактом бэкенда. При расхождении скриншота и исходного выбранного HTML/CSS приоритет имеет исходник. `design/` сохраняется как визуальный эталон; уточнения stage7 выполняются отдельными задачами.
|
||||
|
||||
## 3. Зафиксированные решения пользователя
|
||||
|
||||
| Решение | Принятый вариант |
|
||||
|---|---|
|
||||
| Первый результат | Оформить все существующие рабочие экраны и выполнить необходимые точечные доработки |
|
||||
| Следующий приоритет | Редакторы страниц и записей |
|
||||
| Доступ | Один администратор через существующую конфигурацию; пользователи и роли позднее |
|
||||
| Сохранение | Только по явной кнопке, без автозаписи файла после изменения поля |
|
||||
| Превью редактора | Интерактивное сразу в этапе развития редакторов, с отдельным origin |
|
||||
| Оформление | Antirion Rework; Rose Graphite и другие концепции не внедряются в 001 |
|
||||
| Взаимодействие UI и бэкенда | htmx + Jinja; UI вызывает единый JSON API FastAPI через серверный клиент, по схеме flexly-estimator |
|
||||
| Транспорт API | В одном приложении `httpx.ASGITransport`, без сетевого соединения; API-ключи не передаются браузеру |
|
||||
|
||||
Технические значения по умолчанию: светлая палитра при первом входе; предпочтение оформления хранится только как UI-настройка; срок токена превью — 10 минут. Изменяемый контент остаётся в файлах сайта.
|
||||
|
||||
## 4. Исходное состояние и расхождения со stage7
|
||||
|
||||
| Область | Уже существует | Доработка в 001 |
|
||||
|---|---|---|
|
||||
| Контент | Page/Entry, YAML front matter, Markdown, коллекции и display | Использовать текущую модель в новом UI |
|
||||
| Композиция | Layout, Fragment, регионы, слоты, fixed, явные ID, `hidden`/`requires` | Дерево и инспектор без уплощения структуры |
|
||||
| Значения | Literal, Binding, LinkRef, Query; разрешение на сервере | Единый буфер и операции Конструктора |
|
||||
| Запись | ContentService: ETag, блокировка сайта, история, атомарная запись | Перенести прикладные операции из HTTP-обработчиков в сервисы |
|
||||
| Валидация | Workspace/release, проверки нового текста до записи | Общая проверка Конструктора и «Эксперта» |
|
||||
| Доступ | Одна учётная запись, cookie, CSRF, ограничение входа, аудит | Сохранить; передавать проверенного автора в новые сервисы |
|
||||
| Конфликт | 409 с текущим ETag, общая страница сообщения | Сохранить ввод, показать версии и дать повторное сохранение после разрешения |
|
||||
| Превью | Рендер сохранённого документа без скриптов | Временный рендер буфера, отдельное приложение и взаимодействие с деревом |
|
||||
| Публикация | Build сразу переключает `current`; сохранённые релизы и rollback | Новое оформление существующих операций |
|
||||
| HTTP-контракт | FastAPI-адаптер, общий dispatch редактора, HTML-ответы; OpenAPI отключён | Явные JSON-маршруты, Pydantic DTO, OpenAPI и HTML-адаптер над серверным API-клиентом |
|
||||
|
||||
Обнаруженные несовместимости stage7, подлежащие документированию и исправлению:
|
||||
|
||||
- Для `collection_list.source` нужен `{query: {collection: ...}}`; объект запроса без `query` не соответствует текущему контракту.
|
||||
- У `richtext` поле Markdown называется `content`, а не `source`.
|
||||
- Блоки используют `hidden` и `requires`; `visibility` не поддерживается.
|
||||
- Пример с `layout: landing` требует собственного layout; текущий сайт-пример содержит `default`.
|
||||
- Поля примера Entry должны соответствовать схеме `services`: `title`, `tagline`, `summary`, `order` и системным полям.
|
||||
- Текущая публикация доступна по `/admin/publish`; `/admin/publication` — предложение stage7.
|
||||
- В HTML-формах используются `csrf` и `etag`; параметр сервиса называется `if_match`.
|
||||
- ETag вычисляется по байтам файла, без добавления версии схемы. Ядро использует dataclass, а не Pydantic.
|
||||
- Наличие моделей SQLAlchemy не означает готовности пользователей, заявок, outbox или истории сборок в БД.
|
||||
- Новые ADR stage7 не должны переопределять существующие ADR с теми же номерами без явного сопоставления и сохранения истории.
|
||||
|
||||
Текущий CSP админки не объявляет `frame-src` при `default-src 'none'`, что препятствует загрузке iframe в браузере. Ссылки `/assets/...` в текущем превью относятся к опубликованному сайту, поэтому не гарантируют отображение ассетов workspace. Обе проблемы входят в первый этап.
|
||||
|
||||
## 5. Объём 001
|
||||
|
||||
### Этап A — рабочие экраны
|
||||
|
||||
Вход/выход, обзор, список и создание страниц, формы страницы и блока, операции с блоками, коллекции, список/создание/редактирование записей, существующее превью, публикация, история релизов, откат, ошибки и пустые состояния.
|
||||
|
||||
Рабочие маршруты и обычные формы сохраняются. Пока новые редакторы не готовы, пользователь сохраняет изменения существующими кнопками форм. На этом этапе оформление публикации соответствует текущей операции «собрать и опубликовать».
|
||||
|
||||
### Этап B — редакторы
|
||||
|
||||
Общие сервисы, единый API-контракт и серверный клиент UI, буфер документа, дерево блоков, встроенный инспектор, режим «Эксперт», сохранение документа целиком, разрешение конфликтов и интерактивное превью.
|
||||
|
||||
Начальный режим страницы — «Конструктор». Для Entry Конструктор редактирует поля её коллекции; дерево блоков относится к Page, а display/fixed-блоки вывода Entry доступны для просмотра. Изменение display-кода из редактора записи не предоставляется.
|
||||
|
||||
### Следующая очередь
|
||||
|
||||
Отдельные кандидаты релиза, diff с live, медиабиблиотека и загрузки, changeset/rename, редактирование меню/настроек, пользователи/RBAC, заявки/outbox и MCP описываются следующими спецификациями. В 001 не добавляются Node-сборка, новая структура всего Python-пакета или миграция канонического контента в БД.
|
||||
|
||||
### Контракт интерфейса
|
||||
|
||||
Принята схема, проверенная по коду `../flexly-estimator/`: `web/client.py`, `web/deps.py`, `web/routes/estimates.py`, `api/routers/estimates.py`. Переносится архитектурный подход; модели пользователей, БД и расчётов estimator не являются зависимостями CMS.
|
||||
|
||||
```text
|
||||
Браузер / htmx → UI-маршрут FastAPI → серверный API-клиент
|
||||
→ JSON API FastAPI → прикладной сервис → файловое хранилище
|
||||
← HTML-страница / фрагменты ← результат API
|
||||
```
|
||||
|
||||
UI-маршруты возвращают страницы или HTML-фрагменты; `/admin/api/v1/` возвращает JSON и не выбирает формат по `HX-Request`. Браузер отправляет формы с cookie и CSRF в UI, не получает внутренние credentials и не вызывает API напрямую. Прямой вызов сервисов из UI допустим только как переходное состояние этапа оформления существующих экранов; к завершению 001 операции контента, проверки, превью и публикации проходят через API-клиент. Проверки сессии и рендер шаблонов остаются ответственностью UI.
|
||||
|
||||
API задаёт единый контракт операций и данных. HTML-фрагменты дополнительно имеют собственный UI-контракт: DOM-цели, правила замены, сообщения об ошибках и revision. Общие сервисы остаются доступными CLI и будущему MCP напрямую.
|
||||
|
||||
## 6. Функциональные требования
|
||||
|
||||
| ID | Требование |
|
||||
|---|---|
|
||||
| FR-01 | Общий shell воспроизводит навигацию, верхнюю панель, рабочую область и адаптивное поведение Antirion Rework. |
|
||||
| FR-02 | Экран показывает реальные данные. Действие без серверной реализации не выдаётся за доступную операцию; недоступное состояние объясняется. |
|
||||
| FR-03 | Списки страниц и записей поддерживают поиск по названию/ID/маршруту и фильтр статуса; список страниц также фильтруется по эффективному layout. Выбор показывает свойства и переход в редактор. |
|
||||
| FR-04 | Существующие формы сохраняют маршруты, имена полей, CSRF, контроль версии и работающие операции. |
|
||||
| FR-05 | Ответы 409/422 сохраняют ввод и показывают причину отказа. |
|
||||
| FR-06 | PageService и EntryService предоставляют чтение, создание, проверку и изменение документа независимо от HTTP-представления. |
|
||||
| FR-07 | Снимок документа содержит идентификатор, путь относительно сайта, исходник, модель, ETag и диагностику. |
|
||||
| FR-08 | Конструктор и «Эксперт» изменяют общий временный буфер. Проверка, преобразование и превью не записывают канонические файлы и историю их версий. |
|
||||
| FR-09 | «Сохранить» записывает весь документ одной операцией с проверкой версии, валидацией, историей и аудитом успешного изменения. |
|
||||
| FR-10 | Конструктор сохраняет регионы, слоты, ID, привязки, ссылки, запросы и Markdown; fixed-блоки layout доступны только для просмотра. |
|
||||
| FR-11 | YAML разбирает сервер. Ошибочный исходник остаётся в редакторе и не заменяет последнюю корректную модель. |
|
||||
| FR-12 | Переключение режимов сохраняет корректные правки. Ошибочный исходник не позволяет молча перейти к другой модели; внутренний переход с несохранёнными изменениями требует подтверждения в интерфейсе. |
|
||||
| FR-13 | При 409 доступны пользовательская и текущая серверная версии. Пользователь вручную объединяет правки либо явно принимает серверную версию; повторное сохранение использует актуальный ETag. |
|
||||
| FR-14 | Превью показывает буфер документа и соответствующие ассеты workspace до сохранения файла. |
|
||||
| FR-15 | Клик в превью выбирает блок без прокрутки; выбор в дереве прокручивает к невидимому блоку; обновление поля сохраняет положение и выделение. |
|
||||
| FR-16 | Интерактивное превью обслуживается отдельным origin, доступно по ограниченному токену и использует проверенные сообщения между окнами. |
|
||||
| FR-17 | Обычная публичная сборка не получает служебных атрибутов/скриптов редактора и сохраняет прежнюю семантику. |
|
||||
| FR-18 | Прикладные операции UI проходят через явный версионированный JSON API FastAPI; запросы, ответы и ошибки описаны Pydantic DTO и OpenAPI. Ядро сохраняет dataclass-модели. |
|
||||
| FR-19 | UI вызывает API через серверный клиент с ASGITransport в том же приложении. Проверенный автор и эпоха сессии сохраняются; API отклоняет анонимные, отозванные и поддельные внутренние credentials. |
|
||||
| FR-20 | htmx получает только HTML от UI. Ответы 409/422 и истечение сессии обрабатываются явно; JS редактора сохраняет буфер, revision и связь с превью при частичных обновлениях. |
|
||||
|
||||
## 7. Модель данных и сохранения
|
||||
|
||||
- Canonical Page — `pages/**/*.md`; Entry — `content/<collection>/*.md`. Идентичность документа определяется проверенным реестром и путём, а не произвольным путём из запроса.
|
||||
- Сохраняются типы значений, `regions`, `slots`, `hidden`, `requires`, `editorial`, Markdown и существующие статусы `draft/published/archived`.
|
||||
- Буфер содержит исходник, ETag сохранённой основы и последнюю корректную модель. Преобразование буфера не обновляет ETag основы.
|
||||
- Конструктор изменяет разобранный документ на сервере. Сериализация сохраняет смысл, порядок блоков и данные, которые текущая политика схемы допускает сохранять; поля не исчезают молча.
|
||||
- «Эксперт» сохраняет проверенный исходный текст. Конструктор использует текущую нормализацию YAML; это описано рядом с исходником, без отдельного предупреждения при правке. Исходник можно скачать. Нативные `alert`/`confirm`/`prompt` и `beforeunload`-диалоги не используются; подтверждения удаления, отмены и внутренних переходов с несохранёнными правками показываются в окнах интерфейса. Перезагрузка/закрытие вкладки не вызывает системного подтверждения.
|
||||
- Неполный draft допустим в пределах базовых требований текущей модели: например, Page по-прежнему требует корректный заголовок, но обязательные бизнес-поля фрагмента могут быть не заполнены.
|
||||
- Алиасы, дублирующиеся ключи YAML, недопустимая вложенность, Jinja-выражения в данных и попытки записи кода отклоняются с диагностикой. Действующие лимиты безопасного парсера сохраняются.
|
||||
- Переименование файла и изменение логического slug Entry через исходник запрещены в 001. Изменение route страницы остаётся существующей возможностью без обещания автоматического создания редиректа.
|
||||
- `etag` формы передаётся как `if_match`; его значение — `sha256:` и SHA-256 текущих байтов файла. После успешного сохранения клиент получает новый ETag.
|
||||
- При 409 новый ETag не подставляется в повторную отправку автоматически. Диалог конфликта сохраняет обе версии и требует явного действия пользователя.
|
||||
- Несохранённый исходник хранится в памяти вкладки; UI предлагает скачать его перед отказом от правок. Восстановление буфера после перезагрузки не обещается. LocalStorage допускается для темы/свёрнутой навигации, но не для канонического контента.
|
||||
- Аудит содержит автора, тип операции и идентификатор объекта; содержимое исходника, токены и секреты не записываются.
|
||||
|
||||
## 8. Интерактивное превью
|
||||
|
||||
Превью — временный производный результат. Его создание может писать артефакты в служебное состояние, но не изменяет canonical Page/Entry, историю файлов и live.
|
||||
|
||||
- Отдельные явно заданные origin админки и превью; wildcard и совпадающие origin для интерактивного режима запрещены.
|
||||
- Отдельное приложение превью не имеет login/admin/API-маршрутов и не использует админскую cookie для авторизации.
|
||||
- Токен открывает один подготовленный снимок HTML и его ассеты, действует 10 минут и проверяется на каждом запросе. Выход администратора отзывает доступ через эпоху сессий. Токен одного снимка не открывает другой.
|
||||
- Превью содержит только разрешённый служебный скрипт взаимодействия. Скрипты сайта и произвольный исходник не получают права исполнения.
|
||||
- `postMessage` проверяет origin, source, тип сообщения, текущий снимок и существование блока. Отправка направляется точному origin.
|
||||
- Fixed/layout, display и редактируемые блоки имеют различимые области идентификаторов; совпадение локального ID не даёт возможности менять fixed-блок.
|
||||
- Скрытый блок или блок с выключенным feature остаётся в дереве с пояснением; превью не показывает его как публично видимый. Выбор такого блока не вызывает ошибочную прокрутку.
|
||||
- Удаление выбранного блока сбрасывает выбор на существующий соседний блок или свойства документа. Ответ старого запроса превью не заменяет более новое состояние.
|
||||
- Истечение токена требует повторной генерации из авторизованного редактора. Недоступность приложения превью сохраняет буфер и возможность редактировать/сохранить документ.
|
||||
|
||||
## 9. Качество и совместимость
|
||||
|
||||
| ID | Требование |
|
||||
|---|---|
|
||||
| NFR-01 | Существующие URL, форматы файлов, основные команды CLI и поведение публикации/отката сохраняются. |
|
||||
| NFR-02 | Autoescape, санитайзер Markdown, safe paths, CSRF и защитные cookie сохраняются. CSP разрешает только необходимые ресурсы. |
|
||||
| NFR-03 | Проверяются ширины 1440, 1280, 1024, 768, 390 и 360 px; таблицы могут иметь внутреннюю прокрутку, весь экран не переполняется. |
|
||||
| NFR-04 | Управление доступно с клавиатуры, фокус видим, у полей и iframe есть подписи. Модальные окна удерживают фокус и возвращают его инициатору; учитывается reduced motion. |
|
||||
| NFR-05 | Установленный wheel содержит шаблоны, статику админки и служебные ресурсы превью. Работа не зависит от наличия каталога design на сервере. |
|
||||
| NFR-06 | Канонические файлы и live меняются только соответствующими явными операциями; ответы ошибок не показывают трассировки и секреты. |
|
||||
|
||||
Для FR-18–FR-20 обязательны локальная закреплённая версия htmx с источником, лицензией и SHA-256, запрет eval/скриптов из фрагментов и запросов htmx к сторонним origin. OpenAPI выгружается воспроизводимо для проверки контракта; HTTP-доступ к схеме и документации требует административной авторизации. Анонимные Swagger/OpenAPI не включаются.
|
||||
|
||||
## 10. Приёмочные сценарии
|
||||
|
||||
| ID | Проверка и ожидаемый результат |
|
||||
|---|---|
|
||||
| AC-01 | Вход → обзор → создание/редактирование Page/Block/Entry → reload: существующие операции работают в новом оформлении. |
|
||||
| AC-02 | Конструктор → «Эксперт» → Конструктор сохраняет ID, вложенность, привязки и Markdown; простой переход без правок не переформатирует исходник. |
|
||||
| AC-03 | Изменение поля/блока, validate и preview оставляют байты canonical-файлов, историю и current прежними; «Сохранить» фиксирует все правки документа. |
|
||||
| AC-04 | Ошибочный YAML, повтор ключа, неподдерживаемый блок или попытка изменить fixed не записывают файл; введённый текст остаётся в UI. |
|
||||
| AC-05 | Две вкладки читают один ETag; первая сохраняет, вторая получает 409 с сохранённым вводом и текущей версией; после ручного объединения сохраняет с новым ETag. |
|
||||
| AC-06 | Превью выбирает нужный вложенный/fixed-блок, соблюдает правила прокрутки и отображает последнюю версию буфера, включая ассеты workspace. |
|
||||
| AC-07 | Неверный/истёкший/отозванный токен, чужой снимок, поддельные origin/source/сообщения и traversal отклоняются; приложение превью не открывает admin/login. |
|
||||
| AC-08 | Успешная публикация переключает current; неудачная сохраняет live; откат сохраняет workspace. В UI отсутствует имитация ещё не реализованного кандидата. |
|
||||
| AC-09 | Основные экраны, ошибки, диалоги и редакторы проходят адаптивную и клавиатурную проверку на заданных размерах. |
|
||||
| AC-10 | Wheel содержит runtime-ресурсы; обычная сборка сайта проходит и не содержит служебной разметки/скриптов preview-режима. |
|
||||
| AC-11 | Реальный FastAPI проверяет запросы и ответы JSON API, единый формат ошибок и OpenAPI. HTML- и API-маршруты не смешивают форматы; UI вызывает API через ASGITransport с проверенным автором. Ошибки/отказ API отражаются в UI без обхода через прямую запись. |
|
||||
| AC-12 | Настоящий htmx загружает фрагмент, отправляет форму с CSRF, показывает 409/422, обрабатывает истечение сессии и согласованные обновления без потери буфера. Поддельные внутренние credentials и прежняя эпоха после logout не дают API-доступ; API-токенов нет в HTML и браузерных запросах. |
|
||||
|
||||
Готовность требует исполнения сценариев через реальный FastAPI и браузер. Тесты обработчиков и QA прототипа не заменяют эту проверку.
|
||||
@@ -0,0 +1,156 @@
|
||||
# Задачи 001 — Antirion Rework
|
||||
|
||||
Дата: 2026-11-12. Статус: функциональная реализация проверена; задачи переноса и визуальной приёмки открыты повторно после замечаний пользователя. [Поэтапная проверка дизайна](design-transfer.md). Результаты и ограничения — [verification.md](verification.md), воспроизводимый контракт и запуск — [runtime.md](runtime.md).
|
||||
|
||||
Основание: [спецификация](spec.md) и [технический план](plan.md). Создание этих документов не закрывает перечисленные задачи разработки. Новые ID T037–T041 добавлены без перенумерации прежних задач; порядок выполнения задаётся этапами и зависимостями.
|
||||
|
||||
## Правила выполнения
|
||||
|
||||
- Выполнять этапы A → B → C → D → E → F с контрольными точками ниже.
|
||||
- Задача закрывается после изменения, относящейся к нему проверки и записи результата; наличие кода без проверки не равно завершению.
|
||||
- Существующие проверки запускаются по характеру изменения; чистые CSS-правки проверяются сборкой и браузером, а не тестами, повторяющими CSS.
|
||||
- Несвязанные пользовательские файлы и прототипы сохраняются. Рабочие данные и секреты не используются как место реализации.
|
||||
- Результаты реально выполненных проверок записываются при реализации. Не отмечать задачи выполненными по результатам чтения документации или QA mock-прототипа.
|
||||
|
||||
## A. Подготовка и соответствие документации
|
||||
|
||||
Зависимость: нет. Выход — проверяемая исходная точка для оформления и сервисов.
|
||||
|
||||
- [x] **T001** Сопоставить stage7 текущему коду и исправить несовместимые примеры/контракты.
|
||||
- Матрица охватывает файловую модель, query/content, visibility, layout/schema Entry, маршруты, csrf/etag, preview, release, DB/MCP-заготовки. Примеры проверены в временной копии сайта.
|
||||
- [x] **T002** Сопоставить ADR и зафиксировать границы 001 в документации stage7.
|
||||
- История сохранена; реализованные решения отделены от предложений; новые кандидаты/медиа/RBAC/заявки/MCP отнесены к следующей очереди.
|
||||
- [x] **T003** Подготовить изолированное окружение и выполнить исходные тесты, validate и build.
|
||||
- Зафиксированы команды, результаты и реальные ограничения окружения. Включены server/dev-зависимости; подготовлен способ запускать HTTP/browser QA.
|
||||
- [ ] **T004** Зафиксировать визуальные эталоны рабочих экранов и тестовые состояния.
|
||||
- Использованы выбранные HTML/CSS; сохранены проверки desktop/mobile, пустых состояний, ошибок, формы входа и данных сайта-примера.
|
||||
- [x] **T041** Поставить локальный htmx из flexly-estimator и проверить существующее подключение.
|
||||
- Побайтовая копия 2.0.11, SHA-256 совпадает с источником и VENDOR.md; лицензия/источник записаны, статическая раздача и wheel проверены. Это не реализация API или нового редактора.
|
||||
- Проверено 2026-11-12: `node --check`; 62 теста обработчиков/редактора и 2 теста упаковки, включая сборку wheel; HTTP smoke через настоящий FastAPI/TestClient (файл/MIME/nosniff, вход, hx-boost-разметка, CSRF/422, конфигурация и allowlist).
|
||||
- Тесты обработчиков/редактора запускались на временной копии примера без `.engine`: исходный запуск упёрся в недоступный рабочий `.engine/audit.jsonl`. Рабочие данные и права не менялись. На момент подготовки T041 исполнение htmx в браузере ещё не проверялось; итоговые T023/T032 закрыты реальными Chromium-сценариями, см. verification.md.
|
||||
|
||||
## B. Оформление рабочих экранов
|
||||
|
||||
Зависимость: T001–T004. Этап завершается до перехода к новому общему буферу.
|
||||
|
||||
- [ ] **T005** Перенести стили, токены и ресурсы Antirion Rework в runtime-пакет.
|
||||
- Shell/editor/publication не конфликтуют; светлая палитра по умолчанию и тёмная палитра Antirion согласованы; работа не зависит от `design/` на сервере.
|
||||
- [ ] **T006** Реализовать общий shell, адаптивную навигацию, диалоги и UI-настройки.
|
||||
- Клавиатура, фокус, открытие/закрытие мобильного меню, Esc, возврат фокуса; localStorage содержит только настройки интерфейса.
|
||||
- [ ] **T007** Перенести вход, обзор, сообщения и пустые состояния.
|
||||
- Реальные статусы сайта/релиза, ошибки входа и недоступного сайта; сохранены текущие защитные заголовки и cookie.
|
||||
- [ ] **T008** Перенести списки Page/Entry, поиск, фильтры и просмотр свойств.
|
||||
- Проверены q/status/layout, вложенные ID, пустая выдача, выбранный объект и неизвестный ID; представлены реальные file/layout/count/current.
|
||||
- [ ] **T009** Перенести формы Page, Block и Entry и существующие операции блоков.
|
||||
- Сохранены имена полей и URL, создание draft, слоты/привязки, добавление/порядок/видимость/удаление и семантика формы без изменений.
|
||||
- [ ] **T010** Перенести существующие публикацию, историю и откат с подтверждениями.
|
||||
- В UI отражены реальные build+publish и rollback; кандидат/diff не имитируются; ошибки сборки и отсутствие релизов отображаются.
|
||||
- [x] **T011** Исправить CSP iframe и защищённые ассеты workspace.
|
||||
- Браузер загружает пассивное превью; изображения и зависимые ресурсы берутся из workspace; traversal/выход по symlink отклоняется; binary MIME корректен.
|
||||
- [x] **T012** Сохранить пользовательские значения при 409/422 на существующих формах.
|
||||
- Ошибка не теряет ввод, не выдаёт новый ETag за согласие перезаписать файл и не запускает повторный POST автоматически.
|
||||
- [ ] **T013** Принять оформление рабочих экранов по AC-01, AC-08, AC-09 и упаковочной части AC-10.
|
||||
- Выполнены подходящие существующие тесты, реальные HTTP/browser-сценарии, адаптивная проверка и проверка wheel со статикой/шаблонами.
|
||||
|
||||
**Контрольная точка B:** существующие операции работают в новом оформлении. Новый буфер и интерактивное превью ещё не считаются выполненными.
|
||||
|
||||
## C. Общие сервисы и файловая запись
|
||||
|
||||
Зависимость: T013. Новые сервисы сохраняют действующие файловые контракты.
|
||||
|
||||
- [x] **T014** Определить снимки документов, результаты буфера/сохранения/конфликта и контекст автора.
|
||||
- Использованы dataclass/Report; сервис не зависит от Request/Jinja, автор получен из проверенной сессии.
|
||||
- [x] **T015** Реализовать обновление файла с одним владельцем SiteLock.
|
||||
- CAS и актуальная validation находятся внутри цикла обновления; нет вложенного lock/deadlock; отказ не создаёт историю или частичный файл; два писателя проверены.
|
||||
- [x] **T016** Выделить PageService и перевести операции Page/Block на него.
|
||||
- Чтение, создание, metadata, props, add/delete/toggle/move используют общий validation/save; аудит без дублирования, старые маршруты совместимы.
|
||||
- [x] **T017** Выделить EntryService и перевести операции Entry на него.
|
||||
- Поля коллекции, статус и Markdown проходят общую проверку; идентичность записи и запрет записи кода сохраняются.
|
||||
- [x] **T037** Реализовать основу версионированного JSON API FastAPI и схемы контракта.
|
||||
- Зависимость: T014–T017. Явные маршруты `/admin/api/v1/`, Pydantic request/response и error envelope, текущее чтение/создание/изменение документов, пассивное превью и publish/rollback; защищённые OpenAPI/docs и выгрузка схемы. DTO буфера определены; операции развиваются в T019/T020, интерактивное превью — в T026. Dataclass-ядро сохранено.
|
||||
- [x] **T038** Реализовать серверный API-клиент UI и внутреннюю авторизацию.
|
||||
- Зависимость: T037. httpx включён в server extra; ASGITransport вызывает то же приложение с общим lifespan, синхронные операции не блокируют event loop; credentials связаны с автором/сессией/epoch и не попадают в браузер или логи.
|
||||
- [x] **T039** Перевести существующие UI-операции на единый API-клиент.
|
||||
- Зависимость: T038. Списки/обзор, Page/Block/Entry, validation, превью и publish/rollback используют контракт API; HTML-маршруты сохраняются, ошибки API не обходятся прямым вызовом сервисов. Вход/сессия/статика остаются в UI.
|
||||
- [x] **T040** Проверить API-контракт и реальное прохождение UI → API по AC-11.
|
||||
- Зависимость: T037–T039. Реальный FastAPI проверяет реализованные операции: request/response/OpenAPI, единые 401/403/404/409/422, авторство, эпоху/logout, разграничение JSON/HTML и отсутствие обхода при ошибке API. Проверки расширяются в T024/T030/T032; полная приёмка AC-11 выполняется после редакторов/превью.
|
||||
|
||||
## D. Буфер, Конструктор и «Эксперт»
|
||||
|
||||
Зависимость: T014–T017, T037–T040. Изменение буфера не означает сохранение файла.
|
||||
|
||||
- [x] **T018** Отклонять повторяющиеся ключи YAML и проверить безопасный разбор.
|
||||
- Покрыты вложенные дубли, aliases, лимиты, запрещённые выражения и корректный текущий сайт; ошибка не приводит к потере текста.
|
||||
- [x] **T019** Реализовать получение, проверку и transform буфера без записи.
|
||||
- HTML-endpoints под `/admin/editor/` вызывают JSON API через клиент; проверены сессия/Origin/CSRF на UI, credentials на API, вложенные ID, схемы, типизированные действия и прежний ETag основы.
|
||||
- [x] **T020** Реализовать явное сохранение полного исходника с ETag, историей и аудитом.
|
||||
- API save и HTML-адаптер используют общий контракт; Page/Entry сохраняются одной операцией; slug/path/fixed нельзя изменить в обход правил; клиент получает сохранённый source и новый ETag.
|
||||
- [x] **T021** Реализовать общий буфер Конструктора и «Эксперта», дерево и встроенный инспектор.
|
||||
- Constructor выбран по умолчанию, Entry использует схему коллекции, layout/display показываются read-only, неприменимый source остаётся в редакторе.
|
||||
- [x] **T022** Реализовать подтверждения внутренних переходов с несохранёнными правками через окна интерфейса, скачивание исходника и разрешение 409. Нативные alert/confirm/prompt и beforeunload-диалоги не использовать.
|
||||
- Переход режима/документа и уход не отбрасывают правки; две версии доступны; принятие новой основы явно; повторный конфликт обрабатывается.
|
||||
- [x] **T023** Настроить htmx и обработку согласованных частичных ответов редактора.
|
||||
- Локальная библиотека поставлена в T041; нет inline-выражений/eval/скриптов из ответов и сторонних запросов; 409/422 направляются в нужный регион, не очищают буфер; устаревшие revision игнорируются; истечение сессии и полная форма Save работают по AC-12.
|
||||
- [x] **T024** Принять сервисы и редакторы по AC-02–AC-05.
|
||||
- Проверены semantic round-trip, сохранение исходника без правок, вложенные слоты, refs/query, Entry, отсутствие файловых изменений до Save и реальный CAS двух вкладок.
|
||||
|
||||
**Контрольная точка D:** работают общий буфер и ручное сохранение; подготовка интерактивного превью не подменяется mock-iframe.
|
||||
|
||||
## E. Интерактивное превью
|
||||
|
||||
Зависимость: T019–T024. Приёмка требует двух действительных origin.
|
||||
|
||||
- [x] **T025** Добавить SITE_ADMIN_ORIGIN/SITE_PREVIEW_ORIGIN и отдельное приложение превью.
|
||||
- Валидируются разные точные origin; приложение не имеет admin/login; описан запуск вторым процессом/контейнером, пассивный режим сохранён при отсутствии конфигурации.
|
||||
- [x] **T026** Реализовать временный рендер буфера, ассеты, токены и очистку.
|
||||
- API preview и HTML-адаптер возвращают PreviewResult; 600 секунд, подпись с отдельным назначением ключа, привязка к снимку/epoch, проверка каждого ресурса, последние 20 снимков документа/сессии, очистка и маскирование токенов в логах.
|
||||
- [x] **T027** Добавить preview-маркировку Renderer с различимыми областями блоков.
|
||||
- Page/layout/display и вложенные блоки адресуются однозначно; fixed read-only; лишние контейнеры не меняют layout; обычный рендер не маркируется.
|
||||
- [x] **T028** Реализовать служебный скрипт и двусторонний протокол сообщений.
|
||||
- Точные origin/source, разрешённые типы, snapshot/revision и блоки проверяются; CSP/sandbox допускают только нужное поведение; wildcard отсутствует.
|
||||
- [x] **T029** Связать превью с деревом и инспектором, сохранить viewport и порядок обновлений.
|
||||
- Клик preview без scroll, дерево скроллит только при необходимости, изменение props не сбрасывает позицию; hidden/fixed/deleted и быстрые последовательные правки обработаны.
|
||||
- [x] **T030** Выполнить security-проверки превью по AC-07.
|
||||
- Проверены неверный/истёкший/отозванный токен, чужой снимок, logout, traversal/symlink, поддельные сообщения, запрет admin/login и исполнения скриптов сайта.
|
||||
- [x] **T031** Проверить живое превью буфера и неизменность публичной сборки по AC-06/AC-10.
|
||||
- Используется новый ассет workspace без публикации; canonical/current не меняются; истечение токена/сбой сервиса не теряет буфер; обычный HTML не содержит bridge/служебных атрибутов.
|
||||
|
||||
## F. Сквозная приёмка и документация
|
||||
|
||||
Зависимость: T005–T031, T037–T041.
|
||||
|
||||
- [x] **T032** Выполнить сквозные сценарии через реальное FastAPI и браузер.
|
||||
- Вход/истечение сессии, Page/Entry, режимы, validate/Save/409/422, preview, publish/rollback; настоящий htmx и ASGI-клиент, AC-11/AC-12; результат приложен отдельно от тестов подставного FastAPI.
|
||||
- [ ] **T033** Проверить размеры, клавиатуру, фокус, ошибки и reduced motion.
|
||||
- 1440/1280/1024/768/390/360 px, палитры Antirion, мобильное меню, таблицы, диалоги, инспектор и отсутствие переполнения страницы.
|
||||
- [x] **T034** Выполнить регрессию, validate/build и проверку установленного wheel.
|
||||
- Установленный пакет содержит все runtime-ресурсы, работает без `design/`, сохраняет существующие гарантии CLI/core/build/security.
|
||||
- [x] **T035** Обновить README, AGENTS.md, stage7 и инструкцию запуска превью.
|
||||
- Документация соответствует фактическому состоянию, описывает env, два origin, состояние/очистку токенов, backup тестового сайта и воспроизводимый локальный/Docker-запуск.
|
||||
- [ ] **T036** Сопоставить результаты с FR-01–FR-20, NFR-01–NFR-06 и AC-01–AC-12.
|
||||
- Приложены результаты и ограничения; незавершённые пункты остаются открытыми; 001 не объявляется готовой по одному визуальному сравнению.
|
||||
|
||||
## Матрица требований и задач
|
||||
|
||||
| Требования | Основные задачи | Приёмка |
|
||||
|---|---|---|
|
||||
| FR-01–FR-03 | T004–T008, T033 | AC-01, AC-09 |
|
||||
| FR-04–FR-05 | T009–T013, T022–T023 | AC-01, AC-04, AC-05 |
|
||||
| FR-06–FR-07 | T014–T017, T019–T020 | AC-02–AC-05 |
|
||||
| FR-08–FR-10 | T015–T024 | AC-02, AC-03, AC-05 |
|
||||
| FR-11–FR-13 | T018–T024 | AC-02, AC-04, AC-05 |
|
||||
| FR-14–FR-16 | T025–T031 | AC-03, AC-06, AC-07 |
|
||||
| FR-17 | T027, T031, T034 | AC-10 |
|
||||
| FR-18–FR-19 | T014–T017, T037–T040, T032 | AC-11, AC-12 |
|
||||
| FR-20 | T019–T023, T032, T041 | AC-03–AC-05, AC-12 |
|
||||
| NFR-01–NFR-02 | T003, T009–T020, T025–T030, T032, T034 | AC-01, AC-07, AC-08 |
|
||||
| NFR-03–NFR-04 | T004–T006, T021–T023, T029, T033 | AC-09 |
|
||||
| NFR-05–NFR-06 | T011–T015, T020, T026, T031, T034–T036 | AC-03, AC-05, AC-08, AC-10 |
|
||||
|
||||
Релизы, медиа/настройки, доступы, заявки и MCP следующей очереди не входят в список выполнения 001. Их порядок и зависимости перечислены в конце `plan.md`.
|
||||
|
||||
## Прежняя функциональная проверка (визуальная приёмка открыта повторно)
|
||||
|
||||
2026-11-12: 239 тестов; настоящий FastAPI/ASGITransport; 25 сценариев Chromium на двух origin; 8 экранов и 60 проверок ширины, обе темы, клавиатура и reduced motion; validate/build примеров stage7 — 0 ошибок/0 предупреждений, 7 страниц; wheel установлен вне checkout без design/. Подробная матрица требований, команды и ограничения — [verification.md](verification.md); машиночитаемые результаты — [qa-results.json](qa-results.json).
|
||||
|
||||
Этапы 1–2 приняты пользователем. Этап 3 (Конструктор/Эксперт Page) подготовлен к проверке: исходные компоненты builder-antirion, реальные дерево/инспектор/каталог/источники, автоматическое применение полей и явное сохранение, дублирование поддерева, перетаскивание, 422 без потери ввода, сравнение/отмена/форматирование исходника. 247 тестов; Chromium — 12 сравнений Конструктора и 6 «Эксперта», 11 групп сценариев; регрессия editor/shell/pages, CLI и установленного wheel — OK. Подробности — [design-transfer.md](design-transfer.md). Этапы 4–5 и общая визуальная приёмка T033/T036 остаются открытыми; переход — после проверки пользователя.
|
||||
@@ -0,0 +1,95 @@
|
||||
# Приёмка 001 — 2026-11-12
|
||||
|
||||
**Визуальная приёмка открыта повторно.** Пользователь обнаружил расхождения с исходной вёрсткой и поведением дизайна. Прежние функциональные проверки ниже не доказывают корректность переноса макетов. Повторный перенос идёт по [отдельным этапам с проверкой пользователя](design-transfer.md): каркас, обзор и страницы приняты пользователем; этап 3 (Конструктор/Эксперт Page) подготовлен к проверке. Контент/Entry и публикация ожидают этапов 4–5.
|
||||
|
||||
Текущая регрессия этапа 3: **248 тестов OK**; после исправления CSS-совместимости Chromium и Firefox 142 — в каждом **12 наборов сверки Конструктора + 6 «Эксперта» с оригиналом**, 12 групп реальных сценариев конструктора; Chromium — 25 сквозных сценариев редактора на двух origin. Shell/pages повторно проверены — 12/24 набора и 6/6 групп. Предыдущая общая проверка — 8 экранов/60 ширин; установленный wheel работает без `design/`, CLI validate/build на временной копии studio-site — 0 ошибок/предупреждений, 7 страниц. Подробности и границы сравнения — в разделе этапа 3 [design-transfer.md](design-transfer.md). Ниже сохранены свидетельства предыдущей функциональной реализации, а не статус визуальной приёмки всех экранов.
|
||||
|
||||
Ниже сохранены результаты функциональной реализации A–F. Действующий контракт и инструкции запуска: [runtime.md](runtime.md). Машиночитаемые результаты: [qa-results.json](qa-results.json), JSON-контракт: [openapi.json](openapi.json).
|
||||
|
||||
## Выполненные проверки
|
||||
|
||||
| Проверка | Результат |
|
||||
|---|---|
|
||||
| Исходная точка | 206 тестов, validate/build чистого studio-site; 7 страниц |
|
||||
| Полная регрессия | **239 тестов, OK**, без пропусков |
|
||||
| JSON API после объявления security scheme | Дополнительно 11 тестов `test_api_001.py`, OK |
|
||||
| Настоящий Chromium, обычные экраны | **8 экранов, 60 проверок ширины**, без JS-исключений и переполнения страницы |
|
||||
| Настоящий Chromium, отдельные HTTP-origin admin/preview | **25 сквозных сценариев**, без JS-исключений |
|
||||
| Исправленные примеры stage7 | Page и Entry подставлены в изолированную копию: validate — **0 ошибок, 0 предупреждений**, build — **7 страниц** |
|
||||
| Установленный wheel | Собран и установлен в отдельный каталог вне checkout; `design/` отсутствует; реальные FastAPI, HTML, API, статика и отдельное preview-приложение работают |
|
||||
| Статика и качество кода | `node --check` admin/editor/htmx; новые Python-модули/сценарии прошли Ruff; `git diff --check` |
|
||||
| Публичная сборка | Сохранена семантика build/publish/rollback; нет `data-preview-*` и bridge в публичном HTML |
|
||||
|
||||
Все функциональные записи и публикации выполнялись на временных копиях. Рабочие `.env`, `.engine`, `dist`, права файлов и секреты примера не менялись. Проверка дефекта стилей дополнительно выполнена прямо на сервере пользователя без прокси: исправленные CSS/JS подменялись только в тестовой вкладке, серверная сборка и контент не обновлялись. В тестовом helper `.engine` исключён при копировании: рабочий `audit.jsonl` имеет ограниченные права. Зависимости server/dev и браузеры установлены в отдельном окружении.
|
||||
|
||||
## Покрытие требований
|
||||
|
||||
| Требования | Реализация и свидетельство |
|
||||
|---|---|
|
||||
| FR-01, FR-02 | Runtime Antirion CSS/shell, реальные четыре раздела, будущие действия недоступны с объяснением; скриншоты 8 экранов |
|
||||
| FR-03 | q/status/layout, поиск Page/Entry и свойства; действующие UI и API-фильтры, тесты редактора/API и пустая выдача в Chromium |
|
||||
| FR-04, FR-05 | Старые URL/form fields поддерживаются адаптером к API; 409 сохраняет версии, 422 — источник/поля; реальные обычные формы и htmx |
|
||||
| FR-06, FR-07 | PageService/EntryService, dataclass Snapshot/Context и Report; `test_documents.py`, типизированные Snapshot DTO |
|
||||
| FR-08, FR-09 | Единый буфер и явный Save; отсутствие записи/истории до Save, один lock, CAS двух писателей, текущая схема, атомарная запись и однократный аудит |
|
||||
| FR-10 | Регионы/слоты/ID, ссылки/привязки/query и Markdown сохраняются; вложенные слоты и отказ циклу проверены; layout/display доступны в read-only инспекторе |
|
||||
| FR-11, FR-12 | Серверный YAML, вложенные дубли/aliases/лимиты отклоняются; ошибочный текст и последнее корректное дерево сохраняются; режимы и предупреждения dirty |
|
||||
| FR-13 | Две вкладки: Save → 409 → сравнение → явное принятие основы → отдельный Save; история и чужие данные сохраняются |
|
||||
| FR-14, FR-15 | Несохранённые props и новый SVG workspace отображаются до Save; preview→tree, tree→preview, скрытые блоки и восстановление viewport после загрузки ресурсов |
|
||||
| FR-16 | Второй uvicorn и origin, nonce CSP, подписанный TTL/epoch token для каждого HTML/asset; проверки origin/source/snapshot/revision/owner/id |
|
||||
| FR-17 | Preview-mode Renderer выключен по умолчанию; обычный build не получает маркеры и bridge, проверено тестом и браузерной публикацией |
|
||||
| FR-18, FR-19 | JSON/Pydantic/OpenAPI, request-scoped ASGI-клиент; cookie/forged/expired/old epoch отвергаются; UI не обходит отказ API; credentials отсутствуют в HTML и browser requests |
|
||||
| FR-20 | Настоящий локальный htmx, согласованные partials/revision, 409/422/401, сетевой отказ и устаревшее превью; текст сохраняется и скачивается |
|
||||
| NFR-01, NFR-02 | Прежние 206 тестов, старые формы/CLI; autoescape, санитайзер, cookie/CSRF/CSP и пути сохранены; traversal и запись кода через symlink отвергаются |
|
||||
| NFR-03 | 1440/1280/1024/768/390/360 px: 8 основных экранов + Constructor/Expert в тёмной теме; внутренний scroll таблиц, без overflow всей страницы |
|
||||
| NFR-04 | Tab/Shift+Tab мобильного меню и диалога, Esc и возврат фокуса, подписи, iframe titles; браузер редактора запущен с reduced motion |
|
||||
| NFR-05 | Реально установленный wheel запускает интерфейс и bridge без design/; package-data покрывает все runtime-файлы |
|
||||
| NFR-06 | CAS/validation/history/save и preview snapshots разделены; неудачная сборка не меняет live, rollback не меняет workspace; ошибки без трассировок/секретов |
|
||||
|
||||
## Критерии приёмки
|
||||
|
||||
| Критерий | Свидетельство |
|
||||
|---|---|
|
||||
| AC-01 | Вход, обзор, Page/Block/Entry, старые маршруты и новое оформление: regression + real HTTP + Chromium |
|
||||
| AC-02 | Семантический round-trip существующих форм, вложенные слоты, режимы и точный Save CRLF без изменений |
|
||||
| AC-03 | Байты canonical/история/current неизменны до Save; workspace-ассет и buffer preview проверены |
|
||||
| AC-04 | Дубли/aliases/depth, неверные типы/фрагменты/регионы и fixed не сохраняются; исходник/инспектор остаются доступны |
|
||||
| AC-05 | Настоящие две вкладки, сохранение ввода при 409, обе версии и явный rebase |
|
||||
| AC-06 | Preview-select и read-only fixed, однозначные scope/owner/id и вложенные маркеры; tree scroll, viewport restore и последние unsaved props |
|
||||
| AC-07 | Неверная подпись, expiry, epoch/logout, чужой snapshot, каждый asset, symlink/traversal, поддельные сообщения; preview app возвращает 404 для admin/login/API |
|
||||
| AC-08 | Publish/rollback в настоящем браузере; отказ сборки сохраняет live по регрессионным тестам; candidate pipeline не имитируется |
|
||||
| AC-09 | Responsive 60 проверок; обе темы, мобильная навигация, клавиатура, диалог/фокус и reduced motion |
|
||||
| AC-10 | Wheel вне checkout без design/, CLI build и отсутствие служебной разметки в публичной сборке |
|
||||
| AC-11 | Реальный FastAPI и ASGITransport, Pydantic DTO/actions, OpenAPI security schema, errors/201/401/403/404/409/422/413, доказательство прохождения UI через API |
|
||||
| AC-12 | Настоящий htmx: partials, 409/422/401, source download при истечении сессии, отказ сети, stale preview; отдельная обычная форма Save без JS |
|
||||
|
||||
## Воспроизведение
|
||||
|
||||
Из корня репозитория после установки `.[server,dev]` и `python -m playwright install chromium`:
|
||||
|
||||
```bash
|
||||
python -m unittest discover -s tests -q
|
||||
PYTHONPATH=src python scripts/qa_001.py
|
||||
PYTHONPATH=src python scripts/qa_editor_001.py
|
||||
PYTHONPATH=src python scripts/qa_selection_001.py
|
||||
PYTHONPATH=src python scripts/qa_builder_001.py
|
||||
python scripts/sync_builder_design.py --check
|
||||
python scripts/verify_package_001.py
|
||||
site-engine export-openapi --out /tmp/admin-api.json
|
||||
```
|
||||
|
||||
В приёмке использовался `/tmp/flexly-cms-htmx-check/bin/python`; путь не является зависимостью проекта. QA-скрипты сами создают копию studio-site и закрывают тестовые серверы. Скриншоты и JSON-отчёты находятся в `/tmp/site-engine-001-qa/` и `/tmp/site-engine-001-editor-qa/`; сводный JSON сохранён рядом со спецификацией. Визуально просмотрены рабочие списки и трёхколоночный редактор; reference-снимки Antirion сохранены отдельно от runtime.
|
||||
|
||||
## Практические ограничения
|
||||
|
||||
- Docker-образ, reverse proxy и production HTTPS не разворачивались; проверены две настоящие локальные HTTP-origin и установленный пакет. Команды Docker/proxy приведены в runtime.md.
|
||||
- Каркас, списки и полная регрессия редактора проверены в Chromium. Конструктор дополнительно проверен в Firefox 142: 12 наборов сверки конструктора, 6 «Эксперта» и 12 групп сценариев. Дефект из скриншота пользователя воспроизведён на сервере напрямую без прокси; исправленные ресурсы проверялись подменой в тестовой вкладке, без установки на сервер. Safari отдельно не проверялся.
|
||||
- Без двух корректных origin доступно превью без scripts, с двусторонним выбором секций через родительскую админку. Отдельный preview-процесс требует корректную конфигурацию.
|
||||
- Буфер живёт в открытой вкладке. Для переноса/долгого хранения используйте Save или скачивание исходника. Структурные правки нормализуют YAML без отдельного подтверждения. Нативные диалоги запрещены; при внутренних переходах используются окна интерфейса, а перезагрузка/закрытие вкладки теряют несохранённую редакцию без системного запроса.
|
||||
- Просроченные preview-файлы очищаются при старте/следующем создании, доступ по TTL/epoch блокируется независимо от очистки. Preview assets ограничены 50 MiB.
|
||||
- Спецификации 002–006 (candidate/diff, загрузки/rename/настройки, RBAC, заявки/outbox, MCP) остаются вне 001.
|
||||
|
||||
## Исправления выбора секций и диалогов
|
||||
|
||||
Полная регрессия: **248 тестов OK**; конструктор в Chromium: **12 сравнений + 6 «Эксперта», 12 групп сценариев**; редактор: **25 сценариев**. Дополнительный `qa_selection_001.py` прошёл в Chromium 158 и Firefox 142, в каждом — оба режима превью: локальный выбор без POST и замены iframe, выделение/прокрутку, клики по секциям, fixed-инспектор, повторные правки кешированных форм без записи файла, отмену/подтверждение переходов и выхода через модальные окна интерфейса, перезагрузку без нативного диалога. Артефакты — `/tmp/site-engine-selection-001/`, `/tmp/site-engine-selection-firefox-001/`.
|
||||
|
||||
Во время последнего прогона рабочий `examples/studio-site/pages/index.md` оказался недоступен для чтения (root, 0600). Проверки выполнены на временной копии примера с этим файлом из Git HEAD; остальные доступные файлы примера скопированы как обычно. Права и рабочий контент не менялись. Изменения выбора и диалогов на сервер пользователя не устанавливались.
|
||||
Reference in New Issue
Block a user