Files
flexly-cms/README.md
T

148 lines
18 KiB
Markdown
Raw 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). Код следует журналу решений.
## Быстрый старт
```bash
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/ # 178 тестов: ядро, сборка, безопасность, запись, вход и редактор
└── 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)
```
## Вход в админку
Самый простой вариант: **один администратор, без ролей**, логин и хеш пароля задаются переменными окружения, БД для входа не нужна.
```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 страниц, блоков и записей проверяются регулярным выражением и поиском в реестре, до пути на диске недоступны; предпросмотр отдаётся в `sandbox`-фрейме с CSP без скриптов; в аудит попадают id и тип действия, но не содержимое.
Что работает иначе, чем можно ожидать:
- **Без JS.** Порядок блоков меняется кнопками ↑/↓, элементы списков добавляются через «пустую строку» формы. Скачать htmx и SortableJS в окружении без сети было нельзя, поэтому редактор целиком работает на обычных формах. Если положить `htmx.min.js` в `src/site_engine/web/admin/static/`, админка включит `hx-boost` сама (проверено только разметкой, с настоящим htmx не запускалось).
- **Первая правка файла переформатирует его YAML** в блочный стиль: `{id: b_1, fragment: hero}` станет несколькими строками. Смысл и порядок ключей сохраняются.
- **Ассеты** выбираются по пути из подсказки, загрузки файлов в редакторе пока нет.
- **Блоки не переносятся между регионами**, только внутри своего списка.
- **Запись коллекции со «лишним» ключом**, которого нет в схеме, нельзя сохранить в статусе `published`, пока ключ не уберут из файла: так требует ADR-003.
## Что реализовано
| Этап | Состояние |
|---|---|
| M0 Контракт и прототип | Готово: формат файлов, модель блоков, load → validate → render, CLI, 15 фрагментов, сайт-пример |
| M1 Публикуемый движок | Частично: маршруты, ссылки, редиректы, sitemap, атомарная публикация, откат (`services/publish.py`), превью страницы через CLI. Нет: превью по токену, 404-страница из коробки, тема |
| M2 Коллекции, заявки, доступ | Частично: коллекции, display templates, запросы, формы (разметка, версия формы в релизе), **вход одного администратора с аудитом входов и обзорная страница админки**. Нет: роли, приём заявок, outbox, аудит правок |
| M3 MCP и редактор | Готово: редактор страниц, блоков и записей на `ContentService`, предпросмотр, публикация и откат из админки. Нет: `patch_page`, changeset (rename, delete), MCP-сервера, перетаскивания, загрузки файлов |
| M4 | Не начат |
## Что проверено, а что нет
Тесты и сборка примера выполнялись в окружении без сети: ядро (`core/`, `build/`, `parsing/`, `storage/`, `services/`) и вся логика админки (`web/admin/handlers.py`, `editor.py`, `forms.py`, шаблоны, вход, CSRF, заголовки) запущены и покрыты 178 тестами, включая сквозные через HTML-формы. Тонкий 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). Вход, аудит правок и редактор уже есть; роли и приём заявок остаются на M2.