From c778db6208afe98a01d2edeef680e16263b3a427 Mon Sep 17 00:00:00 2001 From: Alexey Dudin Date: Mon, 9 Nov 2026 15:32:41 +0300 Subject: [PATCH] Init Project Flexly CMS --- .gitignore | 10 + Dockerfile | 10 + Makefile | 10 + README.md | 86 ++ docs/TZ-site-engine-architecture-review.md | 317 ++++++++ docs/TZ-site-engine-decisions.md | 242 ++++++ docs/TZ-site-engine.md | 769 ++++++++++++++++++ examples/studio-site/assets/hero.svg | 1 + .../studio-site/collections/services.yaml | 12 + examples/studio-site/content/services/ai.md | 8 + .../content/services/automation.md | 8 + examples/studio-site/content/services/bots.md | 8 + examples/studio-site/data/company.yaml | 2 + examples/studio-site/display/services.yaml | 14 + examples/studio-site/forms/consultation.yaml | 12 + .../layouts/default/layout.html.j2 | 13 + .../studio-site/layouts/default/layout.yaml | 14 + examples/studio-site/menus/footer.yaml | 3 + examples/studio-site/menus/main.yaml | 4 + examples/studio-site/pages/_section.yaml | 2 + examples/studio-site/pages/contacts.md | 11 + examples/studio-site/pages/drafts/next.md | 8 + examples/studio-site/pages/index.md | 51 ++ examples/studio-site/pages/privacy.md | 10 + examples/studio-site/pages/services/index.md | 13 + examples/studio-site/redirects.yaml | 1 + examples/studio-site/site.yaml | 22 + pyproject.toml | 47 ++ src/site_engine/__init__.py | 3 + src/site_engine/builtin/base.css | 19 + .../builtin/fragments/card_grid/fragment.yaml | 17 + .../builtin/fragments/card_grid/style.css | 4 + .../fragments/card_grid/template.html.j2 | 14 + .../fragments/collection_list/fragment.yaml | 13 + .../fragments/collection_list/style.css | 4 + .../collection_list/template.html.j2 | 18 + .../builtin/fragments/columns/fragment.yaml | 12 + .../builtin/fragments/columns/style.css | 5 + .../fragments/columns/template.html.j2 | 5 + .../fragments/cta_banner/fragment.yaml | 11 + .../builtin/fragments/cta_banner/style.css | 1 + .../fragments/cta_banner/template.html.j2 | 12 + .../fragments/disclaimer/fragment.yaml | 9 + .../builtin/fragments/disclaimer/style.css | 2 + .../fragments/disclaimer/template.html.j2 | 3 + .../fragments/entry_header/fragment.yaml | 9 + .../builtin/fragments/entry_header/style.css | 2 + .../fragments/entry_header/template.html.j2 | 6 + .../builtin/fragments/faq/fragment.yaml | 14 + .../builtin/fragments/faq/style.css | 3 + .../builtin/fragments/faq/template.html.j2 | 8 + .../builtin/fragments/form/fragment.yaml | 8 + .../builtin/fragments/form/style.css | 5 + .../builtin/fragments/form/template.html.j2 | 23 + .../builtin/fragments/hero/fragment.yaml | 13 + .../builtin/fragments/hero/style.css | 4 + .../builtin/fragments/hero/template.html.j2 | 10 + .../builtin/fragments/image/fragment.yaml | 10 + .../builtin/fragments/image/style.css | 1 + .../builtin/fragments/image/template.html.j2 | 4 + .../fragments/page_header/fragment.yaml | 10 + .../builtin/fragments/page_header/style.css | 3 + .../fragments/page_header/template.html.j2 | 15 + .../builtin/fragments/richtext/fragment.yaml | 8 + .../builtin/fragments/richtext/style.css | 1 + .../fragments/richtext/template.html.j2 | 1 + .../builtin/fragments/section/fragment.yaml | 11 + .../builtin/fragments/section/style.css | 5 + .../fragments/section/template.html.j2 | 6 + .../fragments/site_footer/fragment.yaml | 9 + .../builtin/fragments/site_footer/style.css | 2 + .../fragments/site_footer/template.html.j2 | 14 + .../fragments/site_header/fragment.yaml | 9 + .../builtin/fragments/site_header/style.css | 4 + .../fragments/site_header/template.html.j2 | 13 + src/site_engine/cli.py | 94 +++ src/site_engine/core/__init__.py | 1 + src/site_engine/core/models.py | 491 +++++++++++ src/site_engine/core/registry.py | 192 +++++ src/site_engine/core/render.py | 359 ++++++++ src/site_engine/core/resolve.py | 147 ++++ src/site_engine/core/routes.py | 114 +++ src/site_engine/core/validate.py | 315 +++++++ src/site_engine/core/values.py | 107 +++ src/site_engine/db/__init__.py | 1 + src/site_engine/db/engine.py | 26 + src/site_engine/db/models.py | 96 +++ src/site_engine/errors.py | 76 ++ src/site_engine/mcp/__init__.py | 1 + src/site_engine/mcp/server.py | 42 + src/site_engine/parsing/__init__.py | 1 + src/site_engine/parsing/frontmatter.py | 40 + src/site_engine/parsing/markdown.py | 38 + src/site_engine/parsing/yamlio.py | 50 ++ src/site_engine/services/__init__.py | 1 + src/site_engine/services/auth.py | 4 + src/site_engine/services/changeset.py | 13 + src/site_engine/services/content.py | 64 ++ src/site_engine/services/forms.py | 1 + src/site_engine/services/publish.py | 22 + src/site_engine/storage/__init__.py | 1 + src/site_engine/storage/fs.py | 46 ++ src/site_engine/storage/history.py | 35 + src/site_engine/storage/locks.py | 36 + src/site_engine/web/__init__.py | 1 + src/site_engine/web/admin/__init__.py | 1 + src/site_engine/web/app.py | 30 + tests/helpers.py | 32 + tests/test_build.py | 174 ++++ tests/test_content_service.py | 76 ++ tests/test_fragments.py | 77 ++ tests/test_parsing.py | 37 + tests/test_routes.py | 50 ++ tests/test_security.py | 75 ++ tests/test_values.py | 40 + 115 files changed, 5098 insertions(+) create mode 100644 .gitignore create mode 100644 Dockerfile create mode 100644 Makefile create mode 100644 README.md create mode 100644 docs/TZ-site-engine-architecture-review.md create mode 100644 docs/TZ-site-engine-decisions.md create mode 100644 docs/TZ-site-engine.md create mode 100644 examples/studio-site/assets/hero.svg create mode 100644 examples/studio-site/collections/services.yaml create mode 100644 examples/studio-site/content/services/ai.md create mode 100644 examples/studio-site/content/services/automation.md create mode 100644 examples/studio-site/content/services/bots.md create mode 100644 examples/studio-site/data/company.yaml create mode 100644 examples/studio-site/display/services.yaml create mode 100644 examples/studio-site/forms/consultation.yaml create mode 100644 examples/studio-site/layouts/default/layout.html.j2 create mode 100644 examples/studio-site/layouts/default/layout.yaml create mode 100644 examples/studio-site/menus/footer.yaml create mode 100644 examples/studio-site/menus/main.yaml create mode 100644 examples/studio-site/pages/_section.yaml create mode 100644 examples/studio-site/pages/contacts.md create mode 100644 examples/studio-site/pages/drafts/next.md create mode 100644 examples/studio-site/pages/index.md create mode 100644 examples/studio-site/pages/privacy.md create mode 100644 examples/studio-site/pages/services/index.md create mode 100644 examples/studio-site/redirects.yaml create mode 100644 examples/studio-site/site.yaml create mode 100644 pyproject.toml create mode 100644 src/site_engine/__init__.py create mode 100644 src/site_engine/builtin/base.css create mode 100644 src/site_engine/builtin/fragments/card_grid/fragment.yaml create mode 100644 src/site_engine/builtin/fragments/card_grid/style.css create mode 100644 src/site_engine/builtin/fragments/card_grid/template.html.j2 create mode 100644 src/site_engine/builtin/fragments/collection_list/fragment.yaml create mode 100644 src/site_engine/builtin/fragments/collection_list/style.css create mode 100644 src/site_engine/builtin/fragments/collection_list/template.html.j2 create mode 100644 src/site_engine/builtin/fragments/columns/fragment.yaml create mode 100644 src/site_engine/builtin/fragments/columns/style.css create mode 100644 src/site_engine/builtin/fragments/columns/template.html.j2 create mode 100644 src/site_engine/builtin/fragments/cta_banner/fragment.yaml create mode 100644 src/site_engine/builtin/fragments/cta_banner/style.css create mode 100644 src/site_engine/builtin/fragments/cta_banner/template.html.j2 create mode 100644 src/site_engine/builtin/fragments/disclaimer/fragment.yaml create mode 100644 src/site_engine/builtin/fragments/disclaimer/style.css create mode 100644 src/site_engine/builtin/fragments/disclaimer/template.html.j2 create mode 100644 src/site_engine/builtin/fragments/entry_header/fragment.yaml create mode 100644 src/site_engine/builtin/fragments/entry_header/style.css create mode 100644 src/site_engine/builtin/fragments/entry_header/template.html.j2 create mode 100644 src/site_engine/builtin/fragments/faq/fragment.yaml create mode 100644 src/site_engine/builtin/fragments/faq/style.css create mode 100644 src/site_engine/builtin/fragments/faq/template.html.j2 create mode 100644 src/site_engine/builtin/fragments/form/fragment.yaml create mode 100644 src/site_engine/builtin/fragments/form/style.css create mode 100644 src/site_engine/builtin/fragments/form/template.html.j2 create mode 100644 src/site_engine/builtin/fragments/hero/fragment.yaml create mode 100644 src/site_engine/builtin/fragments/hero/style.css create mode 100644 src/site_engine/builtin/fragments/hero/template.html.j2 create mode 100644 src/site_engine/builtin/fragments/image/fragment.yaml create mode 100644 src/site_engine/builtin/fragments/image/style.css create mode 100644 src/site_engine/builtin/fragments/image/template.html.j2 create mode 100644 src/site_engine/builtin/fragments/page_header/fragment.yaml create mode 100644 src/site_engine/builtin/fragments/page_header/style.css create mode 100644 src/site_engine/builtin/fragments/page_header/template.html.j2 create mode 100644 src/site_engine/builtin/fragments/richtext/fragment.yaml create mode 100644 src/site_engine/builtin/fragments/richtext/style.css create mode 100644 src/site_engine/builtin/fragments/richtext/template.html.j2 create mode 100644 src/site_engine/builtin/fragments/section/fragment.yaml create mode 100644 src/site_engine/builtin/fragments/section/style.css create mode 100644 src/site_engine/builtin/fragments/section/template.html.j2 create mode 100644 src/site_engine/builtin/fragments/site_footer/fragment.yaml create mode 100644 src/site_engine/builtin/fragments/site_footer/style.css create mode 100644 src/site_engine/builtin/fragments/site_footer/template.html.j2 create mode 100644 src/site_engine/builtin/fragments/site_header/fragment.yaml create mode 100644 src/site_engine/builtin/fragments/site_header/style.css create mode 100644 src/site_engine/builtin/fragments/site_header/template.html.j2 create mode 100644 src/site_engine/cli.py create mode 100644 src/site_engine/core/__init__.py create mode 100644 src/site_engine/core/models.py create mode 100644 src/site_engine/core/registry.py create mode 100644 src/site_engine/core/render.py create mode 100644 src/site_engine/core/resolve.py create mode 100644 src/site_engine/core/routes.py create mode 100644 src/site_engine/core/validate.py create mode 100644 src/site_engine/core/values.py create mode 100644 src/site_engine/db/__init__.py create mode 100644 src/site_engine/db/engine.py create mode 100644 src/site_engine/db/models.py create mode 100644 src/site_engine/errors.py create mode 100644 src/site_engine/mcp/__init__.py create mode 100644 src/site_engine/mcp/server.py create mode 100644 src/site_engine/parsing/__init__.py create mode 100644 src/site_engine/parsing/frontmatter.py create mode 100644 src/site_engine/parsing/markdown.py create mode 100644 src/site_engine/parsing/yamlio.py create mode 100644 src/site_engine/services/__init__.py create mode 100644 src/site_engine/services/auth.py create mode 100644 src/site_engine/services/changeset.py create mode 100644 src/site_engine/services/content.py create mode 100644 src/site_engine/services/forms.py create mode 100644 src/site_engine/services/publish.py create mode 100644 src/site_engine/storage/__init__.py create mode 100644 src/site_engine/storage/fs.py create mode 100644 src/site_engine/storage/history.py create mode 100644 src/site_engine/storage/locks.py create mode 100644 src/site_engine/web/__init__.py create mode 100644 src/site_engine/web/admin/__init__.py create mode 100644 src/site_engine/web/app.py create mode 100644 tests/helpers.py create mode 100644 tests/test_build.py create mode 100644 tests/test_content_service.py create mode 100644 tests/test_fragments.py create mode 100644 tests/test_parsing.py create mode 100644 tests/test_routes.py create mode 100644 tests/test_security.py create mode 100644 tests/test_values.py diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..e9fa106 --- /dev/null +++ b/.gitignore @@ -0,0 +1,10 @@ +__pycache__/ +*.pyc +.venv/ +dist/ +build/ +*.egg-info/ +.engine/ +*.sqlite3 +.pytest_cache/ +.ruff_cache/ diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..deb7a0a --- /dev/null +++ b/Dockerfile @@ -0,0 +1,10 @@ +# M2+: образ для админки, форм и MCP. Статику в production отдаёт nginx из тома dist/. +FROM python:3.12-slim +WORKDIR /app +COPY pyproject.toml README.md ./ +COPY src ./src +RUN pip install --no-cache-dir ".[server,mcp]" +ENV SITE_ROOT=/data/site SITE_DIST=/data/dist SITE_DB=/data/db/engine.sqlite3 +VOLUME ["/data/site", "/data/dist", "/data/db"] +EXPOSE 8000 +CMD ["uvicorn", "site_engine.web.app:create_app", "--factory", "--host", "0.0.0.0", "--port", "8000"] diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..4a1a829 --- /dev/null +++ b/Makefile @@ -0,0 +1,10 @@ +.PHONY: test build-example validate-example + +test: + PYTHONPATH=src python -m unittest discover -s tests -v + +validate-example: + PYTHONPATH=src python -m site_engine.cli validate examples/studio-site + +build-example: + PYTHONPATH=src python -m site_engine.cli build examples/studio-site --out /tmp/studio-dist diff --git a/README.md b/README.md new file mode 100644 index 0000000..5f08025 --- /dev/null +++ b/README.md @@ -0,0 +1,86 @@ +# 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//` и симлинк `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/@<версия>.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/.yaml`, записи в `content//*.md`, при необходимости `display/.yaml`. +- **Новое правило сайта:** запись в `site.yaml: rules` (сейчас `require_fragment` для коллекции и `require_field` для форм). + +## Известные ограничения M0 + +- Поле `props` в шаблоне — объект `Props`: `props.items` читает поле «items», а не метод словаря. +- `layout.extends` проверяется на существование, наследование шаблонов делается обычным `{% extends 'layout/' %}`. +- CSS и JS собираются в один бандл с хешем в имени; минификации и изоляции по страницам пока нет. +- Нет приёма заявок, входа, MCP и админки: сетевая поверхность записи включается только вместе с контуром «вход, роли, аудит, лимиты» (ADR-006). diff --git a/docs/TZ-site-engine-architecture-review.md b/docs/TZ-site-engine-architecture-review.md new file mode 100644 index 0000000..d376990 --- /dev/null +++ b/docs/TZ-site-engine-architecture-review.md @@ -0,0 +1,317 @@ +# Архитектурное ревью ТЗ Site Engine v0.1 + +**Исходный документ:** `TZ-site-engine.md`, редакция от 06.11.2026 +**Тип ревью:** архитектура, модель данных, границы MVP, безопасность, MCP, эксплуатация +**Вердикт:** концепцию сохранить; до начала реализации уточнить контракты и пересобрать этапы. + +> Это ревью **того, что написано в ТЗ**. Предлагаемые изменения — архитектурные рекомендации, а не утверждение, что в существующей реализации уже есть ошибки. + +## 1. Резюме + +Направление удачное: файловый источник контента, типизированные фрагменты, статический результат, единый сервисный слой, CLI/MCP/админка и контролируемая публикация. Но текущий документ пытается одновременно определить универсальную CMS, контентную платформу, агентский редактор и редакционный workflow. Из-за этого первоначальная версия получается значительно сложнее, чем нужно для первого работающего сайта. + +### Исправить до старта (P0) + +1. **Граница файлов и SQLite:** `slug_history` сейчас хранит не восстанавливаемые из файлов правила редиректов. Это противоречит принципу переносимого сайта. Уточнить файловый источник и исключения. +2. **Контракт данных:** формально определить структуру страницы, ссылки, привязки, запросы, разрешение типов и поведение при отсутствующих значениях. Сейчас несколько разных синтаксисов описывают близкие операции. +3. **Редактирование и релизы:** разделить сохранение рабочего черновика, валидацию для публикации и собственно опубликованный релиз. Неполный черновик не должен быть запрещён только потому, что у него пока нет всех обязательных полей. +4. **Параллельные изменения:** ID блока не гарантирует отсутствие конфликтов. Нужны атомарные `if_match`-операции, версия файла, блокировка/транзакционная граница и пакетные изменения. +5. **Доверенная и недоверенная среда:** отдельно описать границы Python-миграций, Jinja, JS, превью, публичного доступа к файловым ассетам. Jinja sandbox — не полноценная песочница для произвольного кода. +6. **Последовательность этапов:** нельзя запускать пишущий MCP и формы без минимального контура auth/RBAC, аудита, безопасной публикации и надёжной очереди уведомлений. + +### Самое полезное упрощение + +Для первого сайта достаточно около **15 базовых фрагментов**, небольшого набора операций с коллекциями и одного способа публикации. Инкрементальные сборки, произвольный DSL запросов, сложные правила редакционной готовности, Python-миграции схем фрагментов и мощную CMS-аналитику стоит отложить до появления реальных случаев использования. + +## 2. Что оставить без фундаментальных изменений + +| Решение | Оценка | Уточнение | +|---|---|---| +| Файлы Markdown + YAML как канонический контент | Оставить | Фиксировать схему, стабильные ID и формат сериализации | +| FastAPI + Jinja + htmx | Оставить | Достаточно для первой версии без frontend SPA | +| Layout / Fragment / Block | Оставить | Чётче определить роли и наследование | +| Единый сервисный слой для CLI, MCP, UI | Обязательно оставить | Блокировка, проверка прав и аудит тоже должны быть там | +| Рендер в статический `dist` | Оставить | Чёткое разделение рабочего состояния и опубликованного | +| Строгая проверка на публикации | Оставить | Ослабить запрет на сохранение *незавершённых* черновиков | +| MCP с ограниченными правами | Оставить | По умолчанию только рабочее пространство/черновики | +| SQLite для заявок, сессий, аудита | Оставить | Для одиночного сайта нагрузка разумная | + +## 3. Архитектурные проблемы и решения + +### P0-01. File-first не полностью соблюдается + +**Где:** §2, §5.1, §13. +**Проблема:** при изменении `slug` старый URL попадает в историю, а `slug_history` по таблице раздела 13 не восстанавливается из файлов. После переноса каталога сайта и пересоздания БД история редиректов может исчезнуть. Значит, маршрутизация фактически зависит от скрытого состояния базы. + +**Решение:** редиректы — в `redirects.yaml`; автоматическая смена URL атомарно меняет маршрут и добавляет запись в этот файл. БД может индексировать редиректы. У пользователей, токенов, заявок, аудита и служебных логов иной жизненный цикл — это честно оговорённые исключения, не «контент сайта». + +**Критерий приёмки:** чистый `git clone` + `build` порождает ту же карту публичных маршрутов и редиректов без старой SQLite. + +### P0-02. Нужно выбрать формальную модель входных данных + +**Где:** §3.1, §4.4–4.8, §5.4. +В документе одновременно встречаются `source: body`, `source: entry.body`, `{bind: entry.title}`, `{page: contacts}`, `{collection: ...}`, `{children: current}`, `{{ entry.title }}` внутри SEO. Не описано, какие конструкции разрешены в каких полях, что является значением, ссылкой или вычисляемым выражением. + +**Предложение:** + +- Внутренняя модель: `Literal | Binding | LinkRef | Query` с явной нормализацией в конкретный тип поля. +- Унифицированные корни контекста: `site`, `page`, `entry`, `data`, `params` (для сборки лишь заранее известных статических параметров). +- Отсутствующая привязка: структурированная ошибка для обязательного поля, `null` для необязательного; никаких тихих подстановок пустых строк в обязательные поля. +- Ссылка на маршрут: типизированный объект, а не произвольный текст, с проверкой наличия *опубликованной* целевой страницы. +- Строковые выражения в YAML (например `seo.title: '{{ entry.title }}'`) либо запретить на старте, либо разрешить только безопасную ограниченную подстановку, без второго полноценного шаблонизатора. +- Для `source` использовать тот же `bind`, а не отдельный неформальный язык. + +В запросах для MVP разрешить только: `collection`, `ids`, `where.eq/in`, `sort`, `limit`. `offset`, произвольные `contains/gte/lte/not`, `related_to/by` и гибридные фильтры добавить после реального сценария. + +**Критерий приёмки:** схемы сериализуются/десериализуются обратно, типы проверяются до Jinja, неправильная привязка имеет точный путь к полю. + +### P0-03. Публикация не равна сохранению документа + +**Где:** §2.3, §4.5, §6.3–6.5, §10.2. +Фраза «невалидное не сохраняется» делает создание незавершённых страниц неудобным. А `status: published` не означает, что текущий файл уже присутствует в `dist/current`. + +**Предложение:** разделить три состояния: + +1. **Workspace** — редактируемые файлы (валидный синтаксис, допустимы неполные обязательные бизнес-поля у черновиков). +2. **Release candidate** — моментальный снимок файлов, прошедший *строгую* проверку всех публичных страниц, ссылок и ассетов. +3. **Live release** — конкретный `build_id`, на который указывает публикация. + +Статусы `draft`, `review`, `published`, `scheduled`, `archived` описывают включение контента в сборку, а не факт публикации конкретного изменённого файла. Добавить `publish_at` с таймзоной и scheduler только если отложенная публикация реально нужна. До этого `scheduled` можно убрать. + +**Критерий приёмки:** можно сохранить незавершённый черновик; валидная публикация не зависит от текущих незавершённых черновиков; неуспешная сборка не меняет `live`. + +### P0-04. ID блоков ≠ бесконфликтная запись + +**Где:** §2.4, §3.1, §10.2, §12.2. +Стабильный ID позволяет адресовать фрагмент, но два пользователя могут менять разные поля *одного YAML-файла*, и без контроля версий последняя запись перетрёт первую. Хеш в ТЗ есть, но не описана атомарность проверки+записи и работа с несколькими файлами при переносе/смене URL. + +**Предложение:** + +- Каждая запись требует `if_match: `; чтение возвращает этот хеш. +- Проверка хеша и атомарная запись выполняются под блокировкой конкретного документа, а не отдельными незащищёнными операциями. +- Конфликт — `409 Conflict` с текущей версией и машинно-читаемым diff. +- `move_block` принимает `target_region`, `target_slot`, `before_id` или `after_id`, а не позиционный индекс. +- Добавить `patch_page` для пакетного атомарного редактирования нескольких блоков одной страницы. +- Операции между файлами (`rename_page`, редирект, обновление меню) делать через транзакционный changeset/стейджинг с валидацией всего набора и безопасным коммитом. SQLite-транзакция сама по себе не охватывает файловую систему. + +**Критерий приёмки:** два параллельных писателя не теряют обновления; конфликт не оставляет частично записанных файлов. + +### P0-05. Безопасность шаблонов и привилегий + +**Где:** §4.4, §4.4 «Версии», §8.2 `embed_html`, §11.2. +Декларация «шаблоны сайта рендерятся в sandbox» создаёт впечатление, что сторонние шаблоны/JS/Python-миграции безопасно исполнять. Это неверная граница доверия: файл `script.js` исполняется в браузере посетителя, Python-файл миграции — в серверном процессе; Jinja sandbox не заменяет отдельную изоляцию недоверенного кода. + +**Предложение:** + +- **Контентные роли** меняют только данные, не исполняемый код. +- **Developer** добавляет Jinja/CSS/JS как проверяемый код сайта. Такие расширения считаются доверенными после ревью. +- По умолчанию не исполнять Python-миграции, поставленные вместе с произвольным сайтом; в MVP — декларативные миграции или отдельный процесс ручного обновления версии фрагмента. +- Превью — отдельный путь/желательно origin с жёсткими cookies, CSP, `noindex`, сроками действия и ограничением прав токена. Внешняя превью-ссылка не должна случайно открывать админку или чужие черновики. +- Сборка/рендер имеют лимиты на размер файлов, глубину рекурсии, число блоков и запросов, длительность выполнения. +- SVG в начальном MVP проще запретить или конвертировать в безопасный растровый формат, чем обещать универсальную санитизацию. + +**Критерий приёмки:** editor/agent не может добавить исполняемый шаблон, JS, миграционный скрипт или прочитать серверные секреты из шаблона. + +### P0-06. Структура публикации должна учитывать динамические формы + +**Где:** §6.1, §9.2, §13. +После отката статического `dist` HTML формы может ссылаться на прежнюю схему, в то время как `POST /forms/{id}` обрабатывает новую версию `forms/*.yaml`. При несовместимых изменениях старый опубликованный сайт перестанет отправлять заявки. + +**Предложение:** версионировать публичную схему формы или привязать форму к `build_id`, поддерживая переходные версии. Сначала сохранить заявку и событие уведомления в одной DB-транзакции; уведомления доставлять отдельным worker из SQLite outbox. Нужны `attempts`, backoff, `next_attempt_at`, idempotency key и зафиксированная политика повторов. + +**Критерий приёмки:** rollback восстанавливает не только внешний вид формы, но и её рабочую отправку; падение Telegram/email не теряет заявку. + +### P0-07. Переставить security раньше пишущего MCP + +**Где:** §11, §12, §15. +Сейчас MCP с записью включён в M1, а роли/токены/аудит — только в M2. Это небезопасный порядок релизов. В M1 также появляются формы, у которых уже есть персональные данные. + +**Предложение:** встроить в первый сетевой релиз минимальные `auth`, scopes, аудит мутаций, ограничения экспорта, политику секретов и data retention. Полноценный UI управления ролями может появиться позже; сам контроль доступа — нет. + +### P0-08. Статусы review/approval и MCP-согласование неполны + +**Где:** §4.5, §6.4, §11.1, §12.1. +Пример статусов в §4.5 пропускает `review`; указана команда `submit_for_review`, но не описаны `approve`, `request_changes` или привязка согласования к конкретной ревизии. Editor может публиковать и одновременно согласовывать, так что обязательное approval фактически отсутствует. + +**Предложение:** в MVP выбрать простой режим: `draft` → ручная публикация владельцем/редактором, без формального approval. Если review необходим, описать переходы, кто утверждает, кто публикует и что любое изменение после согласования аннулирует approval. + +## 4. Ошибки контракта и неоднозначности (P1) + +| ID | Место | Что уточнить | Предложение | +|---|---|---|---| +| P1-01 | §4.3, §4.7 | В `fixed`-блоках layout и блоках display template отсутствуют ID | Стабильный детерминированный ID из пути шаблона/ключа, который нельзя переименовать бесследно; отдельное пространство имён | +| P1-02 | §3.1, §4.7 | `overrides: allow` и `regions_mode` не определяют точную семантику замены | `append/prepend/replace` только для *региона*, а точечные overrides блоков — отдельный механизм позже | +| P1-03 | §4.4 | `id: hero` не уникален между категориями фрагментов | Канонический ID `marketing/hero` или иная явно заданная система namespace | +| P1-04 | §4.4, §4.6 | Мигрируют только схемы фрагментов, не схемы коллекций | Версионирование `collection.schema` и команда `migrate --dry-run` для обоих типов | +| P1-05 | §4.8 | `paginate` + `filters` конфликтует со статикой | Только заранее определённые маршруты/таксономии; произвольная фильтрация параметрами — client-side или динамический режим позже | +| P1-06 | §4.8, §6.1 | Запросы и зависимости через SQLite требуют синхронного индекса | Для MVP собирать нормализованный in-memory registry из файлов; SQLite использовать как восстанавливаемый кэш и БД сервиса | +| P1-07 | §5.1 | Роутинг не описывает нормализацию и collisions | Зафиксировать trailing slash, регистр, Unicode, percent encoding, reserved routes, конфликты редиректов/автомаршрутов | +| P1-08 | §5.5 | `hreflang` в v1 без полноценной реализации локалей | До появления переводов не генерировать `hreflang` для несуществующих версий; определить стратегию URL локалей | +| P1-09 | §7.4–7.5 | `requires`, `hidden`, `visibility`, `enabled`, `status` частично дублируют друг друга | Описать порядок применения, публикацию зависимых меню/ссылок и значения `null/false/0/[]` | +| P1-10 | §7.5 | `verified: true` не подтверждает реальную достоверность цифр | Ввести необязательную ссылку `evidence` и ручной статус проверки; валидатор может проверить наличие, но не истинность | +| P1-11 | §8.2 | Заявлено 22 MVP-фрагмента, перечислено 23 имени | Исправить количество и отделить семейства/варианты от самостоятельных фрагментов | +| P1-12 | §9.3, §13 | Аудит `before/after` может дублировать персональные данные удалённых заявок | Не сохранять значения ПД в аудите по умолчанию, логировать ID и тип операции; определить сроки хранения бэкапов/логов | +| P1-13 | §9.4 | CSV-экспорт заявок без политики безопасности | Экранировать формулы CSV, фиксировать факт экспорта в аудит, разграничить доступ и хранение | +| P1-14 | §12.1 | Есть `create_page`, но нет `delete_page`, `rename_page`, `delete_entry`; нет batch-патча | Уточнить минимальные жизненные операции и `patch_page` вместо расширения десятками однотипных команд | +| P1-15 | §6.2, §14 | 500 страниц за 10 с, страница за 1 с без определения нагрузки | Сначала базовый benchmark: конфигурация CPU/RAM, cold/warm, обработка изображений, полный/инкрементальный build | + +## 5. Где переусложнён MVP + +### 5.1. Слишком много специализированных фрагментов + +В §8.2 фактически **23 самостоятельных имени фрагментов в MVP** (если `site_header` и `site_footer` считать отдельно), хотя в тексте указано 22. И это не полный объём: помимо них нужны библиотека CSS/JS, конфигурации, рендер, схемы, превью и тесты. + +**Предлагаемое минимальное ядро: 15 фрагментов:** + +1. `site_header` +2. `site_footer` +3. `hero` +4. `page_header` +5. `section` +6. `richtext` +7. `image` +8. `card_grid` (варианты: features, steps, links) +9. `collection_list` +10. `entry_header` +11. `cta_banner` (варианты: контакт, внешняя ссылка, форма) +12. `form` +13. `faq` +14. `disclaimer` +15. `steps` — только если вариант `card_grid` семантически/стилистически недостаточен; иначе заменить на `contact_block`. + +В таком наборе `breadcrumbs` — встроенная функция `page_header`, `pagination` — часть `collection_list`, `requisites` — часть `site_footer` или обычных данных, `legal_text` — шаблон страницы с `richtext`. `feature_grid` обычно вариант `card_grid`; `contact_block` на старте может быть вариантом CTA/контента. `columns` вводить, когда доказано, что `section` со схемой сетки недостаточен. + +**Важно:** если цель именно собирать большой спектр лендингов, `columns` полезнее `steps`. Тогда берём `columns` вместо `steps`. Набор из 15 — ориентир для пилота, не догма. + +### 5.2. Универсальная политика готовности контента — не задача ядра + +**Где:** §7.1, §7.4, §7.5. +`plan.priority`, `plan.state`, `goal`, `next`, `data_ready`, `verified`, `features` образуют отдельную редакционную/проектную подсистему, вытекшую из одного примера сайта. + +**Предложение:** оставить в ядре `status`, `hidden`, `visibility` (последнее — возможно позже), обычные ссылки и строгие схемы. Всё планирование перенести в необязательный namespace `editorial` или `x-*`, доступный для проекта и MCP. Правила типа `scenario-disclaimer` — подключаемый набор валидаторов конкретного сайта, а не универсальная логика ядра. `requires` в MVP только явные `feature.` с чёткой булевой семантикой; `data.*` — позже. + +### 5.3. Упростить структуру файлов страниц + +Сейчас разрешены и `pages/*.md`, и `pages/*.yaml`. Для MVP можно поддержать **только Markdown с YAML front matter**, включая пустое тело. Это уменьшит число ветвей парсера, схем и миграций, сохранив читаемость Git. Добавление чисто YAML-страниц не является блокирующей функцией. + +Отдельно определить, что сложные структуры `regions` сериализуются стабильно, а пустой Markdown body допустим. + +### 5.4. Инкрементальность не должна определять первую архитектуру + +Собирать 500 небольших страниц из файлов и кешировать изображения может оказаться достаточно быстро без зависимостного графа. Предложение: сперва чистая детерминированная полная сборка, реальные профили времени и только потом граф `refs` и инкрементальные invalidation-правила. Граф полезен, но дорого тестируется: меню, шаблоны, тема и данные способны влиять на сотни страниц сразу. + +### 5.5. История Git и ревизии БД дублируют функции + +В ТЗ есть «каждое сохранение — Git-коммит» либо отдельный механизм `revisions`. На старте это две схемы работы, конфликтующие по UX и откатам. + +**Предложение:** Git рекомендован для разработки и агентских изменений; внутренние публикации сохраняют immutable release snapshot вне зависимости от Git; полноценный UI истории/undo — после MVP. Коммитить лучше *логическое изменение* / changeset, а не каждый клик автосохранения. + +## 6. MCP: меньший набор, более сильные контракты + +В спецификации большой список атомарных команд, но мало сказано о композиции, ревизиях и размерах результатов. + +**MVP API для агента:** + +| Назначение | Методы | +|---|---| +| Узнать возможности | `get_site_info`, `get_content_schema`, `list_pages`, `get_page`, `list_entries`, `get_entry`, `list_fragments` | +| Изменить | `create_page`, `patch_page`, `create_entry`, `update_entry`, `upload_asset` | +| Проверить | `validate`, `get_preview_url`, `get_diff` | +| Завершить | `submit_for_review` — лишь если в MVP реально есть review workflow | + +`patch_page` принимает список типизированных операций с `if_match` и `dry_run`; изменение URL — отдельная высокоуровневая операция `rename_page`, одновременно обновляющая редиректы. `publish` и `rollback` в MCP по умолчанию отключены. Доступ агенту — минимальные scopes, позволяющие работать с конкретными страницами или коллекциями, без чтения заявок. + +**Дополнительные обязательные контракты:** ограничения на размер ответа, пагинация `list_*`, размер/способ загрузки asset, срок жизни токена, structured error codes, max-op count, audit correlation ID, запрет широкого `update_data` вне явно разрешённых путей. + +Если требуется совместная работа с редактором, безопаснее по умолчанию модель **draft + optimistic concurrency + ручной publish**. Git-ветки `agent/*` опциональны для команд, которым они действительно нужны. + +## 7. Формы, приватность, обработка заявок + +**Технический контур:** + +1. Сохранить заявку и запись в outbox атомарно в SQLite. +2. Выдать успех после фиксации данных, независимо от Telegram/email. +3. Worker отправляет уведомления с backoff и видимым статусом доставки. +4. Ограничить size/число полей, проверять типы данных, экранировать сообщения в Telegram/email и CSV. +5. Согласие хранить как `policy_id`, `policy_version`/hash, `accepted_at`, язык и проверенную сервером отметку; не рассчитывать, что одна галочка универсально покрывает все правовые основания обработки. +6. Логи и аудит не должны оставлять вечные копии удалённых персональных данных. Для бэкапов указать срок и процедуру восстановления/удаления. +7. В публикации хранить версию формы; сервер принимает версию, с которой посетитель реально отправляет заявку. + +**Рекомендация для первой версии:** один канал (Telegram, поскольку он важен для сайта-примера), опциональный email/webhook — через интерфейс провайдера позднее. Не делать много каналов раньше гарантированной доставки одного. + +## 8. Границы безопасности, которые надо зафиксировать + +| Поверхность | Минимальный контроль | +|---|---| +| Markdown и text props | Autoescape + отдельная санитизация HTML после Markdown, без raw HTML по умолчанию | +| Jinja-фрагменты | Только подтверждённый developer-код, ограниченный контекст и лимиты рендера | +| `script.js` | Только developer, CSP, запрет inline handlers, версионный review | +| Python-миграции сайта | Не запускать автоматом из непроверенного сайта | +| Публичное превью | Токенизированный доступ, отдельная зона cookie/origin, `noindex`, ограниченный срок | +| Админка | Secure/HttpOnly/SameSite cookies, CSRF, rate-limit, аудит мутаций | +| MCP | Scope на объект/раздел, короткие токены, rate-limit, audit trail, `if_match` | +| Медиа | MIME sniffing, разрешённые форматы, лимиты, нормализация пути, карантин/обработка SVG | +| Файловая система | Нет записи вне site root, нет следования symlink наружу, контроль прав и путей | +| Заявки | RBAC, минимизация и сроки хранения ПД, защищённый экспорт, безопасные бэкапы | + +## 9. Обновлённые этапы реализации + +Предлагаю планировать не по списку подсистем, а по **вертикальным цепочкам, которые можно целиком проверить**. + +| Этап | Что реализовать | Готовность к выходу | +|---|---|---| +| **M0 — Контракт и статический прототип** | Форматы, модель Block/Layout/Fragment, 5–7 фрагментов, `load → validate → render`, один сайт, CLI | Чистая сборка сайта из Git без заранее подготовленной БД | +| **M1 — Публикуемый движок** | Маршруты, ссылки, базовая тема, превью, атомарная публикация/rollback, 404/SEO, draft vs live | Можно безопасно опубликовать и откатить полноценный небольшой сайт | +| **M2 — Коллекции и заявки** | Минимальные коллекции/display, query MVP, формы, SQLite outbox, минимальная админка заявок, аутентификация | Работает сайт услуг + отправка заявок, в том числе после отката | +| **M3 — MCP и редактор** | RBAC+аудит (базовые правила безопасности должны появиться до внешнего доступа), CAS/patch, MCP read/write, простая админка htmx | Человек и агент могут менять черновики без потери данных; публикация под контролем человека | +| **M4 — Расширение** | Остальные фрагменты, медиа-варианты, Git-workflow, поиск, инкрементальная сборка только по benchmark | Реальные потребности нескольких сайтов закрыты без усложнения ядра | +| **Позже** | Мультиязычная админка, сложные таксономии, визуальный editor-in-page, scheduled publication, extensions marketplace | Есть конкретные use cases и автоматические регрессионные тесты | + +**Замечание:** минимальную auth/authorization модель следует разработать уже на M1, если там появляется любой публичный API редактирования; в схеме выше внешние изменения подключаются на M3. + +## 10. Решения по открытым вопросам (§16) + +| Вопрос | Решение для MVP | Почему | +|---|---|---| +| Git обязателен? | **Не обязателен для runtime**, но рекомендован для разработки; релизы всегда immutable | Развёртывание проще, нет двух обязательных механизмов версионности | +| Поиск | **Отложить**; при необходимости статический JSON с клиентским поиском | Небольшие сайты не требуют серверного FTS | +| Мультиязычность | Только schema-ready; **не генерировать фиктивные hreflang** | Половинчатая поддержка создаёт ошибки SEO | +| Кто отдаёт статику | Nginx в production, FastAPI в dev | Ясное разделение нагрузки и обязанностей | +| Уведомления | Telegram + SQLite outbox сначала; дополнительные адаптеры потом | Надёжность важнее числа интеграций | +| Курсы и оплата | Внешний URL / форма заявки, без собственной кассы | Соответствует границам v1 | +| JS во фрагментах | Только доверенный developer-код, контентным ролям нельзя | Чёткая граница безопасности | +| Auth | Локальные аккаунты на старте, SSO позже | Минимум дополнительных зависимостей | +| Агент | Правка draft + `if_match`; публикация человеком; Git-ветки необязательны | Контроль и простота на первом этапе | +| Название | Не является блокирующим архитектурным решением | Не влияет на контракты | + +## 11. Набор обязательных тестов, которого не хватает в ТЗ + +- **Fresh clone test:** без старой SQLite работают маршруты, редиректы, сборка. +- **Round trip:** parse → serialize → parse не меняет дерево блоков и их ID. +- **Conflict test:** две одновременные операции на одной странице; одна получает 409, данные не теряются. +- **Invalid draft test:** черновик сохраняется, но неподготовленная страница не попадает в публичный релиз. +- **Broken reference test:** опубликованная страница не может ссылаться на неопубликованную/удалённую запись. +- **Route collision test:** обычные, сгенерированные, taxonomies, redirects и reserved paths не пересекаются. +- **Full rollback test:** HTML, ассеты, ссылки и формы продолжают работать после отката. +- **Partial failure test:** ошибка генерации изображений/Telegram/DB не портит `dist/current`. +- **Privilege escalation test:** agent/editor не может править фрагмент, читать ПД или публиковать без scope. +- **Preview isolation test:** токен превью не открывает админку и чужие черновики. +- **Performance test:** сравнить cold/warm build на фиксированном оборудовании до введения графа зависимостей. +- **Visual baseline:** помимо snapshot HTML — browser screenshots для 3 ширин экрана; особенно hero/header/footer и mobile navigation. + +## 12. Предлагаемые ADR + +Зафиксировать короткие ADR **до реализации** спорных системных решений: + +1. **ADR-001: file-first, SQLite only for service data/cache, redirect persistence in YAML.** +2. **ADR-002: composition model, typed bindings and query DSL subset.** +3. **ADR-003: workspace vs release vs live, rollback and dynamic form compatibility.** +4. **ADR-004: optimistic concurrency and atomic changesets.** +5. **ADR-005: trust model for templates, JS, agent and preview.** +6. **ADR-006: MVP scope and release milestones.** + +## 13. Итоговая рекомендация + +**Не перерабатывать концепцию целиком.** Сохранить файловый движок, FastAPI + htmx, композицию layout/fragment/block, минимальные коллекции и MCP. Основные усилия направить на определения контрактов, безопасность изменения контента и релизный процесс. Урезать первые версии до работающего сайта, где агент способен создавать/менять страницу, пользователь — смотреть превью, а публикация и rollback не теряют данные и не ломают формы. + +Главная опасность ТЗ — не выбор стека, а сложность, скрытая в сочетании **динамических привязок, схем, агентов, редакционных статусов и инкрементальной публикации**. Если эти подсистемы разрабатывать сразу как универсальную CMS, объём резко вырастет. Вертикальные срезы и строгие контракты позволят сохранить достоинства архитектуры и избежать ненужных затрат. diff --git a/docs/TZ-site-engine-decisions.md b/docs/TZ-site-engine-decisions.md new file mode 100644 index 0000000..c14a688 --- /dev/null +++ b/docs/TZ-site-engine-decisions.md @@ -0,0 +1,242 @@ +# Журнал решений по архитектурному ревью ТЗ Site Engine + +*Версия 0.1 · 6 ноября 2026 · основание: `TZ-site-engine-architecture-review.md` к ТЗ v0.1 · статус: проект решений, ждёт подтверждения (раздел 5)* + +## 1. Итог + +Концепцию сохраняем: файловый источник контента, Layout / Fragment / Block, единый сервисный слой, статический результат, FastAPI + Jinja + htmx. Принимаем все восемь замечаний P0 и 15 замечаний P1, упрощение MVP, новый порядок этапов и список обязательных тестов. По итогам этого документа ТЗ переиздаётся как v0.2 (раздел 4). + +**Где я отхожу от ревью (4 пункта):** + +1. **Блокировка записи** в MVP на весь сайт, а не на документ. Один сайт и редкие записи, поэтому простота важнее параллелизма; к блокировке на документ вернёмся, если замеры покажут ожидание. +2. **Страховочная история файлов** `.engine/history/` вместо полного отказа от ревизий. Если агент или человек перезапишет черновик, а Git не подключён, откатиться иначе будет не к чему (релизы хранят только опубликованное). +3. **Пятнадцатый фрагмент — `columns`**, а `steps` становится вариантом `card_grid`. Ревью оставляло выбор открытым; сайт-пример закрывается обоими вариантами, но `columns` полезнее для разнообразия лендингов. +4. **ID фрагментов плоские и уникальные в пределах сайта** (`hero`), а не `marketing/hero`. Категория нужна только для каталога; коллизия имён — ошибка, затенение запрещено. + +**Ошибки самого ТЗ, которые ревью верно нашло:** в MVP-наборе 23 фрагмента, а не 22; в 4.5 статусы без `review`, в 6.4 с ним; у блоков в `fixed` и display template нет ID; принцип «файлы — источник истины» нарушает `slug_history`; формулировка «невалидное не сохраняется» мешает вести черновики. + +## 2. Принятые решения (ADR) + +### ADR-001. Граница файлов и SQLite + +**Решение** + +- Источник истины — файлы. SQLite хранит только (а) служебные данные: пользователи, сессии, токены, аудит, заявки, outbox уведомлений, журнал сборок; (б) восстанавливаемый кэш: индекс страниц и записей, FTS, если появится поиск. +- Редиректы живут в `redirects.yaml`. `rename_page` атомарно меняет маршрут и дописывает запись в этот файл. Таблица `slug_history` убирается. +- Сборка не читает SQLite. Она строит в памяти нормализованный реестр (страницы, записи, фрагменты, данные) только из файлов и конфигурации, то есть остаётся чистой функцией от каталога сайта. Запросы к коллекциям выполняются по реестру. +- Из таблиц MVP убираются `slug_history`, `revisions`, `refs`, `locks`. Граф ссылок вернётся вместе с инкрементальной сборкой. + +**Критерий приёмки:** чистый `git clone` + `build` без старой SQLite даёт ту же карту маршрутов и редиректов. + +### ADR-002. Модель композиции, привязки и запросы + +**Решение.** Значение любого поля — один из четырёх типов, и до Jinja оно нормализуется в тип поля по схеме: + +```yaml +title: Заказная разработка # Literal +subtitle: {bind: entry.summary} # Binding: корни site, page, entry, data, params +cta: {page: contacts, label: Связаться} # LinkRef: page | entry | url (+ подпись) +items: # Query + query: + collection: services + where: {featured: true} # eq; или {tech: {in: [python, go]}} + sort: order + limit: 6 +``` + +- Тело страницы и записи подключаются привязкой: `{bind: page.body}`, `{bind: entry.body}`. Неформальное `source: body` убирается. +- Строки с `{{ ... }}` внутри YAML-значений (в том числе `seo.title`) запрещены. Вместо них `seo.title: {bind: entry.title}` и суффикс из `site.defaults.seo.title_suffix`. +- Отсутствующая привязка: для обязательного поля структурированная ошибка с путём, для необязательного `null`. Пустые строки молча не подставляются. +- LinkRef — типизированный объект; проверяется, что целевая страница или запись существует и опубликована. +- Запросы в MVP: `collection`, `ids`, `where` (eq и `in`), `sort`, `limit`. Отложены: `offset`, `contains/gte/lte/not`, `related_to/by`, `paginate`, `filters`, `children`. +- Порядок применения условий показа блока: `status` страницы → `hidden` → `requires`. `requires` содержит только флаги `feature.<имя>` (булева семантика, неизвестный флаг = ошибка). Поле `visibility` в MVP не вводится; `enabled` остаётся только у пунктов меню. +- Блоки в `fixed` layout и в display template получают явный `id` в файле (обязательное поле); автоматическая генерация по позиции не допускается. Пространства имён id: страница, layout и display template не пересекаются между собой. +- Режимы объединения регионов: `append`, `prepend`, `replace` только для региона целиком. Точечные переопределения блоков — отдельная функция позже. + +**Критерий приёмки:** round-trip parse → serialize → parse не меняет дерево блоков и их ID; типы проверяются до Jinja; ошибка привязки показывает точный путь к полю. + +### ADR-003. Workspace, release candidate, live и формы + +**Решение.** Три состояния вместо одного: + +| Состояние | Что это | Проверка | +|---|---|---| +| Workspace | Рабочие файлы | При сохранении: корректный YAML и Markdown, известные фрагменты, типы указанных значений. Обязательные «бизнес»-поля не требуются, пока `status: draft` | +| Release candidate | Снимок файлов, собранный как публичный сайт (только `published`) | Строгая: обязательные поля, ссылки на опубликованные цели, ассеты, коллизии маршрутов, правила сайта | +| Live | Конкретный `build_id`, на который указывает `current` | Неудачная сборка `live` не меняет | + +- Статусы контента: `draft`, `published`, `archived`. Статусы `review` и `scheduled` из v1 убираются; `publish_at` вернётся, когда понадобится отложенная публикация. +- Формального согласования в MVP нет: убираются роль `reviewer` и инструмент `submit_for_review`. Публикует владелец или редактор. +- **Формы и откат.** Каждый релиз содержит снимок определений форм (`forms/@<хеш>`). В HTML формы лежит `form_version`; сервер проверяет заявку по версии из релиза, которая хранится среди последних N релизов. Неизвестная версия даёт понятное сообщение посетителю и запись в лог. +- **Outbox.** Заявка и событие уведомления записываются в одной транзакции SQLite; успех показывается после фиксации. Отдельный worker доставляет уведомления с полями `attempts`, `next_attempt_at`, `idempotency_key` и backoff. Падение Telegram или почты заявку не теряет. +- Согласие хранится как `policy_id`, `policy_hash`, `accepted_at`, язык; одна галочка не считается универсальным правовым основанием, формулировки согласует юрист владельца. + +**Критерий приёмки:** черновик с пустыми обязательными полями сохраняется, но не попадает в релиз; сбой сборки не портит `dist/current`; после rollback форма продолжает отправлять заявки; падение уведомлений не теряет заявку. + +### ADR-004. Параллельные изменения + +**Решение** + +- Любое чтение возвращает `etag` (хеш содержимого). Любая запись (админка, MCP, CLI) требует `if_match`. +- Путь записи: взять межпроцессную блокировку сайта (файловый lock) → сверить хеш → подготовить изменение во временном каталоге → провалидировать весь набор → закоммитить → снять блокировку. В MVP блокировка на весь сайт. +- Конфликт возвращается как `409` с текущей версией и структурным diff. +- `patch_page` принимает упорядоченный список типизированных операций; применяется «всё или ничего», поддерживает `dry_run` и лимит числа операций: + +```json +{ + "page": "services/index", + "if_match": "sha256:9f2c...", + "dry_run": true, + "ops": [ + {"op": "set_prop", "block": "b_7k2m", "path": "props.title", "value": "Новый заголовок"}, + {"op": "move_block", "block": "b_9xq1", "target_region": "main", "after": "b_7k2m"}, + {"op": "add_block", "target_region": "main", "after": "b_9xq1", "block": {"fragment": "faq", "props": {}}} + ] +} +``` + +- `move_block` принимает `target_region`, `target_slot` и `before` либо `after` (id блока), позиционные индексы не используются. +- Операции над несколькими файлами (`rename_page`, `delete_page`, `delete_entry`, обновление меню) выполняются как changeset: staging → проверка всего набора → commit с журналом `.engine/journal` для восстановления после сбоя. Оговорка: файловая система не транзакционна, поэтому гарантируем восстановимость после сбоя, а не атомарность на уровне ОС. +- История: перед каждой записью предыдущая версия сохраняется в `.engine/history/` (последние 20 на файл). Git необязателен; если каталог сайта — репозиторий, делается один коммит на changeset с автором (человек или агент). Автосохранения не коммитятся, ветки `agent/*` по умолчанию не создаются. +- Удаление: `delete_*` требует отдельного scope `content:delete`; агенту по умолчанию выключено (вместо удаления — статус `archived`). + +**Критерий приёмки:** два параллельных писателя не теряют обновления; `kill -9` в середине commit не оставляет наполовину записанных файлов, сайт восстанавливается по журналу. + +### ADR-005. Модель доверия + +| Кто | Что меняет | Уровень доверия | +|---|---|---| +| owner, developer | Исполняемое: Jinja, CSS, JS, схемы фрагментов и коллекций | Доверенный код; меняется через репозиторий и ревью | +| editor | Данные: страницы, записи, меню, `data/` | Только данные | +| agent | Данные в рамках scope | Только данные, минимальные права | +| Посетитель, внешний получатель превью | Отправка форм; просмотр по токену | Недоверенный | + +**Решение** + +- `SandboxedEnvironment` Jinja остаётся защитой второго эшелона, но не границей безопасности. Граница — роли: контентные роли не могут добавлять шаблоны, JS и скрипты. +- Лимиты рендера: размер файлов, число блоков, глубина вложенности, число запросов, время рендера. +- Python-миграции из каталога сайта не исполняются. Только декларативные операции (`rename_field`, `set_default`, `remove_field`, `map_value`) и команда `migrate --dry-run`; версионируются и схемы фрагментов, и схемы коллекций. +- Превью: отдельный путь (`/_preview//`) или отдельный хост (`preview_base_url`); токен случайный, с сроком жизни, областью (страница или набор) и возможностью отзыва; `noindex`, собственный CSP, админские cookie не отправляются, чужие черновики недоступны. +- Raw HTML в Markdown выключен, после рендера Markdown идёт санитайзер, в шаблонах включён autoescape. +- SVG: загрузка через админку и MCP запрещена в MVP; SVG из репозитория (код разработчика) допускается. Фрагмент `embed_html` убирается из каталога. +- Файловая система: запись только внутри корня сайта, symlink наружу не разыменовываются, пути нормализуются. +- В контексте шаблонов нет переменных окружения и секретов. +- Админка: Secure, HttpOnly, SameSite cookie, CSRF, лимит попыток входа, аудит мутаций. MCP: scope на раздел или коллекцию, короткоживущие токены, лимиты запросов, `correlation_id` в аудите. +- Заявки: RBAC, сроки хранения, CSV-экспорт с экранированием формул и записью факта экспорта в аудит; аудит не хранит значения ПД, только id и тип операции; срок хранения бэкапов и процедура удаления фиксируются. + +**Критерий приёмки:** editor и agent не могут добавить исполняемый шаблон, JS или скрипт миграции, прочитать секреты и ПД, опубликовать без scope; токен превью не открывает админку и чужие черновики. + +### ADR-006. Границы MVP и этапы + +**Ядро: 15 фрагментов.** `site_header`, `site_footer`, `hero`, `page_header`, `section`, `columns`, `richtext`, `image`, `card_grid`, `collection_list`, `entry_header`, `cta_banner`, `form`, `faq`, `disclaimer`. + +Остальное — варианты и свойства этих фрагментов, а не отдельные фрагменты: + +- `card_grid` покрывает преимущества (`features`), этапы (`steps`) и ссылки (`links`); +- `cta_banner` покрывает контакт, внешнюю ссылку и переход к форме; контакты берутся из `site.contacts`; +- `site_header` и `site_footer` сами выводят меню; реквизиты берутся из `data/company.yaml`; +- `page_header` выводит хлебные крошки; `legal_text` — layout `legal` с `richtext`; +- карточки списка — именованные варианты внутри `collection_list`; пустое состояние (`empty`) — его параметр. + +**Отложено за пределы MVP:** страницы в чистом `.yaml` (только Markdown с front matter, пустое тело допустимо); инкрементальная сборка и граф `refs` (сначала полная детерминированная сборка и замеры); поиск; `hreflang` и мультиязычность (только модель данных); `scheduled` и `review`; `visibility`; `requires: data.*`; Python-миграции; `embed_html`; пагинация, `offset` и расширенные запросы; фрагменты `stats`, `live_examples`, `chat_demo`, `gallery` и прочие из версии «v1». + +**Редакционная подсистема не в ядре.** `plan`, `goal`, `next`, `data_ready` и признак подтверждения цифр переносятся в необязательное пространство `editorial` (ядро его не интерпретирует, но отдаёт через MCP и админку). Вместо булева `verified` — необязательное поле `evidence` (ссылка или пояснение): валидатор проверяет наличие, а не истинность. Правила вроде `scenario-disclaimer` — декларативный набор правил конкретного сайта (`require_fragment`, `require_field`, `require_key`), а не логика ядра. Флаги `features` остаются в `site.yaml`. Блоки 3 и 5 главной сайта-примера, пока нет фрагментов `stats` и `live_examples`, хранятся записями в `editorial.excluded_blocks` и возвращаются вместе с фрагментами. + +**Набор MCP-инструментов MVP** + +| Назначение | Инструменты | +|---|---| +| Узнать возможности | `get_site_info` (схемы, правила, флаги, `editorial`), `list_pages`, `get_page`, `list_entries`, `get_entry`, `list_fragments` | +| Изменить | `create_page`, `patch_page`, `rename_page`, `create_entry`, `update_entry`, `upload_asset` | +| Проверить | `validate`, `get_preview_url`, `get_diff` | + +`publish` и `rollback` в MCP выключены по умолчанию. Обязательные контракты: пагинация и лимит размера ответа у `list_*`, лимит размера и способ загрузки ассетов, срок жизни токена, структурированные коды ошибок, максимум операций в `patch_page`, `correlation_id`. Широкого `update_data` нет: запись только по явно разрешённым путям. + +**Этапы** (по вертикальным срезам, каждый проверяется целиком) + +| Этап | Состав | Выход | +|---|---|---| +| M0. Контракт и прототип | Форматы, модель Block/Layout/Fragment, 5–7 фрагментов, `load → validate → render`, один сайт, CLI | Чистая сборка из каталога без заранее подготовленной БД | +| M1. Публикуемый движок | Маршруты и ссылки, базовая тема, превью с токеном, атомарная публикация и rollback, 404 и SEO, draft vs live | Небольшой сайт безопасно публикуется и откатывается | +| M2. Коллекции, заявки, доступ | Минимальные коллекции и display, запросы MVP, формы, outbox, админка заявок; **вход, роли owner и editor, аудит мутаций, лимиты запросов** | Сайт услуг принимает заявки, в том числе после отката | +| M3. MCP и редактор | Optimistic concurrency, `patch_page`, MCP на чтение и запись со scope, htmx-админка | Человек и агент меняют черновики без потери данных; публикует человек | +| M4. Расширение | Остальные фрагменты, медиа-варианты, Git-workflow, поиск, инкрементальная сборка только по замерам | Закрыты реальные потребности нескольких сайтов | +| Позже | Мультиязычная админка, сложные таксономии, редактор на странице, отложенная публикация | Есть конкретные сценарии и регрессионные тесты | + +Правило порядка: никакая сетевая поверхность записи (редактирование в админке, MCP на запись, формы с ПД) не включается раньше базового контура «вход, роли, аудит, лимиты». Для M2 он включён в состав этапа, а не отнесён на M3, как в таблице ревью, потому что админка заявок открывает доступ к ПД уже на M2. + +**Решения по открытым вопросам ТЗ (раздел 16)** + +| Вопрос | Решение для MVP | +|---|---| +| Git | Не обязателен в runtime, рекомендован для разработки; релизы — неизменяемые снимки | +| Поиск | Отложен; при необходимости статический JSON с клиентским поиском | +| Мультиязычность | Только заложить модель; `hreflang` не генерировать | +| Кто отдаёт статику | nginx в production, FastAPI в dev | +| Уведомления | Только Telegram и SQLite outbox; email и webhook позже через интерфейс провайдера | +| Оплата курсов | Внешний URL или форма заявки, без собственной кассы | +| JS во фрагментах | Только доверенный код разработчика | +| Вход в админку | Локальные аккаунты, SSO позже | +| Режим агента | Правка черновика с `if_match`, публикация человеком, ветки Git необязательны | +| Название | Не блокирует архитектуру | + +## 3. Реестр решений по замечаниям ревью + +| Замечание | Решение | Где | +|---|---|---| +| P0-01 file-first и `slug_history` | Принято | ADR-001 | +| P0-02 формальная модель данных | Принято | ADR-002 | +| P0-03 публикация ≠ сохранение | Принято | ADR-003 | +| P0-04 конфликты записи | Принято с изменением: блокировка на сайт, страховочная история | ADR-004 | +| P0-05 границы доверия | Принято | ADR-005 | +| P0-06 формы и откат | Принято | ADR-003 | +| P0-07 безопасность раньше MCP | Принято; базовый контур входит в M2 | ADR-006 | +| P0-08 review и approval | Принято: формального согласования в MVP нет | ADR-003 | +| P1-01 ID в `fixed` и display | Принято с изменением: явный `id` в файле, автоматических по позиции нет | ADR-002 | +| P1-02 семантика overrides | Принято: только регион целиком | ADR-002 | +| P1-03 уникальность `id` фрагментов | Принято с изменением: плоские уникальные id | раздел 1 | +| P1-04 миграции схем коллекций | Принято, декларативные | ADR-005 | +| P1-05 пагинация и фильтры | Принято: отложены | ADR-006 | +| P1-06 индекс для запросов | Принято: реестр в памяти из файлов | ADR-001 | +| P1-07 нормализация маршрутов | Принято: правила в разделе 5.1 ТЗ v0.2 | раздел 4 | +| P1-08 `hreflang` | Принято: не генерировать | ADR-006 | +| P1-09 порядок `requires`, `hidden`, `status` | Принято | ADR-002 | +| P1-10 `verified` | Принято с изменением: `editorial.evidence` | ADR-006 | +| P1-11 счёт фрагментов | Принято, пересчитано: 15 | ADR-006 | +| P1-12 ПД в аудите | Принято | ADR-005 | +| P1-13 CSV-экспорт | Принято | ADR-005 | +| P1-14 жизненный цикл страниц | Принято: `rename_page`, `patch_page`, удаление под scope | ADR-004, ADR-006 | +| P1-15 бенчмарк | Принято: цели заменяются замерами | ADR-006 | +| 5.1 15 фрагментов | Принято с изменением: `columns` вместо `steps` | ADR-006 | +| 5.2 редакционная подсистема | Принято | ADR-006 | +| 5.3 только Markdown-страницы | Принято | ADR-006 | +| 5.4 инкрементальность | Принято: после замеров | ADR-006 | +| 5.5 Git и ревизии | Принято с изменением: добавлена история файлов | ADR-004 | +| 6 MCP | Принято | ADR-006 | +| 7 формы | Принято | ADR-003 | +| 8 границы безопасности | Принято | ADR-005 | +| 9 этапы | Принято с изменением: контур доступа в M2 | ADR-006 | +| 10 открытые вопросы | Принято | ADR-006 | +| 11 тесты | Принято: входят в ТЗ и в критерии этапов | раздел 4 | +| 12 ADR | Этот документ | — | + +## 4. Что меняется в ТЗ (версия 0.2) + +- **Раздел 2.** Принцип 6: песочница Jinja — второй эшелон, граница — роли. Принцип 3: на сохранении проверяются синтаксис и типы, на публикации — полнота. +- **Разделы 3–4.** Четыре типа значений (4.8 переписать); убрать `{{ }}` из YAML; `source` заменить привязкой; убрать `.yaml`-страницы; явные `id` в `fixed` и display; плоские `id` фрагментов; декларативные миграции вместо `migrations/*.py`; статусы `draft`, `published`, `archived`. +- **Раздел 5.** Добавить правила маршрутов: завершающий слэш, регистр, Unicode и percent-encoding, зарезервированные пути, коллизии редиректов и автомаршрутов; убрать `hreflang`, `children`, `paginate`. +- **Раздел 6.** Состояния workspace, release candidate, live; убрать инкрементальность, `scheduled`, `review`; историю заменить на `.engine/history/` и необязательный Git; цели по времени сборки заменить замерами. +- **Раздел 7.** `plan`, `goal`, `next`, `data_ready`, `verified` перенести в `editorial`; правила сделать декларативным набором сайта; `requires` оставить только для `feature.*`; блоки 3 и 5 хранить в `editorial.excluded_blocks`. +- **Раздел 8.** Каталог заменить 15 фрагментами и их вариантами. +- **Раздел 9.** Outbox, версия формы в релизе, один канал (Telegram), структура согласия, аудит без ПД, безопасный CSV-экспорт. +- **Разделы 10–12.** `if_match` во всех формах админки; набор MCP из ADR-006, `patch_page`, `rename_page`, `publish` и `rollback` выключены по умолчанию, лимиты, пагинация, коды ошибок, `correlation_id`; роль `reviewer` убрать. +- **Раздел 13.** Убрать `slug_history`, `revisions`, `refs`, `locks`; добавить `outbox`. +- **Раздел 14.** Добавить 12 обязательных тестов из ревью (fresh clone, round trip, конфликты, невалидный черновик, битые ссылки, коллизии маршрутов, полный rollback, частичные сбои, эскалация привилегий, изоляция превью, производительность, визуальные базовые снимки). +- **Разделы 15–16.** Этапы заменить таблицей из ADR-006; открытые вопросы заменить принятыми решениями. + +## 5. К подтверждению + +1. Четыре отступления от ревью (раздел 1): блокировка на сайт, `.engine/history/`, `columns` вместо `steps`, плоские `id` фрагментов. +2. Превью: отдельный хост или путь с токеном (отдельный поддомен нужен, если превью будут показывать внешним согласующим). +3. Сайт-пример (студия ботов и Академия) использовать как тестовый набор для M0–M2? +4. Юридическая часть по ПД (формулировки согласия, сроки хранения, место размещения сервера) остаётся за владельцем сайта и его юристом. diff --git a/docs/TZ-site-engine.md b/docs/TZ-site-engine.md new file mode 100644 index 0000000..131a9e9 --- /dev/null +++ b/docs/TZ-site-engine.md @@ -0,0 +1,769 @@ +# ТЗ: движок сайтов на Markdown + YAML и фрагментах + +*Черновик v0.1 · 6 ноября 2026 · на ревью · рабочее название проекта пока не задано* + +## Что просим проверить на ревью + +1. Источник истины: файлы (md + yaml), SQLite только как индекс и служебные данные (разделы 2, 13). +2. Модель Layout / Fragment / Block, привязки и запросы (разделы 3–4). +3. Расширения модели по итогам карты сайта-примера (раздел 7.4) и правила контента (7.5). +4. Состав MVP-набора фрагментов (раздел 8.2). +5. Права агента и набор MCP-инструментов (разделы 11–12). +6. Этапы и открытые вопросы (разделы 15–16). + +## Содержание + +1. Цели и границы +2. Принципы архитектуры +3. Модель сущностей +4. Форматы файлов +5. Структура сайта и маршрутизация +6. Сборка, превью и публикация +7. Опорный пример: студия ботов, AI-систем и автоматизаций +8. Базовый набор фрагментов +9. Формы и заявки +10. Админка (FastAPI + htmx) +11. Роли, права и безопасность +12. MCP-сервер +13. Данные в SQLite (SQLAlchemy) +14. Нефункциональные требования +15. Этапы +16. Открытые вопросы + +## 1. Цели и границы + +Самохостимый движок, в котором сайт — это каталог файлов (Markdown + YAML), а страницы собираются из **layouts** и **fragments** (строительных блоков в духе Liferay). С движком одинаково удобно работать человеку (админка), агенту (MCP) и разработчику (git, CLI). + +**Задачи v1** + +- Контент, структура и шаблоны хранятся в файлах (md + yaml); SQLite хранит индекс и служебные данные. +- Страница = layout + дерево блоков; блок = экземпляр фрагмента со схемой полей. +- Типизированные коллекции контента (кейсы, продукты, услуги и т.д.) со списками, страницами записей, связями и таксономиями. +- Многостраничные сайты: разделы, меню, хлебные крошки, пагинация, редиректы, заготовка под мультиязычность. +- Статическая сборка и динамическое превью, публикация атомарной заменой каталога. +- Админка на FastAPI + htmx; MCP-сервер для агентов с правами и валидацией. +- Новые фрагменты и коллекции добавляются файлами, без правки ядра. + +**Вне v1:** визуальный drag-and-drop прямо по странице, мультитенантность, e-commerce и платежи, личные кабинеты посетителей, комментарии. + +**Стек:** Python 3.12+, FastAPI, SQLAlchemy 2 + SQLite (WAL), Alembic, Jinja2, pydantic v2, YAML (только safe load), markdown-it-py, Pillow, MCP Python SDK; в админке htmx (+ SortableJS, EasyMDE). Node-сборки нет. + +## 2. Принципы архитектуры + +1. **Файлы — источник истины.** БД перестраивается командой `reindex`; исключение — служебные таблицы (пользователи, токены, аудит, заявки с форм). +2. **Один сервисный слой.** Админка, MCP и CLI вызывают одни и те же сервисы, поэтому права, валидация и аудит едины. +3. **Всё, что пишется, проходит схему.** Фрагменты и коллекции описаны схемами; невалидное не сохраняется и не публикуется. +4. **Стабильные ID блоков.** Блок адресуется по `id`, а не по индексу, поэтому страницу безопасно патчить параллельно (человек и агент). +5. **Статика по умолчанию.** Динамика только там, где без неё нельзя: формы, поиск, превью. +6. **Безопасность по умолчанию.** Шаблоны сайта рендерятся в sandbox, права разделены по ролям (раздел 11). +7. **Детерминированная сериализация.** Порядок ключей и форматирование YAML фиксированы, чтобы диффы в git были читаемыми. +8. **Расширение файлами.** Фрагмент, layout или коллекция — это папка или файл, а не код ядра. + +## 3. Модель сущностей + +| Сущность | Что это | Где хранится | +|---|---|---| +| Site | Настройки сайта: домены, локали, тема, умолчания | `site.yaml` | +| Page | Страница, собранная вручную из блоков | `pages/**/*.md` или `*.yaml` | +| Layout | Каркас страницы: HTML-оболочка + регионы | `layouts//` | +| Fragment | Блок: шаблон + схема полей + стили/скрипты | `fragments/<категория>//` | +| Block | Экземпляр фрагмента на странице | внутри page или display template | +| Collection | Тип контента со схемой (cases, products...) | `collections/.yaml` | +| Entry | Запись коллекции | `content//.md` | +| Display template | Как запись коллекции превращается в страницу | `display/.yaml` | +| Taxonomy | Словарь терминов (технологии, отрасли, теги) | коллекция с `kind: taxonomy` | +| Menu | Навигация | `menus/.yaml` | +| Data | Произвольные данные (цены, команда, реквизиты) | `data/*.yaml` | +| Form | Определение формы обратной связи | `forms/.yaml` | +| Asset | Изображения и файлы | `assets/` | + +### 3.1 Блок и дерево композиции + +Поля блока: `id` (короткий стабильный, например `b_7k2m`), `fragment`, `props`, `slots` (именованные списки вложенных блоков), опционально `hidden`, `anchor`, `visibility` (по локали и датам). + +Layout объявляет **регионы**, фрагмент объявляет **слоты**; и то и другое — упорядоченные списки блоков. Фрагмент может ограничивать допустимых детей (`allow`), максимальную глубину вложенности задаёт ядро (по умолчанию 4). + +Значения `props` бывают четырёх видов: литерал; привязка `{bind: путь}`; ссылка на страницу или запись `{page: slug}` / `{entry: коллекция/slug}`; запрос к коллекции `{collection: ...}` (см. 4.8). + +## 4. Форматы файлов + +### 4.1 Структура каталога сайта + +``` +site/ + site.yaml + redirects.yaml + pages/ # ручные страницы; путь файла = URL + index.md + about.md + services/ + _section.yaml # настройки раздела: layout, меню, сортировка + index.md + content/ # записи коллекций + cases/clinic-crm.md + products/ + collections/ # схемы коллекций + display/ # шаблоны отображения записей + layouts/ + fragments/ + menus/ forms/ data/ assets/ +``` + +### 4.2 site.yaml + +```yaml +schema: 1 +name: Acme Dev +base_url: https://acme.example +default_locale: ru +locales: [ru, en] +theme: + tokens: + color.primary: '#0b5fff' + font.body: 'Inter, system-ui, sans-serif' + space.section: 4rem +defaults: + layout: default + seo: {title_suffix: ' — Acme Dev'} +menus: {main: main, footer: footer} +``` + +Фрагменты используют токены темы как CSS-переменные (`var(--color-primary)`), а не зашитые значения: смена оформления не требует правки фрагментов. + +### 4.3 Layout + +```yaml +# layouts/default/layout.yaml +id: default +name: Основной +extends: base # необязательно: наследование оболочки +regions: + - {id: header, fixed: [{fragment: site_header}]} # закреплённые блоки + - {id: main, allow: [section, hero, richtext, 'collection_*']} + - {id: footer, fixed: [{fragment: site_footer}]} +``` + +```jinja +{# layouts/default/layout.html.j2 #} + + +{{ seo_head() }}{{ assets_head() }} + + {{ region('header') }} +
{{ region('main') }}
+ {{ region('footer') }} + {{ assets_body() }} + + +``` + +`fixed`-блоки принадлежат layout и не редактируются на странице; регион с `allow` ограничивает набор фрагментов, которые можно туда ставить. + +### 4.4 Фрагмент + +```yaml +# fragments/marketing/hero/fragment.yaml +id: hero +name: Hero-баннер +category: marketing +version: 1 +fields: + - {key: title, type: text, required: true, max: 120} + - {key: subtitle, type: markdown, inline: true} + - {key: image, type: asset, accept: [image]} + - {key: cta, type: link} + - {key: variant, type: select, options: [light, dark, split], default: light} +slots: {} +preview: {title: Заголовок страницы, variant: dark} +``` + +```jinja +{# fragments/marketing/hero/template.html.j2 #} +
+

{{ props.title }}

+ {% if props.subtitle %}
{{ props.subtitle|md_inline }}
{% endif %} + {% if props.cta %}{{ props.cta.label }}{% endif %} +
+``` + +**Состав папки фрагмента:** `fragment.yaml` (манифест), `template.html.j2`, необязательные `style.css` и `script.js`, `preview.yaml` (данные для превью в админке). + +**Типы полей:** `text`, `textarea`, `markdown`, `number`, `boolean`, `select`, `multiselect`, `date`, `datetime`, `color`, `icon`, `slug`, `link` (страница, запись или URL + подпись + target), `asset` (изображение или файл), `ref` и `refs` (ссылки на записи коллекций), `group` (вложенный объект), `list` (повторяемая группа полей), `query` (запрос к коллекции), `json` (только для разработчиков). + +**Контекст шаблона:** `props`, `slots`, `page`, `site`, `entry` (на страницах записей), `block` (id, anchor), хелперы `href`, `md`, `md_inline`, `asset_url`, `image` (адаптивные варианты), `t` (строки интерфейса). + +**CSS и JS:** подключаются на страницу один раз на фрагмент (дедупликация), CSS изолируется префиксом `.f-`; при сборке всё собирается в хешированные бандлы. Фрагменты не должны зависеть от внешних CDN. + +**Версии:** при несовместимом изменении схемы фрагмента увеличивается `version`, рядом кладётся миграция `migrations/1_to_2.py` (или декларативная карта переименований полей); `validate` и админка показывают блоки, требующие миграции. + +### 4.5 Страница + +```markdown +--- +schema: 1 +title: Заказная разработка +layout: default +status: published # draft | published | scheduled | archived +seo: + description: Разработка ПО под ключ + og_image: assets/og/services.png +regions: + main: + - id: b_7k2m + fragment: hero + props: + title: Заказная разработка ПО + variant: dark + cta: {page: contacts, label: Обсудить проект} + - id: b_9xq1 + fragment: collection_list + props: + source: {collection: services, sort: order, limit: 6} + card: service_card + - id: b_3d8f + fragment: richtext + props: {source: body} +--- +Основной текст страницы в Markdown. Он доступен как `page.body` +и выводится фрагментом `richtext` с `source: body`. +``` + +Если у страницы есть тело, но ни один блок его не использует, `validate` выдаёт предупреждение. Страницы без текста могут быть чистыми `.yaml`-файлами с теми же полями. + +### 4.6 Коллекция и запись + +```yaml +# collections/cases.yaml +id: cases +name: Кейсы +route: /cases/{slug}/ +list_page: /cases/ +display: cases # display/cases.yaml +sort: -date +body: markdown # тело записи — Markdown +fields: + - {key: title, type: text, required: true} + - {key: summary, type: textarea} + - key: client + type: group + fields: + - {key: name, type: text} + - {key: industry, type: ref, to: industries} + - {key: confidential, type: boolean} + - {key: services, type: refs, to: services} + - {key: products, type: refs, to: products} + - {key: tech, type: refs, to: technologies} + - key: metrics + type: list + fields: [{key: label, type: text}, {key: value, type: text}] + - {key: cover, type: asset} + - {key: date, type: date} +``` + +```markdown +--- +title: CRM для сети клиник +slug: clinic-crm +status: published +client: {name: Клиника+, industry: healthcare} +services: [web-development, integrations] +tech: [python, postgresql, react] +metrics: + - {label: Сокращение времени записи, value: '−40%'} +cover: assets/cases/clinic.webp +date: 2026-03-12 +--- +## Задача +Текст кейса в Markdown... +``` + +Коллекции с `kind: taxonomy` (технологии, отрасли, теги) — это те же коллекции, но их записи обычно без тела; для них движок сам строит страницы терминов (`/cases/tag/python/`) по настройке `taxonomy_pages`. + +### 4.7 Display template: запись → страница + +```yaml +# display/cases.yaml +layout: default +seo: + title: '{{ entry.title }}' + description: '{{ entry.summary }}' +regions: + main: + - fragment: entry_header + props: {title: {bind: entry.title}, meta: [{bind: entry.client.name}, {bind: entry.date}]} + - fragment: entry_facts + props: {items: {bind: entry.metrics}} + - fragment: richtext + props: {source: entry.body} + - fragment: related_entries + props: + source: {collection: cases, related_to: entry, by: [services, tech], limit: 3} + - fragment: cta_banner + props: {title: Обсудим ваш проект?, cta: {page: contacts, label: Связаться}} +overrides: allow # запись может дополнять или заменять блоки своим regions +``` + +Когда у записи в front matter есть собственный `regions`, он объединяется с шаблоном по id региона в режиме `append`, `prepend` или `replace` (`regions_mode`, по умолчанию `append`). Так типовая страница остаётся типовой, а особый случай получает уникальные блоки без отдельного шаблона. + +### 4.8 Привязки и запросы + +**Привязка** `{bind: путь}` читает значение из контекста: `entry`, `page`, `site`, `data.<файл>`, `params` (параметры пагинации и фильтров). Ссылки `{page: slug}` и `{entry: коллекция/слаг}` при сборке превращаются в URL с учётом локали; битая ссылка — ошибка сборки. + +**Запрос** (`type: query` или `source:`): + +| Ключ | Назначение | +|---|---| +| `collection` | коллекция-источник | +| `where` | условия: `eq`, `in`, `contains`, `gte`, `lte`, `not` по полям записи, в том числе по `refs` | +| `sort`, `limit`, `offset` | порядок и срез (`-date` — убывание) | +| `paginate` | размер страницы; движок генерирует `/page/2/` и т.д. | +| `ids` | ручной выбор записей в нужном порядке | +| `related_to`, `by` | похожие записи по общим значениям связей | +| `locale` | локаль выборки (по умолчанию текущая) | + +Запросы выполняются при сборке по индексу в SQLite. Зависимости (какая страница читает какие записи) пишутся в граф, чтобы инкрементальная сборка пересобирала только затронутое. + +## 5. Структура сайта и маршрутизация + +### 5.1 Маршруты + +- URL = путь файла в `pages/`: `pages/about.md` → `/about/`, `index.md` → корень раздела. Если имя файла не совпадает с нужным URL (`pages/scenario-legal.md` → `/scenarios/legal/`), адрес задаётся полем `route:` в front matter. +- Записи коллекций получают URL из `route` в схеме коллекции, список — из `list_page`. +- Служебные маршруты генерирует движок: `/sitemap.xml`, `/robots.txt`, `/404.html`, страницы пагинации, страницы терминов таксономий, `/feed.xml` (по настройке). +- Два источника на один URL — ошибка сборки. Слаги латиницей; кириллица в slug автоматически транслитерируется. +- Смена slug записывает старый адрес в историю, и редирект создаётся автоматически; ручные правила лежат в `redirects.yaml`. + +### 5.2 Разделы + +Папка с файлом `_section.yaml` — раздел. Он задаёт значения по умолчанию для вложенных страниц и порядок детей: + +```yaml +# pages/services/_section.yaml +title: Услуги +layout: default +nav: {menu: main, label: Услуги, order: 10} +children_sort: order +defaults: + seo: {title_suffix: ' — Acme'} + plan: {priority: P1} +``` + +Хлебные крошки строятся из дерева разделов и переопределяются полем `breadcrumb:` страницы. + +### 5.3 Меню + +Меню — файлы `menus/*.yaml` плюс пункты, которые страницы объявляют сами (`nav: {menu: footer, label: ..., order: ...}`). Пункт может быть ссылкой на страницу, запись или внешний URL и поддерживает поля `enabled`, `requires` (условия показа, см. 7.4) и `note`. Выключенный пункт остаётся в файле, но не попадает в HTML: это удобно, когда раздел временно исключён. + +### 5.4 Типовые структуры + +| Структура | Как реализуется | +|---|---| +| Лендинг из секций | Страница из блоков `section`, якоря через `anchor`, меню по якорям | +| Обзор + дочерние страницы | Раздел, а в обзоре `collection_list` с `source: {children: current}` или коллекция | +| Каталог: список → карточка | Коллекция + display template, пагинация и фильтры по таксономиям | +| Запись с подстраницами | Подмаршруты записи (`/academy/<курс>/program/`), каждый со своим display template | +| Юридические документы | Layout `legal`: оглавление, дата и версия редакции | +| Служебные страницы | 404, «спасибо» после формы, страница превью, печатная версия | +| Несколько языков | Поле `locales`, переводы рядом (`about.en.md`), связь через `translations`, `hreflang` | + +### 5.5 Границы v1 + +Один запуск движка обслуживает один сайт (каталог `site/`). Каталог `sites/<имя>/` для нескольких сайтов закладываем в структуру путей, но не реализуем. Мультиязычность в v1 ограничена моделью данных (`locale` у страниц и записей) и генерацией `hreflang`; интерфейс переводов в админке откладываем. + +## 6. Сборка, превью и публикация + +### 6.1 Конвейер сборки + +1. **load** — чтение файлов, парсинг YAML и Markdown, нормализация. +2. **validate** — схемы, ссылки, ассеты, уникальность маршрутов, правила сайта (см. 6.5). +3. **index** — запись страниц, записей и графа ссылок в SQLite. +4. **resolve** — выполнение запросов и привязок, сборка меню и хлебных крошек. +5. **render** — Jinja в sandbox, HTML каждой страницы. +6. **postprocess** — бандлы CSS/JS с хешами, варианты изображений (webp, srcset), `sitemap.xml`, поисковый индекс. +7. **publish** — запись в `dist//` и атомарное переключение символической ссылки `current`; последние N сборок хранятся для отката. + +### 6.2 Инкрементальность и скорость + +Граф зависимостей (какая страница читает какие записи, фрагменты и данные) позволяет пересобирать только затронутое. Ориентир для v1: полная сборка сайта до 500 страниц менее 10 секунд, правка одной страницы менее 1 секунды. + +### 6.3 Превью + +Динамический рендер одной страницы из рабочего каталога без записи в `dist`. Показывает черновики и использует те же CSS и JS, что и сборка. В админке открывается во фрейме; для внешних согласований выдаётся ссылка с токеном и сроком жизни. + +### 6.4 Статусы и история + +`status`: `draft` → `review` → `published` (плюс `scheduled` с датой и `archived`). В публикуемую сборку попадают только `published` и `scheduled`, чей срок наступил (проверка по расписанию). История изменений: если каталог сайта — git-репозиторий, каждое сохранение коммитится с автором (человек или агент); изменения агента могут идти в отдельную ветку `agent/*` и вливаться человеком. Без git используются ревизии в таблице `revisions`. + +### 6.5 Проверки `validate` + +Ошибки блокируют публикацию, предупреждения — нет. + +- **Ошибки:** невалидный YAML; поля не по схеме; неизвестный фрагмент или версия; фрагмент не разрешён в регионе; дубли `id` блоков; битые ссылки на страницы, записи и ассеты; конфликты маршрутов; нарушение правил сайта (см. 7.5). +- **Предупреждения:** тело страницы не использовано блоком; нет `seo.description`; у изображения нет `alt`; ассеты без ссылок; блоки на устаревшей версии фрагмента; страницы без входящих ссылок. + +### 6.6 Поиск + +Варианты: статический JSON-индекс с клиентским поиском (без сервера) либо серверный поиск на SQLite FTS5. Решение вынесено в открытые вопросы. + +## 7. Опорный пример: студия ботов, AI-систем и автоматизаций + +Пример взят из карты сайта `SiteMap.md` (черновик v0.1): студия Telegram-ботов, AI-систем и автоматизаций с Академией курсов. Раздел показывает, как реальная карта раскладывается по модели ТЗ и что в модели пришлось дополнить. + +### 7.1 Что ложится в модель как есть + +- Дерево страниц → `pages/` и `_section.yaml`; приоритеты P1/P2 переносятся в поле `plan`. +- Шапка и футер → `menus/main.yaml`, `menus/footer.yaml` и фрагменты `site_header`, `site_footer`. +- Каркас главной из восьми блоков → `pages/index.md` с блоками в регионе `main`. +- Колонки «Задача страницы» и «Куда ведёт дальше» → поля страницы `goal` и `next` (видны в админке, на сайт не выводятся; агент использует их для проверки текстов). + +### 7.2 Коллекции + +| Коллекция | Записи | Маршрут | Заметки | +|---|---|---|---| +| `services` | bots, ai, automation | `/services/{slug}/` | Три записи, общий display template, у каждой свои блоки через `overrides` | +| `scenarios` | legal, real-estate, services | `/scenarios/{slug}/` | Типовые сценарии, а не кейсы: схема без `metrics`, обязательный блок-дисклеймер | +| `courses` | по мере появления | `/academy/{slug}/` | Пустая коллекция допустима, поля в 7.6 | +| `cases` | — | `/cases/{slug}/` | Схема есть, раздел выключен: `features.cases: false` | +| `posts` | — | `/blog/{slug}/` | Схема есть, раздел выключен: `features.blog: false` | + +Ручные страницы: главная, о компании, безопасность и данные, контакты, заявка, политика ПД, оферта, страница «спасибо». + +### 7.3 Каркас главной + +| № | Блок карты | Фрагмент | Особенности | +|---|---|---|---| +| 1 | Hero | `hero` | CTA: Telegram и заявка | +| 2 | Три направления | `collection_list` (`services`, карточка `direction_card`) | Данные из коллекции, дублей нет | +| 3 | Живые примеры | `live_examples` | `hidden`, `requires: [feature.demo]` | +| 4 | Что уже работает | `feature_grid` | Плашки со сроками, данные `verified` | +| 5 | Цифры | `stats` | `hidden`, `requires: [data.stats]` | +| 6 | Как идёт работа | `steps` | 5 шагов | +| 7 | О нас | `about_teaser` | Ссылка на `/about/` | +| 8 | Финальный CTA | `cta_banner` | Telegram и форма | + +Исключённые блоки остаются в файле с прежней нумерацией (`id` стабильны), чтобы вернуть их одной правкой: + +```yaml +- id: b_demo + fragment: live_examples + hidden: true + note: Исключён на старте — нет демо + requires: [feature.demo] +- id: b_stats + fragment: stats + hidden: true + note: Исключён на старте — нет подтверждённых цифр + requires: [data.stats] +``` + +### 7.4 Что добавляем в модель по итогам карты + +| Что в карте | Что добавляем | +|---|---| +| Приоритеты P1/P2, пометки ➕ и ⛔ | Поле страницы `plan: {priority, state: planned/added/excluded/done, note, data_ready}`. Движок строит отчёт готовности сайта, он же доступен агенту через MCP | +| «Исключено на старте, можно вернуть» | Флаги `features` в `site.yaml`; у блока `hidden` и `note`; у пункта меню `enabled`. Возврат — одна правка | +| «Включаем, только если есть чем подтвердить» | `requires:` у блока: список ссылок на `feature.*` и `data.*`; блок рендерится, только если все они не пусты | +| Имя файла не равно URL | `route:` в front matter (см. 5.1) | +| «Сценарий, не кейс», без выдуманных результатов | Отдельная коллекция без `metrics`, обязательный фрагмент `disclaimer` и правило сайта (7.5) | +| «Заявка → Благодарность» | У формы `success.page`; страница «спасибо» добавляется в карту | +| «Оплата / запись» на курс | CTA-тип `enroll`: внешняя платёжная страница или форма записи; своя оплата вне v1 | +| 152-ФЗ и политика ПД | Тип поля формы `consent` (чекбокс, ссылка на политику, версия редакции); факт согласия хранится вместе с заявкой | +| «Ждёт данных о курсах» | Пустое состояние `collection_list` (`empty: hide` или `message`); страница `status: draft` с `plan.data_ready: false` | +| Telegram как основной канал | Секция `contacts` в `site.yaml` и CTA-тип `contact`; смена ника правится в одном месте; уведомления о заявках уходят в Telegram | +| Реквизиты, год и название в футере | `data/company.yaml` и фрагмент `requisites`; год подставляет сборка | + +### 7.5 Правила контента сайта + +Договорённости из карты (без выдуманных результатов, согласие на обработку ПД) превращаются в проверяемые правила в `site.yaml`: + +```yaml +rules: + - {id: scenario-disclaimer, collection: scenarios, require_fragment: disclaimer, level: error} + - {id: verified-numbers, fragments: [stats, feature_grid], require: verified, level: warning} + - {id: form-consent, forms: all, require_field: consent, level: error} +``` + +Правила выполняет `validate`; агент получает их через MCP до правки текстов и не нарушает по неведению. + +### 7.6 Коллекция courses (набросок) + +```yaml +id: courses +name: Курсы +route: /academy/{slug}/ +list_page: /academy/ +display: courses +body: markdown +fields: + - {key: title, type: text, required: true} + - {key: summary, type: textarea} + - {key: audience, type: text} + - {key: format, type: select, options: [self-paced, cohort, live]} + - {key: duration, type: text} + - {key: starts, type: date} + - {key: outcomes, type: list, fields: [{key: item, type: text}]} + - key: program + type: list + fields: [{key: module, type: text}, {key: lessons, type: textarea}] + - key: price + type: group + fields: [{key: amount, type: number}, {key: currency, type: text}, {key: note, type: text}] + - key: enroll + type: group + fields: [{key: kind, type: select, options: [link, form]}, {key: url, type: text}] +``` + +Display template курса: `entry_header` → `feature_grid` (чему научится) → `course_program` → `richtext` → `enroll_block` (цена и запись) → `faq` → ссылка на оферту. Точный состав согласуем, когда появятся данные о курсах. + +### 7.7 Что стоит уточнить в самой карте + +- Нет страницы «спасибо», хотя в таблице задач заявка ведёт на «Благодарность». +- Страница курса отсылает к «шаблону ниже», но в файле его нет. +- «Сценарии» отмечены P1, но пункта в шапке нет: решить, откуда на них ведут ссылки (главная и страницы услуг?). +- «Типовые сроки» в блоке «Что уже работает» — тоже числа: нужен источник или пометка «ориентировочно». + +## 8. Базовый набор фрагментов + +### 8.1 Общие свойства блока + +Эти поля есть у любого блока независимо от фрагмента, во фрагментах их дублировать не нужно: `id`, `anchor`, `hidden`, `note`, `requires`, `visibility` (локали, даты) и `style` (отступы, фон из токенов темы, ширина контейнера). + +### 8.2 Каталог (этап: MVP — первая версия, v1 — следом, позже — по потребности) + +**Структура и заголовки** + +| Фрагмент | Назначение | Ключевые поля | Этап | +|---|---|---|---| +| `section` | Контейнер секции со слотом `content` | фон, ширина, отступы | MVP | +| `columns` | 2–4 колонки, слот на колонку | число колонок, пропорции, выравнивание | MVP | +| `hero` | Первый экран | title, subtitle, image, actions, variant | MVP | +| `page_header` | Заголовок внутренней страницы | title, lead, breadcrumbs | MVP | +| `divider` | Разделитель или отступ | тип, высота | v1 | + +**Контент** + +| Фрагмент | Назначение | Ключевые поля | Этап | +|---|---|---|---| +| `richtext` | Текст в Markdown | source (`body`, `entry.body` или текст) | MVP | +| `image` | Изображение | asset, alt, caption | MVP | +| `disclaimer` | Пометка или оговорка | variant (info, warning), text | MVP | +| `legal_text` | Юридический текст | оглавление, дата и версия редакции | MVP | +| `chat_demo` | Пример диалога в мессенджере (статичный) | messages (from: user или bot), buttons | v1 | +| `gallery`, `video_embed`, `quote`, `code_block`, `table` | Типовые контентные блоки | по назначению | v1 | + +**Карточки и списки** + +| Фрагмент | Назначение | Ключевые поля | Этап | +|---|---|---|---| +| `card_grid` | Сетка карточек | items: title, text, link, icon, badge | MVP | +| `feature_grid` | Преимущества или возможности | items: title, text, icon, badge, verified | MVP | +| `steps` | Этапы работы | items: title, text | MVP | +| `faq` | Вопросы и ответы (разметка FAQ для поиска) | items: q, a | MVP | +| `stats` | Цифры | items: value, label, verified | v1 | +| `logo_cloud`, `team_grid`, `testimonials`, `pricing_table` | Клиенты, команда, отзывы, тарифы | по назначению | v1 | +| `timeline`, `comparison_table` | История и сравнение | по назначению | позже | + +**Коллекции** + +| Фрагмент | Назначение | Ключевые поля | Этап | +|---|---|---|---| +| `collection_list` | Список записей | source, card, layout, paginate, filters, empty | MVP | +| `entry_header` | Шапка страницы записи | title, meta, tags | MVP | +| `related_entries` | Похожие записи | source (`related_to`, `by`), limit | v1 | +| `collection_featured` | Ручная подборка записей | ids, card | v1 | +| `entry_facts` | Ключевые факты записи | items: label, value | v1 | +| `entry_nav` | Предыдущая и следующая запись | collection | v1 | +| `course_program` | Программа курса | modules | v1 | +| `enroll_block` | Цена и запись на курс | price, enroll | v1 | + +**Конверсия и контакты** + +| Фрагмент | Назначение | Ключевые поля | Этап | +|---|---|---|---| +| `cta_banner` | Призыв к действию | title, text, actions (тип: link, contact, form, enroll) | MVP | +| `form` | Форма из `forms/.yaml` | form | MVP | +| `contact_block` | Способы связи | берёт `site.contacts` | MVP | +| `requisites` | Реквизиты компании | берёт `data.company` | MVP | + +**Навигация и глобальное** + +| Фрагмент | Назначение | Ключевые поля | Этап | +|---|---|---|---| +| `site_header`, `site_footer` | Шапка и футер | menu, action, источники данных | MVP | +| `nav_menu` | Меню по id | menu, orientation | MVP | +| `breadcrumbs` | Хлебные крошки | — | MVP | +| `pagination` | Постраничная навигация | используется списками | MVP | +| `toc`, `announcement_bar`, `cookie_notice` | Оглавление, плашка, уведомление о cookie | по назначению | v1 | +| `search_box`, `language_switcher` | Поиск и язык | по назначению | позже | +| `embed_html` | Произвольный HTML в sandbox-iframe | code | позже, только роль developer | + +Итого MVP — 22 фрагмента: хватает на сайт-пример (раздел 7) без ручного HTML. Часть сайта-примера (`direction_card`, `about_teaser`, `live_examples`) — это варианты карточек и тематические обёртки поверх базовых; их добавляем как фрагменты сайта, а не ядра. + +### 8.3 Требования к любому фрагменту + +1. Манифест со схемой полей, `preview.yaml` с тестовыми данными, версия. +2. Семантическая разметка, `alt` у изображений, управляемый фокус, контраст из токенов темы. +3. Только токены темы и классы `.f-`, без внешних CDN и без инлайновых обработчиков. +4. Пустые и граничные данные не ломают вёрстку (`hidden_if_empty`, значения по умолчанию). +5. Автоматический snapshot-тест рендера на `preview.yaml`. + +## 9. Формы и заявки + +### 9.1 Определение формы + +```yaml +# forms/consultation.yaml +id: consultation +title: Заявка на разговор +fields: + - {key: name, type: text, label: Имя, required: true} + - {key: contact, type: text, label: Telegram или телефон, required: true} + - {key: task, type: textarea, label: Расскажите о задаче, hint: Свободная форма, ТЗ не нужно} + - {key: consent, type: consent, policy: privacy} +success: {page: consultation/thanks} +notify: + - {kind: telegram, chat: '${TG_CHAT_ID}'} + - {kind: email, to: ['${LEADS_EMAIL}']} +antispam: {honeypot: true, rate_limit: '5/hour'} +store: {retention_days: 365} +``` + +Секреты (токен бота, адреса) берутся из переменных окружения, в файлах сайта их нет. + +### 9.2 Обработка + +- Форма — единственная динамическая часть статического сайта: `POST /forms/{id}` в FastAPI. Без JS это обычный POST с редиректом на `success.page`; htmx или небольшой скрипт делает отправку без перезагрузки. +- Валидация по схеме формы, запись в таблицу `form_submissions` вместе со снимком согласия (время, версия политики), уведомления через очередь с повторными попытками. +- Защита: honeypot, лимит запросов, проверка размера, экранирование при показе в админке. + +### 9.3 Персональные данные + +Заявки содержат ПД, поэтому: доступ к ним только у ролей с правом `submissions:read`, срок хранения и автоматическое удаление, экспорт и удаление по запросу, аудит просмотров. Требования закона к хранению и размещению сервера определяет владелец сайта вместе с юристом; движок даёт технические средства (согласие с версией, срок хранения, удаление, журнал). + +### 9.4 Админка заявок + +Список со статусами (`new`, `processed`, `spam`), поиск, заметки, экспорт в CSV. + +## 10. Админка (FastAPI + htmx) + +### 10.1 Экраны + +| Экран | Что делает | +|---|---| +| Обзор | Отчёт готовности по `plan`: что готово, что ждёт данных, что исключено; ошибки и предупреждения `validate`; последние сборки | +| Страницы | Дерево разделов, статусы, фильтры, создание и перенос страниц | +| Редактор страницы | Регионы и блоки: добавить, удалить, переместить; форма блока строится из схемы фрагмента; превью во фрейме | +| Коллекции | Таблица записей с фильтрами; форма записи; Markdown-редактор | +| Фрагменты и layouts | Каталог с превью и схемой полей; правка кода только у роли developer | +| Меню и данные | Редактирование `menus/*.yaml` и `data/*.yaml` формами по схемам | +| Медиа | Загрузка, подписи (`alt`), поиск неиспользуемых файлов | +| Формы и заявки | Список заявок, статусы, экспорт | +| Доступ | Пользователи, роли, токены агентов | +| Журнал и сборки | Аудит, история публикаций, откат | + +### 10.2 Технические решения + +- Серверный рендер Jinja-партиалами; htmx заменяет регион страницы или форму блока, JS-сборки нет. SortableJS — перенос блоков, EasyMDE — Markdown. +- Формы блоков генерируются из схемы фрагмента макросами по типам полей; ошибки валидации возвращаются в ту же форму. +- Конфликты редактирования: при открытии запоминается хеш файла, при сохранении он сверяется; при расхождении показывается diff и выбор действия (так человек и агент не затирают друг друга). +- Сессионная cookie, CSRF-токен через `hx-headers`, лимит попыток входа. +- Два окружения Jinja: админское и сайтовое (sandbox). Шаблоны сайта не получают доступа к объектам админки. + +## 11. Роли, права и безопасность + +### 11.1 Роли + +| Действие | owner | developer | editor | reviewer | agent | +|---|---|---|---|---|---| +| Страницы, записи, данные, меню | да | да | да | нет | по scope | +| Фрагменты, layouts, схемы коллекций | да | да | нет | нет | нет | +| Публикация и откат | да | да | да | нет | только если разрешено владельцем | +| Согласование и комментарии | да | да | да | да | нет | +| Заявки (ПД) | да | нет | по праву `submissions:read` | нет | нет | +| Пользователи, токены, настройки | да | нет | нет | нет | нет | + +Токен агента несёт scope (например `read`, `content:write`, `publish`), срок жизни и ограничение по разделам сайта. По умолчанию агент пишет в `draft` или в ветку `agent/*`, публикует человек. + +### 11.2 Меры безопасности + +- Шаблоны сайта рендерятся в Jinja `SandboxedEnvironment`, доступны только разрешённые фильтры и функции; шаблоны читаются только из каталога сайта. +- Raw HTML в Markdown выключен по умолчанию; допустимые теги — allowlist, вывод проходит санитизацию. `embed_html` и произвольные скрипты — только роль developer. +- YAML читается только безопасным загрузчиком, с лимитами размера, глубины и числа алиасов. +- Загрузки: проверка типа по содержимому, лимит размера, санитизация SVG, запрет исполняемых типов; защита от выхода за каталог (path traversal). +- Заголовки: CSP, `X-Content-Type-Options`, `Referrer-Policy`; CSRF для админки; лимиты на вход, формы и MCP. +- Токены хранятся только в виде хеша; секреты — в переменных окружения; все записи и просмотр заявок попадают в `audit_log` с актором (человек или агент). +- Резервные копии: каталог сайта (git или архив) и файл SQLite с проверкой восстановления. + +## 12. MCP-сервер + +Транспорт: Streamable HTTP внутри того же FastAPI-приложения; авторизация Bearer-токеном со scope. Инструменты вызывают сервисный слой, поэтому права и валидация такие же, как в админке. + +### 12.1 Инструменты + +| Группа | Инструменты | +|---|---| +| Чтение | `get_site_plan`, `get_rules`, `list_pages`, `get_page`, `list_collections`, `list_entries`, `get_entry`, `list_fragments`, `get_fragment_schema`, `list_layouts`, `list_menus`, `list_assets`, `search` | +| Запись | `create_page`, `update_page_meta`, `add_block`, `update_block`, `move_block`, `remove_block`, `set_block_visibility`, `create_entry`, `update_entry`, `update_menu`, `update_data`, `upload_asset` | +| Контроль | `validate`, `render_preview` (HTML или скриншот), `diff`, `submit_for_review`, `publish`, `list_builds`, `rollback` | + +### 12.2 Принципы + +- Блоки адресуются по `id`, поля — по пути (`regions.main[b_7k2m].props.cta.label`); индексы позиций не используются. +- Все записи принимают `dry_run` и `if_match` (хеш версии файла); при конфликте возвращается актуальная версия. +- Ошибки валидации приходят структурой: путь к полю, правило, ожидаемое значение, подсказка, как исправить. +- Схемы и правила сайта публикуются как MCP-ресурсы; типовые задачи («страница по брифу», «перевод страницы», «проверка текста по карте») — как MCP-промпты. +- Агент не может менять фрагменты, layouts и схемы без роли developer. + +## 13. Данные в SQLite (SQLAlchemy) + +Индексные таблицы восстанавливаются командой `reindex`; остальные хранят то, чего нет в файлах. + +| Таблица | Содержимое | Восстанавливается из файлов | +|---|---|---| +| `pages_index` | путь, маршрут, локаль, статус, layout, `plan`, front matter (JSON), хеш | да | +| `entries_index` | коллекция, slug, маршрут, статус, данные (JSON), хеш | да | +| `refs` | граф ссылок и зависимостей страниц от записей, фрагментов и данных | да | +| `fragments_index`, `assets_index` | фрагменты (версия, схема), ассеты (размер, тип, хеш) | да | +| `search_fts` | полнотекстовый индекс FTS5 | да | +| `slug_history` | старые адреса для редиректов | нет | +| `revisions` | ревизии, если сайт не в git | нет | +| `users`, `roles`, `sessions`, `api_tokens` | доступ; токены только в виде хеша | нет | +| `audit_log` | действия с актором, объектом, до и после | нет | +| `form_submissions` | заявки, согласия, статусы | нет | +| `build_runs` | сборки: статус, время, лог, кто запустил | нет | +| `locks` | блокировки записи страниц | нет | + +SQLite в режиме WAL, миграции Alembic, синхронный доступ в threadpool. + +## 14. Нефункциональные требования + +- **Производительность:** см. 6.2; отдача сайта — статика, нагрузка на FastAPI только от админки, форм и MCP. +- **Надёжность:** атомарная запись файлов (временный файл и rename), атомарная публикация сборки, откат на предыдущую. +- **Развёртывание:** один Docker-образ, тома `site/`, `data/` (SQLite), `dist/`; конфигурация через переменные окружения; статику отдаёт nginx или сам FastAPI. +- **Доступность и SEO:** базовые фрагменты соответствуют WCAG 2.1 AA; canonical, Open Graph, `sitemap.xml`, разметка schema.org там, где применимо. +- **Тестирование:** unit-тесты парсеров и схем; snapshot-тесты рендера каждого фрагмента; сквозной тест сборки сайта-примера; контрактные тесты MCP-инструментов. +- **Наблюдаемость:** структурированные логи, журнал сборок, метрики времени сборки и ошибок валидации. + +## 15. Этапы + +| Этап | Состав | +|---|---| +| M0. Ядро | Парсер md + yaml, схемы (pydantic из манифестов), индекс, рендер, CLI (`build`, `validate`, `serve`, `reindex`), 10 базовых фрагментов; сайт-пример как тестовый набор | +| M1. Коллекции и MCP | Коллекции, display templates, запросы, меню, привязки; MCP: чтение и запись, `validate`, превью; формы и заявки | +| M2. Админка | Экраны раздела 10, роли, токены, аудит, конфликты редактирования | +| M3. Полный MVP-набор | Все 22 фрагмента, тема, инкрементальная сборка, публикация и откат, интеграция с git | +| M4. Расширение | Поиск, мультиязычность, медиа-варианты, фрагменты v1 | +| Позже | Визуальный редактор на самой странице | + +## 16. Открытые вопросы + +1. История изменений: git обязателен или допускаем только таблицу `revisions`? +2. Поиск: статический индекс на клиенте или FTS5 на сервере? +3. Мультиязычность: нужна в первой версии или только заложить модель? +4. Публикация: кто отдаёт `dist` (nginx или FastAPI) и где живёт сервер? +5. Формы: какие каналы уведомлений нужны сразу (Telegram, почта, webhook)? +6. Оплата курсов: внешний провайдер ссылкой или форма записи без оплаты? +7. Политика JS во фрагментах: разрешён ли собственный JS у фрагментов сайта или только из набора ядра? +8. Аутентификация админки: локальные аккаунты или внешний провайдер (SSO)? +9. Режим работы агента: прямая запись в `draft` или обязательно через ветку и согласование? +10. Название проекта. diff --git a/examples/studio-site/assets/hero.svg b/examples/studio-site/assets/hero.svg new file mode 100644 index 0000000..3219d73 --- /dev/null +++ b/examples/studio-site/assets/hero.svg @@ -0,0 +1 @@ +Acme Studio diff --git a/examples/studio-site/collections/services.yaml b/examples/studio-site/collections/services.yaml new file mode 100644 index 0000000..1944a9e --- /dev/null +++ b/examples/studio-site/collections/services.yaml @@ -0,0 +1,12 @@ +id: services +name: Услуги +route: /services/{slug}/ +list_page: /services/ +display: services +sort: order +body: markdown +fields: + - {key: title, type: text, required: true} + - {key: tagline, type: text} + - {key: summary, type: textarea} + - {key: order, type: number} diff --git a/examples/studio-site/content/services/ai.md b/examples/studio-site/content/services/ai.md new file mode 100644 index 0000000..163c6d3 --- /dev/null +++ b/examples/studio-site/content/services/ai.md @@ -0,0 +1,8 @@ +--- +title: AI-системы +status: published +order: 2 +tagline: Ассистенты на ваших данных +summary: Поиск по базе знаний, подготовка ответов, разбор обращений. +--- +AI-ассистент работает с вашими документами и данными в согласованном контуре. diff --git a/examples/studio-site/content/services/automation.md b/examples/studio-site/content/services/automation.md new file mode 100644 index 0000000..892239e --- /dev/null +++ b/examples/studio-site/content/services/automation.md @@ -0,0 +1,8 @@ +--- +title: Автоматизации +status: published +order: 3 +tagline: Меньше рутины в процессах +summary: Интеграции между сервисами и автоматизация повторяющихся операций. +--- +Связываем CRM, таблицы, мессенджеры и внутренние системы. diff --git a/examples/studio-site/content/services/bots.md b/examples/studio-site/content/services/bots.md new file mode 100644 index 0000000..30dddca --- /dev/null +++ b/examples/studio-site/content/services/bots.md @@ -0,0 +1,8 @@ +--- +title: Telegram-боты +status: published +order: 1 +tagline: Автоматизация общения с клиентами +summary: Боты для заявок, записи, напоминаний и поддержки. +--- +Бот принимает обращения, задаёт уточняющие вопросы и передаёт задачу менеджеру. diff --git a/examples/studio-site/data/company.yaml b/examples/studio-site/data/company.yaml new file mode 100644 index 0000000..0f0d7bd --- /dev/null +++ b/examples/studio-site/data/company.yaml @@ -0,0 +1,2 @@ +legal_name: Acme Studio LLC +requisites: реквизиты указывает владелец сайта diff --git a/examples/studio-site/display/services.yaml b/examples/studio-site/display/services.yaml new file mode 100644 index 0000000..b62d74e --- /dev/null +++ b/examples/studio-site/display/services.yaml @@ -0,0 +1,14 @@ +layout: default +seo: + title: {bind: entry.title} + description: {bind: entry.summary} +regions: + main: + - id: d_header + fragment: entry_header + props: {title: {bind: entry.title}, meta: [{bind: entry.tagline}]} + - {id: d_text, fragment: richtext, props: {content: {bind: entry.body}}} + - id: d_cta + fragment: cta_banner + props: {title: 'Обсудим вашу задачу?', variant: contact} +overrides: allow diff --git a/examples/studio-site/forms/consultation.yaml b/examples/studio-site/forms/consultation.yaml new file mode 100644 index 0000000..7544b27 --- /dev/null +++ b/examples/studio-site/forms/consultation.yaml @@ -0,0 +1,12 @@ +id: consultation +title: Заявка на разговор +fields: + - {key: name, type: text, label: Имя, required: true} + - {key: contact, type: text, label: Telegram или телефон, required: true} + - {key: task, type: textarea, label: Расскажите о задаче, hint: Свободная форма, ТЗ не нужно} + - {key: consent, type: consent, policy: privacy} +success: {page: contacts} +notify: + - {kind: telegram, chat: '${TG_CHAT_ID}'} +antispam: {honeypot: true, rate_limit: '5/hour'} +store: {retention_days: 365} diff --git a/examples/studio-site/layouts/default/layout.html.j2 b/examples/studio-site/layouts/default/layout.html.j2 new file mode 100644 index 0000000..0f3d826 --- /dev/null +++ b/examples/studio-site/layouts/default/layout.html.j2 @@ -0,0 +1,13 @@ + + + +{{ seo_head() }} +{{ assets_head() }} + + +{{ region('header') }} +
{{ region('main') }}
+{{ region('footer') }} +{{ assets_body() }} + + diff --git a/examples/studio-site/layouts/default/layout.yaml b/examples/studio-site/layouts/default/layout.yaml new file mode 100644 index 0000000..215a3a7 --- /dev/null +++ b/examples/studio-site/layouts/default/layout.yaml @@ -0,0 +1,14 @@ +id: default +name: Основной +regions: + - id: header + fixed: + - id: lh_header + fragment: site_header + props: + menu: main + action: {url: 'https://t.me/acme_studio', label: Написать в Telegram} + - {id: main, allow: ['*']} + - id: footer + fixed: + - {id: lf_footer, fragment: site_footer, props: {menu: footer}} diff --git a/examples/studio-site/menus/footer.yaml b/examples/studio-site/menus/footer.yaml new file mode 100644 index 0000000..4c07dd5 --- /dev/null +++ b/examples/studio-site/menus/footer.yaml @@ -0,0 +1,3 @@ +items: + - {label: Политика ПД, page: privacy} + - {label: Контакты, page: contacts} diff --git a/examples/studio-site/menus/main.yaml b/examples/studio-site/menus/main.yaml new file mode 100644 index 0000000..2cae788 --- /dev/null +++ b/examples/studio-site/menus/main.yaml @@ -0,0 +1,4 @@ +items: + - {label: Услуги, page: services/index} + - {label: Проекты, page: cases/index, enabled: false, note: Исключено на старте — нет согласий и данных} + - {label: Контакты, page: contacts} diff --git a/examples/studio-site/pages/_section.yaml b/examples/studio-site/pages/_section.yaml new file mode 100644 index 0000000..f08a51a --- /dev/null +++ b/examples/studio-site/pages/_section.yaml @@ -0,0 +1,2 @@ +title: Корень +layout: default diff --git a/examples/studio-site/pages/contacts.md b/examples/studio-site/pages/contacts.md new file mode 100644 index 0000000..6b2ad0d --- /dev/null +++ b/examples/studio-site/pages/contacts.md @@ -0,0 +1,11 @@ +--- +schema: 1 +title: Контакты +status: published +regions: + main: + - {id: b_head, fragment: page_header, props: {title: Контакты, lead: Свяжитесь удобным способом.}} + - {id: b_text, fragment: richtext, props: {content: {bind: page.body}}} + - {id: b_form, fragment: form, props: {form: consultation}} +--- +Основной канал связи — Telegram. Почту и форму ниже используйте, если так удобнее. diff --git a/examples/studio-site/pages/drafts/next.md b/examples/studio-site/pages/drafts/next.md new file mode 100644 index 0000000..d0025e3 --- /dev/null +++ b/examples/studio-site/pages/drafts/next.md @@ -0,0 +1,8 @@ +--- +schema: 1 +title: Черновик новой страницы +status: draft +regions: + main: + - {id: b_head, fragment: page_header, props: {title: Черновик}} +--- diff --git a/examples/studio-site/pages/index.md b/examples/studio-site/pages/index.md new file mode 100644 index 0000000..3d34aa1 --- /dev/null +++ b/examples/studio-site/pages/index.md @@ -0,0 +1,51 @@ +--- +schema: 1 +title: Главная +status: published +seo: + description: Telegram-боты, AI-системы и автоматизации под ваши процессы +editorial: + priority: P1 + goal: За 10 секунд объяснить, что мы делаем, и дать действие +regions: + main: + - id: b_hero + fragment: hero + props: + title: Telegram-боты, AI-системы и автоматизации + subtitle: Разрабатываем и сопровождаем решения под ваши процессы. + variant: dark + actions: + - {page: contacts, label: Обсудить задачу} + - id: b_dirs + fragment: collection_list + props: + title: Направления + source: {query: {collection: services, limit: 3}} + card: direction + - id: b_demo + fragment: faq + requires: [feature.demo] + note: Исключён на старте — нет демо (вернётся при feature.demo) + props: + items: + - {q: Заглушка, a: 'Блок скрыт, пока выключен флаг demo'} + - id: b_steps + fragment: card_grid + props: + title: Как идёт работа + variant: steps + items: + - {title: Разговор, text: Обсуждаем задачу без ТЗ.} + - {title: Постановка, text: Фиксируем границы и сроки.} + - {title: Разработка, text: Делаем по этапам с демонстрациями.} + - {title: Запуск, text: Выпускаем в работу.} + - {title: Поддержка, text: Сопровождаем и дорабатываем.} + - id: b_cta + fragment: cta_banner + props: + title: Расскажите о задаче + variant: contact + actions: + - {page: contacts, label: Оставить заявку} +--- diff --git a/examples/studio-site/pages/privacy.md b/examples/studio-site/pages/privacy.md new file mode 100644 index 0000000..40e36e7 --- /dev/null +++ b/examples/studio-site/pages/privacy.md @@ -0,0 +1,10 @@ +--- +schema: 1 +title: Политика обработки персональных данных +status: published +regions: + main: + - {id: b_head, fragment: page_header, props: {title: Политика обработки персональных данных}} + - {id: b_text, fragment: richtext, props: {content: {bind: page.body}}} +--- +Текст политики добавляет владелец сайта и согласует с юристом. diff --git a/examples/studio-site/pages/services/index.md b/examples/studio-site/pages/services/index.md new file mode 100644 index 0000000..c4387cf --- /dev/null +++ b/examples/studio-site/pages/services/index.md @@ -0,0 +1,13 @@ +--- +schema: 1 +title: Услуги +status: published +regions: + main: + - {id: b_head, fragment: page_header, props: {title: Услуги, lead: Три направления работы.}} + - id: b_list + fragment: collection_list + props: + source: {query: {collection: services}} + layout: list +--- diff --git a/examples/studio-site/redirects.yaml b/examples/studio-site/redirects.yaml new file mode 100644 index 0000000..070acdf --- /dev/null +++ b/examples/studio-site/redirects.yaml @@ -0,0 +1 @@ +- {from: /uslugi/, to: /services/} diff --git a/examples/studio-site/site.yaml b/examples/studio-site/site.yaml new file mode 100644 index 0000000..811816b --- /dev/null +++ b/examples/studio-site/site.yaml @@ -0,0 +1,22 @@ +schema: 1 +name: Acme Studio +base_url: https://studio.example +default_locale: ru +locales: [ru] +theme: + tokens: + color.primary: '#0b5fff' + color.dark: '#14213d' + font.body: 'Inter, system-ui, sans-serif' +defaults: + layout: default + seo: {title_suffix: ' — Acme Studio'} +features: + cases: false + blog: false + demo: false +contacts: + telegram: '@acme_studio' + email: hello@studio.example +rules: + - {id: form-consent, forms: all, require_field: consent, level: error} diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..13d6786 --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,47 @@ +[build-system] +requires = ["setuptools>=68"] +build-backend = "setuptools.build_meta" + +[project] +name = "site-engine" +version = "0.1.0" +description = "Движок сайтов на Markdown + YAML: layouts, fragments, коллекции, MCP для агентов" +readme = "README.md" +requires-python = ">=3.12" +dependencies = [ + "jinja2>=3.1", + "PyYAML>=6.0", + "markdown-it-py>=3.0", + "click>=8.1", + "nh3>=0.2", # санитайзер HTML после Markdown (если не установлен, остаётся только html=False) +] + +[project.optional-dependencies] +server = [ # M2+: админка, формы, превью + "fastapi>=0.115", + "uvicorn>=0.30", + "pydantic>=2.7", + "sqlalchemy>=2.0", + "alembic>=1.13", + "python-multipart>=0.0.9", +] +mcp = ["mcp>=1.2"] # M3 +images = ["Pillow>=10"] # M4: варианты изображений +dev = ["pytest>=8", "ruff>=0.6", "httpx>=0.27"] + +[project.scripts] +site-engine = "site_engine.cli:main" + +[tool.setuptools.packages.find] +where = ["src"] + +[tool.setuptools.package-data] +site_engine = ["builtin/**/*"] + +[tool.pytest.ini_options] +testpaths = ["tests"] +pythonpath = ["src"] + +[tool.ruff] +line-length = 100 +target-version = "py312" diff --git a/src/site_engine/__init__.py b/src/site_engine/__init__.py new file mode 100644 index 0000000..147dde9 --- /dev/null +++ b/src/site_engine/__init__.py @@ -0,0 +1,3 @@ +"""Site Engine: сайты из Markdown + YAML, layouts и fragments.""" + +__version__ = "0.1.0" diff --git a/src/site_engine/builtin/base.css b/src/site_engine/builtin/base.css new file mode 100644 index 0000000..2f0eb94 --- /dev/null +++ b/src/site_engine/builtin/base.css @@ -0,0 +1,19 @@ +/* Базовые стили движка. Оформление задаётся токенами темы: --color-primary и т.д. */ +*, *::before, *::after { box-sizing: border-box; } +body { + margin: 0; + font-family: var(--font-body, system-ui, sans-serif); + color: var(--color-text, #1a1a1a); + background: var(--color-bg, #fff); + line-height: 1.55; +} +img { max-width: 100%; height: auto; } +a { color: var(--color-primary, #0b5fff); } +.f-container { max-width: 72rem; margin: 0 auto; padding: 0 1rem; } +.f-btn { + display: inline-block; padding: .6rem 1.1rem; margin: 0 .5rem .5rem 0; border-radius: .4rem; + background: var(--color-primary, #0b5fff); color: #fff; text-decoration: none; border: 0; cursor: pointer; +} +.f-btn--secondary { background: transparent; color: var(--color-primary, #0b5fff); outline: 1px solid currentColor; } +.f-card { list-style: none; padding: 1rem; border: 1px solid #e2e2e2; border-radius: .6rem; } +.f-badge { font-size: .75rem; padding: .1rem .5rem; border-radius: 1rem; background: #eef3ff; } diff --git a/src/site_engine/builtin/fragments/card_grid/fragment.yaml b/src/site_engine/builtin/fragments/card_grid/fragment.yaml new file mode 100644 index 0000000..5630a94 --- /dev/null +++ b/src/site_engine/builtin/fragments/card_grid/fragment.yaml @@ -0,0 +1,17 @@ +id: card_grid +name: Сетка карточек +category: content +version: 1 +fields: + - {key: title, type: text} + - {key: variant, type: select, options: [features, steps, links], default: features} + - key: items + type: list + required: true + fields: + - {key: title, type: text, required: true} + - {key: text, type: markdown} + - {key: link, type: link} + - {key: badge, type: text} +slots: {} +preview: {variant: features} diff --git a/src/site_engine/builtin/fragments/card_grid/style.css b/src/site_engine/builtin/fragments/card_grid/style.css new file mode 100644 index 0000000..1ee263f --- /dev/null +++ b/src/site_engine/builtin/fragments/card_grid/style.css @@ -0,0 +1,4 @@ +.f-card_grid { padding: 2rem 0; } +.f-card_grid__items { display: grid; grid-template-columns: repeat(auto-fit, minmax(14rem, 1fr)); gap: 1rem; padding: 0; margin: 0; } +.f-card_grid--steps .f-card_grid__items { counter-reset: step; } +.f-card_grid--steps .f-card::before { counter-increment: step; content: counter(step); font-weight: 700; color: var(--color-primary, #0b5fff); } diff --git a/src/site_engine/builtin/fragments/card_grid/template.html.j2 b/src/site_engine/builtin/fragments/card_grid/template.html.j2 new file mode 100644 index 0000000..325d4bb --- /dev/null +++ b/src/site_engine/builtin/fragments/card_grid/template.html.j2 @@ -0,0 +1,14 @@ +
+
+ {% if props.title %}

{{ props.title }}

{% endif %} + <{{ 'ol' if props.variant == 'steps' else 'ul' }} class='f-card_grid__items'> + {% for item in props.items %} +
  • + {% if item.badge %}{{ item.badge }}{% endif %} +

    {% if item.link %}{{ item.title }}{% else %}{{ item.title }}{% endif %}

    + {% if item.text %}
    {{ item.text|md_inline }}
    {% endif %} +
  • + {% endfor %} + +
    +
    diff --git a/src/site_engine/builtin/fragments/collection_list/fragment.yaml b/src/site_engine/builtin/fragments/collection_list/fragment.yaml new file mode 100644 index 0000000..6e57826 --- /dev/null +++ b/src/site_engine/builtin/fragments/collection_list/fragment.yaml @@ -0,0 +1,13 @@ +id: collection_list +name: Список записей коллекции +category: collections +version: 1 +fields: + - {key: title, type: text} + - {key: source, type: query, required: true} + - {key: card, type: select, options: [default, direction], default: default} + - {key: layout, type: select, options: [grid, list], default: grid} + - {key: empty, type: select, options: [hide, message], default: hide} + - {key: empty_message, type: text} +slots: {} +preview: {} diff --git a/src/site_engine/builtin/fragments/collection_list/style.css b/src/site_engine/builtin/fragments/collection_list/style.css new file mode 100644 index 0000000..22a67fe --- /dev/null +++ b/src/site_engine/builtin/fragments/collection_list/style.css @@ -0,0 +1,4 @@ +.f-collection_list { padding: 2rem 0; } +.f-collection_list__items { display: grid; gap: 1rem; padding: 0; margin: 0; } +.f-collection_list--grid .f-collection_list__items { grid-template-columns: repeat(auto-fit, minmax(16rem, 1fr)); } +.f-card__tagline { font-weight: 600; margin: 0 0 .4rem; } diff --git a/src/site_engine/builtin/fragments/collection_list/template.html.j2 b/src/site_engine/builtin/fragments/collection_list/template.html.j2 new file mode 100644 index 0000000..3deee40 --- /dev/null +++ b/src/site_engine/builtin/fragments/collection_list/template.html.j2 @@ -0,0 +1,18 @@ +{% if props.source %} +
    +
    + {% if props.title %}

    {{ props.title }}

    {% endif %} +
      + {% for e in props.source %} +
    • +

      {{ e.title }}

      + {% if props.card == 'direction' and e.get('tagline') %}

      {{ e.tagline }}

      {% endif %} + {% if e.get('summary') %}

      {{ e.summary }}

      {% endif %} +
    • + {% endfor %} +
    +
    +
    +{% elif props.empty == 'message' %} +

    {{ props.empty_message }}

    +{% endif %} diff --git a/src/site_engine/builtin/fragments/columns/fragment.yaml b/src/site_engine/builtin/fragments/columns/fragment.yaml new file mode 100644 index 0000000..768141b --- /dev/null +++ b/src/site_engine/builtin/fragments/columns/fragment.yaml @@ -0,0 +1,12 @@ +id: columns +name: Колонки +category: layout +version: 1 +fields: + - {key: count, type: select, options: [2, 3, 4], default: 2} +slots: + col_1: {} + col_2: {} + col_3: {} + col_4: {} +preview: {count: 2} diff --git a/src/site_engine/builtin/fragments/columns/style.css b/src/site_engine/builtin/fragments/columns/style.css new file mode 100644 index 0000000..fcdb12a --- /dev/null +++ b/src/site_engine/builtin/fragments/columns/style.css @@ -0,0 +1,5 @@ +.f-columns { display: grid; gap: 1.5rem; } +.f-columns--2 { grid-template-columns: repeat(2, 1fr); } +.f-columns--3 { grid-template-columns: repeat(3, 1fr); } +.f-columns--4 { grid-template-columns: repeat(4, 1fr); } +@media (max-width: 700px) { .f-columns { grid-template-columns: 1fr; } } diff --git a/src/site_engine/builtin/fragments/columns/template.html.j2 b/src/site_engine/builtin/fragments/columns/template.html.j2 new file mode 100644 index 0000000..bfc43be --- /dev/null +++ b/src/site_engine/builtin/fragments/columns/template.html.j2 @@ -0,0 +1,5 @@ +
    + {% for name in ['col_1', 'col_2', 'col_3', 'col_4'] %} + {% if slots[name] %}
    {{ slots[name] }}
    {% endif %} + {% endfor %} +
    diff --git a/src/site_engine/builtin/fragments/cta_banner/fragment.yaml b/src/site_engine/builtin/fragments/cta_banner/fragment.yaml new file mode 100644 index 0000000..83418d0 --- /dev/null +++ b/src/site_engine/builtin/fragments/cta_banner/fragment.yaml @@ -0,0 +1,11 @@ +id: cta_banner +name: Призыв к действию +category: conversion +version: 1 +fields: + - {key: title, type: text, required: true} + - {key: text, type: markdown} + - {key: variant, type: select, options: [contact, link, form], default: link} + - {key: actions, type: list, of: link} +slots: {} +preview: {title: Расскажите о задаче, variant: contact} diff --git a/src/site_engine/builtin/fragments/cta_banner/style.css b/src/site_engine/builtin/fragments/cta_banner/style.css new file mode 100644 index 0000000..1307652 --- /dev/null +++ b/src/site_engine/builtin/fragments/cta_banner/style.css @@ -0,0 +1 @@ +.f-cta_banner { margin: 2rem 0; padding: 2.5rem 0; background: #f0f4ff; } diff --git a/src/site_engine/builtin/fragments/cta_banner/template.html.j2 b/src/site_engine/builtin/fragments/cta_banner/template.html.j2 new file mode 100644 index 0000000..e0c748e --- /dev/null +++ b/src/site_engine/builtin/fragments/cta_banner/template.html.j2 @@ -0,0 +1,12 @@ +
    +
    +

    {{ props.title }}

    + {% if props.text %}

    {{ props.text|md_inline }}

    {% endif %} +

    + {% if props.variant == 'contact' and site.contacts.get('telegram') %} + Написать в Telegram + {% endif %} + {% for a in props.actions %}{% if a %}{{ a.label }}{% endif %}{% endfor %} +

    +
    +
    diff --git a/src/site_engine/builtin/fragments/disclaimer/fragment.yaml b/src/site_engine/builtin/fragments/disclaimer/fragment.yaml new file mode 100644 index 0000000..0ee8424 --- /dev/null +++ b/src/site_engine/builtin/fragments/disclaimer/fragment.yaml @@ -0,0 +1,9 @@ +id: disclaimer +name: Пометка или оговорка +category: content +version: 1 +fields: + - {key: variant, type: select, options: [info, warning], default: info} + - {key: text, type: markdown, required: true} +slots: {} +preview: {text: Пояснение.} diff --git a/src/site_engine/builtin/fragments/disclaimer/style.css b/src/site_engine/builtin/fragments/disclaimer/style.css new file mode 100644 index 0000000..4d716d1 --- /dev/null +++ b/src/site_engine/builtin/fragments/disclaimer/style.css @@ -0,0 +1,2 @@ +.f-disclaimer { padding: .8rem 0; margin: 1rem 0; background: #fff8e1; border-left: 4px solid #f5b400; } +.f-disclaimer--info { background: #eef6ff; border-left-color: var(--color-primary, #0b5fff); } diff --git a/src/site_engine/builtin/fragments/disclaimer/template.html.j2 b/src/site_engine/builtin/fragments/disclaimer/template.html.j2 new file mode 100644 index 0000000..a8dfedc --- /dev/null +++ b/src/site_engine/builtin/fragments/disclaimer/template.html.j2 @@ -0,0 +1,3 @@ + diff --git a/src/site_engine/builtin/fragments/entry_header/fragment.yaml b/src/site_engine/builtin/fragments/entry_header/fragment.yaml new file mode 100644 index 0000000..0d2e5f6 --- /dev/null +++ b/src/site_engine/builtin/fragments/entry_header/fragment.yaml @@ -0,0 +1,9 @@ +id: entry_header +name: Шапка страницы записи +category: collections +version: 1 +fields: + - {key: title, type: text, required: true} + - {key: meta, type: list, of: text} +slots: {} +preview: {title: Заголовок записи} diff --git a/src/site_engine/builtin/fragments/entry_header/style.css b/src/site_engine/builtin/fragments/entry_header/style.css new file mode 100644 index 0000000..197c713 --- /dev/null +++ b/src/site_engine/builtin/fragments/entry_header/style.css @@ -0,0 +1,2 @@ +.f-entry_header { padding: 2rem 0 .5rem; } +.f-entry_header__meta span { margin-right: .75rem; color: #666; } diff --git a/src/site_engine/builtin/fragments/entry_header/template.html.j2 b/src/site_engine/builtin/fragments/entry_header/template.html.j2 new file mode 100644 index 0000000..e43dec2 --- /dev/null +++ b/src/site_engine/builtin/fragments/entry_header/template.html.j2 @@ -0,0 +1,6 @@ +
    +
    +

    {{ props.title }}

    + {% if props.meta %}

    {% for m in props.meta if m %}{{ m }} {% endfor %}

    {% endif %} +
    +
    diff --git a/src/site_engine/builtin/fragments/faq/fragment.yaml b/src/site_engine/builtin/fragments/faq/fragment.yaml new file mode 100644 index 0000000..51354fb --- /dev/null +++ b/src/site_engine/builtin/fragments/faq/fragment.yaml @@ -0,0 +1,14 @@ +id: faq +name: Вопросы и ответы +category: content +version: 1 +fields: + - {key: title, type: text} + - key: items + type: list + required: true + fields: + - {key: q, type: text, required: true} + - {key: a, type: markdown, required: true} +slots: {} +preview: {} diff --git a/src/site_engine/builtin/fragments/faq/style.css b/src/site_engine/builtin/fragments/faq/style.css new file mode 100644 index 0000000..05377a2 --- /dev/null +++ b/src/site_engine/builtin/fragments/faq/style.css @@ -0,0 +1,3 @@ +.f-faq { padding: 1.5rem 0; } +.f-faq details { border-bottom: 1px solid #e2e2e2; padding: .6rem 0; } +.f-faq summary { cursor: pointer; font-weight: 600; } diff --git a/src/site_engine/builtin/fragments/faq/template.html.j2 b/src/site_engine/builtin/fragments/faq/template.html.j2 new file mode 100644 index 0000000..580cb2a --- /dev/null +++ b/src/site_engine/builtin/fragments/faq/template.html.j2 @@ -0,0 +1,8 @@ +
    +
    + {% if props.title %}

    {{ props.title }}

    {% endif %} + {% for i in props.items %} +
    {{ i.q }}
    {{ i.a|md }}
    + {% endfor %} +
    +
    diff --git a/src/site_engine/builtin/fragments/form/fragment.yaml b/src/site_engine/builtin/fragments/form/fragment.yaml new file mode 100644 index 0000000..c5e1cb9 --- /dev/null +++ b/src/site_engine/builtin/fragments/form/fragment.yaml @@ -0,0 +1,8 @@ +id: form +name: Форма обратной связи +category: conversion +version: 1 +fields: + - {key: form, type: text, required: true} +slots: {} +preview: {} diff --git a/src/site_engine/builtin/fragments/form/style.css b/src/site_engine/builtin/fragments/form/style.css new file mode 100644 index 0000000..d80a675 --- /dev/null +++ b/src/site_engine/builtin/fragments/form/style.css @@ -0,0 +1,5 @@ +.f-form form { display: grid; gap: .8rem; max-width: 36rem; } +.f-form label { display: grid; gap: .25rem; } +.f-form input[type=text], .f-form textarea { padding: .5rem; font: inherit; } +.f-form__trap { position: absolute; left: -9999px; } +.f-form__consent { display: flex; gap: .5rem; align-items: start; } diff --git a/src/site_engine/builtin/fragments/form/template.html.j2 b/src/site_engine/builtin/fragments/form/template.html.j2 new file mode 100644 index 0000000..4d87e5b --- /dev/null +++ b/src/site_engine/builtin/fragments/form/template.html.j2 @@ -0,0 +1,23 @@ +{% set f = forms.get(props.form) %} +{% if f %} +
    +
    +

    {{ f.title }}

    +
    + + + {% for field in f.fields %} + {% if field.type == 'consent' %} + + {% elif field.type == 'textarea' %} + + {% else %} + + {% endif %} + {% endfor %} + +
    +
    +
    +{% endif %} diff --git a/src/site_engine/builtin/fragments/hero/fragment.yaml b/src/site_engine/builtin/fragments/hero/fragment.yaml new file mode 100644 index 0000000..3f7816b --- /dev/null +++ b/src/site_engine/builtin/fragments/hero/fragment.yaml @@ -0,0 +1,13 @@ +id: hero +name: Hero-баннер +category: marketing +version: 1 +fields: + - {key: title, type: text, required: true, max: 120} + - {key: subtitle, type: markdown} + - {key: image, type: asset} + - {key: image_alt, type: text} + - {key: actions, type: list, of: link} + - {key: variant, type: select, options: [light, dark, split], default: light} +slots: {} +preview: {title: Заголовок страницы, variant: dark} diff --git a/src/site_engine/builtin/fragments/hero/style.css b/src/site_engine/builtin/fragments/hero/style.css new file mode 100644 index 0000000..1d8cea1 --- /dev/null +++ b/src/site_engine/builtin/fragments/hero/style.css @@ -0,0 +1,4 @@ +.f-hero { padding: 4rem 0; } +.f-hero--dark { background: var(--color-dark, #14213d); color: #fff; } +.f-hero--dark a:not(.f-btn) { color: #fff; } +.f-hero h1 { font-size: 2.4rem; margin: 0 0 1rem; } diff --git a/src/site_engine/builtin/fragments/hero/template.html.j2 b/src/site_engine/builtin/fragments/hero/template.html.j2 new file mode 100644 index 0000000..3a460e5 --- /dev/null +++ b/src/site_engine/builtin/fragments/hero/template.html.j2 @@ -0,0 +1,10 @@ +
    +
    +

    {{ props.title }}

    + {% if props.subtitle %}

    {{ props.subtitle|md_inline }}

    {% endif %} + {% if props.actions %} +

    {% for a in props.actions %}{% if a %}{{ a.label }}{% endif %}{% endfor %}

    + {% endif %} + {% if props.image %}{{ props.image_alt or {% endif %} +
    +
    diff --git a/src/site_engine/builtin/fragments/image/fragment.yaml b/src/site_engine/builtin/fragments/image/fragment.yaml new file mode 100644 index 0000000..62ebe2d --- /dev/null +++ b/src/site_engine/builtin/fragments/image/fragment.yaml @@ -0,0 +1,10 @@ +id: image +name: Изображение +category: content +version: 1 +fields: + - {key: asset, type: asset, required: true} + - {key: alt, type: text, required: true} + - {key: caption, type: text} +slots: {} +preview: {} diff --git a/src/site_engine/builtin/fragments/image/style.css b/src/site_engine/builtin/fragments/image/style.css new file mode 100644 index 0000000..584151a --- /dev/null +++ b/src/site_engine/builtin/fragments/image/style.css @@ -0,0 +1 @@ +.f-image figcaption { font-size: .85rem; color: #666; } diff --git a/src/site_engine/builtin/fragments/image/template.html.j2 b/src/site_engine/builtin/fragments/image/template.html.j2 new file mode 100644 index 0000000..9cde462 --- /dev/null +++ b/src/site_engine/builtin/fragments/image/template.html.j2 @@ -0,0 +1,4 @@ +
    + {{ props.alt }} + {% if props.caption %}
    {{ props.caption }}
    {% endif %} +
    diff --git a/src/site_engine/builtin/fragments/page_header/fragment.yaml b/src/site_engine/builtin/fragments/page_header/fragment.yaml new file mode 100644 index 0000000..0791d6b --- /dev/null +++ b/src/site_engine/builtin/fragments/page_header/fragment.yaml @@ -0,0 +1,10 @@ +id: page_header +name: Заголовок страницы +category: marketing +version: 1 +fields: + - {key: title, type: text, required: true} + - {key: lead, type: markdown} + - {key: breadcrumbs, type: boolean, default: true} +slots: {} +preview: {title: Заголовок} diff --git a/src/site_engine/builtin/fragments/page_header/style.css b/src/site_engine/builtin/fragments/page_header/style.css new file mode 100644 index 0000000..686961a --- /dev/null +++ b/src/site_engine/builtin/fragments/page_header/style.css @@ -0,0 +1,3 @@ +.f-page_header { padding: 2rem 0 1rem; } +.f-page_header__crumbs { display: flex; gap: .5rem; list-style: none; padding: 0; margin: 0 0 .5rem; font-size: .9rem; } +.f-page_header__crumbs li + li::before { content: '/'; margin-right: .5rem; color: #888; } diff --git a/src/site_engine/builtin/fragments/page_header/template.html.j2 b/src/site_engine/builtin/fragments/page_header/template.html.j2 new file mode 100644 index 0000000..a328184 --- /dev/null +++ b/src/site_engine/builtin/fragments/page_header/template.html.j2 @@ -0,0 +1,15 @@ +
    +
    + {% if props.breadcrumbs and breadcrumbs|length > 1 %} + + {% endif %} +

    {{ props.title }}

    + {% if props.lead %}

    {{ props.lead|md_inline }}

    {% endif %} +
    +
    diff --git a/src/site_engine/builtin/fragments/richtext/fragment.yaml b/src/site_engine/builtin/fragments/richtext/fragment.yaml new file mode 100644 index 0000000..b3cfc57 --- /dev/null +++ b/src/site_engine/builtin/fragments/richtext/fragment.yaml @@ -0,0 +1,8 @@ +id: richtext +name: Текст +category: content +version: 1 +fields: + - {key: content, type: markdown, required: true} +slots: {} +preview: {content: Текст **страницы**.} diff --git a/src/site_engine/builtin/fragments/richtext/style.css b/src/site_engine/builtin/fragments/richtext/style.css new file mode 100644 index 0000000..e945c82 --- /dev/null +++ b/src/site_engine/builtin/fragments/richtext/style.css @@ -0,0 +1 @@ +.f-richtext { padding-top: 1rem; padding-bottom: 1rem; max-width: 52rem; } diff --git a/src/site_engine/builtin/fragments/richtext/template.html.j2 b/src/site_engine/builtin/fragments/richtext/template.html.j2 new file mode 100644 index 0000000..9a2f0e3 --- /dev/null +++ b/src/site_engine/builtin/fragments/richtext/template.html.j2 @@ -0,0 +1 @@ +
    {{ props.content|md }}
    diff --git a/src/site_engine/builtin/fragments/section/fragment.yaml b/src/site_engine/builtin/fragments/section/fragment.yaml new file mode 100644 index 0000000..ecfee67 --- /dev/null +++ b/src/site_engine/builtin/fragments/section/fragment.yaml @@ -0,0 +1,11 @@ +id: section +name: Секция +category: layout +version: 1 +fields: + - {key: title, type: text} + - {key: background, type: select, options: [none, muted, primary], default: none} + - {key: width, type: select, options: [narrow, normal, wide], default: normal} +slots: + content: {} +preview: {title: Секция} diff --git a/src/site_engine/builtin/fragments/section/style.css b/src/site_engine/builtin/fragments/section/style.css new file mode 100644 index 0000000..167bed2 --- /dev/null +++ b/src/site_engine/builtin/fragments/section/style.css @@ -0,0 +1,5 @@ +.f-section { padding: 2.5rem 0; } +.f-section--muted { background: #f6f6f6; } +.f-section--primary { background: var(--color-primary, #0b5fff); color: #fff; } +.f-section--narrow > .f-container { max-width: 44rem; } +.f-section--wide > .f-container { max-width: 90rem; } diff --git a/src/site_engine/builtin/fragments/section/template.html.j2 b/src/site_engine/builtin/fragments/section/template.html.j2 new file mode 100644 index 0000000..d6a011e --- /dev/null +++ b/src/site_engine/builtin/fragments/section/template.html.j2 @@ -0,0 +1,6 @@ +
    +
    + {% if props.title %}

    {{ props.title }}

    {% endif %} + {{ slots.content }} +
    +
    diff --git a/src/site_engine/builtin/fragments/site_footer/fragment.yaml b/src/site_engine/builtin/fragments/site_footer/fragment.yaml new file mode 100644 index 0000000..5635041 --- /dev/null +++ b/src/site_engine/builtin/fragments/site_footer/fragment.yaml @@ -0,0 +1,9 @@ +id: site_footer +name: Подвал сайта +category: global +version: 1 +fields: + - {key: menu, type: text, default: footer} + - {key: note, type: text} +slots: {} +preview: {menu: footer} diff --git a/src/site_engine/builtin/fragments/site_footer/style.css b/src/site_engine/builtin/fragments/site_footer/style.css new file mode 100644 index 0000000..950b08d --- /dev/null +++ b/src/site_engine/builtin/fragments/site_footer/style.css @@ -0,0 +1,2 @@ +.f-site_footer { margin-top: 3rem; padding: 1.5rem 0; background: #f6f6f6; font-size: .9rem; } +.f-site_footer ul { display: flex; gap: 1rem; list-style: none; margin: 0 0 1rem; padding: 0; } diff --git a/src/site_engine/builtin/fragments/site_footer/template.html.j2 b/src/site_engine/builtin/fragments/site_footer/template.html.j2 new file mode 100644 index 0000000..b47cc2d --- /dev/null +++ b/src/site_engine/builtin/fragments/site_footer/template.html.j2 @@ -0,0 +1,14 @@ +
    +
    +
      + {% for item in menus.get(props.menu, []) %} +
    • {{ item.label }}
    • + {% endfor %} +
    + {% if data.get('company') %} +

    {{ data.company.get('legal_name', site.name) }}{% if data.company.get('requisites') %} · {{ data.company.requisites }}{% endif %}

    + {% endif %} + {% if props.note %}

    {{ props.note }}

    {% endif %} +

    © {{ build.year }} {{ site.name }}

    +
    +
    diff --git a/src/site_engine/builtin/fragments/site_header/fragment.yaml b/src/site_engine/builtin/fragments/site_header/fragment.yaml new file mode 100644 index 0000000..c6372dd --- /dev/null +++ b/src/site_engine/builtin/fragments/site_header/fragment.yaml @@ -0,0 +1,9 @@ +id: site_header +name: Шапка сайта +category: global +version: 1 +fields: + - {key: menu, type: text, default: main} + - {key: action, type: link} +slots: {} +preview: {menu: main} diff --git a/src/site_engine/builtin/fragments/site_header/style.css b/src/site_engine/builtin/fragments/site_header/style.css new file mode 100644 index 0000000..e4ae30b --- /dev/null +++ b/src/site_engine/builtin/fragments/site_header/style.css @@ -0,0 +1,4 @@ +.f-site_header { border-bottom: 1px solid #e2e2e2; } +.f-site_header__row { display: flex; align-items: center; gap: 1.5rem; padding-top: .8rem; padding-bottom: .8rem; } +.f-site_header__brand { font-weight: 700; text-decoration: none; margin-right: auto; } +.f-site_header ul { display: flex; gap: 1rem; list-style: none; margin: 0; padding: 0; } diff --git a/src/site_engine/builtin/fragments/site_header/template.html.j2 b/src/site_engine/builtin/fragments/site_header/template.html.j2 new file mode 100644 index 0000000..a5a9408 --- /dev/null +++ b/src/site_engine/builtin/fragments/site_header/template.html.j2 @@ -0,0 +1,13 @@ +
    +
    + {{ site.name }} + + {% if props.action %}{{ props.action.label }}{% endif %} +
    +
    diff --git a/src/site_engine/cli.py b/src/site_engine/cli.py new file mode 100644 index 0000000..ca837a3 --- /dev/null +++ b/src/site_engine/cli.py @@ -0,0 +1,94 @@ +"""CLI: validate, build, preview, fragments.""" + +from __future__ import annotations + +import sys +from pathlib import Path + +import click + +from .build.pipeline import build_site, preview_page +from .core.registry import load_site +from .core.routes import build_route_table +from .core.validate import validate_release, validate_workspace +from .errors import EngineError, Report + + +def _print(report: Report) -> None: + for issue in report.issues: + click.echo(str(issue), err=True) + + +@click.group() +def main() -> None: + """Site Engine: сайты из Markdown + YAML, layouts и fragments.""" + + +@main.command() +@click.argument("site", type=click.Path(exists=True, file_okay=False, path_type=Path)) +def validate(site: Path) -> None: + """Проверить сайт (workspace + release) без записи результата.""" + try: + reg = load_site(site) + except EngineError as exc: + _print(exc.report) + raise click.ClickException(str(exc)) from exc + report = Report() + table_report = Report() + table = build_route_table(reg, table_report) + report.extend(validate_workspace(reg, table)) + report.extend(table_report) + report.extend(validate_release(reg, table)) + _print(report) + click.echo(f"ошибок: {len(report.errors)}, предупреждений: {len(report.warnings)}") + sys.exit(1 if report.errors else 0) + + +@main.command() +@click.argument("site", type=click.Path(exists=True, file_okay=False, path_type=Path)) +@click.option("--out", type=click.Path(path_type=Path), default=Path("dist"), show_default=True) +@click.option("--keep", default=5, show_default=True, help="сколько релизов хранить для отката") +def build(site: Path, out: Path, keep: int) -> None: + """Собрать релиз в OUT/ и переключить OUT/current.""" + try: + result = build_site(site, out, keep=keep) + except EngineError as exc: + _print(exc.report) + raise click.ClickException(str(exc)) from exc + _print(result.report) + click.echo(f"собрано {result.pages} страниц → {result.output_dir} (current → {result.build_id})") + + +@main.command() +@click.argument("site", type=click.Path(exists=True, file_okay=False, path_type=Path)) +@click.argument("page_id") +def preview(site: Path, page_id: str) -> None: + """Напечатать HTML страницы (включая черновик) в stdout.""" + try: + html, report = preview_page(site, page_id) + except EngineError as exc: + _print(exc.report) + raise click.ClickException(str(exc)) from exc + _print(report) + click.echo(html) + + +@main.command() +@click.option("--site", type=click.Path(exists=True, file_okay=False, path_type=Path), default=None) +def fragments(site: Path | None) -> None: + """Список доступных фрагментов (встроенные и сайта).""" + if site is not None: + reg = load_site(site) + items = reg.fragments.values() + else: + import tempfile + + with tempfile.TemporaryDirectory() as tmp: + (Path(tmp) / "site.yaml").write_text("name: tmp\n", encoding="utf-8") + items = load_site(Path(tmp)).fragments.values() + for f in sorted(items, key=lambda x: (x.category, x.id)): + click.echo(f"{f.category:<10} {f.id:<16} v{f.version} {f.name}") + + +if __name__ == "__main__": + main() diff --git a/src/site_engine/core/__init__.py b/src/site_engine/core/__init__.py new file mode 100644 index 0000000..17aa75b --- /dev/null +++ b/src/site_engine/core/__init__.py @@ -0,0 +1 @@ +"""Ядро: модели, реестр, валидация, разрешение значений, рендер, сборка.""" diff --git a/src/site_engine/core/models.py b/src/site_engine/core/models.py new file mode 100644 index 0000000..c96a8bc --- /dev/null +++ b/src/site_engine/core/models.py @@ -0,0 +1,491 @@ +"""Модель данных сайта: dataclass-ы и разбор сырого YAML с путями ошибок. + +Pydantic в ядро не берём: нужны структурированные ошибки с путями вида +`pages/index.md:regions.main[b_hero].props.title`, и валидация управляется манифестами +фрагментов. Pydantic используется на границах API (web, mcp). +""" + +from __future__ import annotations + +import hashlib +import json +import re +from dataclasses import dataclass, field +from pathlib import Path +from typing import Any + +from ..errors import Report + +BLOCK_ID_RE = re.compile(r"^[A-Za-z][A-Za-z0-9_-]{1,63}$") +FRAGMENT_ID_RE = re.compile(r"^[a-z][a-z0-9_]*$") +COLLECTION_ID_RE = re.compile(r"^[a-z][a-z0-9_]*$") +STATUSES = ("draft", "published", "archived") +MAX_DEPTH = 4 +PRIMITIVE_TYPES = { + "text", "textarea", "markdown", "number", "boolean", "select", "multiselect", + "date", "datetime", "color", "icon", "slug", "link", "asset", +} +FIELD_TYPES = PRIMITIVE_TYPES | {"group", "list", "query", "ref", "refs", "json"} + + +# ── блоки ──────────────────────────────────────────────────────────────────── + +@dataclass +class Block: + id: str + fragment: str + props: dict = field(default_factory=dict) + slots: dict[str, list["Block"]] = field(default_factory=dict) + hidden: bool = False + anchor: str | None = None + note: str | None = None + requires: list[str] = field(default_factory=list) + style: dict = field(default_factory=dict) + + +_BLOCK_KEYS = {"id", "fragment", "props", "slots", "hidden", "anchor", "note", "requires", "style"} + + +def parse_block(raw: Any, path: str, report: Report, depth: int = 1) -> Block | None: + if not isinstance(raw, dict): + report.add("E_BLOCK_SHAPE", "блок должен быть объектом", path) + return None + bid = raw.get("id") + label = f"{path}[{bid}]" if isinstance(bid, str) else path + ok = True + unknown = set(raw) - _BLOCK_KEYS + if unknown: + report.add("E_BLOCK_KEY", f"неизвестные ключи блока: {sorted(unknown)}", label) + ok = False + if not isinstance(bid, str) or not BLOCK_ID_RE.match(bid): + report.add("E_BLOCK_ID", "у блока обязателен явный id (латиница, цифры, _ и -)", path) + return None + frag = raw.get("fragment") + if not isinstance(frag, str) or not frag: + report.add("E_BLOCK_FRAGMENT", "у блока обязательно поле fragment", label) + return None + if depth > MAX_DEPTH: + report.add("E_BLOCK_DEPTH", f"вложенность блоков больше {MAX_DEPTH}", label) + return None + props = raw.get("props") or {} + if not isinstance(props, dict): + report.add("E_BLOCK_PROPS", "props должен быть объектом", label) + props, ok = {}, False + requires = raw.get("requires") or [] + if not (isinstance(requires, list) and all(isinstance(r, str) for r in requires)): + report.add("E_BLOCK_REQUIRES", "requires: ожидается список строк", label) + requires, ok = [], False + slots: dict[str, list[Block]] = {} + raw_slots = raw.get("slots") or {} + if not isinstance(raw_slots, dict): + report.add("E_BLOCK_SLOTS", "slots должен быть объектом", label) + raw_slots, ok = {}, False + for name, items in raw_slots.items(): + slots[str(name)] = parse_blocks(items, f"{label}.slots.{name}", report, depth + 1) + if not ok: + return None + return Block( + id=bid, fragment=frag, props=props, slots=slots, hidden=bool(raw.get("hidden", False)), + anchor=raw.get("anchor"), note=raw.get("note"), requires=requires, + style=raw.get("style") or {}, + ) + + +def parse_blocks(raw: Any, path: str, report: Report, depth: int = 1) -> list[Block]: + if raw is None: + return [] + if not isinstance(raw, list): + report.add("E_BLOCKS_SHAPE", "ожидается список блоков", path) + return [] + out = [] + for i, item in enumerate(raw): + block = parse_block(item, f"{path}[{i}]", report, depth) + if block is not None: + out.append(block) + return out + + +def parse_regions(raw: Any, path: str, report: Report) -> dict[str, list[Block]]: + if raw is None: + return {} + if not isinstance(raw, dict): + report.add("E_REGIONS_SHAPE", "regions должен быть объектом", path) + return {} + return {str(n): parse_blocks(b, f"{path}.regions.{n}", report) for n, b in raw.items()} + + +def walk_blocks(blocks: list[Block]): + for b in blocks: + yield b + for children in b.slots.values(): + yield from walk_blocks(children) + + +# ── поля и фрагменты ────────────────────────────────────────────────────────── + +@dataclass +class FieldDef: + key: str + type: str + required: bool = False + default: Any = None + options: list = field(default_factory=list) + label: str | None = None + to: str | None = None + fields: list["FieldDef"] = field(default_factory=list) + of: str | None = None + extra: dict = field(default_factory=dict) + + +_FIELD_KNOWN = {"key", "type", "required", "default", "options", "label", "to", "fields", "of"} + + +def parse_fields(raw: Any, path: str, report: Report) -> list[FieldDef]: + if raw is None: + return [] + if not isinstance(raw, list): + report.add("E_FIELDS_SHAPE", "fields должен быть списком", path) + return [] + out: list[FieldDef] = [] + seen: set[str] = set() + for i, item in enumerate(raw): + where = f"{path}[{i}]" + if not isinstance(item, dict) or not isinstance(item.get("key"), str): + report.add("E_FIELD_SHAPE", "поле: ожидается объект с key", where) + continue + key, ftype = item["key"], item.get("type") + where = f"{path}.{key}" + if key in seen: + report.add("E_FIELD_DUP", f"повтор ключа поля «{key}»", where) + continue + seen.add(key) + if ftype not in FIELD_TYPES: + report.add("E_FIELD_TYPE", f"неизвестный тип поля «{ftype}»", where) + continue + options = item.get("options") or [] + if ftype in ("select", "multiselect") and not options: + report.add("E_FIELD_OPTIONS", "для select/multiselect нужны options", where) + of = item.get("of") + if ftype == "list" and of is not None and of not in PRIMITIVE_TYPES: + report.add("E_FIELD_OF", f"list.of: недопустимый тип «{of}»", where) + of = None + sub = parse_fields(item.get("fields"), f"{where}.fields", report) if item.get("fields") else [] + if ftype == "group" and not sub: + report.add("E_FIELD_GROUP", "group требует fields", where) + if ftype == "list" and not sub and not of: + report.add("E_FIELD_LIST", "list требует fields или of", where) + if ftype in ("ref", "refs") and not item.get("to"): + report.add("E_FIELD_REF", "ref/refs требуют to: <коллекция>", where) + out.append( + FieldDef( + key=key, type=ftype, required=bool(item.get("required", False)), + default=item.get("default"), options=list(options), label=item.get("label"), + to=item.get("to"), fields=sub, of=of, + extra={k: v for k, v in item.items() if k not in _FIELD_KNOWN}, + ) + ) + return out + + +@dataclass +class Fragment: + id: str + name: str + category: str + version: int + fields: list[FieldDef] + slots: dict[str, dict] + preview: dict + template: str + style: str | None = None + script: str | None = None + builtin: bool = False + dir: Path | None = None + + +def parse_fragment( + raw: Any, rel: str, directory: Path, builtin: bool, report: Report +) -> Fragment | None: + if not isinstance(raw, dict): + report.add("E_FRAGMENT_SHAPE", "манифест фрагмента должен быть объектом", rel) + return None + fid = raw.get("id") + if not isinstance(fid, str) or not FRAGMENT_ID_RE.match(fid): + report.add("E_FRAGMENT_ID", "id фрагмента: латиница в нижнем регистре, цифры и _", rel) + return None + template_file = directory / "template.html.j2" + if not template_file.is_file(): + report.add("E_FRAGMENT_TEMPLATE", "нет template.html.j2", rel) + return None + version = raw.get("version", 1) + if not isinstance(version, int) or isinstance(version, bool) or version < 1: + report.add("E_FRAGMENT_VERSION", "version: целое >= 1", rel) + version = 1 + slots = raw.get("slots") or {} + if not isinstance(slots, dict): + report.add("E_FRAGMENT_SLOTS", "slots: ожидается объект", rel) + slots = {} + style = directory / "style.css" + script = directory / "script.js" + return Fragment( + id=fid, name=str(raw.get("name", fid)), category=str(raw.get("category", "misc")), + version=version, fields=parse_fields(raw.get("fields"), f"{rel}:fields", report), + slots={str(k): (v or {}) for k, v in slots.items()}, preview=raw.get("preview") or {}, + template=template_file.read_text(encoding="utf-8"), + style=style.read_text(encoding="utf-8") if style.is_file() else None, + script=script.read_text(encoding="utf-8") if script.is_file() else None, + builtin=builtin, dir=directory, + ) + + +# ── layout ──────────────────────────────────────────────────────────────────── + +@dataclass +class RegionDef: + id: str + allow: list[str] | None + fixed: list[Block] + + +@dataclass +class Layout: + id: str + name: str + extends: str | None + regions: dict[str, RegionDef] + template: str + dir: Path | None = None + + +def parse_layout(raw: Any, rel: str, directory: Path, report: Report) -> Layout | None: + if not isinstance(raw, dict) or not isinstance(raw.get("id"), str): + report.add("E_LAYOUT_SHAPE", "layout.yaml: ожидается объект с id", rel) + return None + tpl = directory / "layout.html.j2" + if not tpl.is_file(): + report.add("E_LAYOUT_TEMPLATE", "нет layout.html.j2", rel) + return None + regions: dict[str, RegionDef] = {} + items = raw.get("regions") or [] + if not isinstance(items, list): + report.add("E_LAYOUT_REGIONS", "regions: ожидается список", rel) + items = [] + for i, item in enumerate(items): + if not isinstance(item, dict) or not isinstance(item.get("id"), str): + report.add("E_REGION_SHAPE", "регион: ожидается объект с id", f"{rel}:regions[{i}]") + continue + rid = item["id"] + allow = item.get("allow") + if allow is not None and not (isinstance(allow, list) and all(isinstance(a, str) for a in allow)): + report.add("E_REGION_ALLOW", "allow: ожидается список строк", f"{rel}:regions.{rid}") + allow = None + fixed = parse_blocks(item.get("fixed"), f"{rel}:regions.{rid}.fixed", report) + regions[rid] = RegionDef(rid, allow, fixed) + return Layout( + id=raw["id"], name=str(raw.get("name", raw["id"])), extends=raw.get("extends"), + regions=regions, template=tpl.read_text(encoding="utf-8"), dir=directory, + ) + + +# ── сайт, страницы, записи, коллекции ───────────────────────────────────────── + +@dataclass +class Site: + name: str + base_url: str + default_locale: str + locales: list[str] + theme_tokens: dict + defaults: dict + menus: dict + features: dict[str, bool] + contacts: dict + rules: list[dict] + + +def parse_site(raw: Any, rel: str, report: Report) -> Site | None: + if not isinstance(raw, dict): + report.add("E_SITE_SHAPE", "site.yaml: ожидается объект", rel) + return None + if raw.get("schema", 1) != 1: + report.add("E_SITE_SCHEMA", "поддерживается только schema: 1", rel) + name = raw.get("name") + if not isinstance(name, str) or not name: + report.add("E_SITE_NAME", "site.yaml: обязательное поле name", rel) + return None + features = raw.get("features") or {} + if not (isinstance(features, dict) and all(isinstance(v, bool) for v in features.values())): + report.add("E_SITE_FEATURES", "features: ожидается объект с булевыми значениями", rel) + features = {} + rules = raw.get("rules") or [] + if not isinstance(rules, list): + report.add("E_SITE_RULES", "rules: ожидается список", rel) + rules = [] + theme = raw.get("theme") or {} + return Site( + name=name, base_url=str(raw.get("base_url", "")).rstrip("/"), + default_locale=str(raw.get("default_locale", "ru")), + locales=list(raw.get("locales") or [raw.get("default_locale", "ru")]), + theme_tokens=dict((theme.get("tokens") or {}) if isinstance(theme, dict) else {}), + defaults=raw.get("defaults") or {}, menus=raw.get("menus") or {}, features=features, + contacts=raw.get("contacts") or {}, rules=rules, + ) + + +@dataclass +class Page: + id: str # путь файла без расширения: «services/index» + file: str + title: str + layout: str | None + status: str + route_override: str | None + seo: dict + regions: dict[str, list[Block]] + editorial: dict + body: str + nav: dict | None = None + + +_PAGE_KEYS = {"schema", "title", "layout", "status", "route", "seo", "regions", "nav", "editorial", "breadcrumb"} + + +def parse_page(meta: dict, body: str, page_id: str, rel: str, report: Report) -> Page | None: + unknown = set(meta) - _PAGE_KEYS + if unknown: + report.add("E_PAGE_KEY", f"неизвестные ключи front matter: {sorted(unknown)}", rel) + title = meta.get("title") + if not isinstance(title, str) or not title: + report.add("E_PAGE_TITLE", "обязательное поле title", rel) + return None + status = meta.get("status", "draft") + if status not in STATUSES: + report.add("E_PAGE_STATUS", f"status: одно из {STATUSES}", rel) + status = "draft" + seo = meta.get("seo") or {} + if not isinstance(seo, dict): + report.add("E_PAGE_SEO", "seo: ожидается объект", rel) + seo = {} + return Page( + id=page_id, file=rel, title=title, layout=meta.get("layout"), status=status, + route_override=meta.get("route"), seo=seo, regions=parse_regions(meta.get("regions"), rel, report), + editorial=meta.get("editorial") or {}, body=body, nav=meta.get("nav"), + ) + + +@dataclass +class Collection: + id: str + name: str + kind: str + route: str + list_page: str | None + display: str | None + sort: str | None + body: str | None + fields: list[FieldDef] + + +def parse_collection(raw: Any, rel: str, report: Report) -> Collection | None: + if not isinstance(raw, dict) or not isinstance(raw.get("id"), str): + report.add("E_COLLECTION_SHAPE", "коллекция: ожидается объект с id", rel) + return None + cid = raw["id"] + if not COLLECTION_ID_RE.match(cid): + report.add("E_COLLECTION_ID", "id коллекции: латиница в нижнем регистре, цифры и _", rel) + return None + kind = raw.get("kind", "content") + route = raw.get("route", "") + if kind != "taxonomy" and "{slug}" not in str(route): + report.add("E_COLLECTION_ROUTE", "route должен содержать {slug}", rel) + return Collection( + id=cid, name=str(raw.get("name", cid)), kind=kind, route=str(route), + list_page=raw.get("list_page"), display=raw.get("display"), sort=raw.get("sort"), + body=raw.get("body"), fields=parse_fields(raw.get("fields"), f"{rel}:fields", report), + ) + + +@dataclass +class Entry: + collection: str + slug: str + file: str + status: str + data: dict + body: str + regions: dict[str, list[Block]] + regions_mode: str = "append" + + +_ENTRY_RESERVED = {"slug", "status", "regions", "regions_mode"} + + +def parse_entry( + meta: dict, body: str, collection: str, default_slug: str, rel: str, report: Report +) -> Entry | None: + slug = meta.get("slug", default_slug) + if not isinstance(slug, str) or not re.match(r"^[a-z0-9][a-z0-9_-]*$", slug): + report.add("E_ENTRY_SLUG", "slug: нижний регистр, латиница, цифры, - и _", rel) + return None + status = meta.get("status", "draft") + if status not in STATUSES: + report.add("E_ENTRY_STATUS", f"status: одно из {STATUSES}", rel) + status = "draft" + mode = meta.get("regions_mode", "append") + if mode not in ("append", "prepend", "replace"): + report.add("E_ENTRY_MODE", "regions_mode: append | prepend | replace", rel) + mode = "append" + return Entry( + collection=collection, slug=slug, file=rel, status=status, + data={k: v for k, v in meta.items() if k not in _ENTRY_RESERVED}, body=body, + regions=parse_regions(meta.get("regions"), rel, report), regions_mode=mode, + ) + + +@dataclass +class Display: + collection: str + layout: str | None + seo: dict + regions: dict[str, list[Block]] + overrides: str = "allow" + + +def parse_display(raw: Any, collection: str, rel: str, report: Report) -> Display | None: + if not isinstance(raw, dict): + report.add("E_DISPLAY_SHAPE", "display template: ожидается объект", rel) + return None + overrides = raw.get("overrides", "allow") + if overrides not in ("allow", "deny"): + report.add("E_DISPLAY_OVERRIDES", "overrides: allow | deny", rel) + overrides = "allow" + return Display( + collection=collection, layout=raw.get("layout"), seo=raw.get("seo") or {}, + regions=parse_regions(raw.get("regions"), rel, report), overrides=overrides, + ) + + +@dataclass +class Form: + id: str + title: str + fields: list[dict] + success: dict + raw: dict + version: str + + +def parse_form(raw: Any, rel: str, report: Report) -> Form | None: + if not isinstance(raw, dict) or not isinstance(raw.get("id"), str): + report.add("E_FORM_SHAPE", "форма: ожидается объект с id", rel) + return None + fields = raw.get("fields") or [] + if not (isinstance(fields, list) and fields and all(isinstance(f, dict) and "key" in f for f in fields)): + report.add("E_FORM_FIELDS", "fields: непустой список полей с key", rel) + return None + canonical = json.dumps(raw, sort_keys=True, ensure_ascii=False, default=str) + return Form( + id=raw["id"], title=str(raw.get("title", raw["id"])), fields=fields, + success=raw.get("success") or {}, raw=raw, + version=hashlib.sha256(canonical.encode("utf-8")).hexdigest()[:12], + ) diff --git a/src/site_engine/core/registry.py b/src/site_engine/core/registry.py new file mode 100644 index 0000000..f850897 --- /dev/null +++ b/src/site_engine/core/registry.py @@ -0,0 +1,192 @@ +"""Реестр: нормализованное представление сайта, собранное только из файлов (ADR-001). + +Сборка не читает SQLite: `load_site` — чистая функция от каталога сайта и встроенных +фрагментов. Ошибки загрузки копятся в `report`, а не бросаются по одной. +""" + +from __future__ import annotations + +from dataclasses import dataclass, field +from pathlib import Path +from typing import Any + +from ..errors import EngineError, Report +from ..parsing import frontmatter +from ..parsing.yamlio import YamlError, load_yaml +from .models import ( + Collection, Display, Entry, Form, Fragment, Layout, Page, Site, parse_collection, + parse_display, parse_entry, parse_form, parse_fragment, parse_layout, parse_page, parse_site, +) + +BUILTIN_DIR = Path(__file__).resolve().parent.parent / "builtin" + + +@dataclass +class Registry: + root: Path + site: Site + layouts: dict[str, Layout] = field(default_factory=dict) + fragments: dict[str, Fragment] = field(default_factory=dict) + collections: dict[str, Collection] = field(default_factory=dict) + entries: dict[str, list[Entry]] = field(default_factory=dict) + pages: dict[str, Page] = field(default_factory=dict) + displays: dict[str, Display] = field(default_factory=dict) + menus: dict[str, list[dict]] = field(default_factory=dict) + data: dict[str, Any] = field(default_factory=dict) + forms: dict[str, Form] = field(default_factory=dict) + redirects: list[dict] = field(default_factory=list) + sections: dict[str, dict] = field(default_factory=dict) # «services» -> данные _section.yaml + report: Report = field(default_factory=Report) + + def effective_layout(self, page: Page) -> str | None: + """Layout страницы: свой → ближайший раздел → умолчание сайта.""" + if page.layout: + return page.layout + parts = page.id.split("/")[:-1] + while True: + section = self.sections.get("/".join(parts)) + if section and section.get("layout"): + return section["layout"] + if not parts: + break + parts.pop() + return self.site.defaults.get("layout") + + +def _read_yaml(path: Path, rel: str, report: Report) -> Any: + try: + return load_yaml(path.read_text(encoding="utf-8")) + except (YamlError, UnicodeDecodeError, OSError) as exc: + report.add("E_YAML", str(exc), rel) + return None + + +def _read_markdown(path: Path, rel: str, report: Report) -> tuple[dict, str] | None: + try: + return frontmatter.parse(path.read_text(encoding="utf-8")) + except (YamlError, UnicodeDecodeError, OSError) as exc: + report.add("E_YAML", str(exc), rel) + return None + + +def _load_fragments(reg: Registry, base: Path, builtin: bool, label: str) -> None: + if not base.is_dir(): + return + for manifest in sorted(base.rglob("fragment.yaml")): + rel = f"{label}/{manifest.parent.relative_to(base).as_posix()}/fragment.yaml" + raw = _read_yaml(manifest, rel, reg.report) + if raw is None: + continue + fragment = parse_fragment(raw, rel, manifest.parent, builtin, reg.report) + if fragment is None: + continue + if fragment.id in reg.fragments: + reg.report.add( + "E_FRAGMENT_DUP", f"id фрагмента «{fragment.id}» уже занят", rel, + hint="id плоские и уникальные в пределах сайта; затенение запрещено", + ) + continue + reg.fragments[fragment.id] = fragment + + +def load_site(root: Path, builtin_dir: Path | None = BUILTIN_DIR) -> Registry: + root = Path(root) + report = Report() + site_file = root / "site.yaml" + if not site_file.is_file(): + raise EngineError(f"нет site.yaml в {root}") + raw_site = _read_yaml(site_file, "site.yaml", report) + site = parse_site(raw_site, "site.yaml", report) if raw_site is not None else None + if site is None: + raise EngineError("site.yaml не прошёл разбор", report) + reg = Registry(root=root, site=site, report=report) + + if builtin_dir is not None: + _load_fragments(reg, builtin_dir / "fragments", True, "builtin") + _load_fragments(reg, root / "fragments", False, "fragments") + + for manifest in sorted((root / "layouts").glob("*/layout.yaml")): + rel = manifest.relative_to(root).as_posix() + layout = parse_layout(_read_yaml(manifest, rel, report), rel, manifest.parent, report) + if layout is not None: + reg.layouts[layout.id] = layout + + for path in sorted((root / "collections").glob("*.yaml")): + rel = path.relative_to(root).as_posix() + coll = parse_collection(_read_yaml(path, rel, report), rel, report) + if coll is not None: + reg.collections[coll.id] = coll + reg.entries.setdefault(coll.id, []) + + content = root / "content" + if content.is_dir(): + for cdir in sorted(p for p in content.iterdir() if p.is_dir()): + if cdir.name not in reg.collections: + report.add("E_ENTRY_COLLECTION", f"нет схемы коллекции «{cdir.name}»", f"content/{cdir.name}") + continue + seen: set[str] = set() + for path in sorted(cdir.glob("*.md")): + rel = path.relative_to(root).as_posix() + parsed = _read_markdown(path, rel, report) + if parsed is None: + continue + entry = parse_entry(parsed[0], parsed[1], cdir.name, path.stem, rel, report) + if entry is None: + continue + if entry.slug in seen: + report.add("E_ENTRY_DUP", f"повтор slug «{entry.slug}»", rel) + continue + seen.add(entry.slug) + reg.entries[cdir.name].append(entry) + + pages_dir = root / "pages" + if pages_dir.is_dir(): + for path in sorted(pages_dir.rglob("_section.yaml")): + rel = path.relative_to(root).as_posix() + raw = _read_yaml(path, rel, report) + prefix = path.parent.relative_to(pages_dir).as_posix() + reg.sections["" if prefix == "." else prefix] = raw if isinstance(raw, dict) else {} + for path in sorted(pages_dir.rglob("*.md")): + rel = path.relative_to(root).as_posix() + page_id = path.relative_to(pages_dir).with_suffix("").as_posix() + parsed = _read_markdown(path, rel, report) + if parsed is None: + continue + page = parse_page(parsed[0], parsed[1], page_id, rel, report) + if page is not None: + reg.pages[page_id] = page + + for path in sorted((root / "display").glob("*.yaml")): + rel = path.relative_to(root).as_posix() + display = parse_display(_read_yaml(path, rel, report), path.stem, rel, report) + if display is not None: + reg.displays[path.stem] = display + + for path in sorted((root / "menus").glob("*.yaml")): + rel = path.relative_to(root).as_posix() + raw = _read_yaml(path, rel, report) + items = raw.get("items") if isinstance(raw, dict) else None + if not isinstance(items, list): + report.add("E_MENU_SHAPE", "меню: ожидается объект с items-списком", rel) + continue + reg.menus[path.stem] = items + + for path in sorted((root / "data").glob("*.yaml")): + raw = _read_yaml(path, path.relative_to(root).as_posix(), report) + if raw is not None: + reg.data[path.stem] = raw + + for path in sorted((root / "forms").glob("*.yaml")): + rel = path.relative_to(root).as_posix() + form = parse_form(_read_yaml(path, rel, report), rel, report) + if form is not None: + reg.forms[form.id] = form + + redirects_file = root / "redirects.yaml" + if redirects_file.is_file(): + raw = _read_yaml(redirects_file, "redirects.yaml", report) + if isinstance(raw, list): + reg.redirects = [r for r in raw if isinstance(r, dict)] + elif raw is not None: + report.add("E_REDIRECTS_SHAPE", "redirects.yaml: ожидается список {from, to}", "redirects.yaml") + return reg diff --git a/src/site_engine/core/render.py b/src/site_engine/core/render.py new file mode 100644 index 0000000..c3b48e5 --- /dev/null +++ b/src/site_engine/core/render.py @@ -0,0 +1,359 @@ +"""Рендер страниц: разрешение props по схеме фрагмента и Jinja в sandbox (ADR-002, ADR-005). + +Sandbox — второй эшелон защиты, а не граница безопасности: шаблоны пишет доверенный +разработчик, контентные роли могут менять только данные. +""" + +from __future__ import annotations + +import datetime as dt +from dataclasses import dataclass, field +from typing import Any + +from jinja2 import DictLoader, StrictUndefined +from jinja2.sandbox import SandboxedEnvironment +from markupsafe import Markup, escape + +from ..errors import Report +from ..parsing.markdown import render_inline, render_markdown +from .models import Block, Collection, Entry, FieldDef, Fragment +from .registry import Registry +from .resolve import MISSING, Resolver, get_path +from .routes import RouteRef +from .values import Binding, LinkRef, Query, ValueShapeError, classify + +ASSETS_HEAD = "" +ASSETS_BODY = "" +_EMPTY = (None, "", [], {}) + + +@dataclass +class PageView: + """Страница к рендеру: ручная страница или запись коллекции, превращённая display template.""" + + id: str + title: str + route: str + layout_id: str + seo: dict + regions: dict[str, list[Block]] + body: str = "" + entry: Entry | None = None + collection: Collection | None = None + source: str = "" + + +@dataclass +class _State: + view: PageView + ctx: dict + used: set[str] = field(default_factory=set) + + +class Props: + """Значения props для шаблона: `props.items` — поле «items», а не метод dict. + + Обычный dict в Jinja отдаёт `.items`/`.keys`/`.values` как методы; поэтому поля + фрагментов и группы оборачиваются в этот класс. + """ + + __slots__ = ("_d",) + + def __init__(self, data: dict): + object.__setattr__(self, "_d", data) + + def __getattr__(self, name: str) -> Any: + try: + return self._d[name] + except KeyError: + raise AttributeError(name) from None + + def __getitem__(self, name: str) -> Any: + return self._d[name] + + def __contains__(self, name: object) -> bool: + return name in self._d + + def __iter__(self): + return iter(self._d) + + def __len__(self) -> int: + return len(self._d) + + def __bool__(self) -> bool: + return bool(self._d) + + +def _md(text: Any) -> Markup: + return Markup(render_markdown(str(text or ""))) + + +def _md_inline(text: Any) -> Markup: + return Markup(render_inline(str(text or ""))) + + +def _href(link: Any) -> str: + if isinstance(link, dict): + return str(link.get("url") or "") + return "" if link is None else str(link) + + +def _empty(value: Any) -> bool: + return value is None or value == "" or value == [] or value == {} + + +def _is_active(url: str, route: str) -> bool: + return url == route or (url != "/" and route.startswith(url)) + + +class Renderer: + def __init__( + self, reg: Registry, table: dict[str, RouteRef], report: Report, *, + strict: bool = True, now: dt.datetime | None = None, build_id: str = "", + ): + self.reg = reg + self.table = table + self.report = report + self.strict = strict + self.build_id = build_id + self.now = now or dt.datetime.now(dt.timezone.utc) + self.resolver = Resolver(reg, table, report, strict) + templates = {f"layout/{lid}": l.template for lid, l in reg.layouts.items()} + templates.update({f"fragment/{fid}": f.template for fid, f in reg.fragments.items()}) + self.env = SandboxedEnvironment( + loader=DictLoader(templates), autoescape=True, undefined=StrictUndefined, + trim_blocks=True, lstrip_blocks=True, + ) + self.env.filters.update(md=_md, md_inline=_md_inline, href=_href) + self.site_ctx = { + "name": reg.site.name, "base_url": reg.site.base_url, + "default_locale": reg.site.default_locale, "locales": reg.site.locales, + "contacts": reg.site.contacts, "features": reg.site.features, + } + self._menus = self._resolve_menus() + self._forms = self._resolve_forms() + + # ── диагностика ─────────────────────────────────────────────────────── + def _issue(self, code: str, message: str, path: str, hint: str = "") -> None: + self.report.add(code, message, path, "error" if self.strict else "warning", hint) + + # ── меню и формы ────────────────────────────────────────────────────── + def _feature_on(self, requires: list[str]) -> bool: + return all(self.reg.site.features.get(str(r)[8:], False) for r in requires) + + def _resolve_menus(self) -> dict[str, list[dict]]: + out: dict[str, list[dict]] = {} + for mid, items in self.reg.menus.items(): + resolved = [] + for i, item in enumerate(items): + if not isinstance(item, dict) or item.get("enabled", True) is False: + continue + if not self._feature_on(item.get("requires") or []): + continue + kind = next((k for k in ("page", "entry", "url") if k in item), None) + if kind is None: + continue + link = self.resolver.link(LinkRef(kind, str(item[kind]), item.get("label")), f"menus/{mid}.yaml:items[{i}]") + if link: + resolved.append({"label": item.get("label"), "url": link["url"]}) + out[mid] = resolved + return out + + def _resolve_forms(self) -> dict[str, dict]: + out = {} + for fid, form in self.reg.forms.items(): + fields = [] + for f in form.fields: + policy_url = None + if f.get("policy"): + ref = self.resolver.page_refs.get(str(f["policy"])) + policy_url = ref.route if ref else None + if ref is None: + self._issue("E_FORM_POLICY", f"страница политики «{f['policy']}» не найдена", f"forms/{fid}.yaml") + fields.append({ + "key": f["key"], "type": f.get("type", "text"), "label": f.get("label", f["key"]), + "required": bool(f.get("required", False)), "hint": f.get("hint"), "policy_url": policy_url, + }) + out[fid] = {"id": fid, "title": form.title, "action": f"/forms/{fid}", "version": form.version, "fields": fields} + return out + + def _breadcrumbs(self, view: PageView) -> list[dict]: + crumbs: list[dict] = [] + segments = [s for s in view.route.split("/") if s and not s.endswith(".html")] + for i in range(len(segments)): + prefix = "/" + "/".join(segments[: i + 1]) + "/" + ref = self.table.get(prefix) + if ref and ref.page and ref.route != view.route: + crumbs.append({"label": ref.page.title, "url": ref.route}) + if view.route != "/" and self.table.get("/") and self.table["/"].page: + crumbs.insert(0, {"label": self.table["/"].page.title, "url": "/"}) + if view.collection and view.collection.list_page: + ref = self.table.get(view.collection.list_page) + if ref and ref.page and not any(c["url"] == ref.route for c in crumbs): + crumbs.append({"label": ref.page.title, "url": ref.route}) + crumbs.append({"label": view.title, "url": None}) + return crumbs + + # ── разрешение props ────────────────────────────────────────────────── + def _field(self, fd: FieldDef, raw: Any, st: _State, path: str, required: bool | None = None) -> Any: + required = fd.required if required is None else required + if raw is None and fd.default is not None: + raw = fd.default + try: + value = classify(raw, fd.type if fd.type in ("link", "query") else None) + except ValueShapeError as exc: + self._issue("E_VALUE_SHAPE", str(exc), path) + return None + if isinstance(value, Binding): + got = get_path(st.ctx, value.path) + if got is MISSING: + if required: + self._issue("E_BIND_MISSING", f"привязка «{value.path}» не найдена", path, + hint="проверьте имя поля записи или страницы") + return None + value = got + t = fd.type + given = value is not None # для query: запрос задан, даже если результат пуст + if t == "link": + if isinstance(value, LinkRef): + value = self.resolver.link(value, path) + elif isinstance(value, str): + value = self.resolver.link(LinkRef("url", value), path) + elif isinstance(value, dict) and "url" in value: + value = {"url": value["url"], "label": value.get("label"), "new_tab": bool(value.get("new_tab"))} + elif value is not None: + self._issue("E_VALUE_SHAPE", "ожидается ссылка", path) + value = None + elif t == "query": + if isinstance(value, Query): + value = self.resolver.query(value, path) + elif value is None: + value = [] + elif t == "asset" and isinstance(value, str): + rel = value.strip("/") + if not rel.startswith("assets/") or ".." in rel.split("/"): + self._issue("E_ASSET_PATH", "путь ассета должен быть вида assets/...", path) + value = None + elif not (self.reg.root / rel).is_file(): + self._issue("E_ASSET_MISSING", f"нет файла {rel}", path) + value = None + else: + value = {"path": rel, "url": "/" + rel} + elif t == "group" and isinstance(value, dict): + value = Props({sub.key: self._field(sub, value.get(sub.key), st, f"{path}.{sub.key}") for sub in fd.fields}) + elif t == "list" and isinstance(value, list): + items = [] + for i, item in enumerate(value): + item_path = f"{path}[{i}]" + if fd.of: + items.append(self._field(FieldDef(f"[{i}]", fd.of), item, st, item_path, required=False)) + else: + group = FieldDef(f"[{i}]", "group", fields=fd.fields) + if isinstance(item, dict) and set(item) == {"bind"}: + got = get_path(st.ctx, item["bind"]) + item = None if got is MISSING else got + items.append(self._field(group, item, st, item_path, required=False)) + value = items + elif t == "ref" and value is not None: + value = self.resolver.ref_entry(fd.to or "", value, path) + elif t == "refs" and isinstance(value, list): + value = [v for v in (self.resolver.ref_entry(fd.to or "", s, f"{path}[{i}]") for i, s in enumerate(value)) if v] + if value is None and t in ("list", "refs", "multiselect"): + value = [] + if _empty(value) and required and not (t == "query" and given): + self._issue("E_REQUIRED", f"обязательное поле «{fd.key}» пусто", path) + return value + + def _props(self, block: Block, fragment: Fragment, st: _State, path: str) -> Props: + return Props({fd.key: self._field(fd, block.props.get(fd.key), st, f"{path}.props.{fd.key}") for fd in fragment.fields}) + + # ── блоки ───────────────────────────────────────────────────────────── + def _block(self, block: Block, st: _State, where: str) -> Markup: + path = f"{where}[{block.id}]" + if block.hidden or not self._feature_on(block.requires): + return Markup("") + fragment = self.reg.fragments.get(block.fragment) + if fragment is None: + self._issue("E_FRAGMENT_UNKNOWN", f"нет фрагмента «{block.fragment}»", path) + return Markup("") + st.used.add(fragment.id) + props = self._props(block, fragment, st, path) + slots = { + name: Markup("".join(str(self._block(c, st, f"{path}.slots.{name}")) for c in block.slots.get(name, []))) + for name in fragment.slots + } + ctx = {**st.ctx, "props": props, "slots": slots, "block": {"id": block.id, "anchor": block.anchor}} + html = self.env.get_template(f"fragment/{fragment.id}").render(ctx) + if block.anchor: + html = f"" + html + return Markup(html) + + def _plain(self, value: Any, st: _State, path: str) -> Any: + try: + value = classify(value, None) + except ValueShapeError as exc: + self._issue("E_VALUE_SHAPE", str(exc), path) + return "" + if isinstance(value, Binding): + got = get_path(st.ctx, value.path) + if got is MISSING: + self._issue("E_BIND_MISSING", f"привязка «{value.path}» не найдена", path) + return "" + return got + return value + + def _seo_head(self, st: _State) -> Markup: + v = st.view + seo = {k: self._plain(val, st, f"{v.source}:seo.{k}") for k, val in v.seo.items()} + suffix = str(self.reg.site.defaults.get("seo", {}).get("title_suffix", "")) + title = f"{seo.get('title') or v.title}{suffix}" + parts = [ + "", + "", + f"{escape(title)}", + ] + if seo.get("description"): + parts.append(f"") + if self.reg.site.base_url: + parts.append(f"") + parts.append(f"") + return Markup("\n".join(parts)) + + # ── страница ────────────────────────────────────────────────────────── + def render(self, view: PageView) -> tuple[str, set[str]]: + layout = self.reg.layouts.get(view.layout_id) + if layout is None: + self._issue("E_LAYOUT_MISSING", f"layout «{view.layout_id}» не найден", view.source) + return "", set() + entry_view = self.resolver.entry_view(view.entry) if view.entry else None + menus = { + mid: [{**item, "active": _is_active(item["url"], view.route)} for item in items] + for mid, items in self._menus.items() + } + ctx = { + "site": self.site_ctx, + "page": {"id": view.id, "title": view.title, "route": view.route, "body": view.body, + "locale": self.reg.site.default_locale, "url": self.reg.site.base_url + view.route}, + "entry": entry_view, "data": self.reg.data, "params": {}, "menus": menus, + "forms": self._forms, "breadcrumbs": self._breadcrumbs(view), + "build": {"id": self.build_id, "year": self.now.year}, + } + st = _State(view, ctx) + + def region(name: str) -> Markup: + rdef = layout.regions.get(name) + if rdef is None: + self._issue("E_REGION_UNKNOWN", f"layout «{layout.id}» не объявляет регион «{name}»", view.source) + return Markup("") + out = [] + for b in rdef.fixed: + out.append(str(self._block(b, st, f"layouts/{layout.id}/layout.yaml:regions.{name}.fixed"))) + for b in view.regions.get(name, []): + out.append(str(self._block(b, st, f"{view.source}:regions.{name}"))) + return Markup("".join(out)) + + html = self.env.get_template(f"layout/{layout.id}").render({ + **ctx, "region": region, "seo_head": lambda: self._seo_head(st), + "assets_head": lambda: Markup(ASSETS_HEAD), "assets_body": lambda: Markup(ASSETS_BODY), + }) + return html, st.used diff --git a/src/site_engine/core/resolve.py b/src/site_engine/core/resolve.py new file mode 100644 index 0000000..cfc9870 --- /dev/null +++ b/src/site_engine/core/resolve.py @@ -0,0 +1,147 @@ +"""Разрешение значений: привязки, ссылки, запросы к коллекциям (ADR-002).""" + +from __future__ import annotations + +import re +from typing import Any + +from ..errors import Report +from .models import Entry +from .registry import Registry +from .routes import RouteRef +from .values import LinkRef, Query, ValueShapeError + + +class _Missing: + def __repr__(self) -> str: # pragma: no cover + return "MISSING" + + +MISSING = _Missing() +_URL_OK = re.compile(r"^(https?://|mailto:|tel:|/)", re.IGNORECASE) + + +def get_path(ctx: dict, path: str) -> Any: + """Читает значение по пути `entry.client.name` или `entry.items.0`. Нет значения → MISSING.""" + cur: Any = ctx + for seg in path.split("."): + if isinstance(cur, dict): + if seg not in cur: + return MISSING + cur = cur[seg] + elif isinstance(cur, (list, tuple)) and seg.isdigit() and int(seg) < len(cur): + cur = cur[int(seg)] + else: + return MISSING + return cur + + +def _match(value: Any, cond: Any) -> bool: + if isinstance(cond, dict): # {in: [...]} + options = cond["in"] + if isinstance(value, list): + return any(v in options for v in value) + return value in options + if isinstance(value, list): + return cond in value + return value == cond + + +class Resolver: + def __init__(self, reg: Registry, table: dict[str, RouteRef], report: Report, strict: bool): + self.reg = reg + self.report = report + self.strict = strict + self.page_refs = {r.page.id: r for r in table.values() if r.kind == "page" and r.page} + self.entry_refs = { + (r.collection.id, r.entry.slug): r + for r in table.values() + if r.kind == "entry" and r.entry and r.collection + } + + def _sev(self) -> str: + return "error" if self.strict else "warning" + + # ── ссылки ──────────────────────────────────────────────────────────── + def link(self, ref: LinkRef, path: str) -> dict | None: + if ref.kind == "url": + if not _URL_OK.match(ref.target): + self.report.add("E_URL_SCHEME", f"недопустимый URL «{ref.target}»", path, + hint="разрешены http(s), mailto, tel и относительные пути") + return None + return {"url": ref.target, "label": ref.label, "new_tab": ref.new_tab} + if ref.kind == "page": + found = self.page_refs.get(ref.target) + label = ref.label or (found.page.title if found and found.page else None) + else: + coll, _, slug = ref.target.partition("/") + found = self.entry_refs.get((coll, slug)) + label = ref.label or (found.entry.data.get("title") if found and found.entry else None) + if found is None: + self.report.add("E_LINK_BROKEN", f"нет цели ссылки {ref.kind}: {ref.target}", path) + return None + if not found.published: + self.report.add("E_LINK_UNPUBLISHED", f"цель ссылки не опубликована: {ref.target}", path, + severity=self._sev()) + return {"url": found.route, "label": label, "new_tab": ref.new_tab} + + # ── записи и запросы ────────────────────────────────────────────────── + def entry_view(self, entry: Entry) -> dict: + ref = self.entry_refs.get((entry.collection, entry.slug)) + view = dict(entry.data) + view.update( + slug=entry.slug, collection=entry.collection, body=entry.body, + url=ref.route if ref else None, + ) + return view + + def query(self, q: Query, path: str) -> list[dict]: + coll = self.reg.collections.get(q.collection) + if coll is None: + self.report.add("E_QUERY_COLLECTION", f"нет коллекции «{q.collection}»", path) + return [] + items = [e for e in self.reg.entries.get(coll.id, []) if e.status == "published"] + if q.ids is not None: + by_slug = {e.slug: e for e in items} + picked = [] + for slug in q.ids: + if slug in by_slug: + picked.append(by_slug[slug]) + else: + self.report.add("E_QUERY_ID", f"нет опубликованной записи «{q.collection}/{slug}»", path) + items = picked + views = [self.entry_view(e) for e in items] + for key, cond in q.where.items(): + views = [v for v in views if _match(v.get(key), cond)] + sort = q.sort or coll.sort + if sort and q.ids is None: + desc = sort.startswith("-") + field_name = sort.lstrip("-") + present = [v for v in views if v.get(field_name) is not None] + absent = [v for v in views if v.get(field_name) is None] + try: + present.sort(key=lambda v: v[field_name], reverse=desc) + except TypeError: + self.report.add("E_QUERY_SORT", f"поле «{field_name}» нельзя сортировать", path) + views = present + absent + if q.limit: + views = views[: q.limit] + return views + + def ref_entry(self, collection: str, slug: Any, path: str) -> dict | None: + found = self.entry_refs.get((collection, str(slug))) + if found is None or found.entry is None: + self.report.add("E_REF_MISSING", f"нет записи «{collection}/{slug}»", path) + return None + return self.entry_view(found.entry) + + +def validate_value_shape(raw: Any, expected: str | None, path: str, report: Report) -> bool: + from .values import classify + + try: + classify(raw, expected) + return True + except ValueShapeError as exc: + report.add("E_VALUE_SHAPE", str(exc), path) + return False diff --git a/src/site_engine/core/routes.py b/src/site_engine/core/routes.py new file mode 100644 index 0000000..2638c8c --- /dev/null +++ b/src/site_engine/core/routes.py @@ -0,0 +1,114 @@ +"""Маршруты: нормализация, таблица маршрутов, коллизии (ТЗ 5.1, ADR-006).""" + +from __future__ import annotations + +import re +from dataclasses import dataclass + +from ..errors import Report +from .models import Collection, Entry, Page +from .registry import Registry + +SEGMENT_RE = re.compile(r"^[a-z0-9][a-z0-9_-]*$") +RESERVED_PREFIXES = ("/assets/", "/forms/", "/_forms/", "/_preview/", "/admin/", "/mcp/") + + +def normalize_route(route: str) -> str: + """Канонический вид: начинается с «/», нижний регистр, завершающий «/» (кроме *.html).""" + if not isinstance(route, str) or not route.startswith("/"): + raise ValueError("маршрут должен начинаться с «/»") + if "//" in route or "\\" in route: + raise ValueError("недопустимые разделители в маршруте") + is_file = route.endswith(".html") + if not is_file and not route.endswith("/"): + route += "/" + segments = [s for s in route.split("/") if s] + for i, seg in enumerate(segments): + base = seg[:-5] if (is_file and i == len(segments) - 1) else seg + if not SEGMENT_RE.match(base): + raise ValueError( + f"недопустимый сегмент «{seg}»: нижний регистр, латиница, цифры, «-» и «_»" + ) + for prefix in RESERVED_PREFIXES: + if route.startswith(prefix): + raise ValueError(f"путь зарезервирован движком ({prefix})") + return route + + +def route_to_output(route: str) -> str: + """Относительный путь файла в dist.""" + rel = route.lstrip("/") + return rel if route.endswith(".html") else rel + "index.html" + + +def page_route(page: Page) -> str: + if page.route_override: + return normalize_route(page.route_override) + if page.id == "404": + return "/404.html" + parts = page.id.split("/") + if parts[-1] == "index": + parts = parts[:-1] + return "/" + "/".join(parts) + ("/" if parts else "") + + +def entry_route(collection: Collection, entry: Entry) -> str: + return normalize_route(collection.route.replace("{slug}", entry.slug)) + + +@dataclass +class RouteRef: + route: str + kind: str # page | entry | redirect + published: bool + page: Page | None = None + entry: Entry | None = None + collection: Collection | None = None + target: str | None = None # для redirect + + +def build_route_table(reg: Registry, report: Report) -> dict[str, RouteRef]: + table: dict[str, RouteRef] = {} + + def put(ref: RouteRef, source: str) -> None: + if ref.route in table: + other = table[ref.route] + where = other.page.file if other.page else other.entry.file if other.entry else "redirects.yaml" + report.add( + "E_ROUTE_COLLISION", f"маршрут {ref.route} уже занят ({where})", source, + hint="смените route/slug или уберите редирект", + ) + return + table[ref.route] = ref + + for page in reg.pages.values(): + try: + route = page_route(page) + except ValueError as exc: + report.add("E_ROUTE", str(exc), page.file) + continue + put(RouteRef(route, "page", page.status == "published", page=page), page.file) + for cid, items in reg.entries.items(): + coll = reg.collections[cid] + if coll.kind == "taxonomy": + continue + for entry in items: + try: + route = entry_route(coll, entry) + except ValueError as exc: + report.add("E_ROUTE", str(exc), entry.file) + continue + put(RouteRef(route, "entry", entry.status == "published", entry=entry, collection=coll), entry.file) + for i, item in enumerate(reg.redirects): + where = f"redirects.yaml[{i}]" + src, dst = item.get("from"), item.get("to") + if not isinstance(src, str) or not isinstance(dst, str): + report.add("E_REDIRECT", "redirect: нужны строки from и to", where) + continue + try: + src_n = normalize_route(src) + except ValueError as exc: + report.add("E_REDIRECT", f"from: {exc}", where) + continue + put(RouteRef(src_n, "redirect", True, target=dst), where) + return table diff --git a/src/site_engine/core/validate.py b/src/site_engine/core/validate.py new file mode 100644 index 0000000..9301eeb --- /dev/null +++ b/src/site_engine/core/validate.py @@ -0,0 +1,315 @@ +"""Проверки: workspace (синтаксис, фрагменты, типы указанных значений) и release (полнота). + +Обязательные поля фрагментов проверяет рендер в строгом режиме: он видит и привязки. +Черновики проходят только структурные проверки (ADR-003). +""" + +from __future__ import annotations + +import datetime as dt +import fnmatch +from typing import Any + +from ..errors import Report +from .models import Block, Display, Entry, FieldDef, Fragment, Layout, Page +from .registry import Registry +from .routes import RouteRef, build_route_table +from .values import Binding, ValueShapeError, classify + + +def _allowed(patterns: list[str] | None, fragment_id: str) -> bool: + return patterns is None or any(fnmatch.fnmatch(fragment_id, p) for p in patterns) + + +def _template_syntax(value: Any) -> bool: + return isinstance(value, str) and ("{{" in value or "{%" in value) + + +# ── значения по схеме поля ──────────────────────────────────────────────────── + +def check_value(fd: FieldDef, raw: Any, path: str, report: Report) -> None: + """Статическая проверка литерала; привязки и запросы проверяются формой.""" + try: + value = classify(raw, fd.type if fd.type in ("link", "query") else None) + except ValueShapeError as exc: + report.add("E_VALUE_SHAPE", str(exc), path) + return + if isinstance(value, Binding) or raw is None: + return + t = fd.type + if t == "link": + return + if t == "query": + return + if t in ("text", "select") and _template_syntax(raw): + report.add("E_TEMPLATE_IN_DATA", "строки с {{ }} в данных запрещены; используйте {bind: ...}", path) + if t in ("text", "textarea", "markdown", "slug", "color", "icon", "asset", "ref"): + if not isinstance(raw, str): + report.add("E_TYPE", f"ожидается строка ({t})", path) + elif t == "number": + if isinstance(raw, bool) or not isinstance(raw, (int, float)): + report.add("E_TYPE", "ожидается число", path) + elif t == "boolean": + if not isinstance(raw, bool): + report.add("E_TYPE", "ожидается true/false", path) + elif t == "select": + if fd.options and str(raw) not in [str(o) for o in fd.options]: + report.add("E_SELECT_VALUE", f"«{raw}» не из options {fd.options}", path) + elif t == "multiselect": + if not isinstance(raw, list) or any(str(v) not in [str(o) for o in fd.options] for v in raw): + report.add("E_SELECT_VALUE", f"ожидается список значений из {fd.options}", path) + elif t in ("date", "datetime"): + if not isinstance(raw, (dt.date, dt.datetime, str)): + report.add("E_TYPE", f"ожидается {t}", path) + elif t == "refs": + if not (isinstance(raw, list) and all(isinstance(v, str) for v in raw)): + report.add("E_TYPE", "ожидается список slug-ов", path) + elif t == "group": + if not isinstance(raw, dict): + report.add("E_TYPE", "ожидается объект", path) + return + check_fields(fd.fields, raw, path, report) + elif t == "list": + if not isinstance(raw, list): + report.add("E_TYPE", "ожидается список", path) + return + for i, item in enumerate(raw): + item_path = f"{path}[{i}]" + if fd.of: + check_value(FieldDef(f"[{i}]", fd.of), item, item_path, report) + elif isinstance(item, dict) and set(item) == {"bind"}: + continue + elif isinstance(item, dict): + check_fields(fd.fields, item, item_path, report) + else: + report.add("E_TYPE", "элемент списка: ожидается объект", item_path) + + +def check_fields(fields: list[FieldDef], data: dict, path: str, report: Report) -> None: + known = {f.key: f for f in fields} + for key in data: + if key not in known: + report.add("E_PROP_UNKNOWN", f"неизвестное поле «{key}»", f"{path}.{key}", + hint=f"доступны: {sorted(known)}") + for key, fd in known.items(): + if key in data: + check_value(fd, data[key], f"{path}.{key}", report) + + +# ── блоки ───────────────────────────────────────────────────────────────────── + +def check_blocks( + blocks: list[Block], where: str, reg: Registry, report: Report, seen: set[str], + region_allow: list[str] | None = None, slot_allow: list[str] | None = None, top: bool = True, +) -> None: + for block in blocks: + path = f"{where}[{block.id}]" + if block.id in seen: + report.add("E_BLOCK_DUP", f"повтор id блока «{block.id}»", path) + seen.add(block.id) + fragment: Fragment | None = reg.fragments.get(block.fragment) + if fragment is None: + report.add("E_FRAGMENT_UNKNOWN", f"нет фрагмента «{block.fragment}»", path, + hint=f"доступны: {sorted(reg.fragments)}") + continue + allow = region_allow if top else slot_allow + if not _allowed(allow, block.fragment): + report.add("E_FRAGMENT_NOT_ALLOWED", f"фрагмент «{block.fragment}» не разрешён здесь", path, + hint=f"allow: {allow}") + for req in block.requires: + if not req.startswith("feature.") or req[8:] not in reg.site.features: + report.add("E_REQUIRES_UNKNOWN", f"requires «{req}»: в MVP только feature.<имя> из site.yaml", path) + check_fields(fragment.fields, block.props, f"{path}.props", report) + for slot_name, children in block.slots.items(): + if slot_name not in fragment.slots: + report.add("E_SLOT_UNKNOWN", f"у «{fragment.id}» нет слота «{slot_name}»", f"{path}.slots.{slot_name}") + continue + check_blocks(children, f"{path}.slots.{slot_name}", reg, report, seen, + slot_allow=fragment.slots[slot_name].get("allow"), top=False) + + +def check_regions( + regions: dict[str, list[Block]], layout: Layout | None, where: str, reg: Registry, report: Report +) -> None: + seen: set[str] = set() + for rname, blocks in regions.items(): + region = layout.regions.get(rname) if layout else None + if layout is not None and region is None: + report.add("E_REGION_UNKNOWN", f"layout «{layout.id}» не объявляет регион «{rname}»", f"{where}.regions.{rname}") + continue + allow = region.allow if region else None + if region is not None and allow is None and region.fixed and blocks: + report.add("E_REGION_FIXED_ONLY", f"регион «{rname}» только из закреплённых блоков", f"{where}.regions.{rname}") + continue + check_blocks(blocks, f"{where}.regions.{rname}", reg, report, seen, region_allow=allow) + + +def check_seo(seo: dict, where: str, report: Report) -> None: + for key, value in seo.items(): + try: + classify(value, None) + except ValueShapeError as exc: + report.add("E_VALUE_SHAPE", str(exc), f"{where}.seo.{key}") + continue + if _template_syntax(value): + report.add("E_TEMPLATE_IN_DATA", "в seo запрещены строки с {{ }}; используйте {bind: ...}", f"{where}.seo.{key}") + + +# ── workspace ───────────────────────────────────────────────────────────────── + +def validate_workspace(reg: Registry, table: dict[str, RouteRef] | None = None) -> Report: + report = Report() + report.extend(reg.report) + + if table is None: + table = build_route_table(reg, report) + + # layouts: закреплённые блоки + for layout in reg.layouts.values(): + seen: set[str] = set() + for region in layout.regions.values(): + check_blocks(region.fixed, f"layouts/{layout.id}/layout.yaml:regions.{region.id}.fixed", + reg, report, seen) + if layout.extends and layout.extends not in reg.layouts: + report.add("E_LAYOUT_EXTENDS", f"extends: нет layout «{layout.extends}»", f"layouts/{layout.id}") + + # страницы + for page in reg.pages.values(): + layout_id = reg.effective_layout(page) + layout = reg.layouts.get(layout_id) if layout_id else None + if layout is None: + report.add("E_LAYOUT_MISSING", f"layout «{layout_id}» не найден", page.file) + check_regions(page.regions, layout, page.file, reg, report) + check_seo(page.seo, page.file, report) + + # display templates и записи + for did, display in reg.displays.items(): + if did not in reg.collections: + report.add("E_DISPLAY_COLLECTION", f"display «{did}»: нет одноимённой коллекции", f"display/{did}.yaml") + layout = reg.layouts.get(display.layout) if display.layout else None + if layout is None: + report.add("E_LAYOUT_MISSING", f"layout «{display.layout}» не найден", f"display/{did}.yaml") + check_regions(display.regions, layout, f"display/{did}.yaml", reg, report) + check_seo(display.seo, f"display/{did}.yaml", report) + + for cid, coll in reg.collections.items(): + display_id = coll.display or coll.id + entries = reg.entries.get(cid, []) + if coll.kind != "taxonomy" and display_id not in reg.displays and any(e.status == "published" for e in entries): + report.add("E_DISPLAY_MISSING", f"нет display/{display_id}.yaml для опубликованных записей «{cid}»", f"collections/{cid}.yaml") + if coll.list_page and coll.list_page not in {r.route for r in table.values()}: + report.add("W_LIST_PAGE", f"list_page {coll.list_page} не найден среди маршрутов", f"collections/{cid}.yaml", severity="warning") + for entry in entries: + _check_entry(reg, coll.fields, entry, report, display_id) + + # меню + for mid, items in reg.menus.items(): + for i, item in enumerate(items): + where = f"menus/{mid}.yaml:items[{i}]" + if not isinstance(item, dict) or not isinstance(item.get("label"), str): + report.add("E_MENU_ITEM", "пункт меню: нужен label", where) + continue + if item.get("enabled", True) is False: + continue + targets = [k for k in ("page", "entry", "url") if k in item] + if len(targets) != 1: + report.add("E_MENU_ITEM", "пункт меню: нужен ровно один из page, entry, url", where) + for req in item.get("requires") or []: + if not str(req).startswith("feature.") or str(req)[8:] not in reg.site.features: + report.add("E_REQUIRES_UNKNOWN", f"requires «{req}» неизвестен", where) + + # формы + for form in reg.forms.values(): + keys = [f.get("key") for f in form.fields] + if len(keys) != len(set(keys)): + report.add("E_FORM_FIELDS", "повтор ключей полей формы", f"forms/{form.id}.yaml") + page_id = form.success.get("page") if isinstance(form.success, dict) else None + if page_id and page_id not in reg.pages: + report.add("E_FORM_SUCCESS", f"success.page «{page_id}» не найдена", f"forms/{form.id}.yaml") + + apply_rules(reg, report) + return report + + +def _check_entry(reg: Registry, fields: list[FieldDef], entry: Entry, report: Report, display_id: str) -> None: + sev = "error" if entry.status == "published" else "warning" + known = {f.key: f for f in fields} + for key in entry.data: + if key not in known: + report.add("E_ENTRY_FIELD_UNKNOWN", f"поле «{key}» не описано схемой коллекции", f"{entry.file}:{key}", severity=sev) + for key, fd in known.items(): + if key in entry.data: + check_value(fd, entry.data[key], f"{entry.file}:{key}", report) + display = reg.displays.get(display_id) + if display and entry.regions: + if display.overrides == "deny": + report.add("E_ENTRY_OVERRIDES", "display запрещает переопределение регионов", entry.file) + layout = reg.layouts.get(display.layout) if display.layout else None + check_regions(entry.regions, layout, entry.file, reg, report) + + +# ── release ─────────────────────────────────────────────────────────────────── + +def validate_release(reg: Registry, table: dict[str, RouteRef]) -> Report: + report = Report() + for cid, coll in reg.collections.items(): + for entry in reg.entries.get(cid, []): + if entry.status != "published": + continue + for fd in coll.fields: + if fd.required and entry.data.get(fd.key) in (None, "", [], {}): + report.add("E_ENTRY_REQUIRED", f"обязательное поле «{fd.key}» пусто", f"{entry.file}:{fd.key}") + routes = set(table) + for i, item in enumerate(reg.redirects): + dst = item.get("to") + if isinstance(dst, str) and not dst.startswith(("http://", "https://")): + target = table.get(dst if dst.endswith(("/", ".html")) else dst + "/") + if target is None or target.kind == "redirect" or not target.published: + report.add("E_REDIRECT_TARGET", f"цель редиректа {dst} не опубликована", f"redirects.yaml[{i}]") + _ = routes + return report + + +# ── декларативные правила сайта ─────────────────────────────────────────────── + +def _fragments_in(regions: dict[str, list[Block]]) -> set[str]: + found: set[str] = set() + + def walk(blocks: list[Block]) -> None: + for b in blocks: + if not b.hidden: + found.add(b.fragment) + for children in b.slots.values(): + walk(children) + + for blocks in regions.values(): + walk(blocks) + return found + + +def apply_rules(reg: Registry, report: Report) -> None: + """Словарь правил: `require_fragment` (для коллекции) и `require_field` (для форм).""" + for i, rule in enumerate(reg.site.rules): + where = f"site.yaml:rules[{i}]" + if not isinstance(rule, dict) or "id" not in rule: + report.add("E_RULE", "правило: нужен id", where) + continue + level = rule.get("level", "error") + if "collection" in rule and "require_fragment" in rule: + cid, needed = rule["collection"], rule["require_fragment"] + display = reg.displays.get((reg.collections[cid].display or cid) if cid in reg.collections else cid) + for entry in reg.entries.get(cid, []): + if entry.status != "published": + continue + regions = dict(display.regions) if display else {} + for name, blocks in entry.regions.items(): + regions[name] = (regions.get(name, []) + blocks) if entry.regions_mode != "replace" else blocks + if needed not in _fragments_in(regions): + report.add(f"R_{rule['id']}", f"в «{entry.file}» нет обязательного фрагмента «{needed}»", where, severity=level) + elif "forms" in rule and "require_field" in rule: + needed = rule["require_field"] + for form in reg.forms.values(): + if not any(f.get("type") == needed for f in form.fields): + report.add(f"R_{rule['id']}", f"в форме «{form.id}» нет поля типа «{needed}»", where, severity=level) + else: + report.add("W_RULE_UNKNOWN", f"правило «{rule['id']}»: неизвестный вид", where, severity="warning") diff --git a/src/site_engine/core/values.py b/src/site_engine/core/values.py new file mode 100644 index 0000000..1551783 --- /dev/null +++ b/src/site_engine/core/values.py @@ -0,0 +1,107 @@ +"""Четыре вида значений props: Literal | Binding | LinkRef | Query (ADR-002). + +Форма значения определяется типом поля: `{page: ...}` — ссылка только у поля `link`, +`{query: ...}` — запрос только у поля `query`; `{bind: ...}` допустим везде. +""" + +from __future__ import annotations + +from dataclasses import dataclass, field +from typing import Any + +BIND_ROOTS = ("site", "page", "entry", "data", "params") +_LINK_KEYS = {"page", "entry", "url", "label", "target"} +_QUERY_KEYS = {"collection", "ids", "where", "sort", "limit"} + + +class ValueShapeError(ValueError): + """Значение не соответствует ожидаемой форме.""" + + +@dataclass(frozen=True) +class Binding: + path: str + + +@dataclass(frozen=True) +class LinkRef: + kind: str # page | entry | url + target: str + label: str | None = None + new_tab: bool = False + + +@dataclass(frozen=True) +class Query: + collection: str + ids: tuple[str, ...] | None = None + where: dict = field(default_factory=dict) + sort: str | None = None + limit: int | None = None + + +def _parse_query(raw: Any) -> Query: + if not isinstance(raw, dict): + raise ValueShapeError("query: ожидается объект") + unknown = set(raw) - _QUERY_KEYS + if unknown: + raise ValueShapeError( + f"query: неизвестные ключи {sorted(unknown)} (в MVP: {sorted(_QUERY_KEYS)})" + ) + collection = raw.get("collection") + if not isinstance(collection, str) or not collection: + raise ValueShapeError("query.collection: обязательная строка") + ids = raw.get("ids") + if ids is not None and not (isinstance(ids, list) and all(isinstance(i, str) for i in ids)): + raise ValueShapeError("query.ids: ожидается список строк") + where = raw.get("where") or {} + if not isinstance(where, dict): + raise ValueShapeError("query.where: ожидается объект") + for key, cond in where.items(): + if isinstance(cond, dict) and set(cond) != {"in"}: + raise ValueShapeError(f"query.where.{key}: в MVP поддерживаются eq и in") + if isinstance(cond, dict) and not isinstance(cond["in"], list): + raise ValueShapeError(f"query.where.{key}.in: ожидается список") + sort = raw.get("sort") + if sort is not None and not isinstance(sort, str): + raise ValueShapeError("query.sort: ожидается строка") + limit = raw.get("limit") + if limit is not None and (not isinstance(limit, int) or isinstance(limit, bool) or limit < 1): + raise ValueShapeError("query.limit: ожидается целое > 0") + return Query(collection, tuple(ids) if ids is not None else None, where, sort, limit) + + +def _parse_link(raw: dict) -> LinkRef: + unknown = set(raw) - _LINK_KEYS + if unknown: + raise ValueShapeError(f"link: неизвестные ключи {sorted(unknown)}") + targets = [k for k in ("page", "entry", "url") if k in raw] + if len(targets) != 1: + raise ValueShapeError("link: нужен ровно один из ключей page, entry, url") + kind = targets[0] + target = raw[kind] + if not isinstance(target, str) or not target: + raise ValueShapeError(f"link.{kind}: ожидается непустая строка") + label = raw.get("label") + if label is not None and not isinstance(label, str): + raise ValueShapeError("link.label: ожидается строка") + return LinkRef(kind, target, label, raw.get("target") == "_blank") + + +def classify(raw: Any, expected: str | None = None) -> Any: + """Binding | LinkRef | Query либо исходный литерал.""" + if isinstance(raw, dict): + if set(raw) == {"bind"}: + path = raw["bind"] + if not isinstance(path, str) or path.split(".")[0] not in BIND_ROOTS: + raise ValueShapeError(f"bind: путь должен начинаться с одного из {BIND_ROOTS}") + return Binding(path) + if expected == "query": + if set(raw) != {"query"}: + raise ValueShapeError("поле типа query: ожидается {query: {...}} или {bind: ...}") + return _parse_query(raw["query"]) + if expected == "link": + return _parse_link(raw) + elif expected == "query" and raw is not None: + raise ValueShapeError("поле типа query: ожидается {query: {...}} или {bind: ...}") + return raw diff --git a/src/site_engine/db/__init__.py b/src/site_engine/db/__init__.py new file mode 100644 index 0000000..c41575f --- /dev/null +++ b/src/site_engine/db/__init__.py @@ -0,0 +1 @@ +"""SQLite через SQLAlchemy 2: служебные данные (ADR-001). Не тестировалось в песочнице без сети.""" diff --git a/src/site_engine/db/engine.py b/src/site_engine/db/engine.py new file mode 100644 index 0000000..5827308 --- /dev/null +++ b/src/site_engine/db/engine.py @@ -0,0 +1,26 @@ +"""Подключение SQLite: WAL, внешние ключи, busy_timeout (ТЗ 13). Миграции Alembic — M2.""" + +from __future__ import annotations + +from sqlalchemy import Engine, create_engine, event + +from .models import Base + + +def make_engine(url: str = "sqlite:///engine.sqlite3") -> Engine: + engine = create_engine(url) + + @event.listens_for(engine, "connect") + def _pragmas(dbapi_connection, _record): # noqa: ANN001 + cur = dbapi_connection.cursor() + cur.execute("PRAGMA journal_mode=WAL") + cur.execute("PRAGMA foreign_keys=ON") + cur.execute("PRAGMA busy_timeout=5000") + cur.close() + + return engine + + +def init_db(engine: Engine) -> None: + """Для разработки и тестов; в production схему ведёт Alembic.""" + Base.metadata.create_all(engine) diff --git a/src/site_engine/db/models.py b/src/site_engine/db/models.py new file mode 100644 index 0000000..75143bd --- /dev/null +++ b/src/site_engine/db/models.py @@ -0,0 +1,96 @@ +"""Служебные таблицы (ADR-001): доступ, аудит, заявки, outbox, сборки. + +Индексные таблицы страниц и записей в MVP не нужны: сборка строит реестр из файлов. +В аудит пишутся id и типы операций, значения ПД не пишутся (ADR-005). +""" + +from __future__ import annotations + +from datetime import datetime + +from sqlalchemy import JSON, Boolean, DateTime, ForeignKey, Integer, String, Text, func +from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column + + +class Base(DeclarativeBase): + pass + + +class User(Base): + __tablename__ = "users" + id: Mapped[int] = mapped_column(primary_key=True) + login: Mapped[str] = mapped_column(String(64), unique=True) + password_hash: Mapped[str] = mapped_column(String(255)) + role: Mapped[str] = mapped_column(String(16)) # owner | developer | editor + is_active: Mapped[bool] = mapped_column(Boolean, default=True) + created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now()) + + +class SessionRow(Base): + __tablename__ = "sessions" + id: Mapped[str] = mapped_column(String(64), primary_key=True) + user_id: Mapped[int] = mapped_column(ForeignKey("users.id", ondelete="CASCADE")) + created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now()) + expires_at: Mapped[datetime] = mapped_column(DateTime(timezone=True)) + + +class ApiToken(Base): + __tablename__ = "api_tokens" + id: Mapped[int] = mapped_column(primary_key=True) + token_hash: Mapped[str] = mapped_column(String(128), unique=True) # только хеш + label: Mapped[str] = mapped_column(String(128)) + scopes: Mapped[list] = mapped_column(JSON) # ["read", "content:write", ...] + sections: Mapped[list | None] = mapped_column(JSON, nullable=True) # ограничение по разделам + user_id: Mapped[int | None] = mapped_column(ForeignKey("users.id"), nullable=True) + expires_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True) + revoked_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True) + last_used_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True) + + +class AuditLog(Base): + __tablename__ = "audit_log" + id: Mapped[int] = mapped_column(primary_key=True) + at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now()) + actor_kind: Mapped[str] = mapped_column(String(16)) # human | agent | system + actor_id: Mapped[str] = mapped_column(String(64)) + action: Mapped[str] = mapped_column(String(64)) + object_kind: Mapped[str] = mapped_column(String(32)) + object_id: Mapped[str] = mapped_column(String(255)) + correlation_id: Mapped[str | None] = mapped_column(String(64), nullable=True) + details: Mapped[dict | None] = mapped_column(JSON, nullable=True) # без значений ПД + + +class FormSubmission(Base): + __tablename__ = "form_submissions" + id: Mapped[int] = mapped_column(primary_key=True) + form_id: Mapped[str] = mapped_column(String(64), index=True) + form_version: Mapped[str] = mapped_column(String(32)) + created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now()) + payload: Mapped[dict] = mapped_column(JSON) + consent: Mapped[dict | None] = mapped_column(JSON, nullable=True) # policy_id, policy_hash, accepted_at, lang + status: Mapped[str] = mapped_column(String(16), default="new") # new | processed | spam + note: Mapped[str | None] = mapped_column(Text, nullable=True) + + +class OutboxEvent(Base): + __tablename__ = "outbox_events" + id: Mapped[int] = mapped_column(primary_key=True) + kind: Mapped[str] = mapped_column(String(32)) # telegram | email | webhook + payload: Mapped[dict] = mapped_column(JSON) + status: Mapped[str] = mapped_column(String(16), default="pending") # pending | done | failed + attempts: Mapped[int] = mapped_column(Integer, default=0) + next_attempt_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True) + idempotency_key: Mapped[str] = mapped_column(String(128), unique=True) + last_error: Mapped[str | None] = mapped_column(Text, nullable=True) + created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now()) + + +class BuildRun(Base): + __tablename__ = "build_runs" + id: Mapped[int] = mapped_column(primary_key=True) + build_id: Mapped[str] = mapped_column(String(32), index=True) + status: Mapped[str] = mapped_column(String(16)) # ok | failed + started_at: Mapped[datetime] = mapped_column(DateTime(timezone=True)) + finished_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True) + actor: Mapped[str] = mapped_column(String(64)) + log: Mapped[str | None] = mapped_column(Text, nullable=True) diff --git a/src/site_engine/errors.py b/src/site_engine/errors.py new file mode 100644 index 0000000..d5dddb0 --- /dev/null +++ b/src/site_engine/errors.py @@ -0,0 +1,76 @@ +"""Структурированные ошибки: код, путь к полю, серьёзность, подсказка (ADR-002, ADR-006).""" + +from __future__ import annotations + +from dataclasses import dataclass, field + + +@dataclass(frozen=True) +class Issue: + code: str + message: str + path: str = "" + severity: str = "error" # error | warning + hint: str = "" + + def __str__(self) -> str: + loc = f"{self.path}: " if self.path else "" + hint = f" ({self.hint})" if self.hint else "" + return f"[{self.severity}] {self.code} {loc}{self.message}{hint}" + + def to_dict(self) -> dict: + return { + "code": self.code, + "message": self.message, + "path": self.path, + "severity": self.severity, + "hint": self.hint, + } + + +@dataclass +class Report: + issues: list[Issue] = field(default_factory=list) + + def add( + self, code: str, message: str, path: str = "", severity: str = "error", hint: str = "" + ) -> None: + self.issues.append(Issue(code, message, path, severity, hint)) + + def extend(self, other: "Report") -> None: + self.issues.extend(other.issues) + + @property + def errors(self) -> list[Issue]: + return [i for i in self.issues if i.severity == "error"] + + @property + def warnings(self) -> list[Issue]: + return [i for i in self.issues if i.severity == "warning"] + + @property + def ok(self) -> bool: + return not self.errors + + def codes(self) -> set[str]: + return {i.code for i in self.issues} + + +class EngineError(Exception): + """Базовая ошибка движка; может нести отчёт валидации.""" + + def __init__(self, message: str, report: Report | None = None): + super().__init__(message) + self.report = report or Report() + + +class ConflictError(EngineError): + """Версия файла изменилась (if_match не совпал). Для API это ответ 409.""" + + def __init__(self, message: str, current_etag: str): + super().__init__(message) + self.current_etag = current_etag + + +class UnsafePathError(EngineError): + """Путь выходит за корень сайта или содержит недопустимые элементы.""" diff --git a/src/site_engine/mcp/__init__.py b/src/site_engine/mcp/__init__.py new file mode 100644 index 0000000..a5c2601 --- /dev/null +++ b/src/site_engine/mcp/__init__.py @@ -0,0 +1 @@ +"""MCP-сервер для агентов (M3).""" diff --git a/src/site_engine/mcp/server.py b/src/site_engine/mcp/server.py new file mode 100644 index 0000000..4b1a4f9 --- /dev/null +++ b/src/site_engine/mcp/server.py @@ -0,0 +1,42 @@ +"""MCP-инструменты MVP (ADR-006). Включаются только после контура «вход, роли, аудит, лимиты». + +Контракты: пагинация и лимит размера у `list_*`, `if_match` и `dry_run` у записей, +структурные коды ошибок, максимум операций в `patch_page`, `correlation_id`. +`publish` и `rollback` по умолчанию выключены. +""" + +from __future__ import annotations + +from dataclasses import dataclass + + +@dataclass(frozen=True) +class ToolSpec: + name: str + group: str # discover | change | check + writes: bool + scope: str + + +TOOLS: tuple[ToolSpec, ...] = ( + ToolSpec("get_site_info", "discover", False, "read"), + ToolSpec("list_pages", "discover", False, "read"), + ToolSpec("get_page", "discover", False, "read"), + ToolSpec("list_entries", "discover", False, "read"), + ToolSpec("get_entry", "discover", False, "read"), + ToolSpec("list_fragments", "discover", False, "read"), + ToolSpec("create_page", "change", True, "content:write"), + ToolSpec("patch_page", "change", True, "content:write"), + ToolSpec("rename_page", "change", True, "content:write"), + ToolSpec("create_entry", "change", True, "content:write"), + ToolSpec("update_entry", "change", True, "content:write"), + ToolSpec("upload_asset", "change", True, "content:write"), + ToolSpec("validate", "check", False, "read"), + ToolSpec("get_preview_url", "check", False, "read"), + ToolSpec("get_diff", "check", False, "read"), +) + + +def build_server(site_root: str): + """Собрать MCP-сервер на официальном SDK (`pip install site-engine[mcp]`). M3.""" + raise NotImplementedError("M3: см. ADR-004 и ADR-006") diff --git a/src/site_engine/parsing/__init__.py b/src/site_engine/parsing/__init__.py new file mode 100644 index 0000000..0552978 --- /dev/null +++ b/src/site_engine/parsing/__init__.py @@ -0,0 +1 @@ +"""Разбор файлов сайта: YAML, front matter, Markdown.""" diff --git a/src/site_engine/parsing/frontmatter.py b/src/site_engine/parsing/frontmatter.py new file mode 100644 index 0000000..c7f6be3 --- /dev/null +++ b/src/site_engine/parsing/frontmatter.py @@ -0,0 +1,40 @@ +"""Markdown-файл с YAML front matter: разбор и детерминированная сериализация.""" + +from __future__ import annotations + +from .yamlio import YamlError, dump_yaml, load_yaml + +FENCE = "---" + + +def split(text: str) -> tuple[str | None, str]: + """(yaml_text | None, body). Без начального `---` весь текст считается телом.""" + text = text.lstrip("\ufeff").replace("\r\n", "\n") + if not text.startswith(FENCE + "\n"): + return None, text + rest = text[len(FENCE) + 1 :] + if rest.startswith(FENCE + "\n") or rest == FENCE: # пустой front matter + return "", rest[len(FENCE) + 1 :] + idx = rest.find("\n" + FENCE + "\n") + if idx == -1: + if rest.endswith("\n" + FENCE): + return rest[: -len(FENCE) - 1], "" + return None, text + return rest[:idx], rest[idx + len(FENCE) + 2 :] + + +def parse(text: str) -> tuple[dict, str]: + raw, body = split(text) + if raw is None: + return {}, body + meta = load_yaml(raw) if raw.strip() else {} + if meta is None: + meta = {} + if not isinstance(meta, dict): + raise YamlError("front matter должен быть объектом") + return meta, body + + +def dumps(meta: dict, body: str = "") -> str: + head = dump_yaml(meta) if meta else "" + return f"{FENCE}\n{head}{FENCE}\n{body}" diff --git a/src/site_engine/parsing/markdown.py b/src/site_engine/parsing/markdown.py new file mode 100644 index 0000000..ec58ea6 --- /dev/null +++ b/src/site_engine/parsing/markdown.py @@ -0,0 +1,38 @@ +"""Markdown → HTML: raw HTML выключен, затем санитайзер (ADR-005).""" + +from __future__ import annotations + +from markdown_it import MarkdownIt + +try: # необязательная зависимость + import nh3 +except ImportError: # pragma: no cover + nh3 = None + +_md = MarkdownIt("commonmark", {"html": False, "linkify": False}).enable( + ["table", "strikethrough"] +) + +_ALLOWED_TAGS = { + "p", "br", "strong", "em", "del", "code", "pre", "blockquote", "ul", "ol", "li", + "h2", "h3", "h4", "h5", "h6", "a", "hr", "table", "thead", "tbody", "tr", "th", "td", "img", +} + + +def _clean(html: str) -> str: + if nh3 is None: + return html + return nh3.clean( + html, + tags=_ALLOWED_TAGS, + attributes={"a": {"href", "title"}, "img": {"src", "alt", "title"}}, + url_schemes={"http", "https", "mailto", "tel"}, + ) + + +def render_markdown(text: str) -> str: + return _clean(_md.render(text or "")) + + +def render_inline(text: str) -> str: + return _clean(_md.renderInline(text or "")) diff --git a/src/site_engine/parsing/yamlio.py b/src/site_engine/parsing/yamlio.py new file mode 100644 index 0000000..6535e26 --- /dev/null +++ b/src/site_engine/parsing/yamlio.py @@ -0,0 +1,50 @@ +"""YAML: только безопасная загрузка, без алиасов, с лимитами (ADR-005).""" + +from __future__ import annotations + +from typing import Any + +import yaml + +MAX_BYTES = 1_000_000 +MAX_DEPTH = 40 + + +class YamlError(ValueError): + pass + + +class _NoAliasLoader(yaml.SafeLoader): + def compose_node(self, parent, index): # type: ignore[override] + if self.check_event(yaml.events.AliasEvent): + raise yaml.YAMLError("алиасы YAML запрещены") + return super().compose_node(parent, index) + + +def _depth(obj: Any, level: int = 0) -> int: + if level > MAX_DEPTH: + return level + if isinstance(obj, dict): + return max((_depth(v, level + 1) for v in obj.values()), default=level + 1) + if isinstance(obj, list): + return max((_depth(v, level + 1) for v in obj), default=level + 1) + return level + + +def load_yaml(text: str) -> Any: + if len(text.encode("utf-8")) > MAX_BYTES: + raise YamlError(f"YAML больше {MAX_BYTES} байт") + try: + data = yaml.load(text, Loader=_NoAliasLoader) # noqa: S506 (безопасный подкласс SafeLoader) + except yaml.YAMLError as exc: + raise YamlError(str(exc).replace("\n", " ")) from exc + if _depth(data) > MAX_DEPTH: + raise YamlError(f"вложенность YAML больше {MAX_DEPTH}") + return data + + +def dump_yaml(data: Any) -> str: + """Детерминированный вывод: порядок ключей сохраняется, Unicode без экранирования.""" + return yaml.safe_dump( + data, sort_keys=False, allow_unicode=True, default_flow_style=False, width=100 + ) diff --git a/src/site_engine/services/__init__.py b/src/site_engine/services/__init__.py new file mode 100644 index 0000000..b5a9147 --- /dev/null +++ b/src/site_engine/services/__init__.py @@ -0,0 +1 @@ +"""Сервисный слой: единая точка для админки, MCP и CLI (принцип 2 ТЗ).""" diff --git a/src/site_engine/services/auth.py b/src/site_engine/services/auth.py new file mode 100644 index 0000000..f7463ac --- /dev/null +++ b/src/site_engine/services/auth.py @@ -0,0 +1,4 @@ +"""Вход, роли owner/developer/editor, токены агентов со scope — M2 (ADR-005, ADR-006). + +Правило порядка: сетевая поверхность записи включается только вместе с этим модулем. +""" diff --git a/src/site_engine/services/changeset.py b/src/site_engine/services/changeset.py new file mode 100644 index 0000000..5d6986c --- /dev/null +++ b/src/site_engine/services/changeset.py @@ -0,0 +1,13 @@ +"""Changeset для операций над несколькими файлами (rename_page, delete_*) — M3, ADR-004. + +План: staging во временном каталоге → проверка всего набора → commit с журналом +`.engine/journal` → восстановление после сбоя по журналу. Оговорка из ADR-004: файловая +система не транзакционна, поэтому гарантируем восстановимость, а не атомарность ОС. +""" + +from __future__ import annotations + + +class Changeset: + def __init__(self, *args, **kwargs): + raise NotImplementedError("M3: см. ADR-004 (changeset и журнал)") diff --git a/src/site_engine/services/content.py b/src/site_engine/services/content.py new file mode 100644 index 0000000..605c905 --- /dev/null +++ b/src/site_engine/services/content.py @@ -0,0 +1,64 @@ +"""ContentService: безопасная запись файлов сайта (ADR-004). + +Путь записи: блокировка сайта → проверка if_match → проверка синтаксиса → история → +атомарная запись. Права (scope) ограничиваются `allowed_prefixes`: для роли editor и +агента это `pages/`, `content/`, `data/`, `menus/`, `assets/`; код (`fragments/`, +`layouts/`, схемы) им недоступен. +""" + +from __future__ import annotations + +from pathlib import Path + +from ..errors import ConflictError, EngineError, Report, UnsafePathError +from ..parsing import frontmatter +from ..parsing.yamlio import YamlError, load_yaml +from ..storage.fs import atomic_write, etag_of, file_etag, safe_join +from ..storage.history import save_previous +from ..storage.locks import SiteLock + +CONTENT_PREFIXES = ("pages/", "content/", "data/", "menus/", "assets/") +ABSENT = "absent" # if_match для создания нового файла + + +class ContentService: + def __init__(self, root: Path, allowed_prefixes: tuple[str, ...] | None = None): + self.root = Path(root) + self.allowed_prefixes = allowed_prefixes + + def _resolve(self, rel: str) -> Path: + path = safe_join(self.root, rel) + if self.allowed_prefixes is not None and not rel.startswith(self.allowed_prefixes): + raise UnsafePathError(f"запись в «{rel}» не разрешена для этой роли") + return path + + def read(self, rel: str) -> tuple[str, str]: + """(текст, etag).""" + path = safe_join(self.root, rel) + data = path.read_bytes() + return data.decode("utf-8"), etag_of(data) + + @staticmethod + def _check_syntax(rel: str, text: str) -> None: + try: + if rel.endswith(".md"): + frontmatter.parse(text) + elif rel.endswith((".yaml", ".yml")): + load_yaml(text) + except YamlError as exc: + report = Report() + report.add("E_YAML", str(exc), rel) + raise EngineError(f"{rel}: синтаксическая ошибка", report) from exc + + def write(self, rel: str, text: str, if_match: str) -> str: + """Записывает файл; возвращает новый etag. Конфликт версий → ConflictError (HTTP 409).""" + path = self._resolve(rel) + self._check_syntax(rel, text) + with SiteLock(self.root): + current = file_etag(path) + expected = current if current is not None else ABSENT + if if_match != expected: + raise ConflictError(f"{rel}: файл изменился (ожидали {if_match}, сейчас {expected})", expected) + save_previous(self.root, rel) + atomic_write(path, text) + return etag_of(text.encode("utf-8")) diff --git a/src/site_engine/services/forms.py b/src/site_engine/services/forms.py new file mode 100644 index 0000000..8f1233b --- /dev/null +++ b/src/site_engine/services/forms.py @@ -0,0 +1 @@ +"""Приём заявок: проверка по версии формы из релиза, запись заявки и outbox в одной транзакции — M2 (ADR-003).""" diff --git a/src/site_engine/services/publish.py b/src/site_engine/services/publish.py new file mode 100644 index 0000000..c4948bf --- /dev/null +++ b/src/site_engine/services/publish.py @@ -0,0 +1,22 @@ +"""Публикация: сборка релиза и переключение `current` под блокировкой сайта.""" + +from __future__ import annotations + +from pathlib import Path + +from ..build.pipeline import BuildResult, build_site +from ..storage.locks import SiteLock + + +def publish(root: Path, dist: Path, keep: int = 5) -> BuildResult: + with SiteLock(root): + return build_site(root, dist, keep=keep) + + +def rollback(dist: Path, build_id: str) -> None: + """Переключить `current` на сохранённый релиз (ADR-003).""" + from ..build.pipeline import BUILD_ID_RE, switch_current + + if not BUILD_ID_RE.match(build_id) or not (dist / build_id).is_dir(): + raise ValueError(f"нет релиза {build_id}") + switch_current(dist, build_id) diff --git a/src/site_engine/storage/__init__.py b/src/site_engine/storage/__init__.py new file mode 100644 index 0000000..99ec272 --- /dev/null +++ b/src/site_engine/storage/__init__.py @@ -0,0 +1 @@ +"""Файловое хранилище: безопасные пути, атомарная запись, блокировка сайта, история.""" diff --git a/src/site_engine/storage/fs.py b/src/site_engine/storage/fs.py new file mode 100644 index 0000000..70e2f73 --- /dev/null +++ b/src/site_engine/storage/fs.py @@ -0,0 +1,46 @@ +"""Безопасные пути и атомарная запись (ADR-004, ADR-005).""" + +from __future__ import annotations + +import hashlib +import os +import tempfile +from pathlib import Path + +from ..errors import UnsafePathError + + +def safe_join(root: Path, rel: str) -> Path: + """Путь внутри корня сайта. Абсолютные пути, `..` и symlink наружу запрещены.""" + if not rel or rel.startswith(("/", "\\")) or "\x00" in rel: + raise UnsafePathError(f"недопустимый путь: {rel!r}") + root_r = root.resolve() + candidate = (root_r / rel).resolve() + if candidate != root_r and root_r not in candidate.parents: + raise UnsafePathError(f"путь выходит за корень сайта: {rel!r}") + return candidate + + +def etag_of(data: bytes) -> str: + return "sha256:" + hashlib.sha256(data).hexdigest() + + +def file_etag(path: Path) -> str | None: + return etag_of(path.read_bytes()) if path.is_file() else None + + +def atomic_write(path: Path, data: str | bytes) -> None: + """Запись через временный файл и rename: читатель видит либо старое, либо новое.""" + path.parent.mkdir(parents=True, exist_ok=True) + raw = data.encode("utf-8") if isinstance(data, str) else data + fd, tmp_name = tempfile.mkstemp(dir=path.parent, prefix=f".{path.name}.", suffix=".tmp") + try: + with os.fdopen(fd, "wb") as fh: + fh.write(raw) + fh.flush() + os.fsync(fh.fileno()) + os.replace(tmp_name, path) + except BaseException: + if os.path.exists(tmp_name): + os.unlink(tmp_name) + raise diff --git a/src/site_engine/storage/history.py b/src/site_engine/storage/history.py new file mode 100644 index 0000000..3bdf748 --- /dev/null +++ b/src/site_engine/storage/history.py @@ -0,0 +1,35 @@ +"""Страховочная история файлов `.engine/history/` (ADR-004): последние N версий на файл.""" + +from __future__ import annotations + +import shutil +import time +from pathlib import Path + +from .fs import etag_of + + +def save_previous(root: Path, rel: str, keep: int = 20) -> Path | None: + """Копирует текущую версию файла в историю перед перезаписью.""" + src = root / rel + if not src.is_file(): + return None + data = src.read_bytes() + folder = root / ".engine" / "history" / rel + folder.mkdir(parents=True, exist_ok=True) + stamp = time.strftime("%Y%m%dT%H%M%S", time.gmtime()) + target = folder / f"{stamp}-{etag_of(data)[7:15]}" + n = 0 + while target.exists(): # две записи в одну секунду с одинаковым содержимым + n += 1 + target = folder / f"{stamp}-{etag_of(data)[7:15]}-{n}" + shutil.copy2(src, target) + versions = sorted(p for p in folder.iterdir() if p.is_file()) + for old in versions[:-keep]: + old.unlink() + return target + + +def list_versions(root: Path, rel: str) -> list[Path]: + folder = root / ".engine" / "history" / rel + return sorted(p for p in folder.iterdir() if p.is_file()) if folder.is_dir() else [] diff --git a/src/site_engine/storage/locks.py b/src/site_engine/storage/locks.py new file mode 100644 index 0000000..55508cb --- /dev/null +++ b/src/site_engine/storage/locks.py @@ -0,0 +1,36 @@ +"""Межпроцессная блокировка записи на весь сайт (ADR-004, MVP).""" + +from __future__ import annotations + +import fcntl +import time +from pathlib import Path + +from ..errors import EngineError + + +class SiteLock: + def __init__(self, root: Path, timeout: float = 10.0): + self.path = root / ".engine" / "site.lock" + self.timeout = timeout + self._fh = None + + def __enter__(self) -> "SiteLock": + self.path.parent.mkdir(parents=True, exist_ok=True) + self._fh = open(self.path, "a+") + deadline = time.monotonic() + self.timeout + while True: + try: + fcntl.flock(self._fh, fcntl.LOCK_EX | fcntl.LOCK_NB) + return self + except BlockingIOError: + if time.monotonic() >= deadline: + self._fh.close() + raise EngineError("не удалось получить блокировку записи сайта") from None + time.sleep(0.05) + + def __exit__(self, *exc) -> None: + if self._fh is not None: + fcntl.flock(self._fh, fcntl.LOCK_UN) + self._fh.close() + self._fh = None diff --git a/src/site_engine/web/__init__.py b/src/site_engine/web/__init__.py new file mode 100644 index 0000000..62cb37a --- /dev/null +++ b/src/site_engine/web/__init__.py @@ -0,0 +1 @@ +"""HTTP-слой на FastAPI: форма, превью, админка (htmx). Не тестировалось в песочнице без сети.""" diff --git a/src/site_engine/web/admin/__init__.py b/src/site_engine/web/admin/__init__.py new file mode 100644 index 0000000..77f7d93 --- /dev/null +++ b/src/site_engine/web/admin/__init__.py @@ -0,0 +1 @@ +"""Админка: роутеры, Jinja-партиалы и статика htmx (M2–M3, ТЗ раздел 10). if_match обязателен во всех формах.""" diff --git a/src/site_engine/web/app.py b/src/site_engine/web/app.py new file mode 100644 index 0000000..f831ff2 --- /dev/null +++ b/src/site_engine/web/app.py @@ -0,0 +1,30 @@ +"""Фабрика приложения. M0–M1: health и раздача `dist/current` для разработки. + +Дальше: `POST /forms/{id}` и outbox (M2), админка `web/admin/` (M2–M3), превью по токену +`/_preview//` (M1), MCP на `/mcp/` (M3). В production статику отдаёт nginx. +""" + +from __future__ import annotations + +import os +from pathlib import Path + + +def create_app(): + from fastapi import FastAPI, HTTPException + from fastapi.staticfiles import StaticFiles + + app = FastAPI(title="Site Engine") + dist = Path(os.environ.get("SITE_DIST", "dist")) + + @app.get("/healthz") + def healthz() -> dict: + return {"status": "ok"} + + @app.post("/forms/{form_id}") + def submit_form(form_id: str) -> None: + raise HTTPException(status_code=501, detail="приём заявок появится в M2 (ADR-003)") + + if (dist / "current").exists(): + app.mount("/", StaticFiles(directory=dist / "current", html=True), name="site") + return app diff --git a/tests/helpers.py b/tests/helpers.py new file mode 100644 index 0000000..f6b93ab --- /dev/null +++ b/tests/helpers.py @@ -0,0 +1,32 @@ +import datetime as dt +import shutil +import tempfile +import unittest +from pathlib import Path + +ROOT = Path(__file__).resolve().parent.parent +EXAMPLE = ROOT / "examples" / "studio-site" +NOW = dt.datetime(2026, 11, 7, 12, 0, 0, tzinfo=dt.timezone.utc) + + +class SiteTestCase(unittest.TestCase): + """Каждый тест получает свежую копию примера во временном каталоге.""" + + def setUp(self): + self._tmp = tempfile.TemporaryDirectory() + self.addCleanup(self._tmp.cleanup) + self.tmp = Path(self._tmp.name) + self.site = self.tmp / "site" + shutil.copytree(EXAMPLE, self.site) + self.out = self.tmp / "dist" + + def edit(self, rel: str, old: str, new: str) -> None: + path = self.site / rel + text = path.read_text(encoding="utf-8") + assert old in text, f"{old!r} не найден в {rel}" + path.write_text(text.replace(old, new), encoding="utf-8") + + def write(self, rel: str, text: str) -> None: + path = self.site / rel + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(text, encoding="utf-8") diff --git a/tests/test_build.py b/tests/test_build.py new file mode 100644 index 0000000..211b49b --- /dev/null +++ b/tests/test_build.py @@ -0,0 +1,174 @@ +import json +import os +import unittest + +from helpers import NOW, SiteTestCase + +from site_engine.build.pipeline import build_site, preview_page +from site_engine.core.registry import load_site +from site_engine.core.routes import build_route_table +from site_engine.core.validate import validate_workspace +from site_engine.errors import EngineError, Report + + +class BuildTest(SiteTestCase): + def build(self, out=None): + return build_site(self.site, out or self.out, now=NOW) + + def codes_of_failed_build(self): + with self.assertRaises(EngineError) as ctx: + self.build() + return ctx.exception.report.codes() + + def test_example_builds_published_pages_only(self): + result = self.build() + cur = self.out / "current" + self.assertTrue(cur.is_symlink()) + self.assertEqual(os.readlink(cur), result.build_id) + for rel in ("index.html", "services/index.html", "services/bots/index.html", + "contacts/index.html", "privacy/index.html", "sitemap.xml", "robots.txt"): + self.assertTrue((cur / rel).is_file(), rel) + self.assertFalse((cur / "drafts").exists(), "черновик не должен попадать в релиз") + self.assertEqual(result.pages, 7) + + def test_hidden_features_and_disabled_menu_items_are_absent(self): + self.build() + html = (self.out / "current" / "index.html").read_text(encoding="utf-8") + self.assertNotIn("Заглушка", html) # блок с requires: feature.demo + self.assertNotIn("Проекты", html) # пункт меню enabled: false + self.assertIn("Telegram-боты", html) # данные из коллекции без дублей + + def test_feature_flag_returns_block(self): + self.edit("site.yaml", "demo: false", "demo: true") + self.build() + html = (self.out / "current" / "index.html").read_text(encoding="utf-8") + self.assertIn("Заглушка", html) + + def test_redirect_forms_snapshot_and_sitemap(self): + self.build() + cur = self.out / "current" + self.assertIn("/services/", (cur / "uslugi" / "index.html").read_text(encoding="utf-8")) + forms = list((cur / "_forms").glob("consultation@*.json")) + self.assertEqual(len(forms), 1) + self.assertEqual(json.loads(forms[0].read_text(encoding="utf-8"))["id"], "consultation") + sitemap = (cur / "sitemap.xml").read_text(encoding="utf-8") + self.assertIn("/services/bots/", sitemap) + self.assertNotIn("drafts", sitemap) + self.assertNotIn("uslugi", sitemap) + + def test_form_html_carries_version_and_consent(self): + self.build() + html = (self.out / "current" / "contacts" / "index.html").read_text(encoding="utf-8") + self.assertIn("name='form_version'", html) + self.assertIn("href='/privacy/'", html) + self.assertIn("type='checkbox' name='consent' required", html) + + def test_build_is_deterministic_without_database(self): + a = self.build(self.tmp / "a") + b = self.build(self.tmp / "b") + self.assertEqual(a.build_id, b.build_id) + self.assertEqual(a.source_hash, b.source_hash) + for rel in ("index.html", "services/ai/index.html", "sitemap.xml"): + self.assertEqual((a.output_dir / rel).read_bytes(), (b.output_dir / rel).read_bytes()) + + def test_failed_build_does_not_touch_live(self): + first = self.build() + self.edit("display/services.yaml", "{bind: entry.summary}", "{bind: entry.no_such_field}") + with self.assertRaises(EngineError) as ctx: + build_site(self.site, self.out, now=NOW.replace(minute=30)) + self.assertIn("E_BIND_MISSING", ctx.exception.report.codes()) + self.assertEqual(os.readlink(self.out / "current"), first.build_id) + leftovers = [p.name for p in self.out.iterdir() if p.name.startswith(".staging")] + self.assertEqual(leftovers, []) + + def test_unknown_fragment_is_reported(self): + self.edit("pages/contacts.md", "fragment: form", "fragment: no_such_fragment") + self.assertIn("E_FRAGMENT_UNKNOWN", self.codes_of_failed_build()) + + def test_unknown_prop_and_wrong_type(self): + self.edit("pages/contacts.md", "props: {title: Контакты, lead: Свяжитесь удобным способом.}", + "props: {title: 5, bogus: 1}") + codes = self.codes_of_failed_build() + self.assertIn("E_PROP_UNKNOWN", codes) + self.assertIn("E_TYPE", codes) + + def test_template_syntax_in_data_is_rejected(self): + self.edit("display/services.yaml", "title: {bind: entry.title}", "title: '{{ entry.title }}'") + self.assertIn("E_TEMPLATE_IN_DATA", self.codes_of_failed_build()) + + def test_unknown_requires_feature(self): + self.edit("pages/index.md", "requires: [feature.demo]", "requires: [feature.nope]") + self.assertIn("E_REQUIRES_UNKNOWN", self.codes_of_failed_build()) + + def test_site_rule_requires_consent_field(self): + self.edit("forms/consultation.yaml", " - {key: consent, type: consent, policy: privacy}\n", "") + self.assertIn("R_form-consent", self.codes_of_failed_build()) + + def test_draft_may_be_incomplete_but_publishing_it_fails(self): + # ADR-003: у черновика обязательные поля не требуются; в релиз он не попадает + self.write("pages/wip.md", "---\ntitle: WIP\nstatus: draft\nregions:\n main:\n - {id: b_h, fragment: hero}\n---\n") + report = validate_workspace(load_site(self.site)) + self.assertEqual(report.errors, []) + self.build() # черновик не рендерится + self.edit("pages/wip.md", "status: draft", "status: published") + self.assertIn("E_REQUIRED", self.codes_of_failed_build()) + + def test_duplicate_block_ids(self): + self.edit("pages/contacts.md", "id: b_form", "id: b_text") + self.assertIn("E_BLOCK_DUP", self.codes_of_failed_build()) + + def test_block_without_explicit_id_is_rejected(self): + self.write("pages/noid.md", "---\ntitle: X\nstatus: published\nregions:\n main:\n - {fragment: hero, props: {title: A}}\n---\n") + self.assertIn("E_BLOCK_ID", self.codes_of_failed_build()) + + def test_link_to_unpublished_page_fails_release(self): + self.edit("pages/index.md", "{page: contacts, label: Обсудить задачу}", "{page: drafts/next, label: Черновик}") + self.assertIn("E_LINK_UNPUBLISHED", self.codes_of_failed_build()) + + def test_asset_must_exist(self): + self.edit("pages/index.md", "variant: dark\n", "variant: dark\n image: assets/missing.png\n") + self.assertIn("E_ASSET_MISSING", self.codes_of_failed_build()) + + def test_asset_ok_and_copied(self): + self.edit("pages/index.md", "variant: dark\n", "variant: dark\n image: assets/hero.svg\n image_alt: Баннер\n") + self.build() + self.assertTrue((self.out / "current" / "assets" / "hero.svg").is_file()) + + def test_empty_collection_hides_list(self): + for f in (self.site / "content" / "services").glob("*.md"): + f.unlink() + self.edit("pages/index.md", "card: direction", "card: direction\n empty: hide") + self.edit("pages/services/index.md", "layout: list", "layout: list\n empty: message\n empty_message: Скоро") + self.build() + self.assertNotIn("Направления", (self.out / "current" / "index.html").read_text(encoding="utf-8")) + self.assertIn("Скоро", (self.out / "current" / "services" / "index.html").read_text(encoding="utf-8")) + + def test_entry_regions_override_appends_blocks(self): + self.edit("content/services/bots.md", "order: 1\n", + "order: 1\nregions:\n main:\n - {id: e_note, fragment: disclaimer, props: {text: Только для этой услуги}}\n") + self.build() + self.assertIn("Только для этой услуги", (self.out / "current" / "services" / "bots" / "index.html").read_text(encoding="utf-8")) + self.assertNotIn("Только для этой услуги", (self.out / "current" / "services" / "ai" / "index.html").read_text(encoding="utf-8")) + + def test_old_releases_are_pruned_but_current_kept(self): + for minute in range(4): + self.edit("pages/privacy.md", "Текст политики", f"Текст политики v{minute}") + build_site(self.site, self.out, keep=2, now=NOW.replace(minute=minute)) + self.edit("pages/privacy.md", f"Текст политики v{minute}", "Текст политики") + builds = [p for p in self.out.iterdir() if p.is_dir() and p.name[0].isdigit()] + self.assertEqual(len(builds), 2) + + def test_preview_renders_draft_leniently(self): + html, report = preview_page(self.site, "drafts/next") + self.assertIn("Черновик", html) + self.assertIn("