Files

253 lines
32 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Site Engine
Движок сайтов на Markdown + YAML: страницы собираются из **layouts** и **fragments**, контент и структура живут в файлах, результат — статический сайт. Подключение агента по MCP — часть архитектуры (этап M3).
Документы проекта лежат в `docs/`: ТЗ v0.1, архитектурное ревью и журнал принятых решений (ADR-001…006). Код следует журналу решений. Правила веток и коммитов — [BRANCHING.md](docs/BRANCHING.md).
Предложение по подключению внешнего агента, API keys/scopes, онбоардингу и этапам развития MCP — [MCP и внешний агент](docs/extends/mcp-agent-integration.md). Это основа будущей спецификации; MCP-сервер пока не реализован.
## Быстрый старт
```bash
pip install -e ".[server,dev]" # ядру нужны jinja2, PyYAML, markdown-it-py, click
site-engine validate examples/site-studio
site-engine build examples/site-studio --out /tmp/site-studio-dist
site-engine preview examples/site-studio index > /tmp/site-preview.html
site-engine fragments # каталог встроенных фрагментов
make test # временная историческая фикстура, без записи в examples/
```
Результат сборки: `OUT/<build_id>/` и симлинк `OUT/current`, который переключается атомарно. Неудачная сборка `current` не трогает.
Актуальный пример на схеме версии 1 — [examples/site-studio](examples/site-studio/README.md): услуги, сценарии, кейсы, связи и схемы полей. Проверка: `site-engine validate examples/site-studio`, сборка: `site-engine build examples/site-studio --out /tmp/site-studio-dist`, браузерная приёмка: `PYTHONPATH=src python scripts/qa_site_studio_002.py`. Полная регрессия: `PYTHONPATH=src python scripts/run_regression.py` (или `make test`). Runner извлекает старую фикстуру `studio-site` из Git-коммита `231490b` во временный каталог и мигрирует её тему; нужны Git и эта история, дополнительные файлы из `/tmp` не требуются. Обычные `pytest`/`unittest discover` пока не готовят эту фикстуру. Целевые тесты нового UI и браузерные QA используют собственные фикстуры и текущий Site Studio.
Отдельный перенос публичного дизайна из `design/examples/site-studio/` — [examples/site-studio](examples/site-studio/README.md): 13 страниц, пять layouts, общие `steps` и `entry_card`, файловая тема и ширины секций, сохранённые черновики и отключённые коллекции. `site-engine validate examples/site-studio`, `site-engine build examples/site-studio --out /tmp/site-studio-dist`; браузерная сверка с оригиналом — `PYTHONPATH=src python scripts/qa_site_studio_002.py`. Отчёт — [этап 4](specs/002-site-studio-theme/verification-stage-4.md).
## Каталог фрагментов
Фрагмент определяется файлом `fragment.yaml`, поиск рекурсивный. Поддерживаются прежнее плоское размещение `fragments/richtext/fragment.yaml` и категории `fragments/content/richtext/fragment.yaml`. ID берётся из манифеста и не зависит от имени папки; в блоках по-прежнему указывается `fragment: richtext`.
Для вложенного размещения категория определяется первым каталогом относительно `fragments/` и имеет приоритет над `category` в YAML. Для плоского размещения сохраняется категория из YAML, по умолчанию `misc`. Встроенные фрагменты разложены по `content`, `data`, `forms`, `marketing`, `media`, `system`; дополнительные категории сайта допустимы. Повторные ID, включая совпадения с builtin, запрещены.
В конструкторе категория видна рядом с названием; назначение остаётся под названием. Поиск учитывает ID, название, описание и категорию, фильтры объединяют прежние русские подписи со стандартными категориями.
Данные для добавления блока можно вынести в соседний `preview.yaml`:
```yaml
name: Пример текстовой секции
props:
title: Новый раздел
text: Начальный текст раздела
```
`props` из этого файла переопределяет одноимённые значения inline `fragment.yaml:preview`, затем применяются defaults полей. Название самого фрагмента остаётся в `fragment.yaml:name`. Некорректный preview входит в диагностику загрузки и не пропускается молча.
Этапы 1–5 [спецификации 002](specs/002-site-studio-theme/spec.md) реализованы: категории, файловая тема, ширина блоков, отдельный Site Studio и Theme Manager. Экран `/admin/theme` доступен через «Дизайн сайта»; для нового сайта мастер открывается через `/admin/setup/theme`. [Отчёт этапа 5](specs/002-site-studio-theme/verification-stage-5.md) подготовлен к пользовательской приёмке.
## Тема и ширина секций
В `site.yaml` тема подключается через `theme: {file: theme.yaml}`. Документ темы:
```yaml
schema: 1
preset: minimal
preset_version: 1
overrides:
colors:
primary: '#4255b9'
ui:
container:
mode: boxed
max_width: 1080
gutter: {desktop: 36, tablet: 24, mobile: 16}
```
Доступны перенесённые из дизайна пресеты `minimal`, `dark`, `editorial`, `bold`, `natural`, `custom` версии 1. Один resolver проверяет цвета, разрешённые шрифты, числовые токены, дополнительные цвета и градиенты для CLI, сборки и preview. Недостаточный контраст — предупреждение. Без настройки темы новый сайт использует minimal@1 без записи файла; явная неправильная ссылка и старый inline `theme.tokens` дают ошибку. Конфигурации `studio-site` и `ai-studio` обновлены в исходниках; автоматической миграции нет.
Блок может задать `layout: {section_width: full, content_width: boxed}`: первая ширина отвечает за фон секции, вторая — за содержимое. Допустимы `inherit`, `boxed`, `fluid`, `full`; наследование идёт от темы. В конструкторе эти поля находятся в инспекторе «Макет блока · ширина» и сохраняются в YAML при явном Save. Изменение preview не записывает страницу.
Theme Manager переносит четыре шага исходного Antirion: пресеты, цвета/градиенты, шрифты, дизайн-токены/ширину. Правки остаются в памяти вкладки до «Сохранить тему»; YAML экспортируется после серверной проверки. Стенд компонентов и реальная страница используют изолированное серверное превью. Save изменяет workspace, публикация — отдельное действие. Состояние мастера (пропуск/повтор/завершение) хранится в `SITE_STATE_DIR/theme-onboarding.json`; палитры в нём нет. Для новых ресурсов нужна пересборка образа. Проверка: `PYTHONPATH=src python scripts/qa_theme_manager_002.py`.
Тема и вычисленные токены фиксируются в `manifest.json` релиза; fingerprint учитывает файлы сайта и ресурсы рендера. Откат возвращает готовый HTML/CSS выбранного релиза, сохраняя рабочие файлы. Подробный контракт и таблица CSS-переменных — [runtime 002](specs/002-site-studio-theme/runtime.md), приёмка — [проверки этапов 2–3](specs/002-site-studio-theme/verification-stages-2-3.md).
## Структура проекта
```
site-engine/
├── pyproject.toml # зависимости ядра и extras: server, mcp, images, dev
├── Makefile Dockerfile # Dockerfile — для M2+ (админка, формы, MCP)
├── docs/ # ТЗ, ревью, журнал решений
├── examples/studio-site/ # сайт-пример из SiteMap.md (услуги, формы, коллекция, редирект)
├── .env.example # переменные окружения для админки
├── tests/ # 206 тестов: ядро, сборка, безопасность, запись, вход и редактор
└── src/site_engine/
├── cli.py # validate · build · preview · fragments
├── errors.py # Issue/Report: код, путь к полю, серьёзность, подсказка
├── core/
│ ├── values.py # Literal | Binding | LinkRef | Query (ADR-002)
│ ├── models.py # Block, Page, Entry, Fragment, Layout, Collection…
│ ├── registry.py # чистая загрузка каталога сайта в память (ADR-001)
│ ├── routes.py # нормализация маршрутов, таблица, коллизии
│ ├── resolve.py # привязки, ссылки, запросы MVP
│ ├── validate.py # workspace-проверки, release-проверки, правила сайта
│ ├── draft_check.py # проверка при сохранении: новый текст файла против реестра
│ ├── page_ops.py # добавить, переместить, удалить блок по id в сыром front matter
│ └── render.py # Jinja SandboxedEnvironment, разрешение props по схеме
├── build/pipeline.py # load → validate → render → релиз → атомарный current
├── parsing/ # безопасный YAML, front matter, Markdown (raw HTML выключен)
├── storage/ # safe_join, atomic_write, SiteLock, .engine/history
├── services/ # auth (вход админа), ContentService (if_match, история), publish; stubs: changeset, forms
├── builtin/ # base.css и 15 фрагментов ядра (ADR-006)
├── db/ # SQLAlchemy-модели служебных таблиц (M2)
├── web/ # FastAPI-фабрика; admin/: handlers (вход, обзор), editor (страницы, блоки, записи, публикация), forms, шаблоны, routes-адаптер
└── mcp/ # перечень инструментов MVP (M3)
```
## Запуск в Docker
Один том `/data`, в нём три каталога. Всё, что важно сохранить, лежит на хосте в `./data`.
| На хосте | В контейнере | Что это |
|---|---|---|
| `data/site` | `/data/site` | Ваш сайт: `site.yaml`, `pages/`, `content/`, фрагменты. Его правит редактор |
| `data/dist` | `/data/dist` | Опубликованные релизы и симлинк `current` |
| `data/state` | `/data/state` | Состояние входа и журнал `audit.jsonl` |
```bash
docker build -t site-engine .
docker run --rm -it site-engine site-engine hash-password # спросит пароль, напечатает хеш
docker run --rm site-engine site-engine gen-secret # ключ подписи сессий
cp .env.example .env # впишите хеш и ключ
mkdir -p data && cp -r examples/studio-site data/site # или положите свой сайт в data/site
docker run -d --name site-engine -p 8181:8000 --env-file .env -v "$PWD/data:/data" site-engine
```
Админка: `http://localhost:8181/admin/` (на обзоре сверху показаны абсолютные пути, которыми пользуется приложение), опубликованный сайт: `http://localhost:8181/`. Проверка того, что видит контейнер:
```bash
docker logs site-engine # строка «site-engine: site=/data/site, dist=/data/dist, state=/data/state, admin=on»
docker exec site-engine env | grep '^SITE_' # SITE_ROOT, SITE_DIST, SITE_STATE_DIR должны начинаться с /data/
```
Если вместо `/data/...` там относительные пути (`examples/studio-site`, `dist`), эти строки остались в вашем `.env` от старой версии: удалите `SITE_ROOT`, `SITE_DIST`, `SITE_STATE_DIR` из `.env`, так как значения из `--env-file` перекрывают значения из образа. При старте приложение само пишет об этом предупреждение.
Правила для `.env` при `docker run --env-file`:
- **Без кавычек.** Docker не снимает их, они станут частью значения.
- **Без комментариев в конце строки.** `KEY=value # текст` даёт значение «value # текст».
- **Знак `$` в хеше экранировать не нужно.** (Для `docker compose` и его `.env` его нужно удваивать: `$$`.)
Приложение проверяет эти значения строго: хеш, ключ, логин, флаг Secure и host с лишними символами не принимаются молча, `/admin/` не включается, а в `docker logs` пишется причина.
| Симптом | Причина |
|---|---|
| `/admin/` даёт 404 | Не заданы `SITE_ADMIN_PASSWORD_HASH` и `SITE_SECRET_KEY`, ключ короче 32 символов или в значении кавычки или комментарий; причина в `docker logs`: «админка отключена: …» |
| «Сайт не загружен» на обзоре | В `data/site` нет `site.yaml` или том не смонтирован; на обзоре виден абсолютный путь, который проверял движок |
| Опубликованного сайта нет на хосте | Том не смонтирован (`-v "$PWD/data:/data"`): релизы лежат внутри контейнера и пропадут вместе с ним |
| После ввода пароля снова страница входа | Cookie с флагом Secure не принимается по `http://` с адреса не `localhost`: поставьте `SITE_COOKIE_SECURE=0` |
| Ответ 422 с `"loc": ["query","request"]` | Образ собран из версии до исправления: пересоберите `docker build` |
Контейнер работает от root, поэтому файлы в `data/` на Linux будут принадлежать root. Чтобы этого избежать, добавьте `--user "$(id -u):$(id -g)"`.
## Вход в админку
Самый простой вариант: **один администратор, без ролей**, логин и хеш пароля задаются переменными окружения, БД для входа не нужна.
```bash
site-engine hash-password # спросит пароль (от 12 символов) и напечатает scrypt-хеш
site-engine gen-secret # ключ подписи сессий
cp .env.example .env # впишите SITE_ADMIN_PASSWORD_HASH и SITE_SECRET_KEY
SITE_COOKIE_SECURE=0 uvicorn site_engine.web.app:create_app --factory --env-file .env # локально по http
```
Без `SITE_ADMIN_PASSWORD_HASH` и `SITE_SECRET_KEY` (не короче 32 символов) `/admin/` не включается вообще: нет пароля — нет входа. После входа `/admin/` показывает страницы сайта со статусами, коллекции и результат проверки (только чтение; редактор — следующий шаг).
| Мера | Как сделано |
|---|---|
| Пароль | scrypt (N=2^15, r=8, p=1), соль на каждый хеш, сравнение за постоянное время |
| Сессия | Подписанная cookie `se_session`: HttpOnly, SameSite=Strict, Secure (выключается только `SITE_COOKIE_SECURE=0`), Path=/admin, срок `SITE_SESSION_HOURS` (по умолчанию 8) |
| Выход | Увеличивает «эпоху» в `.engine/auth_epoch`: все выданные cookie сразу недействительны, в том числе украденные |
| Перебор | 5 неудач за 15 минут блокируют IP (429 + Retry-After), общий порог 30 на все адреса; хеш считается и при неверном логине, поэтому по времени логин не угадать |
| CSRF | POST принимается только с Origin или Referer того же хоста; выход дополнительно требует токен, привязанный к сессии |
| Заголовки | CSP без inline, `frame-ancestors 'none'`, `no-store`, `X-Frame-Options: DENY`, `nosniff` |
| Аудит | `.engine/audit.jsonl`: вход, неудача, блокировка, выход; без паролей и без введённого логина |
Ограничения этого варианта:
- Один пользователь, роль всегда `admin`; таблицы `users` и `api_tokens` из `db/models.py` пока не используются.
- Окно попыток хранится в памяти процесса: при нескольких воркерах у каждого свой счётчик, после перезапуска он обнуляется.
- За обратным прокси `request.client.host` — адрес прокси, поэтому ограничение по IP работает как общее. Доверие к `X-Forwarded-For` нужно включать явно (задача M2).
- Выход завершает все сессии администратора сразу, отдельного списка устройств нет.
- Отдельная смена пароля: сгенерировать новый хеш и перезапустить сервис; чтобы разлогинить всех, поменяйте `SITE_SECRET_KEY`.
## Редактор
После входа в `/admin/` доступны страницы, контент и публикация. Все правки идут через `ContentService`: блокировка сайта, `if_match` по хешу файла, проверка синтаксиса, история в `.engine/history/`, атомарная запись. Редактор пишет только в `pages/` и `content/`; фрагменты, layouts, схемы и `site.yaml` через него изменить нельзя.
| Экран | Что умеет |
|---|---|
| Страницы | Список со статусами и адресами; создание черновика (путь, заголовок, layout) |
| Страница | Заголовок, статус, layout, адрес, описание, текст Markdown; блоки по регионам и слотам: добавить, ↑/↓, скрыть и показать, удалить; предпросмотр в изолированном фрейме; список проблем страницы |
| Блок | Форма строится из манифеста фрагмента: текст, Markdown, число, список, группа, выбор, ссылка (страница, запись, адрес), запрос к коллекции, ассет; у каждого поля поле «привязка» (`entry.title`, `page.body`…); якорь, заметка, скрыть, `requires` по флагам сайта |
| Контент | Записи коллекций: поля по схеме, статус, текст Markdown, создание черновика, предпросмотр |
| Публикация | Сборка релиза, список релизов, возврат к прежнему релизу |
Гарантии, которые проверены тестами:
- **Без потерь.** Форма открывается из файла и отправляется обратно без изменений: у каждого блока примера, всех страниц и записей YAML остаётся тем же по смыслу. Неизвестные ключи не пропадают, привязки сохраняются.
- **Конфликты.** Если файл изменили в другом окне, правка получит 409, а чужие изменения не будут перезаписаны.
- **Проверка при сохранении.** Нельзя сохранить неизвестный фрагмент, несуществующий layout, блок в закреплённый регион, значение не того типа, `{{ }}` в данных, привязку к чужому корню. Пропуск обязательного поля не блокирует сохранение (ADR-003), но он виден в «Проверке страницы», и сборка релиза с ним не пройдёт; опубликованный сайт при этом не меняется.
- **Безопасность.** Каждый POST требует CSRF-токен и Origin своего хоста; id страниц, блоков и записей проверяются регулярным выражением и поиском в реестре, до пути на диске недоступны; пассивное превью использует iframe без scripts, интерактивное — отдельный origin и только nonce bridge; в аудит попадают id и тип действия, но не содержимое.
Что работает иначе, чем можно ожидать:
- **Обычные формы и локальный htmx.** Порядок блоков меняется кнопками ↑/↓, элементы списков добавляются через «пустую строку» формы. htmx 2.0.11 поставляется в `src/site_engine/web/admin/static/` и включает существующий `hx-boost`; источник, лицензия и SHA-256 — в [VENDOR.md](src/site_engine/web/admin/static/VENDOR.md). Без JS сохраняются обычные формы. CDN и Node-сборка не нужны; SortableJS пока не подключён. Конфигурация запрещает eval, скрипты из ответов и сторонние запросы, отключает сохранение HTML в localStorage и разрешает показ HTML-ошибок 4xx. Новый редактор использует HTML-фрагменты htmx, общий буфер в памяти и явный Save; без JS доступна обычная форма исходника.
Развитие админки описано в [001 — Antirion Rework](specs/001-antirion-admin/spec.md): htmx/Jinja → HTML UI → серверный API-клиент → типизированный JSON API FastAPI → сервисы. JSON API, общий буфер Конструктора/«Эксперта», ручной Save и интерактивное превью реализованы. Контракт, env и запуск второго процесса: [runtime.md](specs/001-antirion-admin/runtime.md); приёмка: [verification.md](specs/001-antirion-admin/verification.md).
Publication перенесён из оригинального дизайна: проверка → неизменяемый кандидат → preview/diff → отдельная публикация с комментарием и проверкой актуальности. История/откат сохраняют workspace. Контракт и границы — [publication-backend.md](specs/001-antirion-admin/publication-backend.md), проверки — [verification-publication.md](specs/001-antirion-admin/verification-publication.md).
- **Конструктор пересобирает YAML**: комментарии и форматирование могут измениться. «Эксперт» и переходы режимов без правок сохраняют точный исходник. «Применить к буферу» не пишет файл; «Сохранить документ» записывает весь документ с CAS, историей и аудитом. До Save исходник можно скачать.
- **Ассеты** выбираются по пути из подсказки, загрузки файлов в редакторе пока нет.
- **Блоки перемещаются** кнопками ↑/↓ или перед указанным ID. Между регионами/слотами действует проверка схемы; циклы и изменение fixed-блоков запрещены.
- **Запись коллекции со «лишним» ключом**, которого нет в схеме, нельзя сохранить в статусе `published`, пока ключ не уберут из файла: так требует ADR-003.
## Что реализовано
| Этап | Состояние |
|---|---|
| M0 Контракт и прототип | Готово: формат файлов, модель блоков, load → validate → render, CLI, 15 встроенных фрагментов, сайт-пример; отдельный steps поставляется с ai-studio |
| M1 Публикуемый движок | Частично: маршруты, ссылки, редиректы, sitemap, атомарная публикация, откат (`services/publish.py`), превью страницы через CLI. Превью по токену реализовано в 001; нет 404-страницы из коробки и системы публичных тем |
| M2 Коллекции, заявки, доступ | Частично: коллекции, display templates, запросы, формы (разметка, версия формы в релизе), **вход одного администратора с аудитом входов и обзорная страница админки**. Аудит Save/create/publish/rollback реализован; нет ролей, приёма заявок и outbox |
| M3 MCP и редактор | Готово: редактор страниц, блоков и записей на `ContentService`, предпросмотр, публикация и откат из админки. Нет: `patch_page`, changeset (rename, delete), MCP-сервера, перетаскивания, загрузки файлов |
| M4 | Не начат |
## Что проверено, а что нет
Приёмка 001 включает полную регрессию ядра/CLI/админки, настоящий FastAPI, JSON-контракт и ASGI-клиент, Chromium на двух origin, адаптивные экраны и установленный wheel без `design/`. Воспроизводимые команды, результаты и ограничения: [verification.md](specs/001-antirion-admin/verification.md). Docker/proxy deployment, БД и MCP-сервер не запускались. Ядро сохраняет dataclass; Pydantic используется на границе API.
## Соответствие журналу решений
| Решение | Где в коде |
|---|---|
| ADR-001: сборка не читает SQLite | `core/registry.load_site`, `build/pipeline.build_site` |
| ADR-002: 4 вида значений, `bind`, запросы MVP | `core/values.py`, `core/resolve.py`; `{{ }}` в данных запрещены (`validate.py`) |
| ADR-003: draft / release / live, версия формы в релизе | `validate_workspace` vs `validate_release`, `_forms/<id>@<версия>.json`, `switch_current` |
| ADR-004: `if_match`, блокировка сайта, история | `services/content.py`, `storage/locks.py`, `storage/history.py` |
| ADR-005: границы доверия | `SandboxedEnvironment`, Markdown без raw HTML, `safe_join`, токены темы, YAML без алиасов |
| ADR-006: 15 встроенных фрагментов, локальный steps в ai-studio, `editorial`, `requires` только `feature.*` | `builtin/fragments/`, `examples/ai-studio/fragments/steps/`, `models.Page.editorial`, `render._feature_on` |
## Как расширять
- **Новый фрагмент:** папка `fragments/<имя>/` сайта с `fragment.yaml`, `template.html.j2`, необязательным `style.css`. `id` плоский и уникальный, затенение встроенных запрещено.
- **Новая коллекция:** `collections/<id>.yaml`, записи в `content/<id>/*.md`, при необходимости `display/<id>.yaml`.
- **Новое правило сайта:** запись в `site.yaml: rules` (сейчас `require_fragment` для коллекции и `require_field` для форм).
## Известные ограничения M0
- Поле `props` в шаблоне — объект `Props`: `props.items` читает поле «items», а не метод словаря.
- `layout.extends` проверяется на существование, наследование шаблонов делается обычным `{% extends 'layout/<id>' %}`.
- CSS и JS собираются в один бандл с хешем в имени; минификации и изоляции по страницам пока нет.
- Нет приёма заявок и MCP: сетевая поверхность записи включается только вместе с контуром «вход, роли, аудит, лимиты» (ADR-006). Вход, аудит правок и редактор уже есть; роли и приём заявок остаются на M2.