# Журнал решений по архитектурному ревью ТЗ Site Engine *Версия 0.1 · 6 ноября 2026 · основание: `TZ-site-engine-architecture-review.md` к ТЗ v0.1 · статус: проект решений, ждёт подтверждения (раздел 5)* **Уточнение от 12 ноября 2026.** По решению владельца проекта отдельный `steps` («Этапы») возвращён из `design/`, одновременно с `columns`. Он поставляется локально в `examples/ai-studio/fragments/steps/`: схема, шаблон и стили доступны установленному движку вместе с файлами сайта, без пересборки Docker. Встроенный набор содержит 15 фрагментов; схема сайта и версия фрагментов остаются 1. `card_grid.variant: steps` сохранён для совместимости. Историческое «columns вместо steps» ниже описывает первоначальное сокращение MVP; в отношении steps действует это уточнение. ## 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/@<хеш>`). В 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//`) или отдельный хост (`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`. По уточнению от 12 ноября 2026 отдельный `steps` доступен как локальный компонент ai-studio. Остальное — варианты и свойства этих фрагментов, а не отдельные фрагменты: - `card_grid` покрывает преимущества (`features`) и ссылки (`links`); прежний вариант `steps` поддерживается для совместимости. Для новых последовательностей этапов используется отдельный `steps`: `title` и список `items` (`title`, необязательный Markdown `text`), с оформлением из дизайна; - `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. Юридическая часть по ПД (формулировки согласия, сроки хранения, место размещения сервера) остаётся за владельцем сайта и его юристом.