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