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
+317
View File
@@ -0,0 +1,317 @@
# Архитектурное ревью ТЗ Site Engine v0.1
**Исходный документ:** `TZ-site-engine.md`, редакция от 06.11.2026
**Тип ревью:** архитектура, модель данных, границы MVP, безопасность, MCP, эксплуатация
**Вердикт:** концепцию сохранить; до начала реализации уточнить контракты и пересобрать этапы.
> Это ревью **того, что написано в ТЗ**. Предлагаемые изменения — архитектурные рекомендации, а не утверждение, что в существующей реализации уже есть ошибки.
## 1. Резюме
Направление удачное: файловый источник контента, типизированные фрагменты, статический результат, единый сервисный слой, CLI/MCP/админка и контролируемая публикация. Но текущий документ пытается одновременно определить универсальную CMS, контентную платформу, агентский редактор и редакционный workflow. Из-за этого первоначальная версия получается значительно сложнее, чем нужно для первого работающего сайта.
### Исправить до старта (P0)
1. **Граница файлов и SQLite:** `slug_history` сейчас хранит не восстанавливаемые из файлов правила редиректов. Это противоречит принципу переносимого сайта. Уточнить файловый источник и исключения.
2. **Контракт данных:** формально определить структуру страницы, ссылки, привязки, запросы, разрешение типов и поведение при отсутствующих значениях. Сейчас несколько разных синтаксисов описывают близкие операции.
3. **Редактирование и релизы:** разделить сохранение рабочего черновика, валидацию для публикации и собственно опубликованный релиз. Неполный черновик не должен быть запрещён только потому, что у него пока нет всех обязательных полей.
4. **Параллельные изменения:** ID блока не гарантирует отсутствие конфликтов. Нужны атомарные `if_match`-операции, версия файла, блокировка/транзакционная граница и пакетные изменения.
5. **Доверенная и недоверенная среда:** отдельно описать границы Python-миграций, Jinja, JS, превью, публичного доступа к файловым ассетам. Jinja sandbox — не полноценная песочница для произвольного кода.
6. **Последовательность этапов:** нельзя запускать пишущий MCP и формы без минимального контура auth/RBAC, аудита, безопасной публикации и надёжной очереди уведомлений.
### Самое полезное упрощение
Для первого сайта достаточно около **15 базовых фрагментов**, небольшого набора операций с коллекциями и одного способа публикации. Инкрементальные сборки, произвольный DSL запросов, сложные правила редакционной готовности, Python-миграции схем фрагментов и мощную CMS-аналитику стоит отложить до появления реальных случаев использования.
## 2. Что оставить без фундаментальных изменений
| Решение | Оценка | Уточнение |
|---|---|---|
| Файлы Markdown + YAML как канонический контент | Оставить | Фиксировать схему, стабильные ID и формат сериализации |
| FastAPI + Jinja + htmx | Оставить | Достаточно для первой версии без frontend SPA |
| Layout / Fragment / Block | Оставить | Чётче определить роли и наследование |
| Единый сервисный слой для CLI, MCP, UI | Обязательно оставить | Блокировка, проверка прав и аудит тоже должны быть там |
| Рендер в статический `dist` | Оставить | Чёткое разделение рабочего состояния и опубликованного |
| Строгая проверка на публикации | Оставить | Ослабить запрет на сохранение *незавершённых* черновиков |
| MCP с ограниченными правами | Оставить | По умолчанию только рабочее пространство/черновики |
| SQLite для заявок, сессий, аудита | Оставить | Для одиночного сайта нагрузка разумная |
## 3. Архитектурные проблемы и решения
### P0-01. File-first не полностью соблюдается
**Где:** §2, §5.1, §13.
**Проблема:** при изменении `slug` старый URL попадает в историю, а `slug_history` по таблице раздела 13 не восстанавливается из файлов. После переноса каталога сайта и пересоздания БД история редиректов может исчезнуть. Значит, маршрутизация фактически зависит от скрытого состояния базы.
**Решение:** редиректы — в `redirects.yaml`; автоматическая смена URL атомарно меняет маршрут и добавляет запись в этот файл. БД может индексировать редиректы. У пользователей, токенов, заявок, аудита и служебных логов иной жизненный цикл — это честно оговорённые исключения, не «контент сайта».
**Критерий приёмки:** чистый `git clone` + `build` порождает ту же карту публичных маршрутов и редиректов без старой SQLite.
### P0-02. Нужно выбрать формальную модель входных данных
**Где:** §3.1, §4.4–4.8, §5.4.
В документе одновременно встречаются `source: body`, `source: entry.body`, `{bind: entry.title}`, `{page: contacts}`, `{collection: ...}`, `{children: current}`, `{{ entry.title }}` внутри SEO. Не описано, какие конструкции разрешены в каких полях, что является значением, ссылкой или вычисляемым выражением.
**Предложение:**
- Внутренняя модель: `Literal | Binding | LinkRef | Query` с явной нормализацией в конкретный тип поля.
- Унифицированные корни контекста: `site`, `page`, `entry`, `data`, `params` (для сборки лишь заранее известных статических параметров).
- Отсутствующая привязка: структурированная ошибка для обязательного поля, `null` для необязательного; никаких тихих подстановок пустых строк в обязательные поля.
- Ссылка на маршрут: типизированный объект, а не произвольный текст, с проверкой наличия *опубликованной* целевой страницы.
- Строковые выражения в YAML (например `seo.title: '{{ entry.title }}'`) либо запретить на старте, либо разрешить только безопасную ограниченную подстановку, без второго полноценного шаблонизатора.
- Для `source` использовать тот же `bind`, а не отдельный неформальный язык.
В запросах для MVP разрешить только: `collection`, `ids`, `where.eq/in`, `sort`, `limit`. `offset`, произвольные `contains/gte/lte/not`, `related_to/by` и гибридные фильтры добавить после реального сценария.
**Критерий приёмки:** схемы сериализуются/десериализуются обратно, типы проверяются до Jinja, неправильная привязка имеет точный путь к полю.
### P0-03. Публикация не равна сохранению документа
**Где:** §2.3, §4.5, §6.3–6.5, §10.2.
Фраза «невалидное не сохраняется» делает создание незавершённых страниц неудобным. А `status: published` не означает, что текущий файл уже присутствует в `dist/current`.
**Предложение:** разделить три состояния:
1. **Workspace** — редактируемые файлы (валидный синтаксис, допустимы неполные обязательные бизнес-поля у черновиков).
2. **Release candidate** — моментальный снимок файлов, прошедший *строгую* проверку всех публичных страниц, ссылок и ассетов.
3. **Live release** — конкретный `build_id`, на который указывает публикация.
Статусы `draft`, `review`, `published`, `scheduled`, `archived` описывают включение контента в сборку, а не факт публикации конкретного изменённого файла. Добавить `publish_at` с таймзоной и scheduler только если отложенная публикация реально нужна. До этого `scheduled` можно убрать.
**Критерий приёмки:** можно сохранить незавершённый черновик; валидная публикация не зависит от текущих незавершённых черновиков; неуспешная сборка не меняет `live`.
### P0-04. ID блоков ≠ бесконфликтная запись
**Где:** §2.4, §3.1, §10.2, §12.2.
Стабильный ID позволяет адресовать фрагмент, но два пользователя могут менять разные поля *одного YAML-файла*, и без контроля версий последняя запись перетрёт первую. Хеш в ТЗ есть, но не описана атомарность проверки+записи и работа с несколькими файлами при переносе/смене URL.
**Предложение:**
- Каждая запись требует `if_match: <content-hash>`; чтение возвращает этот хеш.
- Проверка хеша и атомарная запись выполняются под блокировкой конкретного документа, а не отдельными незащищёнными операциями.
- Конфликт — `409 Conflict` с текущей версией и машинно-читаемым diff.
- `move_block` принимает `target_region`, `target_slot`, `before_id` или `after_id`, а не позиционный индекс.
- Добавить `patch_page` для пакетного атомарного редактирования нескольких блоков одной страницы.
- Операции между файлами (`rename_page`, редирект, обновление меню) делать через транзакционный changeset/стейджинг с валидацией всего набора и безопасным коммитом. SQLite-транзакция сама по себе не охватывает файловую систему.
**Критерий приёмки:** два параллельных писателя не теряют обновления; конфликт не оставляет частично записанных файлов.
### P0-05. Безопасность шаблонов и привилегий
**Где:** §4.4, §4.4 «Версии», §8.2 `embed_html`, §11.2.
Декларация «шаблоны сайта рендерятся в sandbox» создаёт впечатление, что сторонние шаблоны/JS/Python-миграции безопасно исполнять. Это неверная граница доверия: файл `script.js` исполняется в браузере посетителя, Python-файл миграции — в серверном процессе; Jinja sandbox не заменяет отдельную изоляцию недоверенного кода.
**Предложение:**
- **Контентные роли** меняют только данные, не исполняемый код.
- **Developer** добавляет Jinja/CSS/JS как проверяемый код сайта. Такие расширения считаются доверенными после ревью.
- По умолчанию не исполнять Python-миграции, поставленные вместе с произвольным сайтом; в MVP — декларативные миграции или отдельный процесс ручного обновления версии фрагмента.
- Превью — отдельный путь/желательно origin с жёсткими cookies, CSP, `noindex`, сроками действия и ограничением прав токена. Внешняя превью-ссылка не должна случайно открывать админку или чужие черновики.
- Сборка/рендер имеют лимиты на размер файлов, глубину рекурсии, число блоков и запросов, длительность выполнения.
- SVG в начальном MVP проще запретить или конвертировать в безопасный растровый формат, чем обещать универсальную санитизацию.
**Критерий приёмки:** editor/agent не может добавить исполняемый шаблон, JS, миграционный скрипт или прочитать серверные секреты из шаблона.
### P0-06. Структура публикации должна учитывать динамические формы
**Где:** §6.1, §9.2, §13.
После отката статического `dist` HTML формы может ссылаться на прежнюю схему, в то время как `POST /forms/{id}` обрабатывает новую версию `forms/*.yaml`. При несовместимых изменениях старый опубликованный сайт перестанет отправлять заявки.
**Предложение:** версионировать публичную схему формы или привязать форму к `build_id`, поддерживая переходные версии. Сначала сохранить заявку и событие уведомления в одной DB-транзакции; уведомления доставлять отдельным worker из SQLite outbox. Нужны `attempts`, backoff, `next_attempt_at`, idempotency key и зафиксированная политика повторов.
**Критерий приёмки:** rollback восстанавливает не только внешний вид формы, но и её рабочую отправку; падение Telegram/email не теряет заявку.
### P0-07. Переставить security раньше пишущего MCP
**Где:** §11, §12, §15.
Сейчас MCP с записью включён в M1, а роли/токены/аудит — только в M2. Это небезопасный порядок релизов. В M1 также появляются формы, у которых уже есть персональные данные.
**Предложение:** встроить в первый сетевой релиз минимальные `auth`, scopes, аудит мутаций, ограничения экспорта, политику секретов и data retention. Полноценный UI управления ролями может появиться позже; сам контроль доступа — нет.
### P0-08. Статусы review/approval и MCP-согласование неполны
**Где:** §4.5, §6.4, §11.1, §12.1.
Пример статусов в §4.5 пропускает `review`; указана команда `submit_for_review`, но не описаны `approve`, `request_changes` или привязка согласования к конкретной ревизии. Editor может публиковать и одновременно согласовывать, так что обязательное approval фактически отсутствует.
**Предложение:** в MVP выбрать простой режим: `draft` → ручная публикация владельцем/редактором, без формального approval. Если review необходим, описать переходы, кто утверждает, кто публикует и что любое изменение после согласования аннулирует approval.
## 4. Ошибки контракта и неоднозначности (P1)
| ID | Место | Что уточнить | Предложение |
|---|---|---|---|
| P1-01 | §4.3, §4.7 | В `fixed`-блоках layout и блоках display template отсутствуют ID | Стабильный детерминированный ID из пути шаблона/ключа, который нельзя переименовать бесследно; отдельное пространство имён |
| P1-02 | §3.1, §4.7 | `overrides: allow` и `regions_mode` не определяют точную семантику замены | `append/prepend/replace` только для *региона*, а точечные overrides блоков — отдельный механизм позже |
| P1-03 | §4.4 | `id: hero` не уникален между категориями фрагментов | Канонический ID `marketing/hero` или иная явно заданная система namespace |
| P1-04 | §4.4, §4.6 | Мигрируют только схемы фрагментов, не схемы коллекций | Версионирование `collection.schema` и команда `migrate --dry-run` для обоих типов |
| P1-05 | §4.8 | `paginate` + `filters` конфликтует со статикой | Только заранее определённые маршруты/таксономии; произвольная фильтрация параметрами — client-side или динамический режим позже |
| P1-06 | §4.8, §6.1 | Запросы и зависимости через SQLite требуют синхронного индекса | Для MVP собирать нормализованный in-memory registry из файлов; SQLite использовать как восстанавливаемый кэш и БД сервиса |
| P1-07 | §5.1 | Роутинг не описывает нормализацию и collisions | Зафиксировать trailing slash, регистр, Unicode, percent encoding, reserved routes, конфликты редиректов/автомаршрутов |
| P1-08 | §5.5 | `hreflang` в v1 без полноценной реализации локалей | До появления переводов не генерировать `hreflang` для несуществующих версий; определить стратегию URL локалей |
| P1-09 | §7.4–7.5 | `requires`, `hidden`, `visibility`, `enabled`, `status` частично дублируют друг друга | Описать порядок применения, публикацию зависимых меню/ссылок и значения `null/false/0/[]` |
| P1-10 | §7.5 | `verified: true` не подтверждает реальную достоверность цифр | Ввести необязательную ссылку `evidence` и ручной статус проверки; валидатор может проверить наличие, но не истинность |
| P1-11 | §8.2 | Заявлено 22 MVP-фрагмента, перечислено 23 имени | Исправить количество и отделить семейства/варианты от самостоятельных фрагментов |
| P1-12 | §9.3, §13 | Аудит `before/after` может дублировать персональные данные удалённых заявок | Не сохранять значения ПД в аудите по умолчанию, логировать ID и тип операции; определить сроки хранения бэкапов/логов |
| P1-13 | §9.4 | CSV-экспорт заявок без политики безопасности | Экранировать формулы CSV, фиксировать факт экспорта в аудит, разграничить доступ и хранение |
| P1-14 | §12.1 | Есть `create_page`, но нет `delete_page`, `rename_page`, `delete_entry`; нет batch-патча | Уточнить минимальные жизненные операции и `patch_page` вместо расширения десятками однотипных команд |
| P1-15 | §6.2, §14 | 500 страниц за 10 с, страница за 1 с без определения нагрузки | Сначала базовый benchmark: конфигурация CPU/RAM, cold/warm, обработка изображений, полный/инкрементальный build |
## 5. Где переусложнён MVP
### 5.1. Слишком много специализированных фрагментов
В §8.2 фактически **23 самостоятельных имени фрагментов в MVP** (если `site_header` и `site_footer` считать отдельно), хотя в тексте указано 22. И это не полный объём: помимо них нужны библиотека CSS/JS, конфигурации, рендер, схемы, превью и тесты.
**Предлагаемое минимальное ядро: 15 фрагментов:**
1. `site_header`
2. `site_footer`
3. `hero`
4. `page_header`
5. `section`
6. `richtext`
7. `image`
8. `card_grid` (варианты: features, steps, links)
9. `collection_list`
10. `entry_header`
11. `cta_banner` (варианты: контакт, внешняя ссылка, форма)
12. `form`
13. `faq`
14. `disclaimer`
15. `steps` — только если вариант `card_grid` семантически/стилистически недостаточен; иначе заменить на `contact_block`.
В таком наборе `breadcrumbs` — встроенная функция `page_header`, `pagination` — часть `collection_list`, `requisites` — часть `site_footer` или обычных данных, `legal_text` — шаблон страницы с `richtext`. `feature_grid` обычно вариант `card_grid`; `contact_block` на старте может быть вариантом CTA/контента. `columns` вводить, когда доказано, что `section` со схемой сетки недостаточен.
**Важно:** если цель именно собирать большой спектр лендингов, `columns` полезнее `steps`. Тогда берём `columns` вместо `steps`. Набор из 15 — ориентир для пилота, не догма.
### 5.2. Универсальная политика готовности контента — не задача ядра
**Где:** §7.1, §7.4, §7.5.
`plan.priority`, `plan.state`, `goal`, `next`, `data_ready`, `verified`, `features` образуют отдельную редакционную/проектную подсистему, вытекшую из одного примера сайта.
**Предложение:** оставить в ядре `status`, `hidden`, `visibility` (последнее — возможно позже), обычные ссылки и строгие схемы. Всё планирование перенести в необязательный namespace `editorial` или `x-*`, доступный для проекта и MCP. Правила типа `scenario-disclaimer` — подключаемый набор валидаторов конкретного сайта, а не универсальная логика ядра. `requires` в MVP только явные `feature.<name>` с чёткой булевой семантикой; `data.*` — позже.
### 5.3. Упростить структуру файлов страниц
Сейчас разрешены и `pages/*.md`, и `pages/*.yaml`. Для MVP можно поддержать **только Markdown с YAML front matter**, включая пустое тело. Это уменьшит число ветвей парсера, схем и миграций, сохранив читаемость Git. Добавление чисто YAML-страниц не является блокирующей функцией.
Отдельно определить, что сложные структуры `regions` сериализуются стабильно, а пустой Markdown body допустим.
### 5.4. Инкрементальность не должна определять первую архитектуру
Собирать 500 небольших страниц из файлов и кешировать изображения может оказаться достаточно быстро без зависимостного графа. Предложение: сперва чистая детерминированная полная сборка, реальные профили времени и только потом граф `refs` и инкрементальные invalidation-правила. Граф полезен, но дорого тестируется: меню, шаблоны, тема и данные способны влиять на сотни страниц сразу.
### 5.5. История Git и ревизии БД дублируют функции
В ТЗ есть «каждое сохранение — Git-коммит» либо отдельный механизм `revisions`. На старте это две схемы работы, конфликтующие по UX и откатам.
**Предложение:** Git рекомендован для разработки и агентских изменений; внутренние публикации сохраняют immutable release snapshot вне зависимости от Git; полноценный UI истории/undo — после MVP. Коммитить лучше *логическое изменение* / changeset, а не каждый клик автосохранения.
## 6. MCP: меньший набор, более сильные контракты
В спецификации большой список атомарных команд, но мало сказано о композиции, ревизиях и размерах результатов.
**MVP API для агента:**
| Назначение | Методы |
|---|---|
| Узнать возможности | `get_site_info`, `get_content_schema`, `list_pages`, `get_page`, `list_entries`, `get_entry`, `list_fragments` |
| Изменить | `create_page`, `patch_page`, `create_entry`, `update_entry`, `upload_asset` |
| Проверить | `validate`, `get_preview_url`, `get_diff` |
| Завершить | `submit_for_review` — лишь если в MVP реально есть review workflow |
`patch_page` принимает список типизированных операций с `if_match` и `dry_run`; изменение URL — отдельная высокоуровневая операция `rename_page`, одновременно обновляющая редиректы. `publish` и `rollback` в MCP по умолчанию отключены. Доступ агенту — минимальные scopes, позволяющие работать с конкретными страницами или коллекциями, без чтения заявок.
**Дополнительные обязательные контракты:** ограничения на размер ответа, пагинация `list_*`, размер/способ загрузки asset, срок жизни токена, structured error codes, max-op count, audit correlation ID, запрет широкого `update_data` вне явно разрешённых путей.
Если требуется совместная работа с редактором, безопаснее по умолчанию модель **draft + optimistic concurrency + ручной publish**. Git-ветки `agent/*` опциональны для команд, которым они действительно нужны.
## 7. Формы, приватность, обработка заявок
**Технический контур:**
1. Сохранить заявку и запись в outbox атомарно в SQLite.
2. Выдать успех после фиксации данных, независимо от Telegram/email.
3. Worker отправляет уведомления с backoff и видимым статусом доставки.
4. Ограничить size/число полей, проверять типы данных, экранировать сообщения в Telegram/email и CSV.
5. Согласие хранить как `policy_id`, `policy_version`/hash, `accepted_at`, язык и проверенную сервером отметку; не рассчитывать, что одна галочка универсально покрывает все правовые основания обработки.
6. Логи и аудит не должны оставлять вечные копии удалённых персональных данных. Для бэкапов указать срок и процедуру восстановления/удаления.
7. В публикации хранить версию формы; сервер принимает версию, с которой посетитель реально отправляет заявку.
**Рекомендация для первой версии:** один канал (Telegram, поскольку он важен для сайта-примера), опциональный email/webhook — через интерфейс провайдера позднее. Не делать много каналов раньше гарантированной доставки одного.
## 8. Границы безопасности, которые надо зафиксировать
| Поверхность | Минимальный контроль |
|---|---|
| Markdown и text props | Autoescape + отдельная санитизация HTML после Markdown, без raw HTML по умолчанию |
| Jinja-фрагменты | Только подтверждённый developer-код, ограниченный контекст и лимиты рендера |
| `script.js` | Только developer, CSP, запрет inline handlers, версионный review |
| Python-миграции сайта | Не запускать автоматом из непроверенного сайта |
| Публичное превью | Токенизированный доступ, отдельная зона cookie/origin, `noindex`, ограниченный срок |
| Админка | Secure/HttpOnly/SameSite cookies, CSRF, rate-limit, аудит мутаций |
| MCP | Scope на объект/раздел, короткие токены, rate-limit, audit trail, `if_match` |
| Медиа | MIME sniffing, разрешённые форматы, лимиты, нормализация пути, карантин/обработка SVG |
| Файловая система | Нет записи вне site root, нет следования symlink наружу, контроль прав и путей |
| Заявки | RBAC, минимизация и сроки хранения ПД, защищённый экспорт, безопасные бэкапы |
## 9. Обновлённые этапы реализации
Предлагаю планировать не по списку подсистем, а по **вертикальным цепочкам, которые можно целиком проверить**.
| Этап | Что реализовать | Готовность к выходу |
|---|---|---|
| **M0 — Контракт и статический прототип** | Форматы, модель Block/Layout/Fragment, 5–7 фрагментов, `load → validate → render`, один сайт, CLI | Чистая сборка сайта из Git без заранее подготовленной БД |
| **M1 — Публикуемый движок** | Маршруты, ссылки, базовая тема, превью, атомарная публикация/rollback, 404/SEO, draft vs live | Можно безопасно опубликовать и откатить полноценный небольшой сайт |
| **M2 — Коллекции и заявки** | Минимальные коллекции/display, query MVP, формы, SQLite outbox, минимальная админка заявок, аутентификация | Работает сайт услуг + отправка заявок, в том числе после отката |
| **M3 — MCP и редактор** | RBAC+аудит (базовые правила безопасности должны появиться до внешнего доступа), CAS/patch, MCP read/write, простая админка htmx | Человек и агент могут менять черновики без потери данных; публикация под контролем человека |
| **M4 — Расширение** | Остальные фрагменты, медиа-варианты, Git-workflow, поиск, инкрементальная сборка только по benchmark | Реальные потребности нескольких сайтов закрыты без усложнения ядра |
| **Позже** | Мультиязычная админка, сложные таксономии, визуальный editor-in-page, scheduled publication, extensions marketplace | Есть конкретные use cases и автоматические регрессионные тесты |
**Замечание:** минимальную auth/authorization модель следует разработать уже на M1, если там появляется любой публичный API редактирования; в схеме выше внешние изменения подключаются на M3.
## 10. Решения по открытым вопросам (§16)
| Вопрос | Решение для MVP | Почему |
|---|---|---|
| Git обязателен? | **Не обязателен для runtime**, но рекомендован для разработки; релизы всегда immutable | Развёртывание проще, нет двух обязательных механизмов версионности |
| Поиск | **Отложить**; при необходимости статический JSON с клиентским поиском | Небольшие сайты не требуют серверного FTS |
| Мультиязычность | Только schema-ready; **не генерировать фиктивные hreflang** | Половинчатая поддержка создаёт ошибки SEO |
| Кто отдаёт статику | Nginx в production, FastAPI в dev | Ясное разделение нагрузки и обязанностей |
| Уведомления | Telegram + SQLite outbox сначала; дополнительные адаптеры потом | Надёжность важнее числа интеграций |
| Курсы и оплата | Внешний URL / форма заявки, без собственной кассы | Соответствует границам v1 |
| JS во фрагментах | Только доверенный developer-код, контентным ролям нельзя | Чёткая граница безопасности |
| Auth | Локальные аккаунты на старте, SSO позже | Минимум дополнительных зависимостей |
| Агент | Правка draft + `if_match`; публикация человеком; Git-ветки необязательны | Контроль и простота на первом этапе |
| Название | Не является блокирующим архитектурным решением | Не влияет на контракты |
## 11. Набор обязательных тестов, которого не хватает в ТЗ
- **Fresh clone test:** без старой SQLite работают маршруты, редиректы, сборка.
- **Round trip:** parse → serialize → parse не меняет дерево блоков и их ID.
- **Conflict test:** две одновременные операции на одной странице; одна получает 409, данные не теряются.
- **Invalid draft test:** черновик сохраняется, но неподготовленная страница не попадает в публичный релиз.
- **Broken reference test:** опубликованная страница не может ссылаться на неопубликованную/удалённую запись.
- **Route collision test:** обычные, сгенерированные, taxonomies, redirects и reserved paths не пересекаются.
- **Full rollback test:** HTML, ассеты, ссылки и формы продолжают работать после отката.
- **Partial failure test:** ошибка генерации изображений/Telegram/DB не портит `dist/current`.
- **Privilege escalation test:** agent/editor не может править фрагмент, читать ПД или публиковать без scope.
- **Preview isolation test:** токен превью не открывает админку и чужие черновики.
- **Performance test:** сравнить cold/warm build на фиксированном оборудовании до введения графа зависимостей.
- **Visual baseline:** помимо snapshot HTML — browser screenshots для 3 ширин экрана; особенно hero/header/footer и mobile navigation.
## 12. Предлагаемые ADR
Зафиксировать короткие ADR **до реализации** спорных системных решений:
1. **ADR-001: file-first, SQLite only for service data/cache, redirect persistence in YAML.**
2. **ADR-002: composition model, typed bindings and query DSL subset.**
3. **ADR-003: workspace vs release vs live, rollback and dynamic form compatibility.**
4. **ADR-004: optimistic concurrency and atomic changesets.**
5. **ADR-005: trust model for templates, JS, agent and preview.**
6. **ADR-006: MVP scope and release milestones.**
## 13. Итоговая рекомендация
**Не перерабатывать концепцию целиком.** Сохранить файловый движок, FastAPI + htmx, композицию layout/fragment/block, минимальные коллекции и MCP. Основные усилия направить на определения контрактов, безопасность изменения контента и релизный процесс. Урезать первые версии до работающего сайта, где агент способен создавать/менять страницу, пользователь — смотреть превью, а публикация и rollback не теряют данные и не ломают формы.
Главная опасность ТЗ — не выбор стека, а сложность, скрытая в сочетании **динамических привязок, схем, агентов, редакционных статусов и инкрементальной публикации**. Если эти подсистемы разрабатывать сразу как универсальную CMS, объём резко вырастет. Вертикальные срезы и строгие контракты позволят сохранить достоинства архитектуры и избежать ненужных затрат.
+242
View File
@@ -0,0 +1,242 @@
# Журнал решений по архитектурному ревью ТЗ Site Engine
*Версия 0.1 · 6 ноября 2026 · основание: `TZ-site-engine-architecture-review.md` к ТЗ v0.1 · статус: проект решений, ждёт подтверждения (раздел 5)*
## 1. Итог
Концепцию сохраняем: файловый источник контента, Layout / Fragment / Block, единый сервисный слой, статический результат, FastAPI + Jinja + htmx. Принимаем все восемь замечаний P0 и 15 замечаний P1, упрощение MVP, новый порядок этапов и список обязательных тестов. По итогам этого документа ТЗ переиздаётся как v0.2 (раздел 4).
**Где я отхожу от ревью (4 пункта):**
1. **Блокировка записи** в MVP на весь сайт, а не на документ. Один сайт и редкие записи, поэтому простота важнее параллелизма; к блокировке на документ вернёмся, если замеры покажут ожидание.
2. **Страховочная история файлов** `.engine/history/` вместо полного отказа от ревизий. Если агент или человек перезапишет черновик, а Git не подключён, откатиться иначе будет не к чему (релизы хранят только опубликованное).
3. **Пятнадцатый фрагмент — `columns`**, а `steps` становится вариантом `card_grid`. Ревью оставляло выбор открытым; сайт-пример закрывается обоими вариантами, но `columns` полезнее для разнообразия лендингов.
4. **ID фрагментов плоские и уникальные в пределах сайта** (`hero`), а не `marketing/hero`. Категория нужна только для каталога; коллизия имён — ошибка, затенение запрещено.
**Ошибки самого ТЗ, которые ревью верно нашло:** в MVP-наборе 23 фрагмента, а не 22; в 4.5 статусы без `review`, в 6.4 с ним; у блоков в `fixed` и display template нет ID; принцип «файлы — источник истины» нарушает `slug_history`; формулировка «невалидное не сохраняется» мешает вести черновики.
## 2. Принятые решения (ADR)
### ADR-001. Граница файлов и SQLite
**Решение**
- Источник истины — файлы. SQLite хранит только (а) служебные данные: пользователи, сессии, токены, аудит, заявки, outbox уведомлений, журнал сборок; (б) восстанавливаемый кэш: индекс страниц и записей, FTS, если появится поиск.
- Редиректы живут в `redirects.yaml`. `rename_page` атомарно меняет маршрут и дописывает запись в этот файл. Таблица `slug_history` убирается.
- Сборка не читает SQLite. Она строит в памяти нормализованный реестр (страницы, записи, фрагменты, данные) только из файлов и конфигурации, то есть остаётся чистой функцией от каталога сайта. Запросы к коллекциям выполняются по реестру.
- Из таблиц MVP убираются `slug_history`, `revisions`, `refs`, `locks`. Граф ссылок вернётся вместе с инкрементальной сборкой.
**Критерий приёмки:** чистый `git clone` + `build` без старой SQLite даёт ту же карту маршрутов и редиректов.
### ADR-002. Модель композиции, привязки и запросы
**Решение.** Значение любого поля — один из четырёх типов, и до Jinja оно нормализуется в тип поля по схеме:
```yaml
title: Заказная разработка # Literal
subtitle: {bind: entry.summary} # Binding: корни site, page, entry, data, params
cta: {page: contacts, label: Связаться} # LinkRef: page | entry | url (+ подпись)
items: # Query
query:
collection: services
where: {featured: true} # eq; или {tech: {in: [python, go]}}
sort: order
limit: 6
```
- Тело страницы и записи подключаются привязкой: `{bind: page.body}`, `{bind: entry.body}`. Неформальное `source: body` убирается.
- Строки с `{{ ... }}` внутри YAML-значений (в том числе `seo.title`) запрещены. Вместо них `seo.title: {bind: entry.title}` и суффикс из `site.defaults.seo.title_suffix`.
- Отсутствующая привязка: для обязательного поля структурированная ошибка с путём, для необязательного `null`. Пустые строки молча не подставляются.
- LinkRef — типизированный объект; проверяется, что целевая страница или запись существует и опубликована.
- Запросы в MVP: `collection`, `ids`, `where` (eq и `in`), `sort`, `limit`. Отложены: `offset`, `contains/gte/lte/not`, `related_to/by`, `paginate`, `filters`, `children`.
- Порядок применения условий показа блока: `status` страницы → `hidden` → `requires`. `requires` содержит только флаги `feature.<имя>` (булева семантика, неизвестный флаг = ошибка). Поле `visibility` в MVP не вводится; `enabled` остаётся только у пунктов меню.
- Блоки в `fixed` layout и в display template получают явный `id` в файле (обязательное поле); автоматическая генерация по позиции не допускается. Пространства имён id: страница, layout и display template не пересекаются между собой.
- Режимы объединения регионов: `append`, `prepend`, `replace` только для региона целиком. Точечные переопределения блоков — отдельная функция позже.
**Критерий приёмки:** round-trip parse → serialize → parse не меняет дерево блоков и их ID; типы проверяются до Jinja; ошибка привязки показывает точный путь к полю.
### ADR-003. Workspace, release candidate, live и формы
**Решение.** Три состояния вместо одного:
| Состояние | Что это | Проверка |
|---|---|---|
| Workspace | Рабочие файлы | При сохранении: корректный YAML и Markdown, известные фрагменты, типы указанных значений. Обязательные «бизнес»-поля не требуются, пока `status: draft` |
| Release candidate | Снимок файлов, собранный как публичный сайт (только `published`) | Строгая: обязательные поля, ссылки на опубликованные цели, ассеты, коллизии маршрутов, правила сайта |
| Live | Конкретный `build_id`, на который указывает `current` | Неудачная сборка `live` не меняет |
- Статусы контента: `draft`, `published`, `archived`. Статусы `review` и `scheduled` из v1 убираются; `publish_at` вернётся, когда понадобится отложенная публикация.
- Формального согласования в MVP нет: убираются роль `reviewer` и инструмент `submit_for_review`. Публикует владелец или редактор.
- **Формы и откат.** Каждый релиз содержит снимок определений форм (`forms/<id>@<хеш>`). В HTML формы лежит `form_version`; сервер проверяет заявку по версии из релиза, которая хранится среди последних N релизов. Неизвестная версия даёт понятное сообщение посетителю и запись в лог.
- **Outbox.** Заявка и событие уведомления записываются в одной транзакции SQLite; успех показывается после фиксации. Отдельный worker доставляет уведомления с полями `attempts`, `next_attempt_at`, `idempotency_key` и backoff. Падение Telegram или почты заявку не теряет.
- Согласие хранится как `policy_id`, `policy_hash`, `accepted_at`, язык; одна галочка не считается универсальным правовым основанием, формулировки согласует юрист владельца.
**Критерий приёмки:** черновик с пустыми обязательными полями сохраняется, но не попадает в релиз; сбой сборки не портит `dist/current`; после rollback форма продолжает отправлять заявки; падение уведомлений не теряет заявку.
### ADR-004. Параллельные изменения
**Решение**
- Любое чтение возвращает `etag` (хеш содержимого). Любая запись (админка, MCP, CLI) требует `if_match`.
- Путь записи: взять межпроцессную блокировку сайта (файловый lock) → сверить хеш → подготовить изменение во временном каталоге → провалидировать весь набор → закоммитить → снять блокировку. В MVP блокировка на весь сайт.
- Конфликт возвращается как `409` с текущей версией и структурным diff.
- `patch_page` принимает упорядоченный список типизированных операций; применяется «всё или ничего», поддерживает `dry_run` и лимит числа операций:
```json
{
"page": "services/index",
"if_match": "sha256:9f2c...",
"dry_run": true,
"ops": [
{"op": "set_prop", "block": "b_7k2m", "path": "props.title", "value": "Новый заголовок"},
{"op": "move_block", "block": "b_9xq1", "target_region": "main", "after": "b_7k2m"},
{"op": "add_block", "target_region": "main", "after": "b_9xq1", "block": {"fragment": "faq", "props": {}}}
]
}
```
- `move_block` принимает `target_region`, `target_slot` и `before` либо `after` (id блока), позиционные индексы не используются.
- Операции над несколькими файлами (`rename_page`, `delete_page`, `delete_entry`, обновление меню) выполняются как changeset: staging → проверка всего набора → commit с журналом `.engine/journal` для восстановления после сбоя. Оговорка: файловая система не транзакционна, поэтому гарантируем восстановимость после сбоя, а не атомарность на уровне ОС.
- История: перед каждой записью предыдущая версия сохраняется в `.engine/history/` (последние 20 на файл). Git необязателен; если каталог сайта — репозиторий, делается один коммит на changeset с автором (человек или агент). Автосохранения не коммитятся, ветки `agent/*` по умолчанию не создаются.
- Удаление: `delete_*` требует отдельного scope `content:delete`; агенту по умолчанию выключено (вместо удаления — статус `archived`).
**Критерий приёмки:** два параллельных писателя не теряют обновления; `kill -9` в середине commit не оставляет наполовину записанных файлов, сайт восстанавливается по журналу.
### ADR-005. Модель доверия
| Кто | Что меняет | Уровень доверия |
|---|---|---|
| owner, developer | Исполняемое: Jinja, CSS, JS, схемы фрагментов и коллекций | Доверенный код; меняется через репозиторий и ревью |
| editor | Данные: страницы, записи, меню, `data/` | Только данные |
| agent | Данные в рамках scope | Только данные, минимальные права |
| Посетитель, внешний получатель превью | Отправка форм; просмотр по токену | Недоверенный |
**Решение**
- `SandboxedEnvironment` Jinja остаётся защитой второго эшелона, но не границей безопасности. Граница — роли: контентные роли не могут добавлять шаблоны, JS и скрипты.
- Лимиты рендера: размер файлов, число блоков, глубина вложенности, число запросов, время рендера.
- Python-миграции из каталога сайта не исполняются. Только декларативные операции (`rename_field`, `set_default`, `remove_field`, `map_value`) и команда `migrate --dry-run`; версионируются и схемы фрагментов, и схемы коллекций.
- Превью: отдельный путь (`/_preview/<token>/`) или отдельный хост (`preview_base_url`); токен случайный, с сроком жизни, областью (страница или набор) и возможностью отзыва; `noindex`, собственный CSP, админские cookie не отправляются, чужие черновики недоступны.
- Raw HTML в Markdown выключен, после рендера Markdown идёт санитайзер, в шаблонах включён autoescape.
- SVG: загрузка через админку и MCP запрещена в MVP; SVG из репозитория (код разработчика) допускается. Фрагмент `embed_html` убирается из каталога.
- Файловая система: запись только внутри корня сайта, symlink наружу не разыменовываются, пути нормализуются.
- В контексте шаблонов нет переменных окружения и секретов.
- Админка: Secure, HttpOnly, SameSite cookie, CSRF, лимит попыток входа, аудит мутаций. MCP: scope на раздел или коллекцию, короткоживущие токены, лимиты запросов, `correlation_id` в аудите.
- Заявки: RBAC, сроки хранения, CSV-экспорт с экранированием формул и записью факта экспорта в аудит; аудит не хранит значения ПД, только id и тип операции; срок хранения бэкапов и процедура удаления фиксируются.
**Критерий приёмки:** editor и agent не могут добавить исполняемый шаблон, JS или скрипт миграции, прочитать секреты и ПД, опубликовать без scope; токен превью не открывает админку и чужие черновики.
### ADR-006. Границы MVP и этапы
**Ядро: 15 фрагментов.** `site_header`, `site_footer`, `hero`, `page_header`, `section`, `columns`, `richtext`, `image`, `card_grid`, `collection_list`, `entry_header`, `cta_banner`, `form`, `faq`, `disclaimer`.
Остальное — варианты и свойства этих фрагментов, а не отдельные фрагменты:
- `card_grid` покрывает преимущества (`features`), этапы (`steps`) и ссылки (`links`);
- `cta_banner` покрывает контакт, внешнюю ссылку и переход к форме; контакты берутся из `site.contacts`;
- `site_header` и `site_footer` сами выводят меню; реквизиты берутся из `data/company.yaml`;
- `page_header` выводит хлебные крошки; `legal_text` — layout `legal` с `richtext`;
- карточки списка — именованные варианты внутри `collection_list`; пустое состояние (`empty`) — его параметр.
**Отложено за пределы MVP:** страницы в чистом `.yaml` (только Markdown с front matter, пустое тело допустимо); инкрементальная сборка и граф `refs` (сначала полная детерминированная сборка и замеры); поиск; `hreflang` и мультиязычность (только модель данных); `scheduled` и `review`; `visibility`; `requires: data.*`; Python-миграции; `embed_html`; пагинация, `offset` и расширенные запросы; фрагменты `stats`, `live_examples`, `chat_demo`, `gallery` и прочие из версии «v1».
**Редакционная подсистема не в ядре.** `plan`, `goal`, `next`, `data_ready` и признак подтверждения цифр переносятся в необязательное пространство `editorial` (ядро его не интерпретирует, но отдаёт через MCP и админку). Вместо булева `verified` — необязательное поле `evidence` (ссылка или пояснение): валидатор проверяет наличие, а не истинность. Правила вроде `scenario-disclaimer` — декларативный набор правил конкретного сайта (`require_fragment`, `require_field`, `require_key`), а не логика ядра. Флаги `features` остаются в `site.yaml`. Блоки 3 и 5 главной сайта-примера, пока нет фрагментов `stats` и `live_examples`, хранятся записями в `editorial.excluded_blocks` и возвращаются вместе с фрагментами.
**Набор MCP-инструментов MVP**
| Назначение | Инструменты |
|---|---|
| Узнать возможности | `get_site_info` (схемы, правила, флаги, `editorial`), `list_pages`, `get_page`, `list_entries`, `get_entry`, `list_fragments` |
| Изменить | `create_page`, `patch_page`, `rename_page`, `create_entry`, `update_entry`, `upload_asset` |
| Проверить | `validate`, `get_preview_url`, `get_diff` |
`publish` и `rollback` в MCP выключены по умолчанию. Обязательные контракты: пагинация и лимит размера ответа у `list_*`, лимит размера и способ загрузки ассетов, срок жизни токена, структурированные коды ошибок, максимум операций в `patch_page`, `correlation_id`. Широкого `update_data` нет: запись только по явно разрешённым путям.
**Этапы** (по вертикальным срезам, каждый проверяется целиком)
| Этап | Состав | Выход |
|---|---|---|
| M0. Контракт и прототип | Форматы, модель Block/Layout/Fragment, 5–7 фрагментов, `load → validate → render`, один сайт, CLI | Чистая сборка из каталога без заранее подготовленной БД |
| M1. Публикуемый движок | Маршруты и ссылки, базовая тема, превью с токеном, атомарная публикация и rollback, 404 и SEO, draft vs live | Небольшой сайт безопасно публикуется и откатывается |
| M2. Коллекции, заявки, доступ | Минимальные коллекции и display, запросы MVP, формы, outbox, админка заявок; **вход, роли owner и editor, аудит мутаций, лимиты запросов** | Сайт услуг принимает заявки, в том числе после отката |
| M3. MCP и редактор | Optimistic concurrency, `patch_page`, MCP на чтение и запись со scope, htmx-админка | Человек и агент меняют черновики без потери данных; публикует человек |
| M4. Расширение | Остальные фрагменты, медиа-варианты, Git-workflow, поиск, инкрементальная сборка только по замерам | Закрыты реальные потребности нескольких сайтов |
| Позже | Мультиязычная админка, сложные таксономии, редактор на странице, отложенная публикация | Есть конкретные сценарии и регрессионные тесты |
Правило порядка: никакая сетевая поверхность записи (редактирование в админке, MCP на запись, формы с ПД) не включается раньше базового контура «вход, роли, аудит, лимиты». Для M2 он включён в состав этапа, а не отнесён на M3, как в таблице ревью, потому что админка заявок открывает доступ к ПД уже на M2.
**Решения по открытым вопросам ТЗ (раздел 16)**
| Вопрос | Решение для MVP |
|---|---|
| Git | Не обязателен в runtime, рекомендован для разработки; релизы — неизменяемые снимки |
| Поиск | Отложен; при необходимости статический JSON с клиентским поиском |
| Мультиязычность | Только заложить модель; `hreflang` не генерировать |
| Кто отдаёт статику | nginx в production, FastAPI в dev |
| Уведомления | Только Telegram и SQLite outbox; email и webhook позже через интерфейс провайдера |
| Оплата курсов | Внешний URL или форма заявки, без собственной кассы |
| JS во фрагментах | Только доверенный код разработчика |
| Вход в админку | Локальные аккаунты, SSO позже |
| Режим агента | Правка черновика с `if_match`, публикация человеком, ветки Git необязательны |
| Название | Не блокирует архитектуру |
## 3. Реестр решений по замечаниям ревью
| Замечание | Решение | Где |
|---|---|---|
| P0-01 file-first и `slug_history` | Принято | ADR-001 |
| P0-02 формальная модель данных | Принято | ADR-002 |
| P0-03 публикация ≠ сохранение | Принято | ADR-003 |
| P0-04 конфликты записи | Принято с изменением: блокировка на сайт, страховочная история | ADR-004 |
| P0-05 границы доверия | Принято | ADR-005 |
| P0-06 формы и откат | Принято | ADR-003 |
| P0-07 безопасность раньше MCP | Принято; базовый контур входит в M2 | ADR-006 |
| P0-08 review и approval | Принято: формального согласования в MVP нет | ADR-003 |
| P1-01 ID в `fixed` и display | Принято с изменением: явный `id` в файле, автоматических по позиции нет | ADR-002 |
| P1-02 семантика overrides | Принято: только регион целиком | ADR-002 |
| P1-03 уникальность `id` фрагментов | Принято с изменением: плоские уникальные id | раздел 1 |
| P1-04 миграции схем коллекций | Принято, декларативные | ADR-005 |
| P1-05 пагинация и фильтры | Принято: отложены | ADR-006 |
| P1-06 индекс для запросов | Принято: реестр в памяти из файлов | ADR-001 |
| P1-07 нормализация маршрутов | Принято: правила в разделе 5.1 ТЗ v0.2 | раздел 4 |
| P1-08 `hreflang` | Принято: не генерировать | ADR-006 |
| P1-09 порядок `requires`, `hidden`, `status` | Принято | ADR-002 |
| P1-10 `verified` | Принято с изменением: `editorial.evidence` | ADR-006 |
| P1-11 счёт фрагментов | Принято, пересчитано: 15 | ADR-006 |
| P1-12 ПД в аудите | Принято | ADR-005 |
| P1-13 CSV-экспорт | Принято | ADR-005 |
| P1-14 жизненный цикл страниц | Принято: `rename_page`, `patch_page`, удаление под scope | ADR-004, ADR-006 |
| P1-15 бенчмарк | Принято: цели заменяются замерами | ADR-006 |
| 5.1 15 фрагментов | Принято с изменением: `columns` вместо `steps` | ADR-006 |
| 5.2 редакционная подсистема | Принято | ADR-006 |
| 5.3 только Markdown-страницы | Принято | ADR-006 |
| 5.4 инкрементальность | Принято: после замеров | ADR-006 |
| 5.5 Git и ревизии | Принято с изменением: добавлена история файлов | ADR-004 |
| 6 MCP | Принято | ADR-006 |
| 7 формы | Принято | ADR-003 |
| 8 границы безопасности | Принято | ADR-005 |
| 9 этапы | Принято с изменением: контур доступа в M2 | ADR-006 |
| 10 открытые вопросы | Принято | ADR-006 |
| 11 тесты | Принято: входят в ТЗ и в критерии этапов | раздел 4 |
| 12 ADR | Этот документ | — |
## 4. Что меняется в ТЗ (версия 0.2)
- **Раздел 2.** Принцип 6: песочница Jinja — второй эшелон, граница — роли. Принцип 3: на сохранении проверяются синтаксис и типы, на публикации — полнота.
- **Разделы 3–4.** Четыре типа значений (4.8 переписать); убрать `{{ }}` из YAML; `source` заменить привязкой; убрать `.yaml`-страницы; явные `id` в `fixed` и display; плоские `id` фрагментов; декларативные миграции вместо `migrations/*.py`; статусы `draft`, `published`, `archived`.
- **Раздел 5.** Добавить правила маршрутов: завершающий слэш, регистр, Unicode и percent-encoding, зарезервированные пути, коллизии редиректов и автомаршрутов; убрать `hreflang`, `children`, `paginate`.
- **Раздел 6.** Состояния workspace, release candidate, live; убрать инкрементальность, `scheduled`, `review`; историю заменить на `.engine/history/` и необязательный Git; цели по времени сборки заменить замерами.
- **Раздел 7.** `plan`, `goal`, `next`, `data_ready`, `verified` перенести в `editorial`; правила сделать декларативным набором сайта; `requires` оставить только для `feature.*`; блоки 3 и 5 хранить в `editorial.excluded_blocks`.
- **Раздел 8.** Каталог заменить 15 фрагментами и их вариантами.
- **Раздел 9.** Outbox, версия формы в релизе, один канал (Telegram), структура согласия, аудит без ПД, безопасный CSV-экспорт.
- **Разделы 10–12.** `if_match` во всех формах админки; набор MCP из ADR-006, `patch_page`, `rename_page`, `publish` и `rollback` выключены по умолчанию, лимиты, пагинация, коды ошибок, `correlation_id`; роль `reviewer` убрать.
- **Раздел 13.** Убрать `slug_history`, `revisions`, `refs`, `locks`; добавить `outbox`.
- **Раздел 14.** Добавить 12 обязательных тестов из ревью (fresh clone, round trip, конфликты, невалидный черновик, битые ссылки, коллизии маршрутов, полный rollback, частичные сбои, эскалация привилегий, изоляция превью, производительность, визуальные базовые снимки).
- **Разделы 15–16.** Этапы заменить таблицей из ADR-006; открытые вопросы заменить принятыми решениями.
## 5. К подтверждению
1. Четыре отступления от ревью (раздел 1): блокировка на сайт, `.engine/history/`, `columns` вместо `steps`, плоские `id` фрагментов.
2. Превью: отдельный хост или путь с токеном (отдельный поддомен нужен, если превью будут показывать внешним согласующим).
3. Сайт-пример (студия ботов и Академия) использовать как тестовый набор для M0–M2?
4. Юридическая часть по ПД (формулировки согласия, сроки хранения, место размещения сервера) остаётся за владельцем сайта и его юристом.
+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. Название проекта.