Files
flexly-cms/docs/TZ-site-engine-decisions.md
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

245 lines
33 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Журнал решений по архитектурному ревью ТЗ 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/<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`. По уточнению от 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. Юридическая часть по ПД (формулировки согласия, сроки хранения, место размещения сервера) остаётся за владельцем сайта и его юристом.