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
+317
View File
@@ -0,0 +1,317 @@
# Архитектурное ревью ТЗ 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, объём резко вырастет. Вертикальные срезы и строгие контракты позволят сохранить достоинства архитектуры и избежать ненужных затрат.