Files
flexly-cms/docs/TZ-site-engine-architecture-review.md
T
2026-11-09 15:32:41 +03:00

318 lines
43 KiB
Markdown
Raw 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 v0.1
**Исходный документ:** `TZ-site-engine.md`, редакция от 06.11.2026
**Тип ревью:** архитектура, модель данных, границы MVP, безопасность, MCP, эксплуатация
**Вердикт:** концепцию сохранить; до начала реализации уточнить контракты и пересобрать этапы.
> Это ревью **того, что написано в ТЗ**. Предлагаемые изменения — архитектурные рекомендации, а не утверждение, что в существующей реализации уже есть ошибки.
## 1. Резюме
Направление удачное: файловый источник контента, типизированные фрагменты, статический результат, единый сервисный слой, CLI/MCP/админка и контролируемая публикация. Но текущий документ пытается одновременно определить универсальную CMS, контентную платформу, агентский редактор и редакционный workflow. Из-за этого первоначальная версия получается значительно сложнее, чем нужно для первого работающего сайта.
### Исправить до старта (P0)
1. **Граница файлов и SQLite:** `slug_history` сейчас хранит не восстанавливаемые из файлов правила редиректов. Это противоречит принципу переносимого сайта. Уточнить файловый источник и исключения.
2. **Контракт данных:** формально определить структуру страницы, ссылки, привязки, запросы, разрешение типов и поведение при отсутствующих значениях. Сейчас несколько разных синтаксисов описывают близкие операции.
3. **Редактирование и релизы:** разделить сохранение рабочего черновика, валидацию для публикации и собственно опубликованный релиз. Неполный черновик не должен быть запрещён только потому, что у него пока нет всех обязательных полей.
4. **Параллельные изменения:** ID блока не гарантирует отсутствие конфликтов. Нужны атомарные `if_match`-операции, версия файла, блокировка/транзакционная граница и пакетные изменения.
5. **Доверенная и недоверенная среда:** отдельно описать границы Python-миграций, Jinja, JS, превью, публичного доступа к файловым ассетам. Jinja sandbox — не полноценная песочница для произвольного кода.
6. **Последовательность этапов:** нельзя запускать пишущий MCP и формы без минимального контура auth/RBAC, аудита, безопасной публикации и надёжной очереди уведомлений.
### Самое полезное упрощение
Для первого сайта достаточно около **15 базовых фрагментов**, небольшого набора операций с коллекциями и одного способа публикации. Инкрементальные сборки, произвольный DSL запросов, сложные правила редакционной готовности, Python-миграции схем фрагментов и мощную CMS-аналитику стоит отложить до появления реальных случаев использования.
## 2. Что оставить без фундаментальных изменений
| Решение | Оценка | Уточнение |
|---|---|---|
| Файлы Markdown + YAML как канонический контент | Оставить | Фиксировать схему, стабильные ID и формат сериализации |
| FastAPI + Jinja + htmx | Оставить | Достаточно для первой версии без frontend SPA |
| Layout / Fragment / Block | Оставить | Чётче определить роли и наследование |
| Единый сервисный слой для CLI, MCP, UI | Обязательно оставить | Блокировка, проверка прав и аудит тоже должны быть там |
| Рендер в статический `dist` | Оставить | Чёткое разделение рабочего состояния и опубликованного |
| Строгая проверка на публикации | Оставить | Ослабить запрет на сохранение *незавершённых* черновиков |
| MCP с ограниченными правами | Оставить | По умолчанию только рабочее пространство/черновики |
| SQLite для заявок, сессий, аудита | Оставить | Для одиночного сайта нагрузка разумная |
## 3. Архитектурные проблемы и решения
### P0-01. File-first не полностью соблюдается
**Где:** §2, §5.1, §13.
**Проблема:** при изменении `slug` старый URL попадает в историю, а `slug_history` по таблице раздела 13 не восстанавливается из файлов. После переноса каталога сайта и пересоздания БД история редиректов может исчезнуть. Значит, маршрутизация фактически зависит от скрытого состояния базы.
**Решение:** редиректы — в `redirects.yaml`; автоматическая смена URL атомарно меняет маршрут и добавляет запись в этот файл. БД может индексировать редиректы. У пользователей, токенов, заявок, аудита и служебных логов иной жизненный цикл — это честно оговорённые исключения, не «контент сайта».
**Критерий приёмки:** чистый `git clone` + `build` порождает ту же карту публичных маршрутов и редиректов без старой SQLite.
### P0-02. Нужно выбрать формальную модель входных данных
**Где:** §3.1, §4.4–4.8, §5.4.
В документе одновременно встречаются `source: body`, `source: entry.body`, `{bind: entry.title}`, `{page: contacts}`, `{collection: ...}`, `{children: current}`, `{{ entry.title }}` внутри SEO. Не описано, какие конструкции разрешены в каких полях, что является значением, ссылкой или вычисляемым выражением.
**Предложение:**
- Внутренняя модель: `Literal | Binding | LinkRef | Query` с явной нормализацией в конкретный тип поля.
- Унифицированные корни контекста: `site`, `page`, `entry`, `data`, `params` (для сборки лишь заранее известных статических параметров).
- Отсутствующая привязка: структурированная ошибка для обязательного поля, `null` для необязательного; никаких тихих подстановок пустых строк в обязательные поля.
- Ссылка на маршрут: типизированный объект, а не произвольный текст, с проверкой наличия *опубликованной* целевой страницы.
- Строковые выражения в YAML (например `seo.title: '{{ entry.title }}'`) либо запретить на старте, либо разрешить только безопасную ограниченную подстановку, без второго полноценного шаблонизатора.
- Для `source` использовать тот же `bind`, а не отдельный неформальный язык.
В запросах для MVP разрешить только: `collection`, `ids`, `where.eq/in`, `sort`, `limit`. `offset`, произвольные `contains/gte/lte/not`, `related_to/by` и гибридные фильтры добавить после реального сценария.
**Критерий приёмки:** схемы сериализуются/десериализуются обратно, типы проверяются до Jinja, неправильная привязка имеет точный путь к полю.
### P0-03. Публикация не равна сохранению документа
**Где:** §2.3, §4.5, §6.3–6.5, §10.2.
Фраза «невалидное не сохраняется» делает создание незавершённых страниц неудобным. А `status: published` не означает, что текущий файл уже присутствует в `dist/current`.
**Предложение:** разделить три состояния:
1. **Workspace** — редактируемые файлы (валидный синтаксис, допустимы неполные обязательные бизнес-поля у черновиков).
2. **Release candidate** — моментальный снимок файлов, прошедший *строгую* проверку всех публичных страниц, ссылок и ассетов.
3. **Live release** — конкретный `build_id`, на который указывает публикация.
Статусы `draft`, `review`, `published`, `scheduled`, `archived` описывают включение контента в сборку, а не факт публикации конкретного изменённого файла. Добавить `publish_at` с таймзоной и scheduler только если отложенная публикация реально нужна. До этого `scheduled` можно убрать.
**Критерий приёмки:** можно сохранить незавершённый черновик; валидная публикация не зависит от текущих незавершённых черновиков; неуспешная сборка не меняет `live`.
### P0-04. ID блоков ≠ бесконфликтная запись
**Где:** §2.4, §3.1, §10.2, §12.2.
Стабильный ID позволяет адресовать фрагмент, но два пользователя могут менять разные поля *одного YAML-файла*, и без контроля версий последняя запись перетрёт первую. Хеш в ТЗ есть, но не описана атомарность проверки+записи и работа с несколькими файлами при переносе/смене URL.
**Предложение:**
- Каждая запись требует `if_match: <content-hash>`; чтение возвращает этот хеш.
- Проверка хеша и атомарная запись выполняются под блокировкой конкретного документа, а не отдельными незащищёнными операциями.
- Конфликт — `409 Conflict` с текущей версией и машинно-читаемым diff.
- `move_block` принимает `target_region`, `target_slot`, `before_id` или `after_id`, а не позиционный индекс.
- Добавить `patch_page` для пакетного атомарного редактирования нескольких блоков одной страницы.
- Операции между файлами (`rename_page`, редирект, обновление меню) делать через транзакционный changeset/стейджинг с валидацией всего набора и безопасным коммитом. SQLite-транзакция сама по себе не охватывает файловую систему.
**Критерий приёмки:** два параллельных писателя не теряют обновления; конфликт не оставляет частично записанных файлов.
### P0-05. Безопасность шаблонов и привилегий
**Где:** §4.4, §4.4 «Версии», §8.2 `embed_html`, §11.2.
Декларация «шаблоны сайта рендерятся в sandbox» создаёт впечатление, что сторонние шаблоны/JS/Python-миграции безопасно исполнять. Это неверная граница доверия: файл `script.js` исполняется в браузере посетителя, Python-файл миграции — в серверном процессе; Jinja sandbox не заменяет отдельную изоляцию недоверенного кода.
**Предложение:**
- **Контентные роли** меняют только данные, не исполняемый код.
- **Developer** добавляет Jinja/CSS/JS как проверяемый код сайта. Такие расширения считаются доверенными после ревью.
- По умолчанию не исполнять Python-миграции, поставленные вместе с произвольным сайтом; в MVP — декларативные миграции или отдельный процесс ручного обновления версии фрагмента.
- Превью — отдельный путь/желательно origin с жёсткими cookies, CSP, `noindex`, сроками действия и ограничением прав токена. Внешняя превью-ссылка не должна случайно открывать админку или чужие черновики.
- Сборка/рендер имеют лимиты на размер файлов, глубину рекурсии, число блоков и запросов, длительность выполнения.
- SVG в начальном MVP проще запретить или конвертировать в безопасный растровый формат, чем обещать универсальную санитизацию.
**Критерий приёмки:** editor/agent не может добавить исполняемый шаблон, JS, миграционный скрипт или прочитать серверные секреты из шаблона.
### P0-06. Структура публикации должна учитывать динамические формы
**Где:** §6.1, §9.2, §13.
После отката статического `dist` HTML формы может ссылаться на прежнюю схему, в то время как `POST /forms/{id}` обрабатывает новую версию `forms/*.yaml`. При несовместимых изменениях старый опубликованный сайт перестанет отправлять заявки.
**Предложение:** версионировать публичную схему формы или привязать форму к `build_id`, поддерживая переходные версии. Сначала сохранить заявку и событие уведомления в одной DB-транзакции; уведомления доставлять отдельным worker из SQLite outbox. Нужны `attempts`, backoff, `next_attempt_at`, idempotency key и зафиксированная политика повторов.
**Критерий приёмки:** rollback восстанавливает не только внешний вид формы, но и её рабочую отправку; падение Telegram/email не теряет заявку.
### P0-07. Переставить security раньше пишущего MCP
**Где:** §11, §12, §15.
Сейчас MCP с записью включён в M1, а роли/токены/аудит — только в M2. Это небезопасный порядок релизов. В M1 также появляются формы, у которых уже есть персональные данные.
**Предложение:** встроить в первый сетевой релиз минимальные `auth`, scopes, аудит мутаций, ограничения экспорта, политику секретов и data retention. Полноценный UI управления ролями может появиться позже; сам контроль доступа — нет.
### P0-08. Статусы review/approval и MCP-согласование неполны
**Где:** §4.5, §6.4, §11.1, §12.1.
Пример статусов в §4.5 пропускает `review`; указана команда `submit_for_review`, но не описаны `approve`, `request_changes` или привязка согласования к конкретной ревизии. Editor может публиковать и одновременно согласовывать, так что обязательное approval фактически отсутствует.
**Предложение:** в MVP выбрать простой режим: `draft` → ручная публикация владельцем/редактором, без формального approval. Если review необходим, описать переходы, кто утверждает, кто публикует и что любое изменение после согласования аннулирует approval.
## 4. Ошибки контракта и неоднозначности (P1)
| ID | Место | Что уточнить | Предложение |
|---|---|---|---|
| P1-01 | §4.3, §4.7 | В `fixed`-блоках layout и блоках display template отсутствуют ID | Стабильный детерминированный ID из пути шаблона/ключа, который нельзя переименовать бесследно; отдельное пространство имён |
| P1-02 | §3.1, §4.7 | `overrides: allow` и `regions_mode` не определяют точную семантику замены | `append/prepend/replace` только для *региона*, а точечные overrides блоков — отдельный механизм позже |
| P1-03 | §4.4 | `id: hero` не уникален между категориями фрагментов | Канонический ID `marketing/hero` или иная явно заданная система namespace |
| P1-04 | §4.4, §4.6 | Мигрируют только схемы фрагментов, не схемы коллекций | Версионирование `collection.schema` и команда `migrate --dry-run` для обоих типов |
| P1-05 | §4.8 | `paginate` + `filters` конфликтует со статикой | Только заранее определённые маршруты/таксономии; произвольная фильтрация параметрами — client-side или динамический режим позже |
| P1-06 | §4.8, §6.1 | Запросы и зависимости через SQLite требуют синхронного индекса | Для MVP собирать нормализованный in-memory registry из файлов; SQLite использовать как восстанавливаемый кэш и БД сервиса |
| P1-07 | §5.1 | Роутинг не описывает нормализацию и collisions | Зафиксировать trailing slash, регистр, Unicode, percent encoding, reserved routes, конфликты редиректов/автомаршрутов |
| P1-08 | §5.5 | `hreflang` в v1 без полноценной реализации локалей | До появления переводов не генерировать `hreflang` для несуществующих версий; определить стратегию URL локалей |
| P1-09 | §7.4–7.5 | `requires`, `hidden`, `visibility`, `enabled`, `status` частично дублируют друг друга | Описать порядок применения, публикацию зависимых меню/ссылок и значения `null/false/0/[]` |
| P1-10 | §7.5 | `verified: true` не подтверждает реальную достоверность цифр | Ввести необязательную ссылку `evidence` и ручной статус проверки; валидатор может проверить наличие, но не истинность |
| P1-11 | §8.2 | Заявлено 22 MVP-фрагмента, перечислено 23 имени | Исправить количество и отделить семейства/варианты от самостоятельных фрагментов |
| P1-12 | §9.3, §13 | Аудит `before/after` может дублировать персональные данные удалённых заявок | Не сохранять значения ПД в аудите по умолчанию, логировать ID и тип операции; определить сроки хранения бэкапов/логов |
| P1-13 | §9.4 | CSV-экспорт заявок без политики безопасности | Экранировать формулы CSV, фиксировать факт экспорта в аудит, разграничить доступ и хранение |
| P1-14 | §12.1 | Есть `create_page`, но нет `delete_page`, `rename_page`, `delete_entry`; нет batch-патча | Уточнить минимальные жизненные операции и `patch_page` вместо расширения десятками однотипных команд |
| P1-15 | §6.2, §14 | 500 страниц за 10 с, страница за 1 с без определения нагрузки | Сначала базовый benchmark: конфигурация CPU/RAM, cold/warm, обработка изображений, полный/инкрементальный build |
## 5. Где переусложнён MVP
### 5.1. Слишком много специализированных фрагментов
В §8.2 фактически **23 самостоятельных имени фрагментов в MVP** (если `site_header` и `site_footer` считать отдельно), хотя в тексте указано 22. И это не полный объём: помимо них нужны библиотека CSS/JS, конфигурации, рендер, схемы, превью и тесты.
**Предлагаемое минимальное ядро: 15 фрагментов:**
1. `site_header`
2. `site_footer`
3. `hero`
4. `page_header`
5. `section`
6. `richtext`
7. `image`
8. `card_grid` (варианты: features, steps, links)
9. `collection_list`
10. `entry_header`
11. `cta_banner` (варианты: контакт, внешняя ссылка, форма)
12. `form`
13. `faq`
14. `disclaimer`
15. `steps` — только если вариант `card_grid` семантически/стилистически недостаточен; иначе заменить на `contact_block`.
В таком наборе `breadcrumbs` — встроенная функция `page_header`, `pagination` — часть `collection_list`, `requisites` — часть `site_footer` или обычных данных, `legal_text` — шаблон страницы с `richtext`. `feature_grid` обычно вариант `card_grid`; `contact_block` на старте может быть вариантом CTA/контента. `columns` вводить, когда доказано, что `section` со схемой сетки недостаточен.
**Важно:** если цель именно собирать большой спектр лендингов, `columns` полезнее `steps`. Тогда берём `columns` вместо `steps`. Набор из 15 — ориентир для пилота, не догма.
### 5.2. Универсальная политика готовности контента — не задача ядра
**Где:** §7.1, §7.4, §7.5.
`plan.priority`, `plan.state`, `goal`, `next`, `data_ready`, `verified`, `features` образуют отдельную редакционную/проектную подсистему, вытекшую из одного примера сайта.
**Предложение:** оставить в ядре `status`, `hidden`, `visibility` (последнее — возможно позже), обычные ссылки и строгие схемы. Всё планирование перенести в необязательный namespace `editorial` или `x-*`, доступный для проекта и MCP. Правила типа `scenario-disclaimer` — подключаемый набор валидаторов конкретного сайта, а не универсальная логика ядра. `requires` в MVP только явные `feature.<name>` с чёткой булевой семантикой; `data.*` — позже.
### 5.3. Упростить структуру файлов страниц
Сейчас разрешены и `pages/*.md`, и `pages/*.yaml`. Для MVP можно поддержать **только Markdown с YAML front matter**, включая пустое тело. Это уменьшит число ветвей парсера, схем и миграций, сохранив читаемость Git. Добавление чисто YAML-страниц не является блокирующей функцией.
Отдельно определить, что сложные структуры `regions` сериализуются стабильно, а пустой Markdown body допустим.
### 5.4. Инкрементальность не должна определять первую архитектуру
Собирать 500 небольших страниц из файлов и кешировать изображения может оказаться достаточно быстро без зависимостного графа. Предложение: сперва чистая детерминированная полная сборка, реальные профили времени и только потом граф `refs` и инкрементальные invalidation-правила. Граф полезен, но дорого тестируется: меню, шаблоны, тема и данные способны влиять на сотни страниц сразу.
### 5.5. История Git и ревизии БД дублируют функции
В ТЗ есть «каждое сохранение — Git-коммит» либо отдельный механизм `revisions`. На старте это две схемы работы, конфликтующие по UX и откатам.
**Предложение:** Git рекомендован для разработки и агентских изменений; внутренние публикации сохраняют immutable release snapshot вне зависимости от Git; полноценный UI истории/undo — после MVP. Коммитить лучше *логическое изменение* / changeset, а не каждый клик автосохранения.
## 6. MCP: меньший набор, более сильные контракты
В спецификации большой список атомарных команд, но мало сказано о композиции, ревизиях и размерах результатов.
**MVP API для агента:**
| Назначение | Методы |
|---|---|
| Узнать возможности | `get_site_info`, `get_content_schema`, `list_pages`, `get_page`, `list_entries`, `get_entry`, `list_fragments` |
| Изменить | `create_page`, `patch_page`, `create_entry`, `update_entry`, `upload_asset` |
| Проверить | `validate`, `get_preview_url`, `get_diff` |
| Завершить | `submit_for_review` — лишь если в MVP реально есть review workflow |
`patch_page` принимает список типизированных операций с `if_match` и `dry_run`; изменение URL — отдельная высокоуровневая операция `rename_page`, одновременно обновляющая редиректы. `publish` и `rollback` в MCP по умолчанию отключены. Доступ агенту — минимальные scopes, позволяющие работать с конкретными страницами или коллекциями, без чтения заявок.
**Дополнительные обязательные контракты:** ограничения на размер ответа, пагинация `list_*`, размер/способ загрузки asset, срок жизни токена, structured error codes, max-op count, audit correlation ID, запрет широкого `update_data` вне явно разрешённых путей.
Если требуется совместная работа с редактором, безопаснее по умолчанию модель **draft + optimistic concurrency + ручной publish**. Git-ветки `agent/*` опциональны для команд, которым они действительно нужны.
## 7. Формы, приватность, обработка заявок
**Технический контур:**
1. Сохранить заявку и запись в outbox атомарно в SQLite.
2. Выдать успех после фиксации данных, независимо от Telegram/email.
3. Worker отправляет уведомления с backoff и видимым статусом доставки.
4. Ограничить size/число полей, проверять типы данных, экранировать сообщения в Telegram/email и CSV.
5. Согласие хранить как `policy_id`, `policy_version`/hash, `accepted_at`, язык и проверенную сервером отметку; не рассчитывать, что одна галочка универсально покрывает все правовые основания обработки.
6. Логи и аудит не должны оставлять вечные копии удалённых персональных данных. Для бэкапов указать срок и процедуру восстановления/удаления.
7. В публикации хранить версию формы; сервер принимает версию, с которой посетитель реально отправляет заявку.
**Рекомендация для первой версии:** один канал (Telegram, поскольку он важен для сайта-примера), опциональный email/webhook — через интерфейс провайдера позднее. Не делать много каналов раньше гарантированной доставки одного.
## 8. Границы безопасности, которые надо зафиксировать
| Поверхность | Минимальный контроль |
|---|---|
| Markdown и text props | Autoescape + отдельная санитизация HTML после Markdown, без raw HTML по умолчанию |
| Jinja-фрагменты | Только подтверждённый developer-код, ограниченный контекст и лимиты рендера |
| `script.js` | Только developer, CSP, запрет inline handlers, версионный review |
| Python-миграции сайта | Не запускать автоматом из непроверенного сайта |
| Публичное превью | Токенизированный доступ, отдельная зона cookie/origin, `noindex`, ограниченный срок |
| Админка | Secure/HttpOnly/SameSite cookies, CSRF, rate-limit, аудит мутаций |
| MCP | Scope на объект/раздел, короткие токены, rate-limit, audit trail, `if_match` |
| Медиа | MIME sniffing, разрешённые форматы, лимиты, нормализация пути, карантин/обработка SVG |
| Файловая система | Нет записи вне site root, нет следования symlink наружу, контроль прав и путей |
| Заявки | RBAC, минимизация и сроки хранения ПД, защищённый экспорт, безопасные бэкапы |
## 9. Обновлённые этапы реализации
Предлагаю планировать не по списку подсистем, а по **вертикальным цепочкам, которые можно целиком проверить**.
| Этап | Что реализовать | Готовность к выходу |
|---|---|---|
| **M0 — Контракт и статический прототип** | Форматы, модель Block/Layout/Fragment, 5–7 фрагментов, `load → validate → render`, один сайт, CLI | Чистая сборка сайта из Git без заранее подготовленной БД |
| **M1 — Публикуемый движок** | Маршруты, ссылки, базовая тема, превью, атомарная публикация/rollback, 404/SEO, draft vs live | Можно безопасно опубликовать и откатить полноценный небольшой сайт |
| **M2 — Коллекции и заявки** | Минимальные коллекции/display, query MVP, формы, SQLite outbox, минимальная админка заявок, аутентификация | Работает сайт услуг + отправка заявок, в том числе после отката |
| **M3 — MCP и редактор** | RBAC+аудит (базовые правила безопасности должны появиться до внешнего доступа), CAS/patch, MCP read/write, простая админка htmx | Человек и агент могут менять черновики без потери данных; публикация под контролем человека |
| **M4 — Расширение** | Остальные фрагменты, медиа-варианты, Git-workflow, поиск, инкрементальная сборка только по benchmark | Реальные потребности нескольких сайтов закрыты без усложнения ядра |
| **Позже** | Мультиязычная админка, сложные таксономии, визуальный editor-in-page, scheduled publication, extensions marketplace | Есть конкретные use cases и автоматические регрессионные тесты |
**Замечание:** минимальную auth/authorization модель следует разработать уже на M1, если там появляется любой публичный API редактирования; в схеме выше внешние изменения подключаются на M3.
## 10. Решения по открытым вопросам (§16)
| Вопрос | Решение для MVP | Почему |
|---|---|---|
| Git обязателен? | **Не обязателен для runtime**, но рекомендован для разработки; релизы всегда immutable | Развёртывание проще, нет двух обязательных механизмов версионности |
| Поиск | **Отложить**; при необходимости статический JSON с клиентским поиском | Небольшие сайты не требуют серверного FTS |
| Мультиязычность | Только schema-ready; **не генерировать фиктивные hreflang** | Половинчатая поддержка создаёт ошибки SEO |
| Кто отдаёт статику | Nginx в production, FastAPI в dev | Ясное разделение нагрузки и обязанностей |
| Уведомления | Telegram + SQLite outbox сначала; дополнительные адаптеры потом | Надёжность важнее числа интеграций |
| Курсы и оплата | Внешний URL / форма заявки, без собственной кассы | Соответствует границам v1 |
| JS во фрагментах | Только доверенный developer-код, контентным ролям нельзя | Чёткая граница безопасности |
| Auth | Локальные аккаунты на старте, SSO позже | Минимум дополнительных зависимостей |
| Агент | Правка draft + `if_match`; публикация человеком; Git-ветки необязательны | Контроль и простота на первом этапе |
| Название | Не является блокирующим архитектурным решением | Не влияет на контракты |
## 11. Набор обязательных тестов, которого не хватает в ТЗ
- **Fresh clone test:** без старой SQLite работают маршруты, редиректы, сборка.
- **Round trip:** parse → serialize → parse не меняет дерево блоков и их ID.
- **Conflict test:** две одновременные операции на одной странице; одна получает 409, данные не теряются.
- **Invalid draft test:** черновик сохраняется, но неподготовленная страница не попадает в публичный релиз.
- **Broken reference test:** опубликованная страница не может ссылаться на неопубликованную/удалённую запись.
- **Route collision test:** обычные, сгенерированные, taxonomies, redirects и reserved paths не пересекаются.
- **Full rollback test:** HTML, ассеты, ссылки и формы продолжают работать после отката.
- **Partial failure test:** ошибка генерации изображений/Telegram/DB не портит `dist/current`.
- **Privilege escalation test:** agent/editor не может править фрагмент, читать ПД или публиковать без scope.
- **Preview isolation test:** токен превью не открывает админку и чужие черновики.
- **Performance test:** сравнить cold/warm build на фиксированном оборудовании до введения графа зависимостей.
- **Visual baseline:** помимо snapshot HTML — browser screenshots для 3 ширин экрана; особенно hero/header/footer и mobile navigation.
## 12. Предлагаемые ADR
Зафиксировать короткие ADR **до реализации** спорных системных решений:
1. **ADR-001: file-first, SQLite only for service data/cache, redirect persistence in YAML.**
2. **ADR-002: composition model, typed bindings and query DSL subset.**
3. **ADR-003: workspace vs release vs live, rollback and dynamic form compatibility.**
4. **ADR-004: optimistic concurrency and atomic changesets.**
5. **ADR-005: trust model for templates, JS, agent and preview.**
6. **ADR-006: MVP scope and release milestones.**
## 13. Итоговая рекомендация
**Не перерабатывать концепцию целиком.** Сохранить файловый движок, FastAPI + htmx, композицию layout/fragment/block, минимальные коллекции и MCP. Основные усилия направить на определения контрактов, безопасность изменения контента и релизный процесс. Урезать первые версии до работающего сайта, где агент способен создавать/менять страницу, пользователь — смотреть превью, а публикация и rollback не теряют данные и не ломают формы.
Главная опасность ТЗ — не выбор стека, а сложность, скрытая в сочетании **динамических привязок, схем, агентов, редакционных статусов и инкрементальной публикации**. Если эти подсистемы разрабатывать сразу как универсальную CMS, объём резко вырастет. Вертикальные срезы и строгие контракты позволят сохранить достоинства архитектуры и избежать ненужных затрат.