Init Project Flexly CMS

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