Files
flexly-cms/docs/TZ-site-engine-decisions.md
T
phelex 88ac95dd19 Integrate Antirion admin with FastAPI and htmx
Add the shared document API, constructor and expert editors, isolated preview, and fragment catalog metadata with typed block IDs.

Include design references, specification 001, QA scripts, project guidance, and cached Docker dependency installation. Leave example sites for a separate commit.
2026-11-12 21:55:36 +03:00

33 KiB
Raw Blame History

Журнал решений по архитектурному ревью ТЗ 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 оно нормализуется в тип поля по схеме:

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 и лимит числа операций:
{
  "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. По уточнению от 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. Юридическая часть по ПД (формулировки согласия, сроки хранения, место размещения сервера) остаётся за владельцем сайта и его юристом.