32 KiB
Журнал решений по архитектурному ревью ТЗ 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 пункта):
- Блокировка записи в MVP на весь сайт, а не на документ. Один сайт и редкие записи, поэтому простота важнее параллелизма; к блокировке на документ вернёмся, если замеры покажут ожидание.
- Страховочная история файлов
.engine/history/вместо полного отказа от ревизий. Если агент или человек перезапишет черновик, а Git не подключён, откатиться иначе будет не к чему (релизы хранят только опубликованное). - Пятнадцатый фрагмент —
columns, аstepsстановится вариантомcard_grid. Ревью оставляло выбор открытым; сайт-пример закрывается обоими вариантами, ноcolumnsполезнее для разнообразия лендингов. - 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 оно нормализуется в тип поля по схеме:
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остаётся только у пунктов меню. - Блоки в
fixedlayout и в 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и лимит числа операций:
{
"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_*требует отдельного scopecontent:delete; агенту по умолчанию выключено (вместо удаления — статусarchived).
Критерий приёмки: два параллельных писателя не теряют обновления; kill -9 в середине commit не оставляет наполовину записанных файлов, сайт восстанавливается по журналу.
ADR-005. Модель доверия
| Кто | Что меняет | Уровень доверия |
|---|---|---|
| owner, developer | Исполняемое: Jinja, CSS, JS, схемы фрагментов и коллекций | Доверенный код; меняется через репозиторий и ревью |
| editor | Данные: страницы, записи, меню, data/ |
Только данные |
| agent | Данные в рамках scope | Только данные, минимальные права |
| Посетитель, внешний получатель превью | Отправка форм; просмотр по токену | Недоверенный |
Решение
SandboxedEnvironmentJinja остаётся защитой второго эшелона, но не границей безопасности. Граница — роли: контентные роли не могут добавлять шаблоны, 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— layoutlegalс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): блокировка на сайт,
.engine/history/,columnsвместоsteps, плоскиеidфрагментов. - Превью: отдельный хост или путь с токеном (отдельный поддомен нужен, если превью будут показывать внешним согласующим).
- Сайт-пример (студия ботов и Академия) использовать как тестовый набор для M0–M2?
- Юридическая часть по ПД (формулировки согласия, сроки хранения, место размещения сервера) остаётся за владельцем сайта и его юристом.