Files
flexly-cms/docs/TZ-site-engine.md
2026-11-09 15:32:41 +03:00

55 KiB
Raw Permalink Blame History

ТЗ: движок сайтов на 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

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 Конвейер сборки

  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 стабильны), чтобы вернуть их одной правкой:

- 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 Требования к любому фрагменту

  1. Манифест со схемой полей, preview.yaml с тестовыми данными, версия.
  2. Семантическая разметка, alt у изображений, управляемый фокус, контраст из токенов темы.
  3. Только токены темы и классы .f-<id>, без внешних CDN и без инлайновых обработчиков.
  4. Пустые и граничные данные не ломают вёрстку (hidden_if_empty, значения по умолчанию).
  5. Автоматический 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. Открытые вопросы

  1. История изменений: git обязателен или допускаем только таблицу revisions?
  2. Поиск: статический индекс на клиенте или FTS5 на сервере?
  3. Мультиязычность: нужна в первой версии или только заложить модель?
  4. Публикация: кто отдаёт dist (nginx или FastAPI) и где живёт сервер?
  5. Формы: какие каналы уведомлений нужны сразу (Telegram, почта, webhook)?
  6. Оплата курсов: внешний провайдер ссылкой или форма записи без оплаты?
  7. Политика JS во фрагментах: разрешён ли собственный JS у фрагментов сайта или только из набора ядра?
  8. Аутентификация админки: локальные аккаунты или внешний провайдер (SSO)?
  9. Режим работы агента: прямая запись в draft или обязательно через ветку и согласование?
  10. Название проекта.