87 lines
7.9 KiB
Markdown
87 lines
7.9 KiB
Markdown
# 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 (услуги, формы, коллекция, редирект)
|
||
├── tests/ # 62 теста: значения, разбор, маршруты, сборка, безопасность, запись
|
||
└── 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/ # ContentService (if_match, история, синтаксис), publish; stubs: changeset, auth, forms
|
||
├── builtin/ # base.css и 15 фрагментов ядра (ADR-006)
|
||
├── db/ # SQLAlchemy-модели служебных таблиц (M2)
|
||
├── web/ # FastAPI-фабрика, место для админки htmx (M1–M3)
|
||
└── mcp/ # перечень инструментов MVP (M3)
|
||
```
|
||
|
||
## Что реализовано
|
||
|
||
| Этап | Состояние |
|
||
|---|---|
|
||
| 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/content.py`) запущено и покрыто 62 тестами. Модули `db/`, `web/`, `mcp/` и `Dockerfile` проверены только компиляцией и чтением: SQLAlchemy, FastAPI и 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).
|