Init Project Flexly CMS
This commit is contained in:
+10
@@ -0,0 +1,10 @@
|
||||
__pycache__/
|
||||
*.pyc
|
||||
.venv/
|
||||
dist/
|
||||
build/
|
||||
*.egg-info/
|
||||
.engine/
|
||||
*.sqlite3
|
||||
.pytest_cache/
|
||||
.ruff_cache/
|
||||
+10
@@ -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"]
|
||||
@@ -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
|
||||
@@ -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).
|
||||
@@ -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, объём резко вырастет. Вертикальные срезы и строгие контракты позволят сохранить достоинства архитектуры и избежать ненужных затрат.
|
||||
@@ -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. Юридическая часть по ПД (формулировки согласия, сроки хранения, место размещения сервера) остаётся за владельцем сайта и его юристом.
|
||||
@@ -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. Название проекта.
|
||||
@@ -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: Боты для заявок, записи, напоминаний и поддержки.
|
||||
---
|
||||
Бот принимает обращения, задаёт уточняющие вопросы и передаёт задачу менеджеру.
|
||||
@@ -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}}
|
||||
@@ -0,0 +1,3 @@
|
||||
items:
|
||||
- {label: Политика ПД, page: privacy}
|
||||
- {label: Контакты, page: contacts}
|
||||
@@ -0,0 +1,4 @@
|
||||
items:
|
||||
- {label: Услуги, page: services/index}
|
||||
- {label: Проекты, page: cases/index, enabled: false, note: Исключено на старте — нет согласий и данных}
|
||||
- {label: Контакты, page: contacts}
|
||||
@@ -0,0 +1,2 @@
|
||||
title: Корень
|
||||
layout: default
|
||||
@@ -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: Черновик}}
|
||||
---
|
||||
@@ -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: Оставить заявку}
|
||||
---
|
||||
@@ -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
|
||||
---
|
||||
@@ -0,0 +1 @@
|
||||
- {from: /uslugi/, to: /services/}
|
||||
@@ -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}
|
||||
@@ -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"
|
||||
@@ -0,0 +1,3 @@
|
||||
"""Site Engine: сайты из Markdown + YAML, layouts и fragments."""
|
||||
|
||||
__version__ = "0.1.0"
|
||||
@@ -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>
|
||||
@@ -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()
|
||||
@@ -0,0 +1 @@
|
||||
"""Ядро: модели, реестр, валидация, разрешение значений, рендер, сборка."""
|
||||
@@ -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],
|
||||
)
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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")
|
||||
@@ -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
|
||||
@@ -0,0 +1 @@
|
||||
"""SQLite через SQLAlchemy 2: служебные данные (ADR-001). Не тестировалось в песочнице без сети."""
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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):
|
||||
"""Путь выходит за корень сайта или содержит недопустимые элементы."""
|
||||
@@ -0,0 +1 @@
|
||||
"""MCP-сервер для агентов (M3)."""
|
||||
@@ -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")
|
||||
@@ -0,0 +1 @@
|
||||
"""Разбор файлов сайта: YAML, front matter, Markdown."""
|
||||
@@ -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}"
|
||||
@@ -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 ""))
|
||||
@@ -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
|
||||
)
|
||||
@@ -0,0 +1 @@
|
||||
"""Сервисный слой: единая точка для админки, MCP и CLI (принцип 2 ТЗ)."""
|
||||
@@ -0,0 +1,4 @@
|
||||
"""Вход, роли owner/developer/editor, токены агентов со scope — M2 (ADR-005, ADR-006).
|
||||
|
||||
Правило порядка: сетевая поверхность записи включается только вместе с этим модулем.
|
||||
"""
|
||||
@@ -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 и журнал)")
|
||||
@@ -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"))
|
||||
@@ -0,0 +1 @@
|
||||
"""Приём заявок: проверка по версии формы из релиза, запись заявки и outbox в одной транзакции — M2 (ADR-003)."""
|
||||
@@ -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
Reference in New Issue
Block a user