55 KiB
ТЗ: движок сайтов на Markdown + YAML и фрагментах
Черновик v0.1 · 6 ноября 2026 · на ревью · рабочее название проекта пока не задано
Что просим проверить на ревью
- Источник истины: файлы (md + yaml), SQLite только как индекс и служебные данные (разделы 2, 13).
- Модель Layout / Fragment / Block, привязки и запросы (разделы 3–4).
- Расширения модели по итогам карты сайта-примера (раздел 7.4) и правила контента (7.5).
- Состав MVP-набора фрагментов (раздел 8.2).
- Права агента и набор MCP-инструментов (разделы 11–12).
- Этапы и открытые вопросы (разделы 15–16).
Содержание
- Цели и границы
- Принципы архитектуры
- Модель сущностей
- Форматы файлов
- Структура сайта и маршрутизация
- Сборка, превью и публикация
- Опорный пример: студия ботов, AI-систем и автоматизаций
- Базовый набор фрагментов
- Формы и заявки
- Админка (FastAPI + htmx)
- Роли, права и безопасность
- MCP-сервер
- Данные в SQLite (SQLAlchemy)
- Нефункциональные требования
- Этапы
- Открытые вопросы
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. Принципы архитектуры
- Файлы — источник истины. БД перестраивается командой
reindex; исключение — служебные таблицы (пользователи, токены, аудит, заявки с форм). - Один сервисный слой. Админка, MCP и CLI вызывают одни и те же сервисы, поэтому права, валидация и аудит едины.
- Всё, что пишется, проходит схему. Фрагменты и коллекции описаны схемами; невалидное не сохраняется и не публикуется.
- Стабильные ID блоков. Блок адресуется по
id, а не по индексу, поэтому страницу безопасно патчить параллельно (человек и агент). - Статика по умолчанию. Динамика только там, где без неё нельзя: формы, поиск, превью.
- Безопасность по умолчанию. Шаблоны сайта рендерятся в sandbox, права разделены по ролям (раздел 11).
- Детерминированная сериализация. Порядок ключей и форматирование YAML фиксированы, чтобы диффы в git были читаемыми.
- Расширение файлами. Фрагмент, 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
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
# 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}]}
{# 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 Фрагмент
# 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}
{# 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 Страница
---
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 Коллекция и запись
# 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}
---
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: запись → страница
# 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 — раздел. Он задаёт значения по умолчанию для вложенных страниц и порядок детей:
# 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 Конвейер сборки
- load — чтение файлов, парсинг YAML и Markdown, нормализация.
- validate — схемы, ссылки, ассеты, уникальность маршрутов, правила сайта (см. 6.5).
- index — запись страниц, записей и графа ссылок в SQLite.
- resolve — выполнение запросов и привязок, сборка меню и хлебных крошек.
- render — Jinja в sandbox, HTML каждой страницы.
- postprocess — бандлы CSS/JS с хешами, варианты изображений (webp, srcset),
sitemap.xml, поисковый индекс. - 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 стабильны), чтобы вернуть их одной правкой:
- 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:
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 (набросок)
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 Требования к любому фрагменту
- Манифест со схемой полей,
preview.yamlс тестовыми данными, версия. - Семантическая разметка,
altу изображений, управляемый фокус, контраст из токенов темы. - Только токены темы и классы
.f-<id>, без внешних CDN и без инлайновых обработчиков. - Пустые и граничные данные не ломают вёрстку (
hidden_if_empty, значения по умолчанию). - Автоматический snapshot-тест рендера на
preview.yaml.
9. Формы и заявки
9.1 Определение формы
# 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. Открытые вопросы
- История изменений: git обязателен или допускаем только таблицу
revisions? - Поиск: статический индекс на клиенте или FTS5 на сервере?
- Мультиязычность: нужна в первой версии или только заложить модель?
- Публикация: кто отдаёт
dist(nginx или FastAPI) и где живёт сервер? - Формы: какие каналы уведомлений нужны сразу (Telegram, почта, webhook)?
- Оплата курсов: внешний провайдер ссылкой или форма записи без оплаты?
- Политика JS во фрагментах: разрешён ли собственный JS у фрагментов сайта или только из набора ядра?
- Аутентификация админки: локальные аккаунты или внешний провайдер (SSO)?
- Режим работы агента: прямая запись в
draftили обязательно через ветку и согласование? - Название проекта.