Files
flexly-cms/README.md
T
phelex 0d171915d7 Add Site Studio themes and Theme Manager
Support categorized fragments, theme presets, block widths, and server-backed theme editing with onboarding and preview.

Include Site Studio, design sources, specification and verification reports; remove the legacy studio-site example.
2026-11-13 14:04:49 +03:00

31 KiB
Raw Blame History

Site Engine

Движок сайтов на Markdown + YAML: страницы собираются из layouts и fragments, контент и структура живут в файлах, результат — статический сайт. Подключение агента по MCP — часть архитектуры (этап M3).

Документы проекта лежат в docs/: ТЗ v0.1, архитектурное ревью и журнал принятых решений (ADR-001…006). Код следует журналу решений.

Быстрый старт

pip install -e ".[dev]"                 # ядру нужны jinja2, PyYAML, markdown-it-py, click
site-engine validate examples/studio-site
site-engine build examples/studio-site --out /tmp/studio-dist
site-engine preview examples/studio-site drafts/next > /tmp/draft.html
site-engine fragments                   # 17 встроенных фрагментов
make test                               # или: pytest

Результат сборки: OUT/<build_id>/ и симлинк OUT/current, который переключается атомарно. Неудачная сборка current не трогает.

Расширенный пример для проверки перед возможным переносом сайта — examples/ai-studio, также на схеме версии 1: услуги, сценарии, кейсы, обложки, связи и понятные схемы полей. Проверка: site-engine validate examples/ai-studio, сборка: site-engine build examples/ai-studio --out /tmp/ai-studio-dist, браузерная приёмка: PYTHONPATH=src python scripts/qa_ai_studio.py. studio-site остаётся базовой фикстурой; отдельный запуск нового примера описан в его README.

Отдельный перенос публичного дизайна из design/examples/site-studio/ — examples/site-studio: 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.

Каталог фрагментов

Фрагмент определяется файлом 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:

name: Пример текстовой секции
props:
  title: Новый раздел
  text: Начальный текст раздела

props из этого файла переопределяет одноимённые значения inline fragment.yaml:preview, затем применяются defaults полей. Название самого фрагмента остаётся в fragment.yaml:name. Некорректный preview входит в диагностику загрузки и не пропускается молча.

Этапы 1–5 спецификации 002 реализованы: категории, файловая тема, ширина блоков, отдельный Site Studio и Theme Manager. Экран /admin/theme доступен через «Дизайн сайта»; для нового сайта мастер открывается через /admin/setup/theme. Отчёт этапа 5 подготовлен к пользовательской приёмке.

Тема и ширина секций

В site.yaml тема подключается через theme: {file: theme.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, приёмка — проверки этапов 2–3.

Структура проекта

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
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/. Проверка того, что видит контейнер:

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)".

Вход в админку

Самый простой вариант: один администратор, без ролей, логин и хеш пароля задаются переменными окружения, БД для входа не нужна.

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. Без JS сохраняются обычные формы. CDN и Node-сборка не нужны; SortableJS пока не подключён. Конфигурация запрещает eval, скрипты из ответов и сторонние запросы, отключает сохранение HTML в localStorage и разрешает показ HTML-ошибок 4xx. Новый редактор использует HTML-фрагменты htmx, общий буфер в памяти и явный Save; без JS доступна обычная форма исходника.

Развитие админки описано в 001 — Antirion Rework: htmx/Jinja → HTML UI → серверный API-клиент → типизированный JSON API FastAPI → сервисы. JSON API, общий буфер Конструктора/«Эксперта», ручной Save и интерактивное превью реализованы. Контракт, env и запуск второго процесса: runtime.md; приёмка: verification.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. 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.