Init Project Flexly CMS

This commit is contained in:
Alexey Dudin
2026-11-09 15:32:41 +03:00
commit c778db6208
115 changed files with 5098 additions and 0 deletions
+10
View File
@@ -0,0 +1,10 @@
__pycache__/
*.pyc
.venv/
dist/
build/
*.egg-info/
.engine/
*.sqlite3
.pytest_cache/
.ruff_cache/
+10
View File
@@ -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"]
+10
View File
@@ -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
+86
View File
@@ -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/<build_id>/` и симлинк `OUT/current`, который переключается атомарно. Неудачная сборка `current` не трогает.
## Структура проекта
```
site-engine/
├── pyproject.toml # зависимости ядра и extras: server, mcp, images, dev
├── Makefile Dockerfile # Dockerfile — для M2+ (админка, формы, MCP)
├── docs/ # ТЗ, ревью, журнал решений
├── examples/studio-site/ # сайт-пример из SiteMap.md (услуги, формы, коллекция, редирект)
├── tests/ # 62 теста: значения, разбор, маршруты, сборка, безопасность, запись
└── src/site_engine/
├── cli.py # validate · build · preview · fragments
├── errors.py # Issue/Report: код, путь к полю, серьёзность, подсказка
├── core/
│ ├── values.py # Literal | Binding | LinkRef | Query (ADR-002)
│ ├── models.py # Block, Page, Entry, Fragment, Layout, Collection…
│ ├── registry.py # чистая загрузка каталога сайта в память (ADR-001)
│ ├── routes.py # нормализация маршрутов, таблица, коллизии
│ ├── resolve.py # привязки, ссылки, запросы MVP
│ ├── validate.py # workspace-проверки, release-проверки, правила сайта
│ └── render.py # Jinja SandboxedEnvironment, разрешение props по схеме
├── build/pipeline.py # load → validate → render → релиз → атомарный current
├── parsing/ # безопасный YAML, front matter, Markdown (raw HTML выключен)
├── storage/ # safe_join, atomic_write, SiteLock, .engine/history
├── services/ # ContentService (if_match, история, синтаксис), publish; stubs: changeset, auth, forms
├── builtin/ # base.css и 15 фрагментов ядра (ADR-006)
├── db/ # SQLAlchemy-модели служебных таблиц (M2)
├── web/ # FastAPI-фабрика, место для админки htmx (M1–M3)
└── mcp/ # перечень инструментов MVP (M3)
```
## Что реализовано
| Этап | Состояние |
|---|---|
| M0 Контракт и прототип | Готово: формат файлов, модель блоков, load → validate → render, CLI, 15 фрагментов, сайт-пример |
| M1 Публикуемый движок | Частично: маршруты, ссылки, редиректы, sitemap, атомарная публикация, откат (`services/publish.py`), превью страницы через CLI. Нет: превью по токену, 404-страница из коробки, тема |
| M2 Коллекции, заявки, доступ | Частично: коллекции, display templates, запросы, формы (разметка, версия формы в релизе). Нет: приём заявок, outbox, вход и роли, аудит |
| M3 MCP и редактор | `ContentService` с `if_match`, блокировкой и историей готов; нет `patch_page`, changeset, MCP-сервера, админки |
| M4 | Не начат |
## Что проверено, а что нет
Тесты и сборка примера выполнялись в окружении без сети: ядро (всё, что в `core/`, `build/`, `parsing/`, `storage/`, `services/content.py`) запущено и покрыто 62 тестами. Модули `db/`, `web/`, `mcp/` и `Dockerfile` проверены только компиляцией и чтением: SQLAlchemy, FastAPI и MCP SDK в окружении не было. Ядро намеренно не зависит от pydantic: ошибки должны нести путь к полю (`pages/index.md:regions.main[b_hero].props.title`), а валидация задаётся манифестами фрагментов. Pydantic нужен на границах API (web, mcp).
## Соответствие журналу решений
| Решение | Где в коде |
|---|---|
| ADR-001: сборка не читает SQLite | `core/registry.load_site`, `build/pipeline.build_site` |
| ADR-002: 4 вида значений, `bind`, запросы MVP | `core/values.py`, `core/resolve.py`; `{{ }}` в данных запрещены (`validate.py`) |
| ADR-003: draft / release / live, версия формы в релизе | `validate_workspace` vs `validate_release`, `_forms/<id>@<версия>.json`, `switch_current` |
| ADR-004: `if_match`, блокировка сайта, история | `services/content.py`, `storage/locks.py`, `storage/history.py` |
| ADR-005: границы доверия | `SandboxedEnvironment`, Markdown без raw HTML, `safe_join`, токены темы, YAML без алиасов |
| ADR-006: 15 фрагментов, `editorial`, `requires` только `feature.*` | `builtin/fragments/`, `models.Page.editorial`, `render._feature_on` |
## Как расширять
- **Новый фрагмент:** папка `fragments/<имя>/` сайта с `fragment.yaml`, `template.html.j2`, необязательным `style.css`. `id` плоский и уникальный, затенение встроенных запрещено.
- **Новая коллекция:** `collections/<id>.yaml`, записи в `content/<id>/*.md`, при необходимости `display/<id>.yaml`.
- **Новое правило сайта:** запись в `site.yaml: rules` (сейчас `require_fragment` для коллекции и `require_field` для форм).
## Известные ограничения M0
- Поле `props` в шаблоне — объект `Props`: `props.items` читает поле «items», а не метод словаря.
- `layout.extends` проверяется на существование, наследование шаблонов делается обычным `{% extends 'layout/<id>' %}`.
- CSS и JS собираются в один бандл с хешем в имени; минификации и изоляции по страницам пока нет.
- Нет приёма заявок, входа, MCP и админки: сетевая поверхность записи включается только вместе с контуром «вход, роли, аудит, лимиты» (ADR-006).
+317
View File
@@ -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: <content-hash>`; чтение возвращает этот хеш.
- Проверка хеша и атомарная запись выполняются под блокировкой конкретного документа, а не отдельными незащищёнными операциями.
- Конфликт — `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.<name>` с чёткой булевой семантикой; `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, объём резко вырастет. Вертикальные срезы и строгие контракты позволят сохранить достоинства архитектуры и избежать ненужных затрат.
+242
View File
@@ -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/<id>@<хеш>`). В 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/<token>/`) или отдельный хост (`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. Юридическая часть по ПД (формулировки согласия, сроки хранения, место размещения сервера) остаётся за владельцем сайта и его юристом.
+769
View File
@@ -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/<id>/` |
| Fragment | Блок: шаблон + схема полей + стили/скрипты | `fragments/<категория>/<id>/` |
| Block | Экземпляр фрагмента на странице | внутри page или display template |
| Collection | Тип контента со схемой (cases, products...) | `collections/<id>.yaml` |
| Entry | Запись коллекции | `content/<collection>/<slug>.md` |
| Display template | Как запись коллекции превращается в страницу | `display/<collection>.yaml` |
| Taxonomy | Словарь терминов (технологии, отрасли, теги) | коллекция с `kind: taxonomy` |
| Menu | Навигация | `menus/<id>.yaml` |
| Data | Произвольные данные (цены, команда, реквизиты) | `data/*.yaml` |
| Form | Определение формы обратной связи | `forms/<id>.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 #}
<!doctype html>
<html lang='{{ page.locale }}'>
<head>{{ seo_head() }}{{ assets_head() }}</head>
<body>
{{ region('header') }}
<main>{{ region('main') }}</main>
{{ region('footer') }}
{{ assets_body() }}
</body>
</html>
```
`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 #}
<section class='f-hero f-hero--{{ props.variant }}'>
<h1>{{ props.title }}</h1>
{% if props.subtitle %}<div>{{ props.subtitle|md_inline }}</div>{% endif %}
{% if props.cta %}<a class='btn' href='{{ props.cta|href }}'>{{ props.cta.label }}</a>{% endif %}
</section>
```
**Состав папки фрагмента:** `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-<id>`; при сборке всё собирается в хешированные бандлы. Фрагменты не должны зависеть от внешних 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/<build-id>/` и атомарное переключение символической ссылки `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/<id>.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-<id>`, без внешних 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. Название проекта.
+1
View File
@@ -0,0 +1 @@
<svg xmlns='http://www.w3.org/2000/svg' width='320' height='120' viewBox='0 0 320 120'><rect width='320' height='120' fill='#14213d'/><text x='20' y='70' fill='#fff' font-size='28'>Acme Studio</text></svg>

After

Width:  |  Height:  |  Size: 206 B

@@ -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}
@@ -0,0 +1,8 @@
---
title: AI-системы
status: published
order: 2
tagline: Ассистенты на ваших данных
summary: Поиск по базе знаний, подготовка ответов, разбор обращений.
---
AI-ассистент работает с вашими документами и данными в согласованном контуре.
@@ -0,0 +1,8 @@
---
title: Автоматизации
status: published
order: 3
tagline: Меньше рутины в процессах
summary: Интеграции между сервисами и автоматизация повторяющихся операций.
---
Связываем CRM, таблицы, мессенджеры и внутренние системы.
@@ -0,0 +1,8 @@
---
title: Telegram-боты
status: published
order: 1
tagline: Автоматизация общения с клиентами
summary: Боты для заявок, записи, напоминаний и поддержки.
---
Бот принимает обращения, задаёт уточняющие вопросы и передаёт задачу менеджеру.
+2
View File
@@ -0,0 +1,2 @@
legal_name: Acme Studio LLC
requisites: реквизиты указывает владелец сайта
@@ -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
@@ -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}
@@ -0,0 +1,13 @@
<!doctype html>
<html lang='{{ page.locale }}'>
<head>
{{ seo_head() }}
{{ assets_head() }}
</head>
<body>
{{ region('header') }}
<main>{{ region('main') }}</main>
{{ region('footer') }}
{{ assets_body() }}
</body>
</html>
@@ -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}}
+3
View File
@@ -0,0 +1,3 @@
items:
- {label: Политика ПД, page: privacy}
- {label: Контакты, page: contacts}
+4
View File
@@ -0,0 +1,4 @@
items:
- {label: Услуги, page: services/index}
- {label: Проекты, page: cases/index, enabled: false, note: Исключено на старте — нет согласий и данных}
- {label: Контакты, page: contacts}
+2
View File
@@ -0,0 +1,2 @@
title: Корень
layout: default
+11
View File
@@ -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. Почту и форму ниже используйте, если так удобнее.
@@ -0,0 +1,8 @@
---
schema: 1
title: Черновик новой страницы
status: draft
regions:
main:
- {id: b_head, fragment: page_header, props: {title: Черновик}}
---
+51
View File
@@ -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: Оставить заявку}
---
+10
View File
@@ -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}}}
---
Текст политики добавляет владелец сайта и согласует с юристом.
@@ -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
---
+1
View File
@@ -0,0 +1 @@
- {from: /uslugi/, to: /services/}
+22
View File
@@ -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}
+47
View File
@@ -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"
+3
View File
@@ -0,0 +1,3 @@
"""Site Engine: сайты из Markdown + YAML, layouts и fragments."""
__version__ = "0.1.0"
+19
View File
@@ -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; }
@@ -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}
@@ -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); }
@@ -0,0 +1,14 @@
<section class='f-card_grid f-card_grid--{{ props.variant }}'>
<div class='f-container'>
{% if props.title %}<h2>{{ props.title }}</h2>{% endif %}
<{{ 'ol' if props.variant == 'steps' else 'ul' }} class='f-card_grid__items'>
{% for item in props.items %}
<li class='f-card'>
{% if item.badge %}<span class='f-badge'>{{ item.badge }}</span>{% endif %}
<h3>{% if item.link %}<a href='{{ item.link|href }}'>{{ item.title }}</a>{% else %}{{ item.title }}{% endif %}</h3>
{% if item.text %}<div>{{ item.text|md_inline }}</div>{% endif %}
</li>
{% endfor %}
</{{ 'ol' if props.variant == 'steps' else 'ul' }}>
</div>
</section>
@@ -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: {}
@@ -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; }
@@ -0,0 +1,18 @@
{% if props.source %}
<section class='f-collection_list f-collection_list--{{ props.layout }}'>
<div class='f-container'>
{% if props.title %}<h2>{{ props.title }}</h2>{% endif %}
<ul class='f-collection_list__items'>
{% for e in props.source %}
<li class='f-card f-card--{{ props.card }}'>
<h3><a href='{{ e.url }}'>{{ e.title }}</a></h3>
{% if props.card == 'direction' and e.get('tagline') %}<p class='f-card__tagline'>{{ e.tagline }}</p>{% endif %}
{% if e.get('summary') %}<p>{{ e.summary }}</p>{% endif %}
</li>
{% endfor %}
</ul>
</div>
</section>
{% elif props.empty == 'message' %}
<section class='f-collection_list f-collection_list--empty'><div class='f-container'><p>{{ props.empty_message }}</p></div></section>
{% endif %}
@@ -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}
@@ -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; } }
@@ -0,0 +1,5 @@
<div class='f-columns f-columns--{{ props.count }}'>
{% for name in ['col_1', 'col_2', 'col_3', 'col_4'] %}
{% if slots[name] %}<div class='f-columns__col'>{{ slots[name] }}</div>{% endif %}
{% endfor %}
</div>
@@ -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}
@@ -0,0 +1 @@
.f-cta_banner { margin: 2rem 0; padding: 2.5rem 0; background: #f0f4ff; }
@@ -0,0 +1,12 @@
<section class='f-cta_banner f-cta_banner--{{ props.variant }}'>
<div class='f-container'>
<h2>{{ props.title }}</h2>
{% if props.text %}<p>{{ props.text|md_inline }}</p>{% endif %}
<p>
{% if props.variant == 'contact' and site.contacts.get('telegram') %}
<a class='f-btn' href='https://t.me/{{ site.contacts.telegram|replace('@', '') }}'>Написать в Telegram</a>
{% endif %}
{% for a in props.actions %}{% if a %}<a class='f-btn f-btn--secondary' href='{{ a|href }}'>{{ a.label }}</a>{% endif %}{% endfor %}
</p>
</div>
</section>
@@ -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: Пояснение.}
@@ -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); }
@@ -0,0 +1,3 @@
<aside class='f-disclaimer f-disclaimer--{{ props.variant }}' role='note'>
<div class='f-container'>{{ props.text|md_inline }}</div>
</aside>
@@ -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: Заголовок записи}
@@ -0,0 +1,2 @@
.f-entry_header { padding: 2rem 0 .5rem; }
.f-entry_header__meta span { margin-right: .75rem; color: #666; }
@@ -0,0 +1,6 @@
<header class='f-entry_header'>
<div class='f-container'>
<h1>{{ props.title }}</h1>
{% if props.meta %}<p class='f-entry_header__meta'>{% for m in props.meta if m %}<span>{{ m }}</span> {% endfor %}</p>{% endif %}
</div>
</header>
@@ -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: {}
@@ -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; }
@@ -0,0 +1,8 @@
<section class='f-faq'>
<div class='f-container'>
{% if props.title %}<h2>{{ props.title }}</h2>{% endif %}
{% for i in props.items %}
<details><summary>{{ i.q }}</summary><div>{{ i.a|md }}</div></details>
{% endfor %}
</div>
</section>
@@ -0,0 +1,8 @@
id: form
name: Форма обратной связи
category: conversion
version: 1
fields:
- {key: form, type: text, required: true}
slots: {}
preview: {}
@@ -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; }
@@ -0,0 +1,23 @@
{% set f = forms.get(props.form) %}
{% if f %}
<section class='f-form'>
<div class='f-container'>
<h2>{{ f.title }}</h2>
<form method='post' action='{{ f.action }}'>
<input type='hidden' name='form_version' value='{{ f.version }}'>
<p class='f-form__trap' aria-hidden='true'><label>Не заполняйте <input type='text' name='website' tabindex='-1' autocomplete='off'></label></p>
{% for field in f.fields %}
{% if field.type == 'consent' %}
<label class='f-form__consent'><input type='checkbox' name='{{ field.key }}' required>
Согласен(на) на обработку персональных данных{% if field.policy_url %} (<a href='{{ field.policy_url }}'>политика</a>){% endif %}</label>
{% elif field.type == 'textarea' %}
<label>{{ field.label }}<textarea name='{{ field.key }}' {% if field.required %}required{% endif %}></textarea></label>
{% else %}
<label>{{ field.label }}<input type='text' name='{{ field.key }}' {% if field.required %}required{% endif %}></label>
{% endif %}
{% endfor %}
<button class='f-btn' type='submit'>Отправить</button>
</form>
</div>
</section>
{% endif %}
@@ -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}
@@ -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; }
@@ -0,0 +1,10 @@
<section class='f-hero f-hero--{{ props.variant }}'>
<div class='f-container'>
<h1>{{ props.title }}</h1>
{% if props.subtitle %}<p class='f-hero__sub'>{{ props.subtitle|md_inline }}</p>{% endif %}
{% if props.actions %}
<p class='f-hero__actions'>{% for a in props.actions %}{% if a %}<a class='f-btn' href='{{ a|href }}'>{{ a.label }}</a>{% endif %}{% endfor %}</p>
{% endif %}
{% if props.image %}<img src='{{ props.image.url }}' alt='{{ props.image_alt or '' }}'>{% endif %}
</div>
</section>
@@ -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: {}
@@ -0,0 +1 @@
.f-image figcaption { font-size: .85rem; color: #666; }
@@ -0,0 +1,4 @@
<figure class='f-image f-container'>
<img src='{{ props.asset.url }}' alt='{{ props.alt }}' loading='lazy'>
{% if props.caption %}<figcaption>{{ props.caption }}</figcaption>{% endif %}
</figure>
@@ -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: Заголовок}
@@ -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; }
@@ -0,0 +1,15 @@
<header class='f-page_header'>
<div class='f-container'>
{% if props.breadcrumbs and breadcrumbs|length > 1 %}
<nav aria-label='Хлебные крошки'>
<ol class='f-page_header__crumbs'>
{% for c in breadcrumbs %}
<li>{% if c.url %}<a href='{{ c.url }}'>{{ c.label }}</a>{% else %}<span aria-current='page'>{{ c.label }}</span>{% endif %}</li>
{% endfor %}
</ol>
</nav>
{% endif %}
<h1>{{ props.title }}</h1>
{% if props.lead %}<p class='f-page_header__lead'>{{ props.lead|md_inline }}</p>{% endif %}
</div>
</header>
@@ -0,0 +1,8 @@
id: richtext
name: Текст
category: content
version: 1
fields:
- {key: content, type: markdown, required: true}
slots: {}
preview: {content: Текст **страницы**.}
@@ -0,0 +1 @@
.f-richtext { padding-top: 1rem; padding-bottom: 1rem; max-width: 52rem; }
@@ -0,0 +1 @@
<div class='f-richtext f-container'>{{ props.content|md }}</div>
@@ -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: Секция}
@@ -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; }
@@ -0,0 +1,6 @@
<section class='f-section f-section--{{ props.background }} f-section--{{ props.width }}'>
<div class='f-container'>
{% if props.title %}<h2>{{ props.title }}</h2>{% endif %}
{{ slots.content }}
</div>
</section>
@@ -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}
@@ -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; }
@@ -0,0 +1,14 @@
<footer class='f-site_footer'>
<div class='f-container'>
<ul>
{% for item in menus.get(props.menu, []) %}
<li><a href='{{ item.url }}'>{{ item.label }}</a></li>
{% endfor %}
</ul>
{% if data.get('company') %}
<p>{{ data.company.get('legal_name', site.name) }}{% if data.company.get('requisites') %} · {{ data.company.requisites }}{% endif %}</p>
{% endif %}
{% if props.note %}<p>{{ props.note }}</p>{% endif %}
<p>© {{ build.year }} {{ site.name }}</p>
</div>
</footer>
@@ -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}
@@ -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; }
@@ -0,0 +1,13 @@
<header class='f-site_header'>
<div class='f-container f-site_header__row'>
<a class='f-site_header__brand' href='/'>{{ site.name }}</a>
<nav aria-label='Основное меню'>
<ul>
{% for item in menus.get(props.menu, []) %}
<li><a href='{{ item.url }}'{% if item.active %} aria-current='page'{% endif %}>{{ item.label }}</a></li>
{% endfor %}
</ul>
</nav>
{% if props.action %}<a class='f-btn' href='{{ props.action|href }}'>{{ props.action.label }}</a>{% endif %}
</div>
</header>
+94
View File
@@ -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/<build_id> и переключить 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()
+1
View File
@@ -0,0 +1 @@
"""Ядро: модели, реестр, валидация, разрешение значений, рендер, сборка."""
+491
View File
@@ -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],
)
+192
View File
@@ -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
+359
View File
@@ -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_HEAD@@-->"
ASSETS_BODY = "<!--@@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"<a id='{escape(block.anchor)}'></a>" + 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 = [
"<meta charset='utf-8'>",
"<meta name='viewport' content='width=device-width, initial-scale=1'>",
f"<title>{escape(title)}</title>",
]
if seo.get("description"):
parts.append(f"<meta name='description' content='{escape(seo['description'])}'>")
if self.reg.site.base_url:
parts.append(f"<link rel='canonical' href='{escape(self.reg.site.base_url + v.route)}'>")
parts.append(f"<meta property='og:title' content='{escape(title)}'>")
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
+147
View File
@@ -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
+114
View File
@@ -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
+315
View File
@@ -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")
+107
View File
@@ -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
+1
View File
@@ -0,0 +1 @@
"""SQLite через SQLAlchemy 2: служебные данные (ADR-001). Не тестировалось в песочнице без сети."""
+26
View File
@@ -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)
+96
View File
@@ -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)
+76
View File
@@ -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):
"""Путь выходит за корень сайта или содержит недопустимые элементы."""
+1
View File
@@ -0,0 +1 @@
"""MCP-сервер для агентов (M3)."""
+42
View File
@@ -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")
+1
View File
@@ -0,0 +1 @@
"""Разбор файлов сайта: YAML, front matter, Markdown."""
+40
View File
@@ -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}"
+38
View File
@@ -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 ""))
+50
View File
@@ -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
)
+1
View File
@@ -0,0 +1 @@
"""Сервисный слой: единая точка для админки, MCP и CLI (принцип 2 ТЗ)."""
+4
View File
@@ -0,0 +1,4 @@
"""Вход, роли owner/developer/editor, токены агентов со scope — M2 (ADR-005, ADR-006).
Правило порядка: сетевая поверхность записи включается только вместе с этим модулем.
"""
+13
View File
@@ -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 и журнал)")
+64
View File
@@ -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"))
+1
View File
@@ -0,0 +1 @@
"""Приём заявок: проверка по версии формы из релиза, запись заявки и outbox в одной транзакции — M2 (ADR-003)."""
+22
View File
@@ -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)

Some files were not shown because too many files have changed in this diff Show More