Files
flexly-cms/README.md
T
2026-11-09 15:42:27 +03:00

12 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                   # 15 встроенных фрагментов
make test                               # или: pytest

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

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

site-engine/
├── pyproject.toml            # зависимости ядра и extras: server, mcp, images, dev
├── Makefile  Dockerfile      # Dockerfile — для M2+ (админка, формы, MCP)
├── docs/                     # ТЗ, ревью, журнал решений
├── examples/studio-site/     # сайт-пример из SiteMap.md (услуги, формы, коллекция, редирект)
├── .env.example              # переменные окружения для админки
├── tests/                    # 112 тестов: ядро, сборка, безопасность, запись, вход в админку
└── 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-проверки, правила сайта
    │   └── 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 (вход, выход, обзор), шаблоны, routes-адаптер
    └── mcp/                  # перечень инструментов MVP (M3)

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

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

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.

Что реализовано

Этап Состояние
M0 Контракт и прототип Готово: формат файлов, модель блоков, load → validate → render, CLI, 15 фрагментов, сайт-пример
M1 Публикуемый движок Частично: маршруты, ссылки, редиректы, sitemap, атомарная публикация, откат (services/publish.py), превью страницы через CLI. Нет: превью по токену, 404-страница из коробки, тема
M2 Коллекции, заявки, доступ Частично: коллекции, display templates, запросы, формы (разметка, версия формы в релизе), вход одного администратора с аудитом входов и обзорная страница админки. Нет: роли, приём заявок, outbox, аудит правок
M3 MCP и редактор ContentService с if_match, блокировкой и историей готов; нет редактора страниц, patch_page, changeset, MCP-сервера
M4 Не начат

Что проверено, а что нет

Тесты и сборка примера выполнялись в окружении без сети: ядро (core/, build/, parsing/, storage/, services/) и вся логика админки (web/admin/handlers.py, шаблоны, вход, CSRF, заголовки) запущены и покрыты 112 тестами. Тонкий FastAPI-адаптер web/admin/routes.py проверен на подставном модуле fastapi, а web/app.py, db/, mcp/ и Dockerfile только компиляцией и чтением: FastAPI, SQLAlchemy и MCP SDK в окружении не было. Ядро намеренно не зависит от pydantic: ошибки должны нести путь к полю (pages/index.md:regions.main[b_hero].props.title), а валидация задаётся манифестами фрагментов. Pydantic нужен на границах API (web, mcp).

Соответствие журналу решений

Решение Где в коде
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 фрагментов, editorial, requires только feature.* builtin/fragments/, 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). Вход уже есть, роли и аудит правок будут вместе с редактором.