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

770 lines
55 KiB
Markdown
Raw Blame History

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