# ТЗ: движок сайтов на Markdown + YAML и фрагментах *Черновик v0.1 · 6 ноября 2026 · на ревью · рабочее название проекта пока не задано* ## Что просим проверить на ревью 1. Источник истины: файлы (md + yaml), SQLite только как индекс и служебные данные (разделы 2, 13). 2. Модель Layout / Fragment / Block, привязки и запросы (разделы 3–4). 3. Расширения модели по итогам карты сайта-примера (раздел 7.4) и правила контента (7.5). 4. Состав MVP-набора фрагментов (раздел 8.2). 5. Права агента и набор MCP-инструментов (разделы 11–12). 6. Этапы и открытые вопросы (разделы 15–16). ## Содержание 1. Цели и границы 2. Принципы архитектуры 3. Модель сущностей 4. Форматы файлов 5. Структура сайта и маршрутизация 6. Сборка, превью и публикация 7. Опорный пример: студия ботов, AI-систем и автоматизаций 8. Базовый набор фрагментов 9. Формы и заявки 10. Админка (FastAPI + htmx) 11. Роли, права и безопасность 12. MCP-сервер 13. Данные в SQLite (SQLAlchemy) 14. Нефункциональные требования 15. Этапы 16. Открытые вопросы ## 1. Цели и границы Самохостимый движок, в котором сайт — это каталог файлов (Markdown + YAML), а страницы собираются из **layouts** и **fragments** (строительных блоков в духе Liferay). С движком одинаково удобно работать человеку (админка), агенту (MCP) и разработчику (git, CLI). **Задачи v1** - Контент, структура и шаблоны хранятся в файлах (md + yaml); SQLite хранит индекс и служебные данные. - Страница = layout + дерево блоков; блок = экземпляр фрагмента со схемой полей. - Типизированные коллекции контента (кейсы, продукты, услуги и т.д.) со списками, страницами записей, связями и таксономиями. - Многостраничные сайты: разделы, меню, хлебные крошки, пагинация, редиректы, заготовка под мультиязычность. - Статическая сборка и динамическое превью, публикация атомарной заменой каталога. - Админка на FastAPI + htmx; MCP-сервер для агентов с правами и валидацией. - Новые фрагменты и коллекции добавляются файлами, без правки ядра. **Вне v1:** визуальный drag-and-drop прямо по странице, мультитенантность, e-commerce и платежи, личные кабинеты посетителей, комментарии. **Стек:** Python 3.12+, FastAPI, SQLAlchemy 2 + SQLite (WAL), Alembic, Jinja2, pydantic v2, YAML (только safe load), markdown-it-py, Pillow, MCP Python SDK; в админке htmx (+ SortableJS, EasyMDE). Node-сборки нет. ## 2. Принципы архитектуры 1. **Файлы — источник истины.** БД перестраивается командой `reindex`; исключение — служебные таблицы (пользователи, токены, аудит, заявки с форм). 2. **Один сервисный слой.** Админка, MCP и CLI вызывают одни и те же сервисы, поэтому права, валидация и аудит едины. 3. **Всё, что пишется, проходит схему.** Фрагменты и коллекции описаны схемами; невалидное не сохраняется и не публикуется. 4. **Стабильные ID блоков.** Блок адресуется по `id`, а не по индексу, поэтому страницу безопасно патчить параллельно (человек и агент). 5. **Статика по умолчанию.** Динамика только там, где без неё нельзя: формы, поиск, превью. 6. **Безопасность по умолчанию.** Шаблоны сайта рендерятся в sandbox, права разделены по ролям (раздел 11). 7. **Детерминированная сериализация.** Порядок ключей и форматирование YAML фиксированы, чтобы диффы в git были читаемыми. 8. **Расширение файлами.** Фрагмент, layout или коллекция — это папка или файл, а не код ядра. ## 3. Модель сущностей | Сущность | Что это | Где хранится | |---|---|---| | Site | Настройки сайта: домены, локали, тема, умолчания | `site.yaml` | | Page | Страница, собранная вручную из блоков | `pages/**/*.md` или `*.yaml` | | Layout | Каркас страницы: HTML-оболочка + регионы | `layouts//` | | Fragment | Блок: шаблон + схема полей + стили/скрипты | `fragments/<категория>//` | | Block | Экземпляр фрагмента на странице | внутри page или display template | | Collection | Тип контента со схемой (cases, products...) | `collections/.yaml` | | Entry | Запись коллекции | `content//.md` | | Display template | Как запись коллекции превращается в страницу | `display/.yaml` | | Taxonomy | Словарь терминов (технологии, отрасли, теги) | коллекция с `kind: taxonomy` | | Menu | Навигация | `menus/.yaml` | | Data | Произвольные данные (цены, команда, реквизиты) | `data/*.yaml` | | Form | Определение формы обратной связи | `forms/.yaml` | | Asset | Изображения и файлы | `assets/` | ### 3.1 Блок и дерево композиции Поля блока: `id` (короткий стабильный, например `b_7k2m`), `fragment`, `props`, `slots` (именованные списки вложенных блоков), опционально `hidden`, `anchor`, `visibility` (по локали и датам). Layout объявляет **регионы**, фрагмент объявляет **слоты**; и то и другое — упорядоченные списки блоков. Фрагмент может ограничивать допустимых детей (`allow`), максимальную глубину вложенности задаёт ядро (по умолчанию 4). Значения `props` бывают четырёх видов: литерал; привязка `{bind: путь}`; ссылка на страницу или запись `{page: slug}` / `{entry: коллекция/slug}`; запрос к коллекции `{collection: ...}` (см. 4.8). ## 4. Форматы файлов ### 4.1 Структура каталога сайта ``` site/ site.yaml redirects.yaml pages/ # ручные страницы; путь файла = URL index.md about.md services/ _section.yaml # настройки раздела: layout, меню, сортировка index.md content/ # записи коллекций cases/clinic-crm.md products/ collections/ # схемы коллекций display/ # шаблоны отображения записей layouts/ fragments/ menus/ forms/ data/ assets/ ``` ### 4.2 site.yaml ```yaml schema: 1 name: Acme Dev base_url: https://acme.example default_locale: ru locales: [ru, en] theme: tokens: color.primary: '#0b5fff' font.body: 'Inter, system-ui, sans-serif' space.section: 4rem defaults: layout: default seo: {title_suffix: ' — Acme Dev'} menus: {main: main, footer: footer} ``` Фрагменты используют токены темы как CSS-переменные (`var(--color-primary)`), а не зашитые значения: смена оформления не требует правки фрагментов. ### 4.3 Layout ```yaml # layouts/default/layout.yaml id: default name: Основной extends: base # необязательно: наследование оболочки regions: - {id: header, fixed: [{fragment: site_header}]} # закреплённые блоки - {id: main, allow: [section, hero, richtext, 'collection_*']} - {id: footer, fixed: [{fragment: site_footer}]} ``` ```jinja {# layouts/default/layout.html.j2 #} {{ seo_head() }}{{ assets_head() }} {{ region('header') }}
{{ region('main') }}
{{ region('footer') }} {{ assets_body() }} ``` `fixed`-блоки принадлежат layout и не редактируются на странице; регион с `allow` ограничивает набор фрагментов, которые можно туда ставить. ### 4.4 Фрагмент ```yaml # fragments/marketing/hero/fragment.yaml id: hero name: Hero-баннер category: marketing version: 1 fields: - {key: title, type: text, required: true, max: 120} - {key: subtitle, type: markdown, inline: true} - {key: image, type: asset, accept: [image]} - {key: cta, type: link} - {key: variant, type: select, options: [light, dark, split], default: light} slots: {} preview: {title: Заголовок страницы, variant: dark} ``` ```jinja {# fragments/marketing/hero/template.html.j2 #}

{{ props.title }}

{% if props.subtitle %}
{{ props.subtitle|md_inline }}
{% endif %} {% if props.cta %}{{ props.cta.label }}{% endif %}
``` **Состав папки фрагмента:** `fragment.yaml` (манифест), `template.html.j2`, необязательные `style.css` и `script.js`, `preview.yaml` (данные для превью в админке). **Типы полей:** `text`, `textarea`, `markdown`, `number`, `boolean`, `select`, `multiselect`, `date`, `datetime`, `color`, `icon`, `slug`, `link` (страница, запись или URL + подпись + target), `asset` (изображение или файл), `ref` и `refs` (ссылки на записи коллекций), `group` (вложенный объект), `list` (повторяемая группа полей), `query` (запрос к коллекции), `json` (только для разработчиков). **Контекст шаблона:** `props`, `slots`, `page`, `site`, `entry` (на страницах записей), `block` (id, anchor), хелперы `href`, `md`, `md_inline`, `asset_url`, `image` (адаптивные варианты), `t` (строки интерфейса). **CSS и JS:** подключаются на страницу один раз на фрагмент (дедупликация), CSS изолируется префиксом `.f-`; при сборке всё собирается в хешированные бандлы. Фрагменты не должны зависеть от внешних CDN. **Версии:** при несовместимом изменении схемы фрагмента увеличивается `version`, рядом кладётся миграция `migrations/1_to_2.py` (или декларативная карта переименований полей); `validate` и админка показывают блоки, требующие миграции. ### 4.5 Страница ```markdown --- schema: 1 title: Заказная разработка layout: default status: published # draft | published | scheduled | archived seo: description: Разработка ПО под ключ og_image: assets/og/services.png regions: main: - id: b_7k2m fragment: hero props: title: Заказная разработка ПО variant: dark cta: {page: contacts, label: Обсудить проект} - id: b_9xq1 fragment: collection_list props: source: {collection: services, sort: order, limit: 6} card: service_card - id: b_3d8f fragment: richtext props: {source: body} --- Основной текст страницы в Markdown. Он доступен как `page.body` и выводится фрагментом `richtext` с `source: body`. ``` Если у страницы есть тело, но ни один блок его не использует, `validate` выдаёт предупреждение. Страницы без текста могут быть чистыми `.yaml`-файлами с теми же полями. ### 4.6 Коллекция и запись ```yaml # collections/cases.yaml id: cases name: Кейсы route: /cases/{slug}/ list_page: /cases/ display: cases # display/cases.yaml sort: -date body: markdown # тело записи — Markdown fields: - {key: title, type: text, required: true} - {key: summary, type: textarea} - key: client type: group fields: - {key: name, type: text} - {key: industry, type: ref, to: industries} - {key: confidential, type: boolean} - {key: services, type: refs, to: services} - {key: products, type: refs, to: products} - {key: tech, type: refs, to: technologies} - key: metrics type: list fields: [{key: label, type: text}, {key: value, type: text}] - {key: cover, type: asset} - {key: date, type: date} ``` ```markdown --- title: CRM для сети клиник slug: clinic-crm status: published client: {name: Клиника+, industry: healthcare} services: [web-development, integrations] tech: [python, postgresql, react] metrics: - {label: Сокращение времени записи, value: '−40%'} cover: assets/cases/clinic.webp date: 2026-03-12 --- ## Задача Текст кейса в Markdown... ``` Коллекции с `kind: taxonomy` (технологии, отрасли, теги) — это те же коллекции, но их записи обычно без тела; для них движок сам строит страницы терминов (`/cases/tag/python/`) по настройке `taxonomy_pages`. ### 4.7 Display template: запись → страница ```yaml # display/cases.yaml layout: default seo: title: '{{ entry.title }}' description: '{{ entry.summary }}' regions: main: - fragment: entry_header props: {title: {bind: entry.title}, meta: [{bind: entry.client.name}, {bind: entry.date}]} - fragment: entry_facts props: {items: {bind: entry.metrics}} - fragment: richtext props: {source: entry.body} - fragment: related_entries props: source: {collection: cases, related_to: entry, by: [services, tech], limit: 3} - fragment: cta_banner props: {title: Обсудим ваш проект?, cta: {page: contacts, label: Связаться}} overrides: allow # запись может дополнять или заменять блоки своим regions ``` Когда у записи в front matter есть собственный `regions`, он объединяется с шаблоном по id региона в режиме `append`, `prepend` или `replace` (`regions_mode`, по умолчанию `append`). Так типовая страница остаётся типовой, а особый случай получает уникальные блоки без отдельного шаблона. ### 4.8 Привязки и запросы **Привязка** `{bind: путь}` читает значение из контекста: `entry`, `page`, `site`, `data.<файл>`, `params` (параметры пагинации и фильтров). Ссылки `{page: slug}` и `{entry: коллекция/слаг}` при сборке превращаются в URL с учётом локали; битая ссылка — ошибка сборки. **Запрос** (`type: query` или `source:`): | Ключ | Назначение | |---|---| | `collection` | коллекция-источник | | `where` | условия: `eq`, `in`, `contains`, `gte`, `lte`, `not` по полям записи, в том числе по `refs` | | `sort`, `limit`, `offset` | порядок и срез (`-date` — убывание) | | `paginate` | размер страницы; движок генерирует `/page/2/` и т.д. | | `ids` | ручной выбор записей в нужном порядке | | `related_to`, `by` | похожие записи по общим значениям связей | | `locale` | локаль выборки (по умолчанию текущая) | Запросы выполняются при сборке по индексу в SQLite. Зависимости (какая страница читает какие записи) пишутся в граф, чтобы инкрементальная сборка пересобирала только затронутое. ## 5. Структура сайта и маршрутизация ### 5.1 Маршруты - URL = путь файла в `pages/`: `pages/about.md` → `/about/`, `index.md` → корень раздела. Если имя файла не совпадает с нужным URL (`pages/scenario-legal.md` → `/scenarios/legal/`), адрес задаётся полем `route:` в front matter. - Записи коллекций получают URL из `route` в схеме коллекции, список — из `list_page`. - Служебные маршруты генерирует движок: `/sitemap.xml`, `/robots.txt`, `/404.html`, страницы пагинации, страницы терминов таксономий, `/feed.xml` (по настройке). - Два источника на один URL — ошибка сборки. Слаги латиницей; кириллица в slug автоматически транслитерируется. - Смена slug записывает старый адрес в историю, и редирект создаётся автоматически; ручные правила лежат в `redirects.yaml`. ### 5.2 Разделы Папка с файлом `_section.yaml` — раздел. Он задаёт значения по умолчанию для вложенных страниц и порядок детей: ```yaml # pages/services/_section.yaml title: Услуги layout: default nav: {menu: main, label: Услуги, order: 10} children_sort: order defaults: seo: {title_suffix: ' — Acme'} plan: {priority: P1} ``` Хлебные крошки строятся из дерева разделов и переопределяются полем `breadcrumb:` страницы. ### 5.3 Меню Меню — файлы `menus/*.yaml` плюс пункты, которые страницы объявляют сами (`nav: {menu: footer, label: ..., order: ...}`). Пункт может быть ссылкой на страницу, запись или внешний URL и поддерживает поля `enabled`, `requires` (условия показа, см. 7.4) и `note`. Выключенный пункт остаётся в файле, но не попадает в HTML: это удобно, когда раздел временно исключён. ### 5.4 Типовые структуры | Структура | Как реализуется | |---|---| | Лендинг из секций | Страница из блоков `section`, якоря через `anchor`, меню по якорям | | Обзор + дочерние страницы | Раздел, а в обзоре `collection_list` с `source: {children: current}` или коллекция | | Каталог: список → карточка | Коллекция + display template, пагинация и фильтры по таксономиям | | Запись с подстраницами | Подмаршруты записи (`/academy/<курс>/program/`), каждый со своим display template | | Юридические документы | Layout `legal`: оглавление, дата и версия редакции | | Служебные страницы | 404, «спасибо» после формы, страница превью, печатная версия | | Несколько языков | Поле `locales`, переводы рядом (`about.en.md`), связь через `translations`, `hreflang` | ### 5.5 Границы v1 Один запуск движка обслуживает один сайт (каталог `site/`). Каталог `sites/<имя>/` для нескольких сайтов закладываем в структуру путей, но не реализуем. Мультиязычность в v1 ограничена моделью данных (`locale` у страниц и записей) и генерацией `hreflang`; интерфейс переводов в админке откладываем. ## 6. Сборка, превью и публикация ### 6.1 Конвейер сборки 1. **load** — чтение файлов, парсинг YAML и Markdown, нормализация. 2. **validate** — схемы, ссылки, ассеты, уникальность маршрутов, правила сайта (см. 6.5). 3. **index** — запись страниц, записей и графа ссылок в SQLite. 4. **resolve** — выполнение запросов и привязок, сборка меню и хлебных крошек. 5. **render** — Jinja в sandbox, HTML каждой страницы. 6. **postprocess** — бандлы CSS/JS с хешами, варианты изображений (webp, srcset), `sitemap.xml`, поисковый индекс. 7. **publish** — запись в `dist//` и атомарное переключение символической ссылки `current`; последние N сборок хранятся для отката. ### 6.2 Инкрементальность и скорость Граф зависимостей (какая страница читает какие записи, фрагменты и данные) позволяет пересобирать только затронутое. Ориентир для v1: полная сборка сайта до 500 страниц менее 10 секунд, правка одной страницы менее 1 секунды. ### 6.3 Превью Динамический рендер одной страницы из рабочего каталога без записи в `dist`. Показывает черновики и использует те же CSS и JS, что и сборка. В админке открывается во фрейме; для внешних согласований выдаётся ссылка с токеном и сроком жизни. ### 6.4 Статусы и история `status`: `draft` → `review` → `published` (плюс `scheduled` с датой и `archived`). В публикуемую сборку попадают только `published` и `scheduled`, чей срок наступил (проверка по расписанию). История изменений: если каталог сайта — git-репозиторий, каждое сохранение коммитится с автором (человек или агент); изменения агента могут идти в отдельную ветку `agent/*` и вливаться человеком. Без git используются ревизии в таблице `revisions`. ### 6.5 Проверки `validate` Ошибки блокируют публикацию, предупреждения — нет. - **Ошибки:** невалидный YAML; поля не по схеме; неизвестный фрагмент или версия; фрагмент не разрешён в регионе; дубли `id` блоков; битые ссылки на страницы, записи и ассеты; конфликты маршрутов; нарушение правил сайта (см. 7.5). - **Предупреждения:** тело страницы не использовано блоком; нет `seo.description`; у изображения нет `alt`; ассеты без ссылок; блоки на устаревшей версии фрагмента; страницы без входящих ссылок. ### 6.6 Поиск Варианты: статический JSON-индекс с клиентским поиском (без сервера) либо серверный поиск на SQLite FTS5. Решение вынесено в открытые вопросы. ## 7. Опорный пример: студия ботов, AI-систем и автоматизаций Пример взят из карты сайта `SiteMap.md` (черновик v0.1): студия Telegram-ботов, AI-систем и автоматизаций с Академией курсов. Раздел показывает, как реальная карта раскладывается по модели ТЗ и что в модели пришлось дополнить. ### 7.1 Что ложится в модель как есть - Дерево страниц → `pages/` и `_section.yaml`; приоритеты P1/P2 переносятся в поле `plan`. - Шапка и футер → `menus/main.yaml`, `menus/footer.yaml` и фрагменты `site_header`, `site_footer`. - Каркас главной из восьми блоков → `pages/index.md` с блоками в регионе `main`. - Колонки «Задача страницы» и «Куда ведёт дальше» → поля страницы `goal` и `next` (видны в админке, на сайт не выводятся; агент использует их для проверки текстов). ### 7.2 Коллекции | Коллекция | Записи | Маршрут | Заметки | |---|---|---|---| | `services` | bots, ai, automation | `/services/{slug}/` | Три записи, общий display template, у каждой свои блоки через `overrides` | | `scenarios` | legal, real-estate, services | `/scenarios/{slug}/` | Типовые сценарии, а не кейсы: схема без `metrics`, обязательный блок-дисклеймер | | `courses` | по мере появления | `/academy/{slug}/` | Пустая коллекция допустима, поля в 7.6 | | `cases` | — | `/cases/{slug}/` | Схема есть, раздел выключен: `features.cases: false` | | `posts` | — | `/blog/{slug}/` | Схема есть, раздел выключен: `features.blog: false` | Ручные страницы: главная, о компании, безопасность и данные, контакты, заявка, политика ПД, оферта, страница «спасибо». ### 7.3 Каркас главной | № | Блок карты | Фрагмент | Особенности | |---|---|---|---| | 1 | Hero | `hero` | CTA: Telegram и заявка | | 2 | Три направления | `collection_list` (`services`, карточка `direction_card`) | Данные из коллекции, дублей нет | | 3 | Живые примеры | `live_examples` | `hidden`, `requires: [feature.demo]` | | 4 | Что уже работает | `feature_grid` | Плашки со сроками, данные `verified` | | 5 | Цифры | `stats` | `hidden`, `requires: [data.stats]` | | 6 | Как идёт работа | `steps` | 5 шагов | | 7 | О нас | `about_teaser` | Ссылка на `/about/` | | 8 | Финальный CTA | `cta_banner` | Telegram и форма | Исключённые блоки остаются в файле с прежней нумерацией (`id` стабильны), чтобы вернуть их одной правкой: ```yaml - id: b_demo fragment: live_examples hidden: true note: Исключён на старте — нет демо requires: [feature.demo] - id: b_stats fragment: stats hidden: true note: Исключён на старте — нет подтверждённых цифр requires: [data.stats] ``` ### 7.4 Что добавляем в модель по итогам карты | Что в карте | Что добавляем | |---|---| | Приоритеты P1/P2, пометки ➕ и ⛔ | Поле страницы `plan: {priority, state: planned/added/excluded/done, note, data_ready}`. Движок строит отчёт готовности сайта, он же доступен агенту через MCP | | «Исключено на старте, можно вернуть» | Флаги `features` в `site.yaml`; у блока `hidden` и `note`; у пункта меню `enabled`. Возврат — одна правка | | «Включаем, только если есть чем подтвердить» | `requires:` у блока: список ссылок на `feature.*` и `data.*`; блок рендерится, только если все они не пусты | | Имя файла не равно URL | `route:` в front matter (см. 5.1) | | «Сценарий, не кейс», без выдуманных результатов | Отдельная коллекция без `metrics`, обязательный фрагмент `disclaimer` и правило сайта (7.5) | | «Заявка → Благодарность» | У формы `success.page`; страница «спасибо» добавляется в карту | | «Оплата / запись» на курс | CTA-тип `enroll`: внешняя платёжная страница или форма записи; своя оплата вне v1 | | 152-ФЗ и политика ПД | Тип поля формы `consent` (чекбокс, ссылка на политику, версия редакции); факт согласия хранится вместе с заявкой | | «Ждёт данных о курсах» | Пустое состояние `collection_list` (`empty: hide` или `message`); страница `status: draft` с `plan.data_ready: false` | | Telegram как основной канал | Секция `contacts` в `site.yaml` и CTA-тип `contact`; смена ника правится в одном месте; уведомления о заявках уходят в Telegram | | Реквизиты, год и название в футере | `data/company.yaml` и фрагмент `requisites`; год подставляет сборка | ### 7.5 Правила контента сайта Договорённости из карты (без выдуманных результатов, согласие на обработку ПД) превращаются в проверяемые правила в `site.yaml`: ```yaml rules: - {id: scenario-disclaimer, collection: scenarios, require_fragment: disclaimer, level: error} - {id: verified-numbers, fragments: [stats, feature_grid], require: verified, level: warning} - {id: form-consent, forms: all, require_field: consent, level: error} ``` Правила выполняет `validate`; агент получает их через MCP до правки текстов и не нарушает по неведению. ### 7.6 Коллекция courses (набросок) ```yaml id: courses name: Курсы route: /academy/{slug}/ list_page: /academy/ display: courses body: markdown fields: - {key: title, type: text, required: true} - {key: summary, type: textarea} - {key: audience, type: text} - {key: format, type: select, options: [self-paced, cohort, live]} - {key: duration, type: text} - {key: starts, type: date} - {key: outcomes, type: list, fields: [{key: item, type: text}]} - key: program type: list fields: [{key: module, type: text}, {key: lessons, type: textarea}] - key: price type: group fields: [{key: amount, type: number}, {key: currency, type: text}, {key: note, type: text}] - key: enroll type: group fields: [{key: kind, type: select, options: [link, form]}, {key: url, type: text}] ``` Display template курса: `entry_header` → `feature_grid` (чему научится) → `course_program` → `richtext` → `enroll_block` (цена и запись) → `faq` → ссылка на оферту. Точный состав согласуем, когда появятся данные о курсах. ### 7.7 Что стоит уточнить в самой карте - Нет страницы «спасибо», хотя в таблице задач заявка ведёт на «Благодарность». - Страница курса отсылает к «шаблону ниже», но в файле его нет. - «Сценарии» отмечены P1, но пункта в шапке нет: решить, откуда на них ведут ссылки (главная и страницы услуг?). - «Типовые сроки» в блоке «Что уже работает» — тоже числа: нужен источник или пометка «ориентировочно». ## 8. Базовый набор фрагментов ### 8.1 Общие свойства блока Эти поля есть у любого блока независимо от фрагмента, во фрагментах их дублировать не нужно: `id`, `anchor`, `hidden`, `note`, `requires`, `visibility` (локали, даты) и `style` (отступы, фон из токенов темы, ширина контейнера). ### 8.2 Каталог (этап: MVP — первая версия, v1 — следом, позже — по потребности) **Структура и заголовки** | Фрагмент | Назначение | Ключевые поля | Этап | |---|---|---|---| | `section` | Контейнер секции со слотом `content` | фон, ширина, отступы | MVP | | `columns` | 2–4 колонки, слот на колонку | число колонок, пропорции, выравнивание | MVP | | `hero` | Первый экран | title, subtitle, image, actions, variant | MVP | | `page_header` | Заголовок внутренней страницы | title, lead, breadcrumbs | MVP | | `divider` | Разделитель или отступ | тип, высота | v1 | **Контент** | Фрагмент | Назначение | Ключевые поля | Этап | |---|---|---|---| | `richtext` | Текст в Markdown | source (`body`, `entry.body` или текст) | MVP | | `image` | Изображение | asset, alt, caption | MVP | | `disclaimer` | Пометка или оговорка | variant (info, warning), text | MVP | | `legal_text` | Юридический текст | оглавление, дата и версия редакции | MVP | | `chat_demo` | Пример диалога в мессенджере (статичный) | messages (from: user или bot), buttons | v1 | | `gallery`, `video_embed`, `quote`, `code_block`, `table` | Типовые контентные блоки | по назначению | v1 | **Карточки и списки** | Фрагмент | Назначение | Ключевые поля | Этап | |---|---|---|---| | `card_grid` | Сетка карточек | items: title, text, link, icon, badge | MVP | | `feature_grid` | Преимущества или возможности | items: title, text, icon, badge, verified | MVP | | `steps` | Этапы работы | items: title, text | MVP | | `faq` | Вопросы и ответы (разметка FAQ для поиска) | items: q, a | MVP | | `stats` | Цифры | items: value, label, verified | v1 | | `logo_cloud`, `team_grid`, `testimonials`, `pricing_table` | Клиенты, команда, отзывы, тарифы | по назначению | v1 | | `timeline`, `comparison_table` | История и сравнение | по назначению | позже | **Коллекции** | Фрагмент | Назначение | Ключевые поля | Этап | |---|---|---|---| | `collection_list` | Список записей | source, card, layout, paginate, filters, empty | MVP | | `entry_header` | Шапка страницы записи | title, meta, tags | MVP | | `related_entries` | Похожие записи | source (`related_to`, `by`), limit | v1 | | `collection_featured` | Ручная подборка записей | ids, card | v1 | | `entry_facts` | Ключевые факты записи | items: label, value | v1 | | `entry_nav` | Предыдущая и следующая запись | collection | v1 | | `course_program` | Программа курса | modules | v1 | | `enroll_block` | Цена и запись на курс | price, enroll | v1 | **Конверсия и контакты** | Фрагмент | Назначение | Ключевые поля | Этап | |---|---|---|---| | `cta_banner` | Призыв к действию | title, text, actions (тип: link, contact, form, enroll) | MVP | | `form` | Форма из `forms/.yaml` | form | MVP | | `contact_block` | Способы связи | берёт `site.contacts` | MVP | | `requisites` | Реквизиты компании | берёт `data.company` | MVP | **Навигация и глобальное** | Фрагмент | Назначение | Ключевые поля | Этап | |---|---|---|---| | `site_header`, `site_footer` | Шапка и футер | menu, action, источники данных | MVP | | `nav_menu` | Меню по id | menu, orientation | MVP | | `breadcrumbs` | Хлебные крошки | — | MVP | | `pagination` | Постраничная навигация | используется списками | MVP | | `toc`, `announcement_bar`, `cookie_notice` | Оглавление, плашка, уведомление о cookie | по назначению | v1 | | `search_box`, `language_switcher` | Поиск и язык | по назначению | позже | | `embed_html` | Произвольный HTML в sandbox-iframe | code | позже, только роль developer | Итого MVP — 22 фрагмента: хватает на сайт-пример (раздел 7) без ручного HTML. Часть сайта-примера (`direction_card`, `about_teaser`, `live_examples`) — это варианты карточек и тематические обёртки поверх базовых; их добавляем как фрагменты сайта, а не ядра. ### 8.3 Требования к любому фрагменту 1. Манифест со схемой полей, `preview.yaml` с тестовыми данными, версия. 2. Семантическая разметка, `alt` у изображений, управляемый фокус, контраст из токенов темы. 3. Только токены темы и классы `.f-`, без внешних CDN и без инлайновых обработчиков. 4. Пустые и граничные данные не ломают вёрстку (`hidden_if_empty`, значения по умолчанию). 5. Автоматический snapshot-тест рендера на `preview.yaml`. ## 9. Формы и заявки ### 9.1 Определение формы ```yaml # forms/consultation.yaml id: consultation title: Заявка на разговор fields: - {key: name, type: text, label: Имя, required: true} - {key: contact, type: text, label: Telegram или телефон, required: true} - {key: task, type: textarea, label: Расскажите о задаче, hint: Свободная форма, ТЗ не нужно} - {key: consent, type: consent, policy: privacy} success: {page: consultation/thanks} notify: - {kind: telegram, chat: '${TG_CHAT_ID}'} - {kind: email, to: ['${LEADS_EMAIL}']} antispam: {honeypot: true, rate_limit: '5/hour'} store: {retention_days: 365} ``` Секреты (токен бота, адреса) берутся из переменных окружения, в файлах сайта их нет. ### 9.2 Обработка - Форма — единственная динамическая часть статического сайта: `POST /forms/{id}` в FastAPI. Без JS это обычный POST с редиректом на `success.page`; htmx или небольшой скрипт делает отправку без перезагрузки. - Валидация по схеме формы, запись в таблицу `form_submissions` вместе со снимком согласия (время, версия политики), уведомления через очередь с повторными попытками. - Защита: honeypot, лимит запросов, проверка размера, экранирование при показе в админке. ### 9.3 Персональные данные Заявки содержат ПД, поэтому: доступ к ним только у ролей с правом `submissions:read`, срок хранения и автоматическое удаление, экспорт и удаление по запросу, аудит просмотров. Требования закона к хранению и размещению сервера определяет владелец сайта вместе с юристом; движок даёт технические средства (согласие с версией, срок хранения, удаление, журнал). ### 9.4 Админка заявок Список со статусами (`new`, `processed`, `spam`), поиск, заметки, экспорт в CSV. ## 10. Админка (FastAPI + htmx) ### 10.1 Экраны | Экран | Что делает | |---|---| | Обзор | Отчёт готовности по `plan`: что готово, что ждёт данных, что исключено; ошибки и предупреждения `validate`; последние сборки | | Страницы | Дерево разделов, статусы, фильтры, создание и перенос страниц | | Редактор страницы | Регионы и блоки: добавить, удалить, переместить; форма блока строится из схемы фрагмента; превью во фрейме | | Коллекции | Таблица записей с фильтрами; форма записи; Markdown-редактор | | Фрагменты и layouts | Каталог с превью и схемой полей; правка кода только у роли developer | | Меню и данные | Редактирование `menus/*.yaml` и `data/*.yaml` формами по схемам | | Медиа | Загрузка, подписи (`alt`), поиск неиспользуемых файлов | | Формы и заявки | Список заявок, статусы, экспорт | | Доступ | Пользователи, роли, токены агентов | | Журнал и сборки | Аудит, история публикаций, откат | ### 10.2 Технические решения - Серверный рендер Jinja-партиалами; htmx заменяет регион страницы или форму блока, JS-сборки нет. SortableJS — перенос блоков, EasyMDE — Markdown. - Формы блоков генерируются из схемы фрагмента макросами по типам полей; ошибки валидации возвращаются в ту же форму. - Конфликты редактирования: при открытии запоминается хеш файла, при сохранении он сверяется; при расхождении показывается diff и выбор действия (так человек и агент не затирают друг друга). - Сессионная cookie, CSRF-токен через `hx-headers`, лимит попыток входа. - Два окружения Jinja: админское и сайтовое (sandbox). Шаблоны сайта не получают доступа к объектам админки. ## 11. Роли, права и безопасность ### 11.1 Роли | Действие | owner | developer | editor | reviewer | agent | |---|---|---|---|---|---| | Страницы, записи, данные, меню | да | да | да | нет | по scope | | Фрагменты, layouts, схемы коллекций | да | да | нет | нет | нет | | Публикация и откат | да | да | да | нет | только если разрешено владельцем | | Согласование и комментарии | да | да | да | да | нет | | Заявки (ПД) | да | нет | по праву `submissions:read` | нет | нет | | Пользователи, токены, настройки | да | нет | нет | нет | нет | Токен агента несёт scope (например `read`, `content:write`, `publish`), срок жизни и ограничение по разделам сайта. По умолчанию агент пишет в `draft` или в ветку `agent/*`, публикует человек. ### 11.2 Меры безопасности - Шаблоны сайта рендерятся в Jinja `SandboxedEnvironment`, доступны только разрешённые фильтры и функции; шаблоны читаются только из каталога сайта. - Raw HTML в Markdown выключен по умолчанию; допустимые теги — allowlist, вывод проходит санитизацию. `embed_html` и произвольные скрипты — только роль developer. - YAML читается только безопасным загрузчиком, с лимитами размера, глубины и числа алиасов. - Загрузки: проверка типа по содержимому, лимит размера, санитизация SVG, запрет исполняемых типов; защита от выхода за каталог (path traversal). - Заголовки: CSP, `X-Content-Type-Options`, `Referrer-Policy`; CSRF для админки; лимиты на вход, формы и MCP. - Токены хранятся только в виде хеша; секреты — в переменных окружения; все записи и просмотр заявок попадают в `audit_log` с актором (человек или агент). - Резервные копии: каталог сайта (git или архив) и файл SQLite с проверкой восстановления. ## 12. MCP-сервер Транспорт: Streamable HTTP внутри того же FastAPI-приложения; авторизация Bearer-токеном со scope. Инструменты вызывают сервисный слой, поэтому права и валидация такие же, как в админке. ### 12.1 Инструменты | Группа | Инструменты | |---|---| | Чтение | `get_site_plan`, `get_rules`, `list_pages`, `get_page`, `list_collections`, `list_entries`, `get_entry`, `list_fragments`, `get_fragment_schema`, `list_layouts`, `list_menus`, `list_assets`, `search` | | Запись | `create_page`, `update_page_meta`, `add_block`, `update_block`, `move_block`, `remove_block`, `set_block_visibility`, `create_entry`, `update_entry`, `update_menu`, `update_data`, `upload_asset` | | Контроль | `validate`, `render_preview` (HTML или скриншот), `diff`, `submit_for_review`, `publish`, `list_builds`, `rollback` | ### 12.2 Принципы - Блоки адресуются по `id`, поля — по пути (`regions.main[b_7k2m].props.cta.label`); индексы позиций не используются. - Все записи принимают `dry_run` и `if_match` (хеш версии файла); при конфликте возвращается актуальная версия. - Ошибки валидации приходят структурой: путь к полю, правило, ожидаемое значение, подсказка, как исправить. - Схемы и правила сайта публикуются как MCP-ресурсы; типовые задачи («страница по брифу», «перевод страницы», «проверка текста по карте») — как MCP-промпты. - Агент не может менять фрагменты, layouts и схемы без роли developer. ## 13. Данные в SQLite (SQLAlchemy) Индексные таблицы восстанавливаются командой `reindex`; остальные хранят то, чего нет в файлах. | Таблица | Содержимое | Восстанавливается из файлов | |---|---|---| | `pages_index` | путь, маршрут, локаль, статус, layout, `plan`, front matter (JSON), хеш | да | | `entries_index` | коллекция, slug, маршрут, статус, данные (JSON), хеш | да | | `refs` | граф ссылок и зависимостей страниц от записей, фрагментов и данных | да | | `fragments_index`, `assets_index` | фрагменты (версия, схема), ассеты (размер, тип, хеш) | да | | `search_fts` | полнотекстовый индекс FTS5 | да | | `slug_history` | старые адреса для редиректов | нет | | `revisions` | ревизии, если сайт не в git | нет | | `users`, `roles`, `sessions`, `api_tokens` | доступ; токены только в виде хеша | нет | | `audit_log` | действия с актором, объектом, до и после | нет | | `form_submissions` | заявки, согласия, статусы | нет | | `build_runs` | сборки: статус, время, лог, кто запустил | нет | | `locks` | блокировки записи страниц | нет | SQLite в режиме WAL, миграции Alembic, синхронный доступ в threadpool. ## 14. Нефункциональные требования - **Производительность:** см. 6.2; отдача сайта — статика, нагрузка на FastAPI только от админки, форм и MCP. - **Надёжность:** атомарная запись файлов (временный файл и rename), атомарная публикация сборки, откат на предыдущую. - **Развёртывание:** один Docker-образ, тома `site/`, `data/` (SQLite), `dist/`; конфигурация через переменные окружения; статику отдаёт nginx или сам FastAPI. - **Доступность и SEO:** базовые фрагменты соответствуют WCAG 2.1 AA; canonical, Open Graph, `sitemap.xml`, разметка schema.org там, где применимо. - **Тестирование:** unit-тесты парсеров и схем; snapshot-тесты рендера каждого фрагмента; сквозной тест сборки сайта-примера; контрактные тесты MCP-инструментов. - **Наблюдаемость:** структурированные логи, журнал сборок, метрики времени сборки и ошибок валидации. ## 15. Этапы | Этап | Состав | |---|---| | M0. Ядро | Парсер md + yaml, схемы (pydantic из манифестов), индекс, рендер, CLI (`build`, `validate`, `serve`, `reindex`), 10 базовых фрагментов; сайт-пример как тестовый набор | | M1. Коллекции и MCP | Коллекции, display templates, запросы, меню, привязки; MCP: чтение и запись, `validate`, превью; формы и заявки | | M2. Админка | Экраны раздела 10, роли, токены, аудит, конфликты редактирования | | M3. Полный MVP-набор | Все 22 фрагмента, тема, инкрементальная сборка, публикация и откат, интеграция с git | | M4. Расширение | Поиск, мультиязычность, медиа-варианты, фрагменты v1 | | Позже | Визуальный редактор на самой странице | ## 16. Открытые вопросы 1. История изменений: git обязателен или допускаем только таблицу `revisions`? 2. Поиск: статический индекс на клиенте или FTS5 на сервере? 3. Мультиязычность: нужна в первой версии или только заложить модель? 4. Публикация: кто отдаёт `dist` (nginx или FastAPI) и где живёт сервер? 5. Формы: какие каналы уведомлений нужны сразу (Telegram, почта, webhook)? 6. Оплата курсов: внешний провайдер ссылкой или форма записи без оплаты? 7. Политика JS во фрагментах: разрешён ли собственный JS у фрагментов сайта или только из набора ядра? 8. Аутентификация админки: локальные аккаунты или внешний провайдер (SSO)? 9. Режим работы агента: прямая запись в `draft` или обязательно через ветку и согласование? 10. Название проекта.