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.
This commit is contained in:
@@ -0,0 +1,81 @@
|
||||
# Site Engine — Этап 5: Публикация, история и откат
|
||||
|
||||
**Design prototype.** HTML / CSS / JavaScript, без Node.js, CDN и серверной интеграции.
|
||||
|
||||
Откройте `index.html` и выберите публикацию в одном из двух активных оформлений. Остальные ранее согласованные экраны и редакторы сохранены.
|
||||
|
||||
## Актуальные варианты дизайна
|
||||
|
||||
| № | Название | Статус | Ключевой файл |
|
||||
|---|---|---|---|
|
||||
| 03 | Antirion | Сохранённый концепт | `antirion.html` |
|
||||
| **04** | **Antirion Rework** | Активно развивается | `antirion-rework.html`, `publication-antirion.html` |
|
||||
| 05 | Ember Graphite | Сохранённый концепт | `ember-graphite.html` |
|
||||
| **06** | **Rose Graphite** | Активно развивается | `rose-graphite.html`, `publication-rose-graphite.html` |
|
||||
|
||||
В Rose Graphite единственный элемент без скруглений — выбор коллекции в разделе Контент. Остальные таблицы, панели и карточки сохранили утверждённый стиль.
|
||||
|
||||
## Что работает в Этапе 5
|
||||
|
||||
- **Workspace:** изменённые / новые / удалённые файлы и их статусы, поиск и фильтры, сравнение с live. Демонстрационные данные поддерживают Page, Entry, Menu, Asset. Сохранённые черновики Этапов 3–4 читаются из `localStorage` при возможности.
|
||||
- **Validation:** ошибки и предупреждения, переход к объекту, тестовое исправление отсутствующей формы и повторная проверка. Ошибки блокируют сборку кандидата.
|
||||
- **Candidate:** зафиксированный снимок файлов и diff относительно live; повторная сборка после новой проверки, инвалидация старого кандидата при изменении workspace или live. Сценарий failed build с логом не меняет live.
|
||||
- **Publish:** подтверждение с комментарием и смена только mock-live ID, хранение релиза в истории и запись действия в демо-аудит.
|
||||
- **История:** список неизменяемых релизов, детали, файлы, отличия и предыдущие версии. История документа представлена отдельно от истории сайта и обозначена зависимостью от Git / revisions.
|
||||
- **Rollback:** сравнение последствий, проверка версии форм, подтверждение и изменение live без потери workspace. Успешный rollback отражается в демо-аудите.
|
||||
- **Роли:** Owner/Developer могут создавать кандидатов, публиковать и откатывать; Editor/Reviewer — просматривать и проверять.
|
||||
- **Интеграция с UI:** из навигации «Публикация» в 04/06 и из редакторов Page/Entry выполняется переход к новому экрану. При открытии `?section=publish` также выполняется переход.
|
||||
|
||||
## Главный сценарий (в двух темах)
|
||||
|
||||
1. Откройте `publication-rose-graphite.html`.
|
||||
2. Нажмите **Проверить** — появится ошибка привязки `form_contact`.
|
||||
3. На вкладке **Проверки** нажмите **Исправить → Применить**. Повторите **Запустить validate**.
|
||||
4. На вкладке **Кандидат** нажмите **Сформировать кандидата**; при нулевом числе ошибок появится готовый `build_id`.
|
||||
5. Нажмите **Опубликовать**, добавьте комментарий и подтвердите.
|
||||
6. На вкладке **История** выберите старый релиз → **Откат** → проверьте последствия → подтвердите. Публичный снимок изменится только внутри браузерной демо-модели.
|
||||
7. На вкладке **Журнал** проверьте события. На вкладке **Кандидат** можно отдельно проверить failed build.
|
||||
|
||||
## Архитектура и ограничения
|
||||
|
||||
Нельзя считать demo-publish реальной публикацией. Все операции выполняются в JS и `localStorage`; записи меняют лишь состояние прототипа. Отсутствуют атомарная файловая публикация, реальные сборки и серверный RBAC. В реальном Site Engine операции должны идти через **единый сервисный слой** для API, CLI и MCP, с `if_match`, структурной и публикационной валидацией, staging/snapshot и проверенным атомарным переключением live.
|
||||
|
||||
Уже существующие редакторы Page/Entry используют отдельные фиксированные демо-live данные (`build_00027`), поэтому live-специфичный рендер на их экранах пока **не синхронизируется** с клиентской моделью Этапа 5. Это задача интеграции с backend. Сохранённые `Page`/`Entry` данные (при доступности `localStorage`) подхватываются; несохранённые изменения в другой вкладке — нет.
|
||||
|
||||
История контентных ревизий может быть реализована через Git или revisions; источник пока не утверждён. Схема формы при rollback проверяется отдельно от immutable HTML-снимка.
|
||||
|
||||
Для полного локального поведения кросс-страничного `localStorage` предпочтительно открыть каталог через простой локальный HTTP-сервер (например, `python -m http.server 8000`) и перейти на `http://localhost:8000`. Одиночные HTML-прототипы можно посмотреть как файлы, однако ограничения `file://` различаются по браузерам.
|
||||
|
||||
## Структура
|
||||
|
||||
```text
|
||||
index.html галерея этапов и тем
|
||||
publication-antirion.html 04 — публикация
|
||||
publication-rose-graphite.html 06 — публикация
|
||||
assets/publication.css общий styling / темы
|
||||
assets/publication.js mock release state / actions
|
||||
builder-antirion.html 04 — Конструктор + Эксперт Page
|
||||
builder-rose-graphite.html 06 — Конструктор + Эксперт Page
|
||||
content-antirion.html 04 — Конструктор + Эксперт Entry
|
||||
content-rose-graphite.html 06 — Конструктор + Эксперт Entry
|
||||
antirion.html, antirion-rework.html,
|
||||
ember-graphite.html, rose-graphite.html четыре согласованных концепта
|
||||
assets/* ассеты и скрипты предыдущих этапов
|
||||
previews/* screenshots / acceptance
|
||||
CHANGELOG.md полный журнал изменений
|
||||
docs/STAGE5_QA.md QA и ограничения
|
||||
```
|
||||
|
||||
## Будущий перенос на FastAPI / Jinja2 / htmx
|
||||
|
||||
| UI | Jinja partial | Сервис / контракт |
|
||||
|---|---|---|
|
||||
| Workspace | `publication/_changes.html` | `workspace.diff(live_build_id)` |
|
||||
| Check / validate | `publication/_validation.html` | `release.validate(workspace_hash)` |
|
||||
| Candidate | `publication/_candidate.html` | `release.build(snapshot_id, if_match)` |
|
||||
| Publish | `publication/_publish_dialog.html` | `release.publish(build_id, if_match)` |
|
||||
| History / details | `publication/_history.html`, `_details.html` | `release.list`, `release.get`, `release.files` |
|
||||
| Rollback preview + confirm | `publication/_rollback.html` | `release.rollback_preview`, `release.rollback(build_id)` |
|
||||
| Audit | `publication/_audit.html` | `audit.list`, `audit.append` |
|
||||
|
||||
**Контрольная точка:** пройти цикл публикации и отката, оценить читаемость статусов и возможность быстро исправлять ошибки. Следом — Этап 6: Медиа, Структура, Формы, Настройки, Журнал, RBAC и финальный UX/адаптивность.
|
||||
@@ -0,0 +1,91 @@
|
||||
# Site Engine — Этап 6: полный HTML-прототип админки
|
||||
|
||||
**Два активных оформления:** `04 Antirion Rework` и `06 Rose Graphite` (ранее YuE Studio). **Четыре зафиксированных концепта 03–06 сохранены.** Пакет работает локально, без обязательных CDN, Node.js и backend.
|
||||
|
||||
Откройте `index.html`, затем новый экран Этапа 6 нужной темы. Переходы в разделы 6.1–6.5 встроены в боковое меню прежних экранов 04/06. Для надёжного общего localStorage при многовкладочной работе используйте локальный HTTP-сервер, например `python -m http.server 8000`; URL: `http://localhost:8000`.
|
||||
|
||||
## Активные новые экраны
|
||||
|
||||
| Тема | HTML | Внутренние разделы |
|
||||
|---|---|---|
|
||||
| 04 Antirion Rework | `modules-antirion.html` | `?section=media`, `structure`, `forms`, `settings`, `journal` |
|
||||
| 06 Rose Graphite | `modules-rose-graphite.html` | те же пять разделов |
|
||||
|
||||
Два новых файла используют **общую** логику `assets/stage6.js` и слой стилей `assets/stage6.css`, опирающийся на уже утверждённый дизайн Stage 5. При переключении между темами сохраняется одна локальная демо-модель данных Stage 6. Файлы 03 и 05 не расширялись.
|
||||
|
||||
## 6.1 — Медиабиблиотека
|
||||
|
||||
- Сетка / таблица, поиск по имени/пути/alt, типы и папки; создание папки.
|
||||
- Выбор ассета, инспектор: файл, тип, размер, `alt`, `caption`, статус и список «Где используется?».
|
||||
- Локальная загрузка PNG/JPEG/WEBP/SVG/PDF/ZIP до 2 МБ (по одному). Превью малых растровых изображений до 300 КБ сохраняется в browser `localStorage`, остальные файлы **только регистрируются как демо-метаданные**, не создавая физического файла. SVG в HTML не встраивается.
|
||||
- Подтверждение удаления; ассет с известными зависимостями превращается в `missing`, не затирая привязки. Состояния `missing` и незаполненный `alt` видны в UI.
|
||||
- Ограничение: автоматическое построение карты зависимостей — пример на фиксированных данных; динамическая индексация при backend-интеграции.
|
||||
|
||||
## 6.2 — Структура
|
||||
|
||||
- Меню: выбор, добавление пунктов, изменение названия/URL, скрытие/показ, порядок вверх/вниз, создание нового меню, предпросмотр, YAML-контракт.
|
||||
- Каталог Layouts с регионами `header`/`main`/`footer`, fixed/allow; каталог Fragment с декларативными полями; Display templates с маршрутом коллекций.
|
||||
- «Где используется?» для схемных объектов и переходы к редакторам.
|
||||
- Код Jinja/CSS/JS — только контекст и просмотр демо-шаблона; редактирование кода через прототип **не поддерживается**, а в будущем требует роли `developer`.
|
||||
|
||||
## 6.3 — Формы и заявки
|
||||
|
||||
- `form_contact`, `form_brief`: включение/отключение полей, required, сообщение после отправки, статус, уведомления Telegram/email (статус доставки — только mock).
|
||||
- Предпросмотр схемы и тестовая неотправляемая кнопка «Отправить (симуляция)».
|
||||
- Таблица заявок, фильтр статуса, просмотр, «В работу», «Закрыть», mock-повтор доставки, CSV с **вымышленными** контактами.
|
||||
- Owner видит тестовые персональные данные. Developer, Editor, Reviewer и Agent **не видят** контактные поля. Это демонстрация UX; реальную защиту обеспечивает только серверный RBAC.
|
||||
- Версия схемы связана с релизом: UI предупреждает о необходимости сохранения совместимости при rollback. Live-схема автоматически не переключается.
|
||||
|
||||
## 6.4 — Настройки и доступы
|
||||
|
||||
- `site.yaml`: название, домен, описание, контактная почта, язык.
|
||||
- Тема сайта: цвета и радиус, интерактивный sample; не изменяет палитру самой админки.
|
||||
- `data/*.yaml`: создание, изменение и удаление глобальных пар `key → value`.
|
||||
- `redirects.yaml`: CRUD, проверка URL и простейших циклических редиректов.
|
||||
- Демонстрационные пользователи, роли, табличный статус доступа; переключение роли для UX-проверки.
|
||||
- MCP-агенты: имитация создания с `read` или `draft-only` scopes и отключения. **Токены и секреты не создаются**, не показываются и не передаются куда-либо.
|
||||
- Build: параметры preview, minify и удержания релизов; кнопка ведёт в Stage 5.
|
||||
|
||||
## 6.5 — Журнал и финальный UX
|
||||
|
||||
- Единый демо-журнал операций Stage 6; отображает также доступную историю Stage 5, если сохранена в localStorage текущего origin.
|
||||
- Поиск, фильтры, детали, экспорт CSV, подтверждение сброса локального журнала (Owner).
|
||||
- Видимый focus, Esc/Tab, Ctrl/Cmd+K (быстрый переход), мобильное боковое меню, адаптивные таблицы с внутренним скроллом.
|
||||
- Проверены размеры 1440×900, 1280×800, 1024×768, 768×1024, 390×844, 360×740, а также отдельные 390px-превью **всех пяти разделов в обеих темах**.
|
||||
|
||||
## Сохранившиеся этапы и концепции
|
||||
|
||||
| Файл | Назначение |
|
||||
|---|---|
|
||||
| `antirion.html` | 03 Antirion, фиксированный концепт |
|
||||
| `antirion-rework.html` | 04 Antirion Rework, shell |
|
||||
| `ember-graphite.html` | 05 Ember Graphite, фиксированный концепт |
|
||||
| `rose-graphite.html` | 06 Rose Graphite, shell; без скруглений **только выбор коллекции** в Контенте |
|
||||
| `builder-antirion.html`, `builder-rose-graphite.html` | Этапы 2–3: Конструктор и Эксперт Page |
|
||||
| `content-antirion.html`, `content-rose-graphite.html` | Этап 4: коллекции и записи Entry |
|
||||
| `publication-antirion.html`, `publication-rose-graphite.html` | Этап 5: кандидат, publish, история, rollback |
|
||||
| `modules-antirion.html`, `modules-rose-graphite.html` | Этап 6: пять дополнительных разделов |
|
||||
|
||||
## Ограничения и следующий этап
|
||||
|
||||
Это **не production CMS**. Здесь нет настоящего сохранения файлов, серверных прав, безопасных сессий, CSRF, обработки реальных заявок, SMTP/Telegram, MCP-ключей, загрузки на сервер, настоящих release build и атомарного переключения live. Данные преимущественно синтетические, операции Stage 6 сохраняются в `localStorage` при его доступности. Состояние ранее разработанных редакторов и Stage 5 *не унифицировано полностью* в одном клиентском store: это предмет service/API-интеграции.
|
||||
|
||||
**Этап 7 (следующий):** техническая карта переноса на FastAPI + Jinja2 + htmx, единый сервисный слой, схема file-first документов, серверный RBAC, конкуренция `if_match`, аудит, обработка заявок и release pipeline. Реализация backend — отдельная задача после утверждения технического дизайна.
|
||||
|
||||
## Проверки
|
||||
|
||||
- `docs/test_stage6.py` — сценарии интерактивности обеих тем, 6 разрешений.
|
||||
- `docs/test_stage6_views.py` — все 5 экранов × 2 темы, desktop/mobile + отсутствие горизонтального переполнения.
|
||||
- `docs/STAGE6_QA_TEST_OUTPUT.txt` и `docs/STAGE6_VISUAL_QA.json` — машинные результаты, `previews/stage6-*` — скриншоты.
|
||||
|
||||
### План для Jinja partials
|
||||
|
||||
| Экран | Partial | Основные сервисы |
|
||||
|---|---|---|
|
||||
| Медиа | `media/_grid.html`, `_asset_detail.html`, `_picker.html` | `asset.list/get/upload/edit/delete`, `dependency.references` |
|
||||
| Структура | `structure/_menu_editor.html`, `_layout_detail.html`, `_fragments.html` | `menu.*`, `layout.list/get`, `fragment.list/get`, `display.*` |
|
||||
| Формы | `forms/_schema.html`, `_submissions.html` | `form.*`, `submission.list/get/update`, `delivery.retry` |
|
||||
| Настройки | `settings/_site.html`, `_theme.html`, `_access.html`, `_mcp.html` | `site.settings`, `theme.*`, `users.*`, `agents.*`, `redirects.*` |
|
||||
| Журнал | `audit/_events.html` | `audit.list/get/export` |
|
||||
|
||||
Все модификации проходят единые серверные permissions/validation/audit, независимо от входа через UI/CLI/MCP. Никакое действие клиента не считается проверкой прав.
|
||||
@@ -0,0 +1,177 @@
|
||||
# Site Engine — Этап 3: Конструктор и Эксперт (интерактивный HTML)
|
||||
|
||||
**Актуальные активные варианты:** `04 Antirion Rework` и `06 Rose Graphite`. Остальные утверждённые оформления `03 Antirion` и `05 Ember Graphite` сохранены неизменёнными в архиве. Откройте `index.html` и выберите редактор. Все HTML работают без серверного API, npm или внешних CDN.
|
||||
|
||||
## Исправление верхнего переключателя режима (2026-11-11)
|
||||
|
||||
При открытии страницы в редакторе по умолчанию активен и визуально выделен **«Конструктор»**. При выборе **«Эксперт»** активная кнопка и заголовок меняются вместе с редактором; обратное переключение восстанавливает выделение «Конструктор». Проверено в обеих активных темах.
|
||||
|
||||
## Реализовано в Этапе 3
|
||||
|
||||
- Переключатель «Конструктор / Эксперт» работает с **одним объектом Page**. Блоки, поля, SEO, bindings и Markdown синхронизируются в обоих направлениях. Корректные изменения в исходнике автоматически применяются примерно через 650 мс или по кнопке **Применить**.
|
||||
- Файловое дерево слева, YAML front matter + Markdown по центру (подсветка, номера строк, поиск, Tab = два пробела), превью и диагностика справа. На мобильных экранах редактор и остальные панели располагаются вертикально.
|
||||
- Структура документа: `schema`, `title`, `route`, `layout`, `status`, `seo`, `regions.main[]`, `id`, `fragment`, `visible`, `anchor`, `note`, `props`, `bindings` и Markdown body. Фиксированные `site_header / site_footer` принадлежат layout, не могут быть удалены правкой Page.
|
||||
- **Валидатор разделён:** ошибки синтаксиса/схемы *останавливают применение к общему состоянию*; публикационные ошибки (невалидные ссылки, отсутствующие ресурсы и т. п.) *допускают локальное сохранение черновика*, но помечаются отдельно. В Expert нет обхода общих правил Page.
|
||||
- **Безопасное переключение:** неверный YAML не уничтожает исходный текст, не меняет последний корректный Page и не позволяет уйти в Конструктор без выбора. Буфер сырого исходника сохраняется отдельно в памяти (и в `localStorage`, где разрешено). Неподдерживаемые ключи блокируются, а не отбрасываются.
|
||||
- **Source diff** в модальном окне: построчное сравнение YAML/Markdown с последним сохранённым draft или неизменяемым mock-live `build_00027`. Предпросмотр Live остаётся прежним.
|
||||
- **Конфликт версий:** кнопка «Симулировать 409 Conflict» изменяет локальный mock-server revision. Следующее сохранение предложит сравнить my/server и явно выбрать действие. В реальной CMS механизм будет опираться на серверный ETag / `if_match` и RBAC.
|
||||
- Комментарии YAML сохраняются в исходном буфере. Для перехода к Конструктору, который может пересоздать YAML без комментариев после редактирования, показывается предупреждение и хранится резервная копия. Форматирование с комментариями также запрашивает подтверждение.
|
||||
|
||||
## Проверка за 5 минут
|
||||
|
||||
1. `builder-rose-graphite.html` → **Эксперт**. Измените `regions.main[0].props.title` и нажмите «Применить». Вернитесь в Конструктор: заголовок Hero в инспекторе должен совпасть.
|
||||
2. В Конструкторе поменяйте описание Hero или добавьте FAQ. Вернитесь в Эксперт: YAML содержит эти изменения. Добавьте в Markdown body новый текст; проверьте его во вкладке «Страница» конструктора.
|
||||
3. Измените `schema: "page/v1"` на `schema: [wrong]`, попробуйте вернуться в Конструктор. Должно появиться сообщение со строкой и безопасными вариантами. После исправления переход работает.
|
||||
4. Нажмите **Сравнить** в режиме Expert. Выберите «С live» или «С сохранённым» и просмотрите добавленные/удалённые строки.
|
||||
5. Нажмите «Симулировать 409 Conflict», затем «Сохранить черновик»: сравните мою и mock-серверную версии. Выберите оставить свои правки или явно подтвердите перезапись. Live не меняется.
|
||||
|
||||
## Границы прототипа / будущая реализация
|
||||
|
||||
- YAML реализован **не полностью**: поддерживается ограниченное подмножество, достаточное для показанной схемы. Не поддерживаются anchors/aliases, произвольные теги, flow collections, сложные ключи или сохранение позиции комментариев после правки в Конструкторе. Неподдерживаемые конструкции дают ошибку, не приводят к незаметной потере данных. В настоящем backend понадобится полноценный YAML 1.2 парсер, schema validation и round-trip механика.
|
||||
- Это **design prototype**, не код реальной CMS. Файлы `pages/*.md` не редактируются на диске, `localStorage` не годится как production storage. Нет FastAPI, SQL, настоящих Jinja permissions, CSRF, Git revision history, атомарной публикации и реального 409/ETag. Ввод исходника не даёт прав на layouts/fragments, CSS, JS, схемы и секреты.
|
||||
- Реальная публикация, история релизов и откат будут в Этапе 5. В Этапе 4 следующим шагом проработаем типизированные записи `Entry`, коллекции и Display templates.
|
||||
|
||||
## QA
|
||||
|
||||
Playwright + системный Chromium: оба редактора на `1440×900`, `1280×800`, `1024×768`, `768×1024`, `390×844`, `360×740` — без ошибок JS/горизонтального переполнения. Пройдены проверки корректного и ошибочного YAML, multiline string `|-`, Markdown, неизвестных ключей, комментариев, source diff, mock-конфликтов и синхронизации Constructor↔Expert. Изображения в `previews/stage3-*.png`. Старые утверждённые скриншоты сохранены.
|
||||
|
||||
## Карта для FastAPI + Jinja2 + htmx (после согласования UX)
|
||||
|
||||
| Интерфейс | Будущий partial | Контракт |
|
||||
|---|---|---|
|
||||
| Конструктор / Эксперт | `editor/_mode_tabs.html` | `page.get`, `permissions`, `if_match` |
|
||||
| YAML / Markdown | `editor/_source_editor.html` | `document.read`, `document.validate`, `document.save` |
|
||||
| Проверки + diff | `editor/_diagnostics.html`, `_source_diff.html` | `validate.schema`, `validate.publish`, `revision.diff` |
|
||||
| Конфликт 409 | `editor/_conflict_dialog.html` | `if_match`, `revision.get`, `revision.compare`, `document.save` |
|
||||
| Preview | `editor/_preview.html` | `preview.render` |
|
||||
|
||||
---
|
||||
|
||||
## История: предыдущие этапы
|
||||
|
||||
# Site Engine · Этап 2.4 — завершение Конструктора страниц
|
||||
|
||||
**Развиваем две темы:** `04 Antirion Rework` (`builder-antirion.html`) и `06 Rose Graphite` (`builder-rose-graphite.html`). В архиве сохранены и **два других утверждённых shell-варианта**: `03 Antirion` и `05 Ember Graphite`; в них новых экранов конструктора нет. Запуск: откройте `index.html` или HTML-файл редактора локально. Node, CDN и сервер не нужны.
|
||||
|
||||
## Новое в 2.4
|
||||
|
||||
- **Три явно разделённых состояния:** несохранённые правки workspace, сохранённый локальный draft, неизменяемый демонстрационный `LIVE build_00027`. Статус `published` в файле не означает, что текущая редакция уже видна на live.
|
||||
- **Сохранение черновика:** `Сохранить черновик` или `Ctrl+S` записывает рабочие Page/Block в `localStorage` (если разрешено браузером). После сохранения показывается индикатор и локальное время. Сохранять можно даже неполную страницу; публикация здесь не производится.
|
||||
- **Отмена правок:** кнопка «Отменить» с подтверждением восстанавливает *весь текущий workspace* из последнего локального сохранения. Live не изменяется. Действие применяется ко всем страницам, о чём интерфейс явно предупреждает.
|
||||
- **Проверка перед публикацией:** отдельный интерактивный список *ошибок* и *предупреждений* по всем Page в workspace. Ошибки трактуются как блокирующие mock-публикацию; предупреждения — нет. Нажатие на проблему открывает нужную страницу, блок и поле инспектора. Проверяются отсутствующие привязки/ассеты, неопубликованные ссылки, title/route/SEO, повторяющиеся anchors и отсутствие видимого `richtext` для Markdown body. Это **клиентский mock-валидатор**, серверную проверку он не заменяет.
|
||||
- **Раздел «Страница»:** SEO title / description с счётчиками длины и условным поисковым превью, поля route/layout/status, Markdown body и безопасный упрощённый Markdown-просмотр (`#`, `##`, `###`, акценты, ссылки, списки). При отсутствии видимого richtext предлагается добавить его.
|
||||
- **Сравнение с двумя базами:** данные/поля и схематичная визуальная сверка **Workspace ↔ Saved draft** и **Workspace ↔ Live**. Показываются изменения Page, SEO, props, bindings, видимости и порядка блоков. Для полноразмерного сравнения используйте превью «Черновик / Live». Схематичная сверка — **не pixel-perfect diff**.
|
||||
- **Исправления:** при выборе поля через маппинг, редактировании и сохранении корректно обновляются статусы; URL вводится как есть и проверяется (без скрытой автоматической нормализации). Доработаны состояния и адаптивность диалогов на телефонах.
|
||||
|
||||
## Сценарии проверки
|
||||
|
||||
1. Открыть Конструктор → «Страница» → изменить SEO title/description и Markdown body. Проверить поисковое и Markdown-превью, затем статус «Не сохранено».
|
||||
2. Нажать «Проверить». Переключить фильтры «Ошибки»/«Предупреждения», нажать на предупреждение о `body` или неопубликованной ссылке. Инспектор должен открыть соответствующее поле.
|
||||
3. Ввести route без начального `/` и запустить проверку. В списке появится **блокирующая ошибка**, по нажатию на которую откроется поле URL.
|
||||
4. Нажать «Сравнить» → выбрать Live / Saved draft; переключить «Данные и поля» / «Визуально (схема)». После правки отличия должны отображаться; после сохранения отличия с Saved draft исчезнут, а с Live останутся.
|
||||
5. Выбрать «Live» в центральном превью: оно продолжает показывать исходный mock-релиз. Изменения в workspace и сохранение не публикуются. Попробовать отменить несохранённые изменения с подтверждением.
|
||||
|
||||
## QA
|
||||
|
||||
Playwright + Chromium: обе темы, размеры `1440×900`, `1280×800`, `1024×768`, `768×1024`, `390×844`, `360×740`: без горизонтального переполнения и ошибок JavaScript. Сценарии включали SEO/Markdown, переход к ошибке, сохранение, оба режима сравнения и проверку битого ассета. Актуальные скриншоты: `previews/stage24-*.png`.
|
||||
|
||||
## Ограничения
|
||||
|
||||
Это **design prototype с локальными mock-данными**, а не реализация файлового движка. Реальные `pages/*.md` и `site.yaml` не меняются; нет backend/API, Git revisions, атомарной публикации, реальных прав доступа, серверной проверки и отката. Клиентское `localStorage` не является надёжным хранилищем черновиков или реальной revision history. Если браузер запрещает storage для локальных `file://`, сохранение останется только в памяти вкладки. В Этапе 3 появится режим «Эксперт» с YAML + Markdown и безопасным переключением; полноценные публикация, история и rollback — Этап 5.
|
||||
|
||||
---
|
||||
|
||||
# Site Engine · Этап 2.3 — Маппинг данных
|
||||
|
||||
**Интерактивные HTML-редакторы:** `builder-antirion.html` (04 Antirion Rework) и `builder-rose-graphite.html` (06 Rose Graphite). В архиве также сохранены утверждённые админки 03 и 05 — без изменений. Откройте `index.html` или любой HTML локально, без Node/CDN/backend.
|
||||
|
||||
## Новое в 2.3
|
||||
|
||||
- **Карта источников:** левый переключатель **«Связи данных»** разворачивает цепочку `Page → Layout → Region → Block ID → Fragment → props → источник → результат` по каждому полю. Отображаются типы `literal / bind / query / ref / asset / link`, а также количество проблемных привязок.
|
||||
- **Инспектор → «Связи»:** тип источника, конкретный путь и вычисленное демо-значение, предупреждение/ошибка у проблемного поля и действие **«Сменить источник»**.
|
||||
- **Выбор источника без YAML:** поиск по полям Page, `data.company.*`, коллекциям, записям, ассетам и URL. Есть специальные несуществующие источники для тестирования ошибок. Изменения обновляют общее состояние Page/Block и iframe-превью без сброса прокрутки.
|
||||
- **Collection query:** `collection`, `sort: order/title`, `limit: 1–12`. `services`, `scenarios`, `cases`, пустые `courses/posts`. Демо-entries имеют статус `published/draft`.
|
||||
- **Прямые refs:** новый Fragment `entry_card` с привязкой к конкретной записи, публичным URL и демонстрацией отсутствующей записи. Медиафайл блока `image` выбирается из медиатеки. Ссылки кнопок — из существующих Page/Entry.
|
||||
- **«Где используется?»**: поиск упоминаний коллекции, записи (включая динамические collection_list), ассета, маршрута или data-поля во всех демо-страницах. Список результатов ведёт прямо к Page → Block в редакторе.
|
||||
- **Валидация:** несуществующие Collection/Entry/Binding/URL дают ошибки, отсутствующий Asset, ссылка на draft и пустая Collection дают предупреждения. Сохранение черновика доступно даже при ошибках публикации; это локальный mock, не deploy.
|
||||
|
||||
## Что проверить
|
||||
|
||||
1. Откройте `builder-rose-graphite.html`, нажмите **«Связи данных»** слева, выберите `services_list`. Справа откройте **«Связи»** → у `collection` нажмите **«Сменить источник»**, выберите `cases`. Проверьте превью и индикатор изменений.
|
||||
2. Нажмите **«Где используется?»** у выбранной коллекции — в появившемся списке выберите использование, чтобы перейти к нужному блоку. Откройте **«Каталог данных»**, посмотрите записи и медиа.
|
||||
3. В каталоге Fragment добавьте `Запись коллекции`, выберите `services/ai`, затем через «Где используется?» посмотрите прямые и динамические ссылки на запись.
|
||||
4. На странице «О компании» выберите `team_asset` и `assets/missing.webp`, затем **«Проверить»**. Проверьте предупреждение и верните существующий ассет.
|
||||
5. Поставьте для коллекции `missing_collection`, запустите проверку, затем исправьте выбор. Проверьте сохранение черновика, Live/Workspace и отсутствие скачка прокрутки при выборе блока.
|
||||
|
||||
**Границы прототипа:** каталоги, ресурсы, связи и build ID демонстрационные. Исходные Markdown/YAML-файлы не изменяются. Обратные зависимости рассчитываются в браузере; в production они должны обрабатываться сервисом Site Engine. 2.4 продолжит работу над состояниями, 3 добавит реальный Expert UX; миграция к FastAPI/Jinja2/htmx — только после утверждения дизайна.
|
||||
|
||||
---
|
||||
|
||||
# Site Engine · Admin Design Lab · Этап 2 (Конструктор страниц)
|
||||
|
||||
**Направления в активной разработке:** `04 Antirion Rework` и `06 Rose Graphite`. **Rose Graphite** — новое собственное название ранее утверждённого **YuE Studio**, не новая палитра. В тёмном 06 **только выбор коллекции** в разделе «Контент» остаётся без скруглений, как согласовано. Весь остальной визуальный стиль старых четырёх вариантов сохранён.
|
||||
|
||||
## Быстрый старт
|
||||
|
||||
Откройте `index.html` локально без сервера, Node.js, CDN и каких-либо установок. Вверху находятся два интерактивных редактора.
|
||||
|
||||
- **`builder-antirion.html`** — Конструктор в светлой рабочей стилистике Antirion Rework.
|
||||
- **`builder-rose-graphite.html`** — тот же Конструктор в тёмной стилистике Rose Graphite.
|
||||
- На прежних экранах `antirion-rework.html` и `rose-graphite.html` можно выбрать страницу и нажать **«Редактор»** — откроется новый Конструктор с выбранной страницей.
|
||||
- Вновь утверждённые стили 03 и 05 сохранены как `antirion.html` и `ember-graphite.html`, но Конструктор для них не разрабатывался.
|
||||
|
||||
## Что работает в Конструкторе
|
||||
|
||||
| Возможность | Сценарий | Статус |
|
||||
|---|---|---|
|
||||
| Page selection | Смена страницы в верхнем селекте; несколько демонстрационных Page | Работает локально |
|
||||
| Layout + регионы | Дерево `header / main / footer`, фиксированные шапка и подвал | Работает локально |
|
||||
| Выбор блоков | Клик в дереве прокручивает iframe к блоку (если он не целиком виден); клик по секции внутри iframe не прокручивает | Работает |
|
||||
| Каталог Fragment | Кнопка `+`, поиск и фильтр по категории, добавление в `main` с переходом к новому блоку; `hero` ограничен одним экземпляром | Работает |
|
||||
| Изменение порядка | Кнопки «Выше / Ниже», drag & drop между блоками одного региона; переход к новой позиции в preview | Работает |
|
||||
| Действия | Дублирование, скрытие/показ, удаление с подтверждением | Работает |
|
||||
| Inspector | Поля по типу Fragment, Anchor, заметка, видимость | Работает |
|
||||
| Binding | Для отдельных текстовых полей переключение literal / page.title / data.company.name / entry.title | Работает (упрощённо) |
|
||||
| Collection query | Выбор `services/scenarios/cases`, limit, карта источников | Работает (упрощённо) |
|
||||
| Preview | Desktop / Tablet / Mobile, черновик / исходный mock-live, props; обновление полей без перезагрузки iframe | Работает |
|
||||
| Page fields | Статус файла, route, layout, SEO, Markdown body | Работает |
|
||||
| Валидация | Проверка обязательных значений, отсутствующей коллекции, отсутствующего asset, потерянного Markdown body | Работает локально |
|
||||
| Черновик | Индикатор изменений, сохранение в `localStorage`, `Ctrl+S` | Работает локально |
|
||||
| Diff | Сравнение текущего workspace с последним локальным сохранением | Работает локально |
|
||||
| Expert | Экран-предупреждение + пример YAML/Markdown структуры | **Этап 3** |
|
||||
|
||||
**Это прототип, не настоящий backend.** Никаких изменений файлов `pages/*.md`, FastAPI, SQL, Git, Jinja, проверок прав, CSRF, реальной публикации или серверного предпросмотра нет. Модель страницы в браузере создана на основе тех же сущностей: `Page`, `Layout`, `Region`, `Block`, `Fragment`, `props`, `bindings` и `collection`. Упрощённые моковые query/bind не заменяют финальный контракт схем. `Live` — фиксированная демонстрационная исходная версия; даже после сохранения Workspace она не меняется. Сохранения между разными локальными HTML-файлами могут быть изолированы политиками `file://` браузера.
|
||||
|
||||
## Что проверить (за 5 минут)
|
||||
|
||||
1. `index.html → 06 Rose Graphite → Открыть Конструктор`. Убедиться, что рабочая область — три панели, интерфейс компактный.
|
||||
2. Выбрать `Hero`, заменить заголовок; изменение появится в iframe и в статусе **«Не сохранено»**. Затем выбрать `page.title` как источник заголовка — preview покажет название Page.
|
||||
3. Открыть `Связи данных`, выбрать `services_list` и проверить `Page → Layout → Region → Block → collection`. Изменить `collection` или `limit` в Inspector.
|
||||
4. Добавить `FAQ`, переместить его вверх, скрыть, включить, дублировать и удалить с подтверждением.
|
||||
5. Открыть вкладку **«Страница»**, изменить Markdown body / SEO. Сохранить черновик, нажать **«Проверить»** и переключить превью **«Черновик / Live»**. Live не должен изменяться.
|
||||
|
||||
## Карта будущих Jinja / htmx фрагментов
|
||||
|
||||
| HTML-компонент | Jinja2 partial | Сервисный контракт |
|
||||
|---|---|---|
|
||||
| `.side`, `.top`, `.head` | `admin/_shell.html` / `_page_bar.html` | `page.list`, permissions |
|
||||
| `.treepane`, `.tree-item` | `editor/_block_tree.html` | `page.get`, `block.move`, `block.add` |
|
||||
| `.stagepane`, `#preview` | `editor/_preview.html` | `preview.render` |
|
||||
| `.inspectpane`, `.field` | `editor/_inspector.html`, `_field.html` | `fragment.schema`, `block.update` |
|
||||
| `.mapping-card` | `editor/_bindings.html` | `binding.resolve`, `usage.where` |
|
||||
| `.modal` | `admin/_modal.html` | permission/CSRF/if_match |
|
||||
| `validate`, `save`, `diff` | `editor/_validation.html` | `page.validate`, `page.save`, `page.diff` |
|
||||
|
||||
## Следующие согласуемые этапы
|
||||
|
||||
1. **2.3 выполнен** — источники, обратные связи и UX «Где используется?» (в локальном mock).
|
||||
2. **2.4** — публикационные состояния и снимки; дополнительные настройки и адаптивная полировка.
|
||||
3. **3** — Эксперт (YAML front matter + Markdown, diff, сохранение одного состояния и конфликты `409`).
|
||||
4. **4–7** — Content, publication/rollback, прочие разделы, затем план интеграции FastAPI + Jinja2 + htmx.
|
||||
|
||||
## QA
|
||||
|
||||
**Навигация по блокам:** в обеих темах выбор из дерева (включая «Связи данных») прокручивает iframe до блока, только если он не помещается в видимой области. При выборе `site_header` прокрутка возвращается к началу; при клике по секции внутри iframe или изменении свойств текущая позиция сохраняется. Добавление, дублирование и перемещение блока ведут к его новой позиции. Для `prefers-reduced-motion: reduce` прокрутка мгновенная, иначе плавная. Дополнительно сохраняется положение прокрутки левого дерева при выборе. Проверено в Playwright/Chromium для двух тем на 1440×900, 1024×768, 390×844 и 360×740: нет горизонтального переполнения или ошибок JS.
|
||||
|
||||
|
||||
Playwright + Chromium: `1440×900`, `1280×800`, `1024×768`, `768×1024`, `390×844`, `360×740` на обоих вариантах; проверена ширина документа, отсутствие JS-ошибок и цепочка добавления / редактирования / перемещения / скрытия / сохранения / валидации. Скриншоты расположены в `previews/`.
|
||||
@@ -0,0 +1,40 @@
|
||||
# Site Engine / Stage 4 — QA
|
||||
|
||||
**Проверено в Chromium (headless) на HTML + локально внедрённых CSS/JS ассетах.** Браузерная политика этой среды блокирует навигацию к `file://` как URL, поэтому сквозные переходы по файловым ссылкам проверены статически (наличие targets, корректные `href`) и на уровне клиентских обработчиков. Это не тест настоящего backend.
|
||||
|
||||
## Пройденные функциональные проверки, обе темы 04 и 06
|
||||
|
||||
- Начальное состояние: открыта коллекция `services`, запись `bots`, селектор «Конструктор» активен.
|
||||
- Изменение Title меняет карточку превью и показывает несохранённое состояние.
|
||||
- «Сохранить черновик» меняет workspace, не переключает Live.
|
||||
- Вкладки: «Связи», «Где используется?», «Схема (READ ONLY)».
|
||||
- Переключение в «Эксперт» создаёт YAML front matter + Markdown body. Редактирование Title, применение исходника, переключение в Конструктор — изменения синхронизируются.
|
||||
- Некорректный YAML остаётся в редакторе. При попытке переключиться видна блокирующая модалка, резервный исходник можно сохранить.
|
||||
- Комментарий YAML сохраняется после применения и возврата из Конструктора в Эксперт.
|
||||
- Конфликт `409 Demo` блокирует сохранение и показывает отдельные варианты разрешения.
|
||||
- Выбор/замена медиа через UI, Live/workspace preview, карточка/полная страница.
|
||||
- Создание, сохранение, дублирование и подтверждённое удаление draft-записи.
|
||||
- +30 демо-записей для большого списка, поиск и фильтры.
|
||||
- В коллекции `cases`, запись `booking`: проверка обнаруживает отсутствующее изображение и направляет к проблемному полю.
|
||||
- В `courses`/`posts` пустые выключенные списки не создают фиктивный контент.
|
||||
- JavaScript-ошибок в указанных сценариях не выявлено.
|
||||
|
||||
## Адаптивность
|
||||
|
||||
| Viewport | Antirion Rework | Rose Graphite |
|
||||
|---|---|---|
|
||||
| 1440×900 | PASS | PASS |
|
||||
| 1280×800 | PASS | PASS |
|
||||
| 1024×768 | PASS | PASS |
|
||||
| 768×1024 | PASS | PASS |
|
||||
| 390×844 | PASS | PASS |
|
||||
| 360×740 | PASS | PASS |
|
||||
|
||||
Проверено отсутствие горизонтального скролла всего документа; на широких экранах независимая прокрутка панелей; на телефоне вертикальный поток.
|
||||
|
||||
## Дополнительные проверки для backend-этапа
|
||||
|
||||
- Работа с настоящими YAML 1.2 и Markdown-файлами, атомарная запись, version/hash, права и CSRF.
|
||||
- Сквозной сценарий сохранённой записи → реальный display render → статическая сборка.
|
||||
- Конкурентное редактирование с реальными 409 ответами сервера и аудиторским журналом.
|
||||
- Полная клавиатурная доступность и screen reader review вне текущего автоматического smoke QA.
|
||||
@@ -0,0 +1,98 @@
|
||||
[
|
||||
{
|
||||
"theme": "antirion",
|
||||
"width": 1440,
|
||||
"height": 900,
|
||||
"overflow": false,
|
||||
"errors": [],
|
||||
"mobile-menu": false
|
||||
},
|
||||
{
|
||||
"theme": "antirion",
|
||||
"width": 1280,
|
||||
"height": 800,
|
||||
"overflow": false,
|
||||
"errors": [],
|
||||
"mobile-menu": false
|
||||
},
|
||||
{
|
||||
"theme": "antirion",
|
||||
"width": 1024,
|
||||
"height": 768,
|
||||
"overflow": false,
|
||||
"errors": [],
|
||||
"mobile-menu": false
|
||||
},
|
||||
{
|
||||
"theme": "antirion",
|
||||
"width": 768,
|
||||
"height": 1024,
|
||||
"overflow": false,
|
||||
"errors": [],
|
||||
"mobile-menu": false
|
||||
},
|
||||
{
|
||||
"theme": "antirion",
|
||||
"width": 390,
|
||||
"height": 844,
|
||||
"overflow": false,
|
||||
"errors": [],
|
||||
"mobile-menu": true
|
||||
},
|
||||
{
|
||||
"theme": "antirion",
|
||||
"width": 360,
|
||||
"height": 740,
|
||||
"overflow": false,
|
||||
"errors": [],
|
||||
"mobile-menu": true
|
||||
},
|
||||
{
|
||||
"theme": "rose-graphite",
|
||||
"width": 1440,
|
||||
"height": 900,
|
||||
"overflow": false,
|
||||
"errors": [],
|
||||
"mobile-menu": false
|
||||
},
|
||||
{
|
||||
"theme": "rose-graphite",
|
||||
"width": 1280,
|
||||
"height": 800,
|
||||
"overflow": false,
|
||||
"errors": [],
|
||||
"mobile-menu": false
|
||||
},
|
||||
{
|
||||
"theme": "rose-graphite",
|
||||
"width": 1024,
|
||||
"height": 768,
|
||||
"overflow": false,
|
||||
"errors": [],
|
||||
"mobile-menu": false
|
||||
},
|
||||
{
|
||||
"theme": "rose-graphite",
|
||||
"width": 768,
|
||||
"height": 1024,
|
||||
"overflow": false,
|
||||
"errors": [],
|
||||
"mobile-menu": false
|
||||
},
|
||||
{
|
||||
"theme": "rose-graphite",
|
||||
"width": 390,
|
||||
"height": 844,
|
||||
"overflow": false,
|
||||
"errors": [],
|
||||
"mobile-menu": true
|
||||
},
|
||||
{
|
||||
"theme": "rose-graphite",
|
||||
"width": 360,
|
||||
"height": 740,
|
||||
"overflow": false,
|
||||
"errors": [],
|
||||
"mobile-menu": true
|
||||
}
|
||||
]
|
||||
@@ -0,0 +1,40 @@
|
||||
# Этап 5 — QA и проверяемые сценарии
|
||||
|
||||
Проверка выполнялась в Chromium headless через Playwright. Из-за ограничений браузерной среды исходники HTML/CSS/JS загружались в тестовую вкладку напрямую (без сетевого или файлового URL). Это позволяет проверить сценарии JS, DOM и CSS, но не является полной проверкой локального file://-режима.
|
||||
|
||||
## Сценарий 1 — Публикация
|
||||
|
||||
1. `index.html` → `publication-antirion.html` / `publication-rose-graphite.html`.
|
||||
2. `Проверить`: обнаруживается ошибка `BIND-001` для `pages/request.md`.
|
||||
3. `Исправить` → `Применить` → `Запустить validate`: блокирующих ошибок 0.
|
||||
4. `Кандидат` → `Сформировать кандидата`: сохраняется полноценный снимок workspace и список изменённых файлов.
|
||||
5. `Опубликовать` → ввести комментарий → `Симулировать публикацию`: live ID становится новым build ID, событие записывается в журнал.
|
||||
|
||||
## Сценарий 2 — История и откат
|
||||
|
||||
1. В `Истории` открыть ранее опубликованный `build_00027`.
|
||||
2. Выбрать `Откат`, посмотреть последствия (количество файлов, версия формы).
|
||||
3. Подтвердить. Live переключается на исторический снимок, workspace не изменяется; запись попадает в аудит.
|
||||
4. Новый кандидат, если был, инвалидируется.
|
||||
|
||||
## Сценарий 3 — Неуспешная сборка и неактуальный кандидат
|
||||
|
||||
1. Нажать `Симулировать сбой` на вкладке «Кандидат».
|
||||
2. Записан failed build, подробности доступны в логе; live ID остаётся неизменным.
|
||||
3. При изменении сохранённых файлов из редактора и последующем обновлении публикации fingerprint перестаёт совпадать с кандидатом; создание свежего кандидата требует повторной проверки.
|
||||
|
||||
## Сценарий 4 — Роли
|
||||
|
||||
Нажать профиль OW/DEV/ED/RV: Owner и Developer могут создать кандидата и публиковать/откатывать; Editor и Reviewer могут проверять, но не создавать и публиковать релизы. Это только клиентская имитация RBAC.
|
||||
|
||||
## Адаптивность
|
||||
|
||||
Проверены 1440×900, 1280×800, 1024×768, 768×1024, 390×844, 360×740 в двух активных темах. Внешнего горизонтального переполнения и ошибок JavaScript в проверенных сценариях нет. На телефоне таблица прокручивается внутри своего контейнера, боковое меню выдвигается по кнопке.
|
||||
|
||||
## Архитектурные ограничения демо
|
||||
|
||||
- Нет FastAPI, атомарного переключения каталогов, сборщика, сервера RBAC, блокировки записи, надежного аудита.
|
||||
- Содержимое редакторов Page/Entry считывается только из **сохранённых** локальных данных; unsaved изменения в других вкладках не видны.
|
||||
- Публикационный снимок в Этапе 5 — отдельная клиентская модель; существующие превью Page/Entry из Этапов 3–4 имеют собственную фиксированную демо-версию live. Полная синхронизация этих моделей требует общего серверного сервиса релизов.
|
||||
- Проверки поддерживают демо-набор ошибок (отсутствующая форма, меню и предупреждения медиа/статусов), а не весь набор Pydantic-схем.
|
||||
- Для обработки форм при rollback требуется проверять контракт версии: старая форма должна поддерживаться текущим обработчиком.
|
||||
@@ -0,0 +1,98 @@
|
||||
[
|
||||
{
|
||||
"theme": "antirion",
|
||||
"width": 1440,
|
||||
"height": 900,
|
||||
"overflow": false,
|
||||
"errors": [],
|
||||
"mobile-menu": false
|
||||
},
|
||||
{
|
||||
"theme": "antirion",
|
||||
"width": 1280,
|
||||
"height": 800,
|
||||
"overflow": false,
|
||||
"errors": [],
|
||||
"mobile-menu": false
|
||||
},
|
||||
{
|
||||
"theme": "antirion",
|
||||
"width": 1024,
|
||||
"height": 768,
|
||||
"overflow": false,
|
||||
"errors": [],
|
||||
"mobile-menu": false
|
||||
},
|
||||
{
|
||||
"theme": "antirion",
|
||||
"width": 768,
|
||||
"height": 1024,
|
||||
"overflow": false,
|
||||
"errors": [],
|
||||
"mobile-menu": false
|
||||
},
|
||||
{
|
||||
"theme": "antirion",
|
||||
"width": 390,
|
||||
"height": 844,
|
||||
"overflow": false,
|
||||
"errors": [],
|
||||
"mobile-menu": true
|
||||
},
|
||||
{
|
||||
"theme": "antirion",
|
||||
"width": 360,
|
||||
"height": 740,
|
||||
"overflow": false,
|
||||
"errors": [],
|
||||
"mobile-menu": true
|
||||
},
|
||||
{
|
||||
"theme": "rose-graphite",
|
||||
"width": 1440,
|
||||
"height": 900,
|
||||
"overflow": false,
|
||||
"errors": [],
|
||||
"mobile-menu": false
|
||||
},
|
||||
{
|
||||
"theme": "rose-graphite",
|
||||
"width": 1280,
|
||||
"height": 800,
|
||||
"overflow": false,
|
||||
"errors": [],
|
||||
"mobile-menu": false
|
||||
},
|
||||
{
|
||||
"theme": "rose-graphite",
|
||||
"width": 1024,
|
||||
"height": 768,
|
||||
"overflow": false,
|
||||
"errors": [],
|
||||
"mobile-menu": false
|
||||
},
|
||||
{
|
||||
"theme": "rose-graphite",
|
||||
"width": 768,
|
||||
"height": 1024,
|
||||
"overflow": false,
|
||||
"errors": [],
|
||||
"mobile-menu": false
|
||||
},
|
||||
{
|
||||
"theme": "rose-graphite",
|
||||
"width": 390,
|
||||
"height": 844,
|
||||
"overflow": false,
|
||||
"errors": [],
|
||||
"mobile-menu": true
|
||||
},
|
||||
{
|
||||
"theme": "rose-graphite",
|
||||
"width": 360,
|
||||
"height": 740,
|
||||
"overflow": false,
|
||||
"errors": [],
|
||||
"mobile-menu": true
|
||||
}
|
||||
]
|
||||
@@ -0,0 +1,33 @@
|
||||
# Этап 6 — отчёт визуального и функционального QA
|
||||
|
||||
**Продукт:** Site Engine · Admin UI (HTML design prototype). 12 ноября 2026.
|
||||
|
||||
## Проверенные функции
|
||||
|
||||
| Сценарий | 04 Antirion Rework | 06 Rose Graphite |
|
||||
|---|---|---|
|
||||
| Медиатека: сетка, выбор, alt и сохранение | PASS | PASS |
|
||||
| Структура: меню, добавление пункта, Fragment usage | PASS | PASS |
|
||||
| Формы: optional/required и предпросмотр | PASS | PASS |
|
||||
| Заявки: скрытие персональных данных для Reviewer | PASS | PASS |
|
||||
| Настройки: новый редирект | PASS | PASS |
|
||||
| Журнал: события, просмотр подробностей | PASS | PASS |
|
||||
| Ctrl+K, быстрый переход к разделу | PASS | PASS |
|
||||
| Основная навигация между пятью разделами | PASS | PASS |
|
||||
|
||||
## Проверка ширины
|
||||
|
||||
Для каждой темы проверены **1440×900, 1280×800, 1024×768, 768×1024, 390×844, 360×740** по основному рабочему экрану. Для каждого из 5 разделов дополнительно проверены desktop 1440 и mobile 390 (в сумме 20 скриншотов, включая обе темы и оба размера). Результаты находятся в `STAGE6_VISUAL_QA.json` и `STAGE6_QA_TEST_OUTPUT.txt`. Ни один проверенный раздел не вызвал горизонтального переполнения документа или незакрытой ошибки JavaScript. Таблицы могут иметь **внутренний** горизонтальный скролл на узком экране — это ожидаемое поведение.
|
||||
|
||||
Тесты выполнялись в Chromium со встроенным `page.set_content` и локальным JS/CSS, поскольку окружение блокирует переходы на localhost. Для фактической локальной проверки готового архива рекомендуется открыть `index.html` или `python -m http.server` в обычном браузере пользователя. Скриншоты делают снимок рабочего макета; не являются подтверждением работы backend.
|
||||
|
||||
## Ограничения / будущая работа
|
||||
|
||||
1. Сохраняемые данные Stage 6 и Stage 5 находятся в отдельных клиентских mock-хранилищах; переход к одному серверному контракту откладывается до backend-интеграции.
|
||||
2. Кнопки «загрузка», «уведомления», «публикация», «MCP scopes» в данном пакете демонстрируют UX, а не соответствующие рабочие системы.
|
||||
3. Состояние безопасности *симулируется*. Требуются серверные RBAC, CSRF, безопасные сессии, аудит и защита PII.
|
||||
4. Код Layout/Fragment и полноценные серверные схемы Form недоступны для изменения из этого этапа; в интерфейсе показан контракт и граница полномочий.
|
||||
5. Ассеты/ссылки используют демонстрационную карту зависимостей, реальный `dependency.references` должен работать в сервисном слое.
|
||||
6. Accessibility: протестированы видимые состояния фокуса и базовые keyboard-сценарии, но полноценный аудит WCAG, screen-reader и кросс-браузерное QA ещё требуется.
|
||||
|
||||
**Статус:** Этап 6 design prototype завершён; следующий этап — техническое планирование интеграции с backend, затем отдельная реализация.
|
||||
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"errors": [],
|
||||
"status": "pass"
|
||||
}
|
||||
@@ -0,0 +1,75 @@
|
||||
{
|
||||
"checks": [
|
||||
{
|
||||
"theme": "rose-graphite",
|
||||
"section": "media",
|
||||
"title": "Медиабиблиотека",
|
||||
"desktopOverflow": 0,
|
||||
"mobileOverflow": 0
|
||||
},
|
||||
{
|
||||
"theme": "rose-graphite",
|
||||
"section": "structure",
|
||||
"title": "Структура сайта",
|
||||
"desktopOverflow": 0,
|
||||
"mobileOverflow": 0
|
||||
},
|
||||
{
|
||||
"theme": "rose-graphite",
|
||||
"section": "forms",
|
||||
"title": "Формы и заявки",
|
||||
"desktopOverflow": 0,
|
||||
"mobileOverflow": 0
|
||||
},
|
||||
{
|
||||
"theme": "rose-graphite",
|
||||
"section": "settings",
|
||||
"title": "Настройки и доступы",
|
||||
"desktopOverflow": 0,
|
||||
"mobileOverflow": 0
|
||||
},
|
||||
{
|
||||
"theme": "rose-graphite",
|
||||
"section": "journal",
|
||||
"title": "Журнал действий",
|
||||
"desktopOverflow": 0,
|
||||
"mobileOverflow": 0
|
||||
},
|
||||
{
|
||||
"theme": "antirion",
|
||||
"section": "media",
|
||||
"title": "Медиабиблиотека",
|
||||
"desktopOverflow": 0,
|
||||
"mobileOverflow": 0
|
||||
},
|
||||
{
|
||||
"theme": "antirion",
|
||||
"section": "structure",
|
||||
"title": "Структура сайта",
|
||||
"desktopOverflow": 0,
|
||||
"mobileOverflow": 0
|
||||
},
|
||||
{
|
||||
"theme": "antirion",
|
||||
"section": "forms",
|
||||
"title": "Формы и заявки",
|
||||
"desktopOverflow": 0,
|
||||
"mobileOverflow": 0
|
||||
},
|
||||
{
|
||||
"theme": "antirion",
|
||||
"section": "settings",
|
||||
"title": "Настройки и доступы",
|
||||
"desktopOverflow": 0,
|
||||
"mobileOverflow": 0
|
||||
},
|
||||
{
|
||||
"theme": "antirion",
|
||||
"section": "journal",
|
||||
"title": "Журнал действий",
|
||||
"desktopOverflow": 0,
|
||||
"mobileOverflow": 0
|
||||
}
|
||||
],
|
||||
"errors": []
|
||||
}
|
||||
@@ -0,0 +1,32 @@
|
||||
started content-antirion.html Telegram-боты {'collection': 'services', 'id': 'bots', 'mode': 'constructor', 'tab': 'fields', 'dirty': False, 'sourceDirty': False, 'issues': [{'severity': 'warning', 'field': 'related_scenarios', 'message': 'Связанная запись services пока не опубликована'}], 'live': 'build_00027', 'records': 8}
|
||||
save msg Сохранено в workspace; live-релиз не изменён
|
||||
source len 518 ---
|
||||
schema: 1
|
||||
collection: "services"
|
||||
id: "bots"
|
||||
status: "published"
|
||||
title: "Tele
|
||||
PASS content-antirion.html errors []
|
||||
started content-rose-graphite.html Telegram-боты {'collection': 'services', 'id': 'bots', 'mode': 'constructor', 'tab': 'fields', 'dirty': False, 'sourceDirty': False, 'issues': [{'severity': 'warning', 'field': 'related_scenarios', 'message': 'Связанная запись services пока не опубликована'}], 'live': 'build_00027', 'records': 8}
|
||||
save msg Сохранено в workspace; live-релиз не изменён
|
||||
source len 518 ---
|
||||
schema: 1
|
||||
collection: "services"
|
||||
id: "bots"
|
||||
status: "published"
|
||||
title: "Tele
|
||||
PASS content-rose-graphite.html errors []
|
||||
VIEW content-antirion.html 1440 900 {'sw': 1440, 'iw': 1440, 'sh': 900, 'ih': 900} errors []
|
||||
VIEW content-rose-graphite.html 1440 900 {'sw': 1440, 'iw': 1440, 'sh': 900, 'ih': 900} errors []
|
||||
VIEW content-antirion.html 1280 800 {'sw': 1280, 'iw': 1280, 'sh': 800, 'ih': 800} errors []
|
||||
VIEW content-rose-graphite.html 1280 800 {'sw': 1280, 'iw': 1280, 'sh': 800, 'ih': 800} errors []
|
||||
VIEW content-antirion.html 1024 768 {'sw': 1024, 'iw': 1024, 'sh': 2421, 'ih': 768} errors []
|
||||
VIEW content-rose-graphite.html 1024 768 {'sw': 1024, 'iw': 1024, 'sh': 2421, 'ih': 768} errors []
|
||||
VIEW content-antirion.html 768 1024 {'sw': 768, 'iw': 768, 'sh': 2788, 'ih': 1024} errors []
|
||||
VIEW content-rose-graphite.html 768 1024 {'sw': 768, 'iw': 768, 'sh': 2788, 'ih': 1024} errors []
|
||||
VIEW content-antirion.html 390 844 {'sw': 390, 'iw': 390, 'sh': 3085, 'ih': 844} errors []
|
||||
VIEW content-rose-graphite.html 390 844 {'sw': 390, 'iw': 390, 'sh': 3085, 'ih': 844} errors []
|
||||
VIEW content-antirion.html 360 740 {'sw': 360, 'iw': 360, 'sh': 3144, 'ih': 740} errors []
|
||||
VIEW content-rose-graphite.html 360 740 {'sw': 360, 'iw': 360, 'sh': 3144, 'ih': 740} errors []
|
||||
PASS extras content-antirion.html errors []
|
||||
PASS extras content-rose-graphite.html errors []
|
||||
@@ -0,0 +1,40 @@
|
||||
from playwright.sync_api import sync_playwright
|
||||
from pathlib import Path
|
||||
import json
|
||||
base=Path('/mnt/data/site-engine-admin-stage5')
|
||||
with sync_playwright() as pw:
|
||||
b=pw.chromium.launch(headless=True, executable_path='/usr/bin/chromium',args=['--no-sandbox','--disable-gpu','--disable-dev-shm-usage'])
|
||||
for mode in ('antirion','rose-graphite'):
|
||||
file=f'publication-{mode}.html'
|
||||
page=b.new_page(viewport={'width':1440,'height':900},device_scale_factor=1)
|
||||
logs=[]
|
||||
page.on('pageerror', lambda e: logs.append(str(e)))
|
||||
print('\nTEST',file)
|
||||
try:
|
||||
html=(base/file).read_text();css=(base/'assets/publication.css').read_text();js=(base/'assets/publication.js').read_text();html=html.replace('<link rel="stylesheet" href="assets/publication.css">','<style>'+css+'</style>').replace('<script src="assets/publication.js" defer></script>','<script>'+js+'</script>');page.set_content(html,wait_until='load',timeout=20000)
|
||||
print('title',page.title(),'tabs',page.locator('.tabs .tab').count(),'deltas',page.locator('.table tbody tr').count())
|
||||
page.screenshot(path=str(base/'previews'/f'stage5-{mode}-changes-1440.png'),full_page=True)
|
||||
page.get_by_role('button',name='Проверить',exact=False).first.click()
|
||||
print('checks',page.locator('.check.bad').count(),page.locator('.check.warn').count())
|
||||
page.get_by_role('button',name='Исправить').first.click()
|
||||
page.get_by_role('button',name='Применить').click()
|
||||
page.get_by_role('button',name='Запустить validate').click()
|
||||
print('validation',page.locator('.check.bad').count())
|
||||
page.get_by_role('button',name='Кандидат').first.click()
|
||||
print('candidate tab',page.locator('.tab.active').inner_text())
|
||||
page.get_by_role('button',name='Сформировать кандидата').click()
|
||||
print('after candidate',page.locator('.panel-body .mono').all_inner_texts()[:3])
|
||||
page.get_by_role('button',name='Опубликовать',exact=True).click()
|
||||
print('modal',page.locator('.dialog h2').inner_text())
|
||||
page.get_by_role('button',name='Симулировать публикацию').click()
|
||||
print('newlive',page.locator('.live-indicator').inner_text())
|
||||
page.get_by_role('button',name='Откат',exact=True).first.click()
|
||||
print('rollback dialog',page.locator('.dialog h2').inner_text())
|
||||
page.get_by_role('button',name='Подтвердить демо-откат').click()
|
||||
print('after rollback',page.locator('.live-indicator').inner_text())
|
||||
page.screenshot(path=str(base/'previews'/f'stage5-{mode}-history-1440.png'),full_page=True)
|
||||
print('pageerrors',logs)
|
||||
except Exception as e:
|
||||
print('FAILED',repr(e));page.screenshot(path=str(base/'previews'/f'stage5-{mode}-failed.png'),full_page=True)
|
||||
page.close()
|
||||
b.close()
|
||||
@@ -0,0 +1,31 @@
|
||||
from pathlib import Path
|
||||
from playwright.sync_api import sync_playwright
|
||||
import json
|
||||
base=Path('/mnt/data/site-engine-admin-stage5')
|
||||
def inline(file):
|
||||
html=(base/file).read_text();css=(base/'assets/publication.css').read_text();js=(base/'assets/publication.js').read_text();return html.replace('<link rel="stylesheet" href="assets/publication.css">','<style>'+css+'</style>').replace('<script src="assets/publication.js" defer></script>','<script>'+js+'</script>')
|
||||
checks=[]
|
||||
with sync_playwright() as pw:
|
||||
br=pw.chromium.launch(headless=True,executable_path='/usr/bin/chromium',args=['--no-sandbox','--disable-gpu','--disable-dev-shm-usage'])
|
||||
for kind in ('antirion','rose-graphite'):
|
||||
for w,h in [(1440,900),(1280,800),(1024,768),(768,1024),(390,844),(360,740)]:
|
||||
pg=br.new_page(viewport={'width':w,'height':h},device_scale_factor=1)
|
||||
errors=[];pg.on('pageerror',lambda ex:errors.append(str(ex)))
|
||||
pg.set_content(inline(f'publication-{kind}.html'),wait_until='load')
|
||||
overflow=pg.evaluate('document.documentElement.scrollWidth > window.innerWidth')
|
||||
menu=pg.locator('.mobile-menu').is_visible()
|
||||
checks.append({'theme':kind,'width':w,'height':h,'overflow':overflow,'errors':errors,'mobile-menu':menu})
|
||||
if w==390:
|
||||
pg.locator('.mobile-menu').click();assert 'menu-open' in pg.locator('.layout').get_attribute('class')
|
||||
pg.locator('.mobile-cover').click();assert 'menu-open' not in pg.locator('.layout').get_attribute('class')
|
||||
pg.screenshot(path=str(base/'previews'/f'stage5-{kind}-390.png'),full_page=True)
|
||||
if w==1440:
|
||||
pg.locator('[data-tab="checks"]').click()
|
||||
pg.screenshot(path=str(base/'previews'/f'stage5-{kind}-checks-1440.png'),full_page=True)
|
||||
pg.locator('[data-tab="history"]').click()
|
||||
pg.screenshot(path=str(base/'previews'/f'stage5-{kind}-history-initial.png'),full_page=True)
|
||||
pg.close()
|
||||
br.close()
|
||||
print(json.dumps(checks,ensure_ascii=False,indent=2))
|
||||
assert all(not x['overflow'] and not x['errors'] for x in checks)
|
||||
(base/'docs'/'STAGE5_QA.json').write_text(json.dumps(checks,ensure_ascii=False,indent=2))
|
||||
@@ -0,0 +1,21 @@
|
||||
# Stage7 и реализация 001
|
||||
|
||||
Приоритет и границы задаёт [specs/001-antirion-admin](../../../specs/001-antirion-admin/spec.md). Реализованный контракт и запуск: [runtime.md](../../../specs/001-antirion-admin/runtime.md); проверки: [verification.md](../../../specs/001-antirion-admin/verification.md). Stage7 сохраняется как история предложений, исходные reference-документы не переписываются.
|
||||
|
||||
| Область | Состояние и контракт |
|
||||
|---|---|
|
||||
| Файлы и композиция | Реализованы dataclass, Page/Entry/Layout/Fragment, regions/slots, bind/link/query. Не переносить модель в БД/Pydantic-ядро. |
|
||||
| YAML | Использовать query wrapper, richtext.content, hidden/requires; visibility не существует. Примеры исправлены под default и коллекцию services. |
|
||||
| HTTP UI | Существующие URL сохраняются, публикация /admin/publish, поля csrf/etag. |
|
||||
| 001 API | JSON /admin/api/v1/ + Pydantic DTO; htmx получает HTML от UI, серверный клиент использует ASGITransport. |
|
||||
| Обзор и Pages, повторный перенос | Общий каркас принят; этап 2 подготовлен к проверке: оригинальные overview/pages, HTML-фильтры и выбор инспектора, создание draft. `PageRow.changed` сравнивает файл с активным релизом; новые manifests содержат SHA-256 опубликованных Page в `page_sources`, для старых без индекса сравнение неизвестно. Это не dependency diff/candidate из 002. Подробности и проверки — [design-transfer.md](../../../specs/001-antirion-admin/design-transfer.md). |
|
||||
| Запись | ETag — SHA-256 байтов, один SiteLock, CAS/проверка/история/атомарная запись. Буфер меняется без записи, Save явный. |
|
||||
| Превью | 001: отдельный origin, scoped token, epoch, CSP и проверенный postMessage. |
|
||||
| Релизы | Существующий build сразу публикует. Immutable candidate/expected_live относятся к 002. |
|
||||
| Медиа/структура | Загрузки, where-used, changeset/rename и настройки относятся к 003. |
|
||||
| Доступ | Один env-admin в 001; пользователи/RBAC/audit UI — 004. |
|
||||
| Формы/MCP | HTTP 501 и заготовки не являются готовыми возможностями; 005/006. |
|
||||
|
||||
Номера ADR stage7 обозначают локальные предложения, а не замену [действующего журнала](../../../docs/TZ-site-engine-decisions.md). Stage7 ADR-001/002/004/005 пересекаются с действующими решениями о файлах, композиции, CAS и безопасности; уточнения 001 задаются её спецификацией. Stage7 ADR-003 про кандидаты относится к 002, ADR-006 — дорожная карта. Статус PROPOSED в исходном реестре сохранён; новые решения не объявляются принятыми задним числом.
|
||||
|
||||
Примеры `examples/page-home.md` и `examples/entry-bots.md` подставлены вместо Page/Entry в изолированную копию studio-site: validate — 0 ошибок/0 предупреждений, build — 7 страниц.
|
||||
@@ -0,0 +1,146 @@
|
||||
# 01. Целевая архитектура Site Engine
|
||||
|
||||
## 1. Принятый архитектурный ориентир
|
||||
|
||||
**Модульный монолит Python, один сайт на инстанс.** Данный раздел — проект реализации в рамках исходного ТЗ, не описание уже готового backend.
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
U[Browser / htmx] --> H[FastAPI HTML routes]
|
||||
AP[REST clients] --> A[FastAPI API routes]
|
||||
MCP[MCP tools] --> S[Application services]
|
||||
CLI[CLI] --> S
|
||||
H --> S
|
||||
A --> S
|
||||
S --> P[Policies + validation + CAS + audit]
|
||||
P --> R[File repositories / changesets]
|
||||
P --> Q[Service repositories]
|
||||
R --> F[(Canonical Site Files)]
|
||||
Q --> D[(SQLite WAL)]
|
||||
S --> B[Preview / Build / Release pipeline]
|
||||
B --> F
|
||||
B --> I[(Immutable build snapshots)]
|
||||
I --> L[Live pointer / static server]
|
||||
```
|
||||
|
||||
**Логические слои:**
|
||||
|
||||
- `web/admin`: Jinja HTML, htmx partials, формы, обработка 409/422, UX навигация.
|
||||
- `web/api`: контракт для технических клиентов, тот же application service, не HTTP loopback из admin.
|
||||
- `mcp` и `cli`: адаптеры поверх сервисов, со своей аутентификацией/контекстом actor.
|
||||
- `application`: use cases, транзакционные границы, права, валидаторы, аудит, idempotency.
|
||||
- `domain`: модели Page/Entry/Layout/Fragment/Block/Release; разрешение привязок и маршрутов, инварианты.
|
||||
- `infrastructure`: работа с файлами, SQLite, render/build, preview, уведомления, индекс зависимостей.
|
||||
|
||||
## 2. Предлагаемая структура Python-пакета
|
||||
|
||||
```text
|
||||
site_engine/
|
||||
app.py # FastAPI app factory
|
||||
config.py # только env/path/runtime-секреты
|
||||
web/
|
||||
admin/
|
||||
routes.py # shell, pages, content, media, publication, ...
|
||||
templates/ # Jinja pages + partials
|
||||
static/ # согласованные CSS/JS, htmx локально
|
||||
api/v1/ # machine-readable endpoints
|
||||
public/ # формы, служебные endpoints, dev static
|
||||
application/
|
||||
pages.py # get/patch/rename, read/write conflicts
|
||||
entries.py # типизированный контент
|
||||
dependencies.py # где используется?
|
||||
media.py
|
||||
structure.py
|
||||
forms.py
|
||||
settings.py
|
||||
releases.py # validate/candidate/publish/rollback
|
||||
auth.py
|
||||
audit.py
|
||||
domain/
|
||||
models.py # Pydantic models + typed refs
|
||||
bindings.py
|
||||
validators.py
|
||||
routing.py
|
||||
errors.py
|
||||
infrastructure/
|
||||
files.py # safe paths, atomic write, changeset
|
||||
sqlite.py # SQLAlchemy models & sessions
|
||||
index.py # reindex, dependency index
|
||||
renderer.py # Jinja/layout/fragment, markdown
|
||||
builder.py # snapshot → dist/build-id
|
||||
preview.py
|
||||
notifications.py # SQLite outbox worker
|
||||
storage.py # asset ingest, MIME & quotas
|
||||
mcp/
|
||||
cli/
|
||||
migrations/ # Alembic для SQLite service data
|
||||
tests/
|
||||
site/ # file-first content root; вне Python package
|
||||
site.yaml
|
||||
redirects.yaml
|
||||
pages/
|
||||
content/
|
||||
collections/
|
||||
display/
|
||||
layouts/
|
||||
fragments/
|
||||
menus/
|
||||
data/
|
||||
forms/
|
||||
assets/
|
||||
var/ # не переносимый публичный контент
|
||||
db/site-engine.sqlite
|
||||
work/changesets/
|
||||
builds/<build_id>/
|
||||
live-pointer
|
||||
```
|
||||
|
||||
Это **предлагаемая** организация, а не подтверждённые имена импортов. Отделение `site/` и `var/` принципиально: `reindex` не требует старой DB для восстановления страниц, маршрутов и редиректов.
|
||||
|
||||
## 3. Владение данными
|
||||
|
||||
| Данные | Канонический источник | SQLite |
|
||||
|---|---|---|
|
||||
| Page + Markdown body | `site/pages/**/*.md` | только индекс и внешние ключи на стабильные ID |
|
||||
| Entry | `site/content/<collection>/*.md` | индекс и поиск по полям |
|
||||
| Collection, Display | `site/collections/*.yaml`, `site/display/*.yaml` | перестраиваемые записи |
|
||||
| Layout/Fragment/Menu/Data/Form/Site/Redirect | соответствующие YAML и шаблоны в `site/` | кэш, индекс зависимостей |
|
||||
| Asset | `site/assets/*`, sidecar manifest если утверждён | хеш, metadata cache, usage index |
|
||||
| User, session, token hash, roles/grants | SQLite | источник истины служебных данных |
|
||||
| Submission, outbox, audit event | SQLite | источник истины служебных данных |
|
||||
| Release metadata, publish events | SQLite + immutable snapshot manifest | синхронизированный служебный индекс; live определяется валидным pointer |
|
||||
|
||||
**Важно:** `slug_history` как скрытый SQLite-источник публичных редиректов недопустим по принципу file-first; при переименовании URI обновляется `redirects.yaml` тем же changeset. Это предложение ревью P0-01, фиксируется ADR-001.
|
||||
|
||||
## 4. Единый запрос без дублирования логики
|
||||
|
||||
```text
|
||||
Browser POST /admin/pages/{id}/blocks/patch
|
||||
-> auth/session + CSRF
|
||||
-> PageService.patch(actor, id, operations, if_match)
|
||||
-> authorize(actor, "pages.write", target)
|
||||
-> open document lock; verify hash; parse + schema validate
|
||||
-> build next document; atomic changeset commit
|
||||
-> update index; audit event
|
||||
-> return PageSnapshot {document, etag, validation}
|
||||
-> Jinja partials: tree, inspector, preview target, status
|
||||
|
||||
MCP patch_page -> same PageService.patch(...)
|
||||
CLI page patch -> same PageService.patch(...)
|
||||
```
|
||||
|
||||
Права и валидация не зависят от выбранной темы и интерфейса.
|
||||
|
||||
## 5. Источники изменений UI
|
||||
|
||||
Для FastAPI/htmx **нет необходимости копировать большой JS-state** из прототипа. Сервер является источником общего состояния Page/Entry. Клиент хранит только кратковременный UI-state: выбранный блок, вкладку инспектора, открытое дерево, размер iframe и неотправленный текст Expert. После успешной операции сервер возвращает новые фрагменты интерфейса и `ETag`.
|
||||
|
||||
Обе темы используют одни Jinja partials с небольшим классом корневой темы (`theme-antirion` / `theme-rose`) и CSS-токенами. 03 и 05 на этом шаге сохраняются как отдельные дизайн-концепты, не обязаны иметь новые backend-маршруты.
|
||||
|
||||
## 6. Важные ограничения первой версии
|
||||
|
||||
- Одна инсталляция — один сайт; мультисайтовости и e-commerce нет.
|
||||
- Контент редактируется декларативно; свободный JS/Jinja/Python в режиме Expert запрещён, нужен отдельный developer workflow.
|
||||
- Сначала детерминированная **полная сборка**; сложная инкрементальная сборка и широкий query DSL — только после реальных метрик и ADR.
|
||||
- Сохранение синтаксически корректного, но неполного черновика допускается; публикация всегда со строгой валидацией.
|
||||
- Реализация публичных форм и MCP возможна только после базовых auth/RBAC/CSRF/audit/обработки файлов.
|
||||
@@ -0,0 +1,110 @@
|
||||
# 02. Карта UI → Jinja partials → htmx → application services
|
||||
|
||||
**Статус:** предлагаемый HTTP-контракт для будущей реализации. Прототипы работают в браузере и НЕ имеют этих endpoints. URL-имена согласовать при первом вертикальном срезе.
|
||||
|
||||
## 1. Экранный маршрут
|
||||
|
||||
| Навигация | HTML route (GET) | Jinja page | Ключевые partials | Сервисы |
|
||||
|---|---|---|---|---|
|
||||
| Обзор | `/admin` | `overview/index.html` | `_status`, `_changes`, `_recent_activity` | `SiteStatus`, `ReleaseService`, `AuditService` |
|
||||
| Страницы | `/admin/pages` | `pages/list.html` | `_table`, `_filters`, `_summary` | `PageService.list/get` |
|
||||
| Page: Конструктор | `/admin/pages/{id}/edit?mode=constructor` | `pages/editor.html` | `_block_tree`, `_canvas`, `_inspector`, `_mapping`, `_toolbar` | `PageService`, `FragmentCatalog`, `PreviewService`, `DependencyService` |
|
||||
| Page: Эксперт | `/admin/pages/{id}/edit?mode=expert` | тот же `pages/editor.html` | `_source_editor`, `_lint`, `_diff`, `_preview`, `_toolbar` | `PageService`, `SourceService`, `ValidationService` |
|
||||
| Контент | `/admin/content` | `content/index.html` | `_collections`, `_entries`, `_filter`, `_empty` | `CollectionService`, `EntryService` |
|
||||
| Entry: редактор | `/admin/content/{collection}/{slug}/edit?mode=constructor\|expert` | `content/editor.html` | `_schema_fields`, `_source`, `_relations`, `_display_preview` | `EntryService`, `CollectionService`, `PreviewService` |
|
||||
| Публикация | `/admin/publication` | `publication/index.html` | `_workspace_changes`, `_validation`, `_candidate`, `_history`, `_release_detail`, `_audit` | `ReleaseService`, `BuildService`, `AuditService` |
|
||||
| Медиа | `/admin/media` | `media/index.html` | `_grid`, `_table`, `_picker`, `_asset_detail`, `_usage` | `AssetService`, `DependencyService` |
|
||||
| Структура | `/admin/structure` | `structure/index.html` | `_menus`, `_menu_editor`, `_layouts`, `_fragments`, `_display` | `MenuService`, `LayoutService`, `FragmentService`, `DisplayService` |
|
||||
| Формы и заявки | `/admin/forms` | `forms/index.html` | `_form_fields`, `_schema`, `_submissions`, `_delivery` | `FormService`, `SubmissionService`, `OutboxService` |
|
||||
| Настройки | `/admin/settings` | `settings/index.html` | `_site`, `_theme`, `_data`, `_redirects`, `_users`, `_agents`, `_build` | `SettingsService`, `AccessService`, `RedirectService` |
|
||||
| Журнал | `/admin/audit` | `audit/index.html` | `_filter`, `_events`, `_details` | `AuditService` |
|
||||
|
||||
Нормальный вход в редактор — `mode=constructor`; верхний селектор должен показывать **«Конструктор»**. Переход в Expert не создаёт второй документ. Этим устраняется ранее найденная UI-регрессия.
|
||||
|
||||
## 2. Общая схема htmx взаимодействий
|
||||
|
||||
Все HTML-запросы рендерятся FastAPI + Jinja. `hx-post`/`hx-patch` → **application service** → partial/redirect. Не создавать второй внутренний REST-вызов с того же сервера.
|
||||
|
||||
| Сценарий | htmx request (рекомендация) | Фрагменты для обновления |
|
||||
|---|---|---|
|
||||
| Фильтр страниц | `GET /admin/partials/pages?query=&status=` | `#page-table`, `#page-count` |
|
||||
| Выбор блока в дереве | `GET /admin/partials/pages/{id}/blocks/{block_id}/inspector` | `#block-inspector`, selection state |
|
||||
| Изменение props | `PATCH /admin/pages/{id}/blocks/{block_id}` + `if_match`, CSRF | `#block-inspector`, `#tree`, `#dirty-status`, preview target |
|
||||
| Добавление/движение | `POST /admin/pages/{id}/operations` с типизированными ops | `#block-tree`, `#preview`, `#inspector` |
|
||||
| Выбор привязки | `POST /admin/pages/{id}/operations` | `#mapping`, `#inspector`, `#preview` |
|
||||
| Проверка | `POST /admin/validate?scope=workspace` (не меняет файл) | `#validation-panel`, summary |
|
||||
| Режим Expert | `GET /admin/partials/pages/{id}/source` | редактор + code status |
|
||||
| Применить Expert | `PUT /admin/pages/{id}/source` + `if_match` | source diagnostics, tree, preview, dirty status |
|
||||
| Сохранить черновик | `POST /admin/pages/{id}/save` или `PATCH ...` | статус и новый ETag |
|
||||
| Данные записи | `GET /admin/partials/content/{collection}/{slug}` | editor/relations/preview |
|
||||
| Выбор медиа | `GET /admin/partials/media/picker?kind=image` | modal contents |
|
||||
| Сборка кандидата | `POST /admin/publication/candidates` | candidate panel + build log |
|
||||
| Подтвердить publish | `POST /admin/publication/{build_id}/publish` | live status, history, audit |
|
||||
| Подтвердить rollback | `POST /admin/publication/{build_id}/rollback` | live status, history, audit |
|
||||
|
||||
Пример *эскиза* Jinja/htmx (не готовая реализация):
|
||||
|
||||
```html
|
||||
<form hx-patch="/admin/pages/{{ page.id }}/blocks/{{ block.id }}"
|
||||
hx-target="#block-inspector" hx-swap="outerHTML">
|
||||
<input type="hidden" name="if_match" value="{{ page.etag }}">
|
||||
<input type="hidden" name="csrf_token" value="{{ csrf_token }}">
|
||||
<label>Заголовок <input name="props.title" value="{{ block.props.title }}"></label>
|
||||
<button type="submit">Применить</button>
|
||||
</form>
|
||||
```
|
||||
|
||||
Нельзя вставлять `page.id`/`block.id` из непроверенного URL в произвольный файловый путь. Не доверять `if_match` и CSRF как доказательству прав: нужен server-side RBAC.
|
||||
|
||||
## 3. Переключение Constructor ↔ Expert
|
||||
|
||||
1. GET страницы с `?mode=constructor` (явно активен селектор «Конструктор»).
|
||||
2. В Constructor любое сохранённое изменение меняет канонический файл через PageService. В UI виден актуальный `ETag`.
|
||||
3. Выбор `Expert` открывает исходник **той же ревизии**, в том числе Markdown body; не дублирует состояние в другой таблице.
|
||||
4. При синтаксической ошибке YAML Expert остаётся на экране, показывает line/path, сохранение отклоняет; необработанный текст сохраняется **в UI buffer**, не попадает в канонический документ.
|
||||
5. При switch back с неопубликованным исходником: `Применить и перейти` / `Остаться` / `Сохранить резервную копию текста` (с оповещением). Никаких тихих автопереписываний комментариев.
|
||||
6. При `409` от сервера: отдельная панель `Моя версия / Текущая версия на сервере`; повторная отправка только на новом `if_match` после осознанного разрешения.
|
||||
|
||||
**Конструктор и Эксперт должны сериализовать одно структурное дерево**. Прототипный `expert-codec.js` — образец UX, не полноценный YAML runtime; серверный парсер должен поддерживать принятую схему и запрещать/обрабатывать дополнительные конструкции явно.
|
||||
|
||||
## 4. Preview ↔ дерево и инспектор
|
||||
|
||||
Это уже утверждённый UX и его необходимо сохранить при переводе на серверный рендер:
|
||||
|
||||
- Клик в iframe по блоку → подсветка, синхронизация дерева/инспектора, **без прокрутки**.
|
||||
- Клик по блоку в дереве → preview scroll к блоку **только если он за пределами видимости**; если в пределах видимости, только выделение.
|
||||
- Добавление/перестановка → переход к новому положению; изменение поля → не сбрасывать позицию iframe.
|
||||
- Верх/фиксированный `site_header` → переход к началу.
|
||||
- Учёт `prefers-reduced-motion`.
|
||||
|
||||
Для preview использовать отдельный защищённый endpoint (в идеале отдельный origin), односторонний минимальный `postMessage` протокол с проверкой `origin`, `source` и `event.kind`; не использовать production-`'*'` из mock. При обновлении preview после PATCH лучше targeted refresh/DOM morph, сохраняющий scroll, либо явное сохранение+восстановление позиции.
|
||||
|
||||
## 5. Представление ошибок/статусов и кодов
|
||||
|
||||
| HTTP status | UI-состояние |
|
||||
|---|---|
|
||||
| `200` | Обновить нужный Jinja partial; вернуть новый ETag |
|
||||
| `201` | Новый объект; открыть редактор или строку списка |
|
||||
| `303` | После create/save полной формы перенаправить на GET |
|
||||
| `400` | Ошибка контракта запроса, показать generic form error |
|
||||
| `401` | Логин/истекшая сессия, безопасное перенаправление |
|
||||
| `403` | Явное «Нет доступа», без утечки данных |
|
||||
| `404` | Не найден объект (или скрытый по политике ресурс) |
|
||||
| `409` | Конфликт `if_match`, сохранить локальный buffer, показать сравнение |
|
||||
| `413` | Превышен лимит upload |
|
||||
| `422` | Схемная/публикационная валидация с `field_path` |
|
||||
| `429` | Rate-limit с понятной подсказкой |
|
||||
| `500` | Не показывать трассировку/секреты; корреляционный ID и ссылка на журнал (если есть право) |
|
||||
|
||||
**HTMX ошибки не заменять пустым контентом.** Для `409/422` используется custom `HX-Trigger`/обработчик `htmx:responseError` для соответствующей модалки; JSON API отдаёт Problem Details или согласованный JSON error DTO. Семантика одинаковая, формат ответа различается.
|
||||
|
||||
## 6. Две темы без раздвоения функциональности
|
||||
|
||||
- `base.html` и одинаковые partials; темы отличаются токенами и классом темы.
|
||||
- Утверждённые стили 04/06 — визуальный baseline; нельзя «случайно» заменить все таблицы 06 на прямоугольные.
|
||||
- `HX-Push-Url`/`hx-boost` для навигации, история и клавиатура доступны без SPA.
|
||||
- Тесты компонентов: состав данных, ошибки, mobile, focus и screenshot на 1440×900 / 390×844.
|
||||
|
||||
## 7. Рекомендуемые точки локальной интеграции JS
|
||||
|
||||
Небольшой JS остаётся для Monaco/EasyMDE (после отдельного решения), iframe bridge, drag-sort, viewport selector, toast, focus-management. Не требуется переписывать весь Python backend в браузер и поддерживать параллельный store. htmx и Jinja — основной канал рендера и обновлений.
|
||||
@@ -0,0 +1,144 @@
|
||||
# 03. Контракты документов, application services и API
|
||||
|
||||
## 1. Canonical file model
|
||||
|
||||
Содержимое сайта переносится вместе с `site/`: Page (`pages/**/*.md`), Entry (`content/<collection>/*.md`), `collections/*.yaml`, `display/*.yaml`, layouts/fragments, `menus/*.yaml`, `forms/*.yaml`, `data/*.yaml`, `assets/`, `redirects.yaml`, `site.yaml`. Схема каталога описана в первичном ТЗ §4.
|
||||
|
||||
### Page
|
||||
|
||||
YAML front matter + Markdown body. Общие поля: `schema`, `title`, `layout`, `status`, `seo`, `regions`. Список `regions.main[]` содержит блоки со стабильным `id`, `fragment`, `props`, опциональными `slots`, `anchor`, `visibility`, `note`. Фиксированные header/footer принадлежат Layout, не копируются на каждую страницу.
|
||||
|
||||
**Сохраняемый формат привязок:** в черновике ТЗ встречаются `{bind: page.title}`, `{page: contacts}`, `{entry: services/bots}`, `{collection: services, sort: order, limit: 6}`, а в JS-прототипе отдельное поле `bindings[key]={kind,...}`. Это **не равнозначные контракты**. Предлагается нормализованная типизированная внутренняя модель, сериализация — после ADR-002. Не сохранять слепо JS-поле `bindings` отдельно от `props`.
|
||||
|
||||
См. полноценный образец `examples/page-home.md` с корректными маркерами YAML front matter `---` и Markdown body. Это иллюстрация **предлагаемого** формата: окончательную сериализацию привязок фиксируем в ADR-002.
|
||||
|
||||
### Entry
|
||||
|
||||
Типизированная запись `content/<collection>/<slug>.md`; схема полей — в `collections/<collection>.yaml`; вывод через `display/<collection>.yaml`. Одна Entry не равна Page. В прототипе есть `fields`, `relations`, `body`, `slug`, `status` — это UI DTO, он не должен стать второй файловой моделью.
|
||||
|
||||
### Layout / Fragment / Menu / Asset
|
||||
|
||||
- Layout объявляет регионы, fixed блоки и `allow`.
|
||||
- Fragment имеет декларативные fields и слоты, серверное разрешение типов и constraints.
|
||||
- Menu и Redirect — YAML; `rename_page` атомарно переносит Page, правит связи/меню/redirects через changeset (не обязательно автоматически переписывать каждую внешнюю ссылку).
|
||||
- Asset path — относительный и нормализованный; metadata/alt/caption — нужен отдельный ADR по размещению sidecar (файловый canonical) vs индекс DB; пользовательские тексты не должны исчезать после `reindex`.
|
||||
|
||||
## 2. Два уровня валидации
|
||||
|
||||
| Уровень | Условия | Итог |
|
||||
|---|---|---|
|
||||
| `draft` | Валиден YAML/Markdown front matter, базовые типы, путь/ID, безопасность | Сохранить неполный документ; выдать предупреждения о required/ссылках |
|
||||
| `release` | Полные обязательные поля, версия фрагмента, allowed region/slots, uniqueness routes, все публичные references/media/forms, безопасность | Блокирующие errors запрещают кандидат; warnings допускаются |
|
||||
|
||||
Ошибочный синтаксис Expert остаётся клиентским буфером (возможно отдельным серверным draft-source хранилищем **по ADR**), не перезаписывает canonical doc.
|
||||
|
||||
## 3. DTO и результат сервиса
|
||||
|
||||
Псевдосхема сервисных DTO (для обсуждения, не реализованные Pydantic классы):
|
||||
|
||||
```text
|
||||
PageSnapshot:
|
||||
id: stable logical id
|
||||
path: site-relative path
|
||||
etag: sha256(canonical bytes + model schema version)
|
||||
document: PageDocument
|
||||
source_text: text (для Expert по доступу)
|
||||
diagnostics: Diagnostic[]
|
||||
workspace_revision: string
|
||||
|
||||
Diagnostic:
|
||||
severity: error | warning
|
||||
code: e.g. REF_MISSING, ROUTE_COLLISION, FIELD_REQUIRED
|
||||
file: pages/index.md
|
||||
path: regions.main[1].props.source
|
||||
block_id: services_list (optional)
|
||||
line: integer (optional)
|
||||
message: localized human-readable text
|
||||
hint: optional
|
||||
|
||||
ActionContext:
|
||||
actor_id, actor_type, roles, scopes, request_id, expected_etag
|
||||
```
|
||||
|
||||
Стабильные ID блоков полезны для ссылок/операций, но **сами по себе не обеспечивают конкурентную безопасность**.
|
||||
|
||||
## 4. Основные application service операции
|
||||
|
||||
| Сервис | Use cases (предлагаемые имена) | Важные инварианты |
|
||||
|---|---|---|
|
||||
| `PageService` | `list/get/create/patch/move_block/delete/rename/get_source/save_source` | if_match, typed ops, safe path, fixed region protected |
|
||||
| `EntryService` | `list/get/create/patch/save_source/delete` | collection schema + display route, distinct Page/Entry |
|
||||
| `CollectionService` | `list/get_schema` | content role читает; developer меняет schema/code |
|
||||
| `DependencyService` | `where_used/resolve_binding/validate_refs` | работает по индексу + full validation, без клиентских seed |
|
||||
| `StructureService` | `menu.list/patch`, `layout.list/get`, `fragment.list/get`, `display.list/get` | редактор контента не меняет Jinja код |
|
||||
| `AssetService` | `list/get/upload/update_metadata/delete/where_used` | безопасный MIME, size limits, запрет path traversal |
|
||||
| `FormService` | `list/get_schema/update_schema`, `submission.list/get/update`, `delivery.retry` | RBAC для ПД, версионированная схема, outbox |
|
||||
| `SettingsService` | `site.get/patch`, `theme.get/patch`, `data.*`, `redirects.*` | site root canonical, секрета нет в site.yaml |
|
||||
| `ReleaseService` | `changes/validate/create_candidate/get_candidate/publish/list_releases/rollback/diff` | snapshot hash, immutable, optimistic compare-and-swap live |
|
||||
| `AuthService` | `login/logout/users/grants/tokens/scopes` | safe sessions, token hash, revocation |
|
||||
| `AuditService` | `list/get/export/append` | immutable append, masking sensitive metadata |
|
||||
|
||||
## 5. Patch / CAS
|
||||
|
||||
Пример запроса на изменение одного документа:
|
||||
|
||||
```json
|
||||
{
|
||||
"if_match": "sha256:old-document-hash",
|
||||
"operations": [
|
||||
{
|
||||
"op": "replace_block_prop",
|
||||
"block_id": "hero_home",
|
||||
"field": "title",
|
||||
"value": "Наш новый заголовок"
|
||||
},
|
||||
{
|
||||
"op": "move_block",
|
||||
"block_id": "services_list",
|
||||
"target_region": "main",
|
||||
"after_id": "hero_home"
|
||||
}
|
||||
],
|
||||
"dry_run": false
|
||||
}
|
||||
```
|
||||
|
||||
**Последовательность:** validate request → RBAC → lock affected document/changeset → re-read bytes → compare `if_match` → apply all ops in memory → draft validation → atomic commit of all affected files → update index/audit → return new ETag. При mismatch ответ `409`, никакой потери изменений. `move_block` использует `before_id`/`after_id`, а не позиционный индекс.
|
||||
|
||||
Для rename и изменений нескольких файлов нужна **стейджинговая директория, журнал changeset и восстановление после crash**. `os.replace` атомарен для одного пути на поддерживаемой FS, но несколько файлов и SQLite одной атомарной операцией не становятся. Порядок recovery, index rebuild и lock scope — в ADR-004.
|
||||
|
||||
## 6. Proposed machine API `/api/v1`
|
||||
|
||||
Это **пример маршрутов**, не требование полного REST слоя в MVP. Admin и MCP используют application services напрямую.
|
||||
|
||||
| Endpoint | Метод | Результат |
|
||||
|---|---|---|
|
||||
| `/api/v1/pages` | GET/POST | list/create |
|
||||
| `/api/v1/pages/{id}` | GET/PATCH | snapshot/typed patch |
|
||||
| `/api/v1/pages/{id}/source` | GET/PUT | source + editor save |
|
||||
| `/api/v1/pages/{id}/validate` | POST | draft diagnostics |
|
||||
| `/api/v1/entries/{collection}` | GET/POST | list/create |
|
||||
| `/api/v1/entries/{collection}/{slug}` | GET/PATCH | get/update |
|
||||
| `/api/v1/dependencies?type=&id=` | GET | reverse refs |
|
||||
| `/api/v1/assets` | GET/POST | list/upload |
|
||||
| `/api/v1/validate` | POST | release strict report |
|
||||
| `/api/v1/releases/candidates` | POST | immutable candidate manifest, build id |
|
||||
| `/api/v1/releases/{build_id}/publish` | POST | live switch with expected_live |
|
||||
| `/api/v1/releases/{build_id}/rollback` | POST | rollback with expected_live |
|
||||
| `/api/v1/releases` | GET | release history |
|
||||
|
||||
В каждом мутирующем вызове: actor/scopes, `if_match` или `expected_live`, idempotency key для значимых ретраев, `request_id` для аудита. Пагинация для списков. Имена URL пока рекомендованы, не утверждены API v1.
|
||||
|
||||
## 7. MCP / CLI
|
||||
|
||||
MCP MVP: `get_site_info`, `get_content_schema`, `list_pages`, `get_page`, `list_entries`, `get_entry`, `list_fragments`, `create_page`, `patch_page`, `create_entry`, `update_entry`, `validate`, `get_preview_url`, `get_diff`. MCP изменение по умолчанию **draft-only**, publish/rollback выключены; narrow scopes по путям/коллекциям. CLI использует те же сервисы и validation, предоставляет `reindex`, `validate`, `build`, `release list`, `rollback` с проверенной локальной identity/policy.
|
||||
|
||||
API/CLI/MCP не могут «подделать» роль лишь потому, что передали `actor_id` как строку: адаптер создаёт ActionContext из проверенной сессии/токена/админского локального контекста.
|
||||
|
||||
## 8. Расхождения прототипа с файловыми контрактами
|
||||
|
||||
- `builder.js`: плоский `page.blocks[]`; canonical должен иметь `regions` и `slots` (прототип отображает фиксированные header/footer отдельно).
|
||||
- `builder.js`: `props` + `bindings` отдельно; принять единый wire format после ADR-002.
|
||||
- `content-editor.js`: `entries[]` сериализуются как браузерное состояние; реальная Entry — самостоятельный markdown-файл и collection schema.
|
||||
- `publication.js`: localStorage overlays и synthetic `build_id`; production snapshots формируются файловым snapshot+manifest и проверяются hash.
|
||||
- `stage6.js`: локальная медиатека, настроечные формы и аудит; canonical данные, безопасные files и server RBAC требуют отдельной реализации.
|
||||
@@ -0,0 +1,118 @@
|
||||
# 04. Безопасность, публикация, откат и динамические формы
|
||||
|
||||
## 1. Auth / permissions / audit — обязательные предусловия
|
||||
|
||||
Production не имеет права доверять клиентскому переключению роли из HTML-прототипа. Минимум: локальные аккаунты, session-cookie `Secure`, `HttpOnly`, `SameSite`, защита CSRF для state-changing admin requests, session expiration/rotation, защита от brute-force/rate-limit, серверный audit trail. Конкретные реализации и policy на approval — ADR-005.
|
||||
|
||||
| Capability | Owner | Developer | Editor | Reviewer | Agent |
|
||||
|---|---|---|---|---|---|
|
||||
| Просмотр Page/Entry | да | да | да | да | по scopes |
|
||||
| Сохранение черновика Page/Entry | да | да | да | нет | только scoped draft |
|
||||
| Редактирование Layout/Fragment **кода** | policy да | да | нет | нет | нет |
|
||||
| Изменение меню/контентных схем | да | да/policy | menu-only по политике | нет | по узким scopes, без кода |
|
||||
| Validate / preview | да | да | да | да | по scopes |
|
||||
| Создание кандидата | да | да | если разрешено | нет | нет по умолчанию |
|
||||
| Publish / rollback | да | да, по разрешению | только явный grant | нет | **нет** |
|
||||
| Заявки / ПД / export | да (специальное разрешение) | **не автоматически** | не автоматически | нет | нет |
|
||||
| Пользователи, роли, MCP scopes | да | нет по умолчанию | нет | нет | нет |
|
||||
|
||||
Матрица — проект политики на основе ТЗ и UX. Отдельные scoped grants решают исключения, роли не заменяют permissions. При отказе в UI — понятная причина; сервер отдаёт 403/404 по конфиденциальности. Секреты и токены при создании показываются один раз только уполномоченному пользователю; хранить хеш/шифрованное значение по назначению, не показывать исходный токен повторно.
|
||||
|
||||
## 2. Trust boundaries
|
||||
|
||||
- **File paths:** root-jail, allowlisted directories, проверка realpath и symlink, обработка `..`, `NUL`, Unicode normalization, MIME sniffing. К загрузкам применяются квоты, ограничения на обработку изображений, карантин для сложных форматов. Нельзя считать клиентскую проверку MIME достаточной.
|
||||
- **Markdown:** raw HTML отключён по умолчанию; output sanitization + автоэкранирование Jinja.
|
||||
- **Jinja/layout/fragment/script.js:** не считать произвольный пользовательский код безопасным из-за sandbox. Только доверенный developer workflow с ревью; запрещены динамические Python-миграции из непроверенного сайта.
|
||||
- **Preview iframe:** желательно отдельный origin и cookie-free isolation; если тот же origin — усиленные CSP/sandbox, отдельные endpoints, `noindex`, TTL токена, без доступа к admin API. `postMessage` только с проверкой origin/source. Не использовать `'*'` как production targetOrigin.
|
||||
- **MCP:** токен с ограниченным TTL, revocation, per-resource scopes, rate-limit, default draft-only; логировать caller и correlation ID.
|
||||
- **Forms / PII:** data minimization, отдельные permissions, redaction в audit/logs, CSV formula injection protection, retention/delete/backup policy; запрет утечек ПД в preview и обезличенные скриншоты.
|
||||
|
||||
## 3. Состояния релиза
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> Workspace
|
||||
Workspace --> Validation : validate snapshot
|
||||
Validation --> Workspace : blocking errors
|
||||
Validation --> Candidate : strict pass + immutable build
|
||||
Candidate --> Workspace : workspace changes / candidate stale
|
||||
Candidate --> Live : authorization + explicit confirmation
|
||||
Live --> Historic : later publish
|
||||
Historic --> Live : rollback pointer with CAS
|
||||
```
|
||||
|
||||
**Workspace:** редактируемые канонические файлы; допускается валидный синтаксис и незавершённый `draft`. Изменение файлов НЕ меняет live.
|
||||
|
||||
**Release candidate:** изолированный, неизменяемый snapshot из рабочей версии, прошедший строгую валидацию и успешный build. `manifest` содержит `build_id`, content hashes, route map, assets, theme bundle hashes, form schema versions, actor, timestamp, validation summary, build logs. Кандидат «устаревает» после новых изменений в workspace только с точки зрения выбранной версии: запрещаем публиковать без сверки актуальности/policy (это решение фиксируется ADR-003).
|
||||
|
||||
**Live:** конкретный `build_id` и доступный статический набор. Значение `status: published` у Page НЕ означает, что её новая версия уже попала на сайт.
|
||||
|
||||
## 4. Pipeline и switch
|
||||
|
||||
```text
|
||||
snapshot(workspace_revision)
|
||||
→ load + syntax/schema validation
|
||||
→ strict reference/route/asset/form compatibility validation
|
||||
→ rebuild index from snapshot or read snapshot-local index
|
||||
→ resolve bindings and bounded queries
|
||||
→ render trusted layouts/fragments + sanitized Markdown
|
||||
→ bundle assets + hash + manifest
|
||||
→ build in isolated dist/<build_id>.tmp
|
||||
→ fsync/verify & finalize immutable dist/<build_id>
|
||||
→ release_candidate(build_id, snapshot_hash)
|
||||
→ confirm publish (RBAC, CSRF, expected_live, candidate validation)
|
||||
→ atomic replace live pointer / commit publish event
|
||||
```
|
||||
|
||||
Сначала поддерживать *детерминированную полную сборку*; инкрементальная оптимизация — отдельно после измерений. Не класть candidate в `dist/current` до подтверждения. На неуспешной сборке/валидации текущий pointer не меняется. Повтор publish с тем же idempotency key не создаёт второй релиз.
|
||||
|
||||
Для POSIX `symlink + atomic rename` на одном FS — возможная реализация; для Windows и чужих mount/FS нужны другой pointer protocol/atomicity contract. Дизайн хранения `var/builds` и serve static должен быть проверен в окружении развертывания (ADR-003).
|
||||
|
||||
## 5. Rollback
|
||||
|
||||
1. Выбрать исторический build ID и показать manifest, состояние форм/ассетов и diff с текущим live.
|
||||
2. Validate, что snapshot существует, целостен, поддерживается текущими runtime-сервисами; проверить form schema compatibility.
|
||||
3. Подтвердить явно и с `expected_live` (CAS). Нельзя откатывать слепо поверх чужой публикации.
|
||||
4. Переключить только указатель live, записать audit event и release history. Не удалять workspace и не «возвращать» рабочие файлы к предыдущим версиям скрытно.
|
||||
5. Сохранить все публичные assets, нужные предыдущему релизу, до окончания retention и пока релиз потенциально доступен для rollback.
|
||||
|
||||
## 6. Динамические формы и outbox
|
||||
|
||||
Публичный HTML должен отправлять `form_id` и **версию схемы**, с которой был собран релиз (`form_schema_hash` и/или build ID). После отката сервер обязан поддерживать обработку заявок по старой схеме или явно блокировать неподдерживаемую публикацию.
|
||||
|
||||
```text
|
||||
POST /forms/{id}
|
||||
-> rate limit, CSRF/anti-abuse по публичной политике, size/type check
|
||||
-> lookup pinned schema from release manifest / compatible versions
|
||||
-> validate consent metadata + payload
|
||||
-> SQLite transaction:
|
||||
INSERT submission (schema version, retained data)
|
||||
INSERT outbox notification event
|
||||
-> commit -> 202/303 OK
|
||||
worker:
|
||||
-> claim outbox
|
||||
-> send Telegram (MVP) with retry/backoff
|
||||
-> record attempt, delivery status, idempotency
|
||||
```
|
||||
|
||||
Успех отправки формы относится к сохранению заявки, **не** к успеху Telegram. Раздел «Заявки» показывает статусы уведомления, права на ПД проверяются на сервере. Восстановление после crash не должно терять события outbox; повторная отправка допустима только с idempotency strategy (at-least-once delivery и dedup key).
|
||||
|
||||
## 7. Audit и recovery
|
||||
|
||||
Audit append события: `actor`, `source` (UI/CLI/MCP), `capability`, `object`, `request_id`, `operation`, `old_etag/new_etag`, `result`, timestamp; не хранить plaintext пароли, токены, payload заявок или лишние данные. Логи build и audit должны иметь retention policy.
|
||||
|
||||
Recovery rehearsal:
|
||||
- Crash между temp write и commit не оставляет битого YAML в `site/`.
|
||||
- Crash между snapshot build и pointer switch оставляет прежний live.
|
||||
- Crash после pointer switch до записи DB требует reconciliation live pointer ↔ release metadata.
|
||||
- Crash после commit заявки, но до Telegram — outbox повторяет доставку.
|
||||
|
||||
## 8. Где нужна отдельная договорённость
|
||||
|
||||
- Политика publish grant редактору, возможность reviewer approval (`review`/`scheduled` — не MVP по умолчанию).
|
||||
- Независимый preview origin и модель токенов.
|
||||
- Поддержка SVG, versioned asset metadata/sidecar.
|
||||
- Формат release manifest и atomic pointer на выбранной OS/FS.
|
||||
- Сроки хранения релизов, аудита, заявок, backup policy и удаление ПД.
|
||||
|
||||
Без утверждения этих пунктов нельзя честно заявлять production-ready безопасность или publish pipeline.
|
||||
@@ -0,0 +1,85 @@
|
||||
# 05. Реализация по вертикальным срезам: задачи, тесты, контрольные точки
|
||||
|
||||
Этапы **V0–V7** ниже — предлагаемая последовательность **последующей разработки backend**, не переименование уже завершённых дизайн-этапов 1–7. Время, стоимость и назначение исполнителей не утверждены. Выполнять один вертикальный срез и проходить приёмку, затем следующий.
|
||||
|
||||
## V0 — Зафиксировать контракты и тестовый сайт
|
||||
|
||||
**Делать:** согласовать ADR-001–006, финальную форму Page/Entry/Binding/Query, layout regions, path mapping, status semantics; собрать reference site с `pages/index.md`, `services`, `forms`, fixtures, ZIP-демо как baseline UI. Настроить тесты parse → serialize → parse.
|
||||
|
||||
**Приёмка:** единая модель файлов не зависит от браузерного localStorage; `reindex` из чистого сайта воспроизводит маршруты/редиректы; не существует неоднозначного определения `source/bind`.
|
||||
|
||||
## V1 — Каркас FastAPI/Jinja/htmx + безопасный Page save
|
||||
|
||||
**Делать:** session auth, RBAC+CSRF, `/admin`, `/admin/pages`, `GET editor`, `_block_tree`, `_inspector`; PageService read/patch + `if_match`; simple preview с 1 Layout/2 Fragment; error/409 UI. Разделить CSS темы 04 и 06 от данных.
|
||||
|
||||
**Приёмка:** открыть существующую Page → выбрать блок → изменить поле → получить новый hash → перезагрузить страницу → изменение сохранено в YAML/MD. Два одновременных редактора: один получил 409, ни одна версия не потеряна. Неполный синтаксически корректный черновик сохраняется, но не публикуется.
|
||||
|
||||
## V2 — Constructor/Expert, data bindings и Content
|
||||
|
||||
**Делать:** safe YAML parse/source editor, round-trip preservation policy, unified Page DTO, page-to-block mapping, typed refs (MVP subset), `where_used`, EntryService + collection schemas + display template, preview refresh preserving scroll and selection.
|
||||
|
||||
**Приёмка:** edit Constructor → Expert → Constructor не меняет ID блоков, связи и Markdown; плохой YAML не перезаписывает документ; выбор блока в дереве скроллит к нему, клик по preview не сдвигает scroll; битый asset/entry выделен на точном поле. Entry и Page имеют разные contracts.
|
||||
|
||||
## V3 — Build, кандидат, публикация, история, откат
|
||||
|
||||
**Делать:** загрузка и валидация snapshot, full static build, manifest, `build_id`, candidate, live pointer с CAS, publish rights, history, rollback и build logs; HTML раздел Публикация на htmx.
|
||||
|
||||
**Приёмка:** workspace → validate → candidate → publish → live, immutable snapshot, без частично опубликованных результатов; ошибка сборки не переключает live, rollback не затирает workspace, повтор publish idempotent. Список изменений и diff относятся к конкретным hashes, а не fake seed.
|
||||
|
||||
## V4 — Media / Structure / Settings
|
||||
|
||||
**Делать:** asset ingest (MIME/size/quotas), metadata и usage links, меню/redirect changesets, layouts/fragments catalog, site.yaml/data/theme/settings. Developer edit шаблонов — отдельный policy gate и review.
|
||||
|
||||
**Приёмка:** загрузка файла → использование в блоке → where_used → запрет/явное последствие удаления, весь маршрут стабильно рендерится после reindex; изменение URL создает redirect и не оставляет half-committed files; Editor не может менять Jinja/JS.
|
||||
|
||||
## V5 — Публичные формы, заявки, outbox
|
||||
|
||||
**Делать:** versioned schema формы, публичный POST с валидацией, SQLite submissions/outbox, worker Telegram, UI форм и заявок, access control на ПД, retry/audit/retention. Не подключать дополнительные провайдеры уведомлений до надёжной доставки одного.
|
||||
|
||||
**Приёмка:** заявка сохраняется при недоступности Telegram, retry восстанавливает уведомление; rollback старого релиза сохраняет работоспособность формы; Developer без PII grant не может прочитать контакты ни через UI, ни через API.
|
||||
|
||||
## V6 — MCP/CLI/операционный контур
|
||||
|
||||
**Делать:** MCP read/write draft-only, объектные scopes, TTL/revoke, CLI reindex/build/validate; audit, conflict, rate limit, backup/restore. Не дублировать логику в MCP handlers.
|
||||
|
||||
**Приёмка:** MCP и Browser с одним и тем же page hash получают одинаковые validation errors; два одновременных автора → 409; MCP без publish grant не публикует; reindex rebuild не зависит от старой DB cache.
|
||||
|
||||
## V7 — Регрессии, стабильность и deploy handoff
|
||||
|
||||
**Делать:** полный browser QA desktop/mobile, keyboard/focus, visual snapshots 04/06, perf benchmark cold/warm builds, backup recovery drill, security tests, production deploy contract (Nginx + FastAPI/worker + SQLite WAL), docs/runbooks.
|
||||
|
||||
**Приёмка:** все матричные тесты ниже зелёные, нет расхождения дизайна/данных после перезагрузки или между темами; rollback после отказа восстанавливает сайт; deploy документ воспроизводим с чистой БД и исходной папкой сайта.
|
||||
|
||||
## Сквозная матрица автоматических тестов
|
||||
|
||||
| Test ID | Уровень | Что доказывает |
|
||||
|---|---|---|
|
||||
| `PARSER-01` | unit/property | Page/Entry parse-serialize round trip с сохранением ID и Markdown |
|
||||
| `BIND-01` | unit | literal/bind/ref/query нормализуются, обязательная отсутствующая ссылка → structured error |
|
||||
| `LAYOUT-01` | unit | `allow`, fixed region, slots, max depth; Editor не обходит ограничения в Expert |
|
||||
| `CAS-01` | integration | два writers, один `409`; atomic patch не создаёт частичный файл |
|
||||
| `CHANGESET-01` | integration | rename page + redirects + menu, crash/recovery, no partial state |
|
||||
| `DRAFT-01` | integration | можно сохранить неполный draft, strict release validation его исключает или блокирует по принятой policy |
|
||||
| `REINDEX-01` | integration | clone+reindex rebuilds routes/redirects без старой SQLite |
|
||||
| `REF-01` | integration | удалённая Entry/Asset, неопубликованная ссылка, route collision — точные diagnostics |
|
||||
| `BUILD-01` | integration | build failure/current pointer не меняется |
|
||||
| `RELEASE-01` | integration | immutable manifest, publish/rollback CAS, workspace survives |
|
||||
| `FORM-01` | integration | форма старого релиза работает после rollback, outbox retry |
|
||||
| `SEC-01` | security | Editor/Agent не исполняют шаблон/JS, не читают ПД, нет file traversal |
|
||||
| `PREVIEW-01` | security | preview token не открывает admin/чужой draft |
|
||||
| `UI-01` | browser | Constructor selected by default; переключение Expert, предупреждения, 409 modal |
|
||||
| `UI-02` | browser | выбор дерева → scroll; клик в iframe → no scroll; edit props → preserve viewport |
|
||||
| `UI-03` | screenshot | 04/06 1440×900, 1280×800, 1024×768, 768×1024, 390×844, 360×740 |
|
||||
| `UI-04` | browser | Rose Graphite: без скруглений **только** выбор коллекции; остальные таблицы как в baseline |
|
||||
| `OPS-01` | chaos | crash mid-build / mid-outbox / mid-commit и recovery |
|
||||
|
||||
**Не обещать соответствие SLA:** исходное ТЗ задаёт ориентиры до 500 страниц / 10 секунд, single page / 1 секунда. Это гипотезы для benchmark; принимать реальные performance SLO после измерений на целевом железе.
|
||||
|
||||
## Definition of Done на каждый срез
|
||||
|
||||
- Код + тесты + документация DTO и возвращаемых ошибок.
|
||||
- Auth/CSRF/RBAC/audit для всех новых мутаций.
|
||||
- Доказано, что база не стала вторым каноническим источником файлов контента.
|
||||
- Две активные темы отображают одинаковые данные.
|
||||
- Утверждённый UX сохранён (включая `mode=constructor` по умолчанию и scroll semantics).
|
||||
- Прототип Stage 6 остаётся отдельным design baseline, без ложных заявлений об интеграции.
|
||||
@@ -0,0 +1,69 @@
|
||||
# 06. Аудит текущих HTML-прототипов и разрывы до production
|
||||
|
||||
Проверено по исходным файлам архива Этапа 6. Это **наблюдения о прототипе**, а не заявление, что backend уже существует. Целевая схема из документов 01–05 — предложение реализации.
|
||||
|
||||
## 1. Фактическая карта интерфейса
|
||||
|
||||
| Реальный файл | Клиентский модуль | Что покрывает | Куда переносить |
|
||||
|---|---|---|---|
|
||||
| `antirion-rework.html` | `assets/antirion-rework.js` | 04 shell, обзор, страницы, legacy summary экраны | `admin/base`, overview, pages list |
|
||||
| `rose-graphite.html` | `assets/rose-graphite.js` | 06 shell с утверждёнными style rules | те же Jinja partials + Rose tokens |
|
||||
| `builder-antirion.html`, `builder-rose-graphite.html` | `assets/builder.js`, `assets/expert-codec.js` | Page Constructor, Expert, mappings, preview, validation, draft | PageService, Fragment/BindingService, source adapter |
|
||||
| `content-antirion.html`, `content-rose-graphite.html` | `assets/content-editor.js`, `assets/expert-codec.js` | Entry edit, Collection schema, preview | Entry/Collection/Display services |
|
||||
| `publication-antirion.html`, `publication-rose-graphite.html` | `assets/publication.js` | changes, validate, candidate, publish, history, rollback | ReleaseService + BuildService + audit |
|
||||
| `modules-antirion.html`, `modules-rose-graphite.html` | `assets/stage6.js` | media, structure, forms, settings, journal | соответствующие application services |
|
||||
| `antirion.html`, `ember-graphite.html` | `assets/admin.js`, `assets/ember-graphite.js` | 03/05 утверждённые концепты | не расширять автоматически; сохранять design baseline |
|
||||
|
||||
## 2. Несогласованные источники данных в демо
|
||||
|
||||
| JS store | В каком коде | Реальное поведение в прототипе | Production замена |
|
||||
|---|---|---|---|
|
||||
| `site-engine-stage2-constructor-v1` | `builder.js` | страницы/blocks сохраняются в localStorage | canonical `pages/**/*.md`, PageService + ETag |
|
||||
| `site-engine-stage3-source-buffers-v1` | `builder.js` | незавершённые исходники Expert в браузере | client-side transient buffer, server autosave — только отдельное решение |
|
||||
| `site-engine-stage4-content-v1` | `content-editor.js` | записи и sourceCache | `content/**/*.md` + CollectionService |
|
||||
| `site-engine-stage5-release-v1` | `publication.js` | build ID, live, overlays, activity | immutable snapshot + DB metadata + live pointer |
|
||||
| `site-engine-stage6-ui-v1` | `stage6.js` | медиа, настройки, заявки и журнал в одной browser-модели | файловые config + DB service data + public forms/outbox |
|
||||
|
||||
В Stage 5 `publication.js` читает сохранённые Stage 2/4 данные из browser storage и смешивает их с demo overlays. В Stage 6 `stage6.js` объединяет свой журнал с Stage 5, если storage доступен. Это полезная **демонстрация UX**, но не транзакционная консистентность и не подходящая архитектура для production.
|
||||
|
||||
## 3. Расхождения schema / serialization
|
||||
|
||||
- `builder.js` хранит `page.blocks` плоско, а YAML-сущность из ТЗ — `regions`, `slots`, `fixed` в Layout. Нельзя терять вложенность в серверной модели.
|
||||
- `builder.js` хранит `bindings` отдельно от `props`; в ТЗ bindings чаще встроены в значения props. Требуется ADR-002 и единая сериализация.
|
||||
- Mock Query поддерживает ограниченные `collection/limit/sort` и фиксированные `ENTRIES`; коллекции из Content Editor живут в другом store. В production query читает canonical entries и индекс.
|
||||
- `content-editor.js` моделирует schemas прямо в JS, а production schemas читаются из `collections/*.yaml`.
|
||||
- Preview в Page Builder формирует `srcdoc` и передаёт `postMessage('*')`. Для сервера нужен защищённый preview и безопасная межокенная коммуникация.
|
||||
- В Stage 6 `role` меняется в JS, а contacts/permissions лишь скрываются клиентом; настоящая защита возможна только на сервере.
|
||||
- Media upload Stage 6 для части форматов записывает метаданные, а не файлы на диск, и существует ограничение размера 2 MiB — это демо-поведение, не production quota policy.
|
||||
- `publication.js` синтезирует релизы из seed/overlays, поэтому `build_id` и published state не соответствуют реальному snapshot.
|
||||
- Даже при совпадении экрана в 04/06 логика UI может дублироваться; целевая реализация должна использовать единую модульную схему шаблонов.
|
||||
|
||||
## 4. Зафиксированные UX-решения из совместных итераций
|
||||
|
||||
1. При открытии редактирования Page сверху **по умолчанию выбран «Конструктор»**, селектор синхронизирован с режимом.
|
||||
2. Клик по блоку в preview **не прокручивает страницу**.
|
||||
3. Выбор блока в дереве прокручивает preview к нему, **если блок не виден**; редактирование поля не сбрасывает scroll.
|
||||
4. Статусы `Workspace draft`, `Saved draft`, `Live release` не смешиваются.
|
||||
5. Все четыре дизайн-концепта 03–06 сохраняются в упаковке; 04 и 06 — активно реализуемые.
|
||||
6. В Rose Graphite **прямоугольный только выбор коллекции** раздела Контент; остальные таблицы и панели не менять без отдельного решения.
|
||||
7. Нет зависимости от сторонних CDN, исходный HTML открывается локально, производственная реализация не требует React/Vue/Next ради прототипа.
|
||||
|
||||
## 5. QA исходного прототипа
|
||||
|
||||
Этап 6 содержит `docs/test_stage6.py`, `docs/test_stage6_views.py`, `docs/STAGE6_QA.md`, JSON и preview screenshots. Это подтверждения тестирования **конкретного mock**, а не автоматическая готовность сервиса. В Этапе 7 HTML не менялся, поэтому повторное визуальное QA нужно при первых server-rendered partials, когда появятся новые data states и network errors.
|
||||
|
||||
## 6. Priority gap list (порядок решения)
|
||||
|
||||
| Gap | Приоритет | Почему |
|
||||
|---|---|---|
|
||||
| Формальное canonical Page/Entry/Binding/Query DTO | P0 | без него Constructor/Expert будут иметь расходящиеся serializers |
|
||||
| CAS + атомарная файловая запись + recovery | P0 | конкурентная правка/агенты могут терять изменения |
|
||||
| Auth, RBAC, CSRF, audit на уровне services | P0 | нельзя подключать UI/CLI/MCP с записью иначе |
|
||||
| Snapshot/manifest/pointer semantics | P0 | нельзя считать publish/rollback безопасными |
|
||||
| Версионирование публичных форм | P0 | rollback может сломать заявки |
|
||||
| Preview isolation и sanitation | P0 | iframe/фрагменты/Markdown недоверенные поверхности |
|
||||
| Sidecar metadata Asset | P1 | file-first теряет alt/caption без явного формата |
|
||||
| Реальный where-used индекс и reference validation | P1 | без него изменение/удаление создаст битые связи |
|
||||
| Multi-file changeset | P1/P0 для rename | одной SQLite-транзакцией не закрыть файловые изменения |
|
||||
| CSS/htmx Jinja partial design tokens | P1 | сохранить UX/стили без двойной серверной логики |
|
||||
| Incremental build, full query DSL, advanced review workflow | Later | не нужны для базового end-to-end сайта |
|
||||
@@ -0,0 +1,37 @@
|
||||
# Задание для следующего чата / Codex-агента: начать backend Site Engine
|
||||
|
||||
Ты — Senior Python Engineer + System Architect, работаешь в Spec-Driven Workflow. Цель — **реализовать первый вертикальный срез** переноса согласованной админки Site Engine на FastAPI + Jinja2 + htmx, без переписывания интерфейса на SPA.
|
||||
|
||||
## Источники (прочитать прежде чем кодить)
|
||||
|
||||
- `docs/stage7/README.md`
|
||||
- `docs/stage7/01_ARCHITECTURE.md`
|
||||
- `docs/stage7/02_UI_HTMX_MAP.md`
|
||||
- `docs/stage7/03_DOCUMENTS_AND_SERVICES.md`
|
||||
- `docs/stage7/04_SECURITY_RELEASES.md`
|
||||
- `docs/stage7/05_IMPLEMENTATION_PLAN.md`
|
||||
- `docs/stage7/06_PROTO_AUDIT_AND_GAPS.md`
|
||||
- `docs/stage7/adr/ADR_REGISTER.md`
|
||||
- `docs/stage7/reference_TZ-site-engine.md`
|
||||
- `docs/stage7/reference_TZ-site-engine-architecture-review.md`
|
||||
- Утверждённые HTML-прототипы: `index.html`, `antirion-rework.html`, `rose-graphite.html`, `builder-*.html`, `content-*.html`, `publication-*.html`, `modules-*.html`, `assets/*`.
|
||||
|
||||
## Правила
|
||||
|
||||
1. Site Engine — самостоятельный продукт, не Flexly AI Core.
|
||||
2. Файлы сайта (YAML/Markdown) — каноническая модель. SQLite — cache/index/service data, не дублировать контент.
|
||||
3. App services едины для admin/API/CLI/MCP. Все writes проходят RBAC, CAS, validation, audit.
|
||||
4. Опубликованный релиз — immutable snapshot; draft save не меняет live.
|
||||
5. Различать принятые UX-решения и **предложения ADR**; сомнительные пункты сначала ADR и тесты.
|
||||
6. Не начинать реализацию всей CMS одновременно; делать вертикальные срезы по `05_IMPLEMENTATION_PLAN.md`.
|
||||
7. Базовые темы: **04 Antirion Rework** и **06 Rose Graphite**. Не менять согласованную сетку/цвета; 03 и 05 хранить как сохранённые концепты.
|
||||
8. Технический стек: Python 3.12+, FastAPI, Jinja2, htmx, Pydantic v2, SQLAlchemy 2, SQLite WAL/Alembic. Не добавлять Node только ради сборки.
|
||||
9. Запускать тесты; приложить результат и ссылки на изменённые файлы. Не выдавать mock publish, role switch или localStorage за реальную интеграцию.
|
||||
|
||||
## Первый запрос (V0)
|
||||
|
||||
Сделай ревью технического пакета и составь минимальный implementation plan для файловой модели Page/Layout/Fragment/Block, typed bindings MVP, `reindex`, draft validation и safe serialization. Обозначь решения ADR-001/002/004, требующие утверждения. Затем реализуй только по принятому согласованному срезу; не подключай MCP или публичные формы раньше auth/RBAC/audit.
|
||||
|
||||
## Следующий срез (V1), после утверждения V0
|
||||
|
||||
FastAPI app, безопасная сессия, PageService с `if_match`, Jinja shell + htmx list/editor/inspector, один рабочий шаблон и preview. Критерий: изменить title Hero → save → reload → увидеть изменение из canonical YAML; одновременно открытые сессии обнаруживают 409.
|
||||
@@ -0,0 +1,54 @@
|
||||
# Site Engine — Этап 7: handoff технической реализации
|
||||
|
||||
Актуальные границы работ и поправки: [сопоставление с 001](001_ALIGNMENT.md). При расхождении применять спецификацию 001 и действующие файловые контракты.
|
||||
|
||||
**Статус:** проект архитектуры для согласования и реализации. **Не является работающим backend.**
|
||||
**Дата:** 12.11.2026. **Продукт:** Site Engine, отдельно от Flexly AI Core.
|
||||
**Целевая платформа:** Python 3.12+, FastAPI, Jinja2, htmx, Pydantic v2, SQLAlchemy 2, SQLite WAL, Alembic; Node.js/SPA не обязательны.
|
||||
|
||||
## Итог Этапа 7
|
||||
|
||||
Завершён технический **план переноса** утверждённых HTML-прототипов Этапов 1–6 на файловый движок и серверную админку. План охватывает URL/partials, модель документов и сервисов, права, безопасность, совместное редактирование, превью, сборку, публикацию, rollback, формы, MCP/CLI и интеграционные тесты. Реальная интеграция **не выполнялась**.
|
||||
|
||||
**Зафиксированные дизайны:** 03 Antirion, 04 Antirion Rework, 05 Ember Graphite, 06 Rose Graphite (ранее YuE Studio). Функционально развиваем **04 и 06**; 03 и 05 остаются неизменёнными концепциями. У Rose Graphite без скруглений только выбор коллекции в разделе «Контент» — не все таблицы.
|
||||
|
||||
## Навигация по документам
|
||||
|
||||
| Файл | Для чего нужен |
|
||||
|---|---|
|
||||
| `01_ARCHITECTURE.md` | Общие слои, дерево проекта, модули, владение данными |
|
||||
| `02_UI_HTMX_MAP.md` | Каждый экран → Jinja partial, HTTP route, событие htmx, доступ |
|
||||
| `03_DOCUMENTS_AND_SERVICES.md` | File-first контракты, операции приложения, DTO, REST/MCP/CLI, concurrency |
|
||||
| `04_SECURITY_RELEASES.md` | RBAC, CSRF, preview isolation, build/release/rollback, формы/outbox |
|
||||
| `05_IMPLEMENTATION_PLAN.md` | Вертикальные срезы, зависимости, критерии приемки и тест-план |
|
||||
| `06_PROTO_AUDIT_AND_GAPS.md` | Точная привязка к исходным HTML/JS и выявленные разрывы между демо и production |
|
||||
| `adr/ADR_REGISTER.md` | Решения, утверждение которых необходимо до старта реализации |
|
||||
| `IMPLEMENTATION_HANDOFF_PROMPT.md` | Готовое задание для нового чата/кодового агента |
|
||||
| `examples/` | Примеры контрактов и ответов API; **не канонический окончательный формат** |
|
||||
|
||||
## Основные границы
|
||||
|
||||
1. **Источник истины — сайт как папка файлов:** `pages/`, `content/`, `collections/`, `display/`, `layouts/`, `fragments/`, `menus/`, `forms/`, `assets/`, `data/`, `site.yaml`, `redirects.yaml`.
|
||||
2. **SQLite не содержит второй канонической копии контента:** в БД — перестраиваемые индексы и служебные сущности (пользователи, сессии, агенты, аудит, заявки, outbox, метаданные сборок).
|
||||
3. **Один сервисный слой** для админки, CLI и MCP; никаких обособленных проверок прав только в htmx или JS.
|
||||
4. **Workspace ≠ Release candidate ≠ Live release.** Сохранённый документ не означает, что посетитель увидел изменения.
|
||||
5. Конструктор и Эксперт — **два способа работы с одним документом**. Ошибочный исходник не перезаписывает последнюю валидную модель.
|
||||
6. Публикация — только валидированный, неизменяемый снимок. Откат переключает live, **не затирает workspace**.
|
||||
7. Дальнейшие решения из архитектурного ревью — **рекомендации, не автоматически утверждённые требования**. Они явно вынесены в ADR.
|
||||
|
||||
## Источники и приоритет
|
||||
|
||||
- `reference_TZ-site-engine.md` — первичное ТЗ от 06.11.2026 (черновик), описание системы и форматов.
|
||||
- `reference_TZ-site-engine-architecture-review.md` — архитектурное ревью, предложения с P0/P1.
|
||||
- `site-engine-admin-design-prompt.md` в исходном обсуждении — требования к дизайну, этапам и поведению UI.
|
||||
- Реально собранный `index.html`, `assets/*.js`, `assets/*.css` и HTML Этапа 6 — **эталон UX**, но **не** production-контракт данных или правил безопасности.
|
||||
|
||||
**Правило для реализации:** если прототип противоречит ТЗ, не копировать случайную структуру JS-state в серверный контракт. Если ревью противоречит черновику ТЗ, оформить ADR и согласовать; в документах этого этапа предложен конкретный стартовый вариант.
|
||||
|
||||
## Что делать дальше
|
||||
|
||||
Согласовать ADR P0, затем начать вертикальный срез `V0` из `05_IMPLEMENTATION_PLAN.md`: один сайт, одна файловая Page, один Fragment, полный цикл **read → edit → validate → atomic save → preview**. Остальные подсистемы подключать к тем же сервисам по мере роста, не создавать отдельный «backend для прототипа».
|
||||
|
||||
### Примечание об объёме
|
||||
|
||||
Пакет содержит весь исходный интерактивный проект Этапа 6 без изменения его поведения. Этап 7 добавляет документы и схемы взаимодействия. **Исходный HTML-проект не требует установки и по-прежнему открывается из `index.html`.** Для общего localStorage в нескольких вкладках рекомендован локальный HTTP-сервер.
|
||||
@@ -0,0 +1,65 @@
|
||||
# ADR Register — решения до написания production-кода
|
||||
|
||||
**Статус всех перечисленных ниже ADR: PROPOSED / НЕ УТВЕРЖДЕНО.** Первичное ТЗ — описание требований; архитектурное ревью предлагает их уточнить. Реализация не должна выдавать предлагаемую позицию за принятую пользователем.
|
||||
|
||||
## ADR-001 — File-first и границы SQLite
|
||||
|
||||
**Контекст:** публичная маршрутизация и редиректы должны переживать перенос каталога сайта без БД. В ТЗ предусмотрена SQLite `slug_history` — потенциальный второй источник маршрутов.
|
||||
|
||||
**Рекомендация:** хранить Page/Entry/Redirect/Menu/Asset metadata как файлы `site/` (asset metadata sidecar отдельно уточнить). SQLite хранит перестраиваемые индексы и служебные сущности. Изменение URL — changeset, обновляющий `redirects.yaml`.
|
||||
|
||||
**Альтернатива:** SQLite как канонический storage — нарушает выбранную file-first модель.
|
||||
|
||||
**Решение требуется:** подтвердить форматы sidecar для ассетов и источник пользовательских метаданных.
|
||||
|
||||
## ADR-002 — Typed Composition / Bindings / Query MVP
|
||||
|
||||
**Контекст:** ТЗ содержит `{bind: ...}`, `{page: ...}`, `{entry: ...}`, `source: body` и коллекционные запросы; прототип имеет независимое `bindings`.
|
||||
|
||||
**Рекомендация:** внутреннее `Literal | Binding | LinkRef | Query`, path roots `site/page/entry/data/params`, canonical YAML как в ТЗ, query MVP `collection/ids/where.eq/in/sort/limit`. Unsupported expressions — явный error. `source: body` нормализовать в `bind: page.body`. Строковые Jinja-like выражения в YAML SEO — запретить в MVP либо разрешить строго ограниченную подстановку после отдельного решения.
|
||||
|
||||
**Альтернатива:** полный DSL и произвольные шаблоны повышают сложность и риски.
|
||||
|
||||
**Решение требуется:** окончательная сериализация, совместимость при round-trip комментариев, media refs, nesting/slots.
|
||||
|
||||
## ADR-003 — Immutable Releases / Live pointer / Form compatibility
|
||||
|
||||
**Контекст:** сохранение не равно публикации. Откат статического сайта может вернуть старую форму.
|
||||
|
||||
**Рекомендация:** `workspace → immutable candidate(snapshot_hash, manifest) → atomic live pointer`, publish & rollback с `expected_live`, retention assets+form schemas, worker принимает schema version текущего отправляемого HTML.
|
||||
|
||||
**Альтернатива:** публикация файлов поодиночке — неподдерживаемая половинчатая live-версия.
|
||||
|
||||
**Решение требуется:** OS/FS (POSIX symlink vs portable pointer), TTL кандидата, правила актуальности, release retention.
|
||||
|
||||
## ADR-004 — CAS / Typed Patch / Multi-file Changesets
|
||||
|
||||
**Контекст:** стабильный block ID не предотвращает потерю изменений при двух writers.
|
||||
|
||||
**Рекомендация:** SHA-256 ETag + `if_match`; lock → verify → apply → validate → atomic file write; rename/menu/redirect через staging+crash recovery, machine-readable `409` diff. Typed `move_block` с `before_id/after_id`, а не только index.
|
||||
|
||||
**Решение требуется:** granularity locks, multi-file transaction journal, recovery/reconciliation, hash canonicalization.
|
||||
|
||||
## ADR-005 — Security / Trusted code / Preview / Agent scopes
|
||||
|
||||
**Контекст:** Jinja sandbox не даёт изоляции произвольному JS/Python; публичная форма и MCP требуют надёжной авторизации.
|
||||
|
||||
**Рекомендация:** editor/agent — только data, developer code через reviewed workflow; cookie session + CSRF, server RBAC, limited preview token/origin/CSP, scoped MCP draft-only, PII grant отдельно. SVG либо запрещён на MVP, либо безопасно преобразуется.
|
||||
|
||||
**Решение требуется:** concrete preview origin, RBAC scopes/grants, TTL токена, retention/PII policy, доверенные расширения.
|
||||
|
||||
## ADR-006 — Scope, milestones и форматы релизов MVP
|
||||
|
||||
**Контекст:** ТЗ охватывает большой универсальный движок и advanced редакционные workflows. Для первого полноценного сайта слишком много расширений.
|
||||
|
||||
**Рекомендация:** 1 сайт/инстанс, 5–15 фрагментов, full build, минимальные query, без scheduled/review approval, поиска FTS, мультисайтовости, сложных таксономий, инкрементальной сборки; эти возможности вернуться по use case и benchmark. Реализовать по V0–V7 из `05_IMPLEMENTATION_PLAN.md`.
|
||||
|
||||
**Решение требуется:** точный MVP fragment list, поддерживаемые формы/уведомления, приоритеты UI modules.
|
||||
|
||||
## Process
|
||||
|
||||
1. Архитектор фиксирует альтернативы и аргументы; reviewer оценивает безопасность/сложность.
|
||||
2. Пользователь утверждает или меняет рекомендацию.
|
||||
3. Только после явного решения ADR получает `Accepted` и дату.
|
||||
4. При изменении решения новая ADR `Supersedes` старую, не удаляя историю.
|
||||
5. Specs и tests ссылаются на ID соответствующей ADR.
|
||||
@@ -0,0 +1,8 @@
|
||||
# Examples — только иллюстративные DTO и YAML
|
||||
|
||||
Эти файлы предназначены для обсуждения контрактов и тестовых фикстур. Их нельзя принимать за автоматически утверждённую схему без ADR-002/003/004. Все ID, ETag и временные значения в JSON фиктивные.
|
||||
|
||||
- `page-home.md`, `entry-bots.md`: примеры file-first документов.
|
||||
- `patch-block.json`: типизированный patch с optimistic concurrency.
|
||||
- `conflict-409.json`: структурированная ошибка при несоответствии версии.
|
||||
- `release-manifest.json`: пример неизменяемого снимка релиза.
|
||||
@@ -0,0 +1,12 @@
|
||||
{
|
||||
"error": {
|
||||
"code": "DOCUMENT_VERSION_CONFLICT",
|
||||
"message": "Документ изменён другим редактором",
|
||||
"document_id": "home",
|
||||
"path": "pages/index.md",
|
||||
"expected_etag": "sha256:EXAMPLE-OLD-HASH",
|
||||
"current_etag": "sha256:EXAMPLE-NEW-HASH",
|
||||
"server_version_url": "/api/v1/pages/home/source",
|
||||
"request_id": "req_example_001"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,11 @@
|
||||
---
|
||||
title: Telegram-боты
|
||||
slug: bots
|
||||
status: published
|
||||
summary: Автоматизируем диалоги и обращения
|
||||
tagline: Диалоги и автоматизация
|
||||
order: 10
|
||||
---
|
||||
Создаём Telegram-ботов под процессы команды.
|
||||
|
||||
Пример. Список допустимых полей задаёт `collections/services.yaml`, а публичный маршрут — его `route`.
|
||||
@@ -0,0 +1,33 @@
|
||||
---
|
||||
schema: 1
|
||||
title: Главная
|
||||
layout: default
|
||||
status: published
|
||||
seo:
|
||||
title: Разработка Telegram-ботов и AI-систем
|
||||
description: AI-ассистенты и автоматизация бизнес-процессов.
|
||||
regions:
|
||||
main:
|
||||
- id: hero_home
|
||||
fragment: hero
|
||||
props:
|
||||
title:
|
||||
bind: page.title
|
||||
subtitle: AI-ассистенты и Telegram-боты
|
||||
- id: services_list
|
||||
fragment: collection_list
|
||||
props:
|
||||
source:
|
||||
query:
|
||||
collection: services
|
||||
sort: order
|
||||
limit: 6
|
||||
- id: body_home
|
||||
fragment: richtext
|
||||
props:
|
||||
content:
|
||||
bind: page.body
|
||||
---
|
||||
Наша студия разрабатывает Telegram-ботов, AI-системы и автоматизацию.
|
||||
|
||||
Пример действующей сериализации Page, проверяемый относительно examples/studio-site.
|
||||
@@ -0,0 +1,18 @@
|
||||
{
|
||||
"if_match": "sha256:EXAMPLE-OLD-HASH",
|
||||
"dry_run": false,
|
||||
"operations": [
|
||||
{
|
||||
"op": "replace_block_prop",
|
||||
"block_id": "hero_home",
|
||||
"field": "title",
|
||||
"value": "Новый заголовок"
|
||||
},
|
||||
{
|
||||
"op": "move_block",
|
||||
"block_id": "services_list",
|
||||
"target_region": "main",
|
||||
"after_id": "hero_home"
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,13 @@
|
||||
{
|
||||
"schema_version": 1,
|
||||
"build_id": "build_example_001",
|
||||
"workspace_revision": "rev_example_37",
|
||||
"snapshot_sha256": "EXAMPLE-SNAPSHOT-SHA256",
|
||||
"created_at": "2026-11-12T13:00:00+03:00",
|
||||
"created_by": "owner_demo",
|
||||
"validation": {"errors": 0, "warnings": 1},
|
||||
"routes": ["/", "/services/", "/services/bots/"],
|
||||
"files": [{"path": "index.html", "sha256": "EXAMPLE-FILE-SHA256"}],
|
||||
"form_schema_versions": {"form_contact": "schema_example_v2"},
|
||||
"notes": "Пример структуры, не утверждённый формат manifest"
|
||||
}
|
||||
@@ -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, объём резко вырастет. Вертикальные срезы и строгие контракты позволят сохранить достоинства архитектуры и избежать ненужных затрат.
|
||||
@@ -0,0 +1,769 @@
|
||||
# ТЗ: движок сайтов на Markdown + YAML и фрагментах
|
||||
|
||||
*Черновик v0.1 · 6 ноября 2026 · на ревью · рабочее название проекта пока не задано*
|
||||
|
||||
## Что просим проверить на ревью
|
||||
|
||||
1. Источник истины: файлы (md + yaml), SQLite только как индекс и служебные данные (разделы 2, 13).
|
||||
2. Модель Layout / Fragment / Block, привязки и запросы (разделы 3–4).
|
||||
3. Расширения модели по итогам карты сайта-примера (раздел 7.4) и правила контента (7.5).
|
||||
4. Состав MVP-набора фрагментов (раздел 8.2).
|
||||
5. Права агента и набор MCP-инструментов (разделы 11–12).
|
||||
6. Этапы и открытые вопросы (разделы 15–16).
|
||||
|
||||
## Содержание
|
||||
|
||||
1. Цели и границы
|
||||
2. Принципы архитектуры
|
||||
3. Модель сущностей
|
||||
4. Форматы файлов
|
||||
5. Структура сайта и маршрутизация
|
||||
6. Сборка, превью и публикация
|
||||
7. Опорный пример: студия ботов, AI-систем и автоматизаций
|
||||
8. Базовый набор фрагментов
|
||||
9. Формы и заявки
|
||||
10. Админка (FastAPI + htmx)
|
||||
11. Роли, права и безопасность
|
||||
12. MCP-сервер
|
||||
13. Данные в SQLite (SQLAlchemy)
|
||||
14. Нефункциональные требования
|
||||
15. Этапы
|
||||
16. Открытые вопросы
|
||||
|
||||
## 1. Цели и границы
|
||||
|
||||
Самохостимый движок, в котором сайт — это каталог файлов (Markdown + YAML), а страницы собираются из **layouts** и **fragments** (строительных блоков в духе Liferay). С движком одинаково удобно работать человеку (админка), агенту (MCP) и разработчику (git, CLI).
|
||||
|
||||
**Задачи v1**
|
||||
|
||||
- Контент, структура и шаблоны хранятся в файлах (md + yaml); SQLite хранит индекс и служебные данные.
|
||||
- Страница = layout + дерево блоков; блок = экземпляр фрагмента со схемой полей.
|
||||
- Типизированные коллекции контента (кейсы, продукты, услуги и т.д.) со списками, страницами записей, связями и таксономиями.
|
||||
- Многостраничные сайты: разделы, меню, хлебные крошки, пагинация, редиректы, заготовка под мультиязычность.
|
||||
- Статическая сборка и динамическое превью, публикация атомарной заменой каталога.
|
||||
- Админка на FastAPI + htmx; MCP-сервер для агентов с правами и валидацией.
|
||||
- Новые фрагменты и коллекции добавляются файлами, без правки ядра.
|
||||
|
||||
**Вне v1:** визуальный drag-and-drop прямо по странице, мультитенантность, e-commerce и платежи, личные кабинеты посетителей, комментарии.
|
||||
|
||||
**Стек:** Python 3.12+, FastAPI, SQLAlchemy 2 + SQLite (WAL), Alembic, Jinja2, pydantic v2, YAML (только safe load), markdown-it-py, Pillow, MCP Python SDK; в админке htmx (+ SortableJS, EasyMDE). Node-сборки нет.
|
||||
|
||||
## 2. Принципы архитектуры
|
||||
|
||||
1. **Файлы — источник истины.** БД перестраивается командой `reindex`; исключение — служебные таблицы (пользователи, токены, аудит, заявки с форм).
|
||||
2. **Один сервисный слой.** Админка, MCP и CLI вызывают одни и те же сервисы, поэтому права, валидация и аудит едины.
|
||||
3. **Всё, что пишется, проходит схему.** Фрагменты и коллекции описаны схемами; невалидное не сохраняется и не публикуется.
|
||||
4. **Стабильные ID блоков.** Блок адресуется по `id`, а не по индексу, поэтому страницу безопасно патчить параллельно (человек и агент).
|
||||
5. **Статика по умолчанию.** Динамика только там, где без неё нельзя: формы, поиск, превью.
|
||||
6. **Безопасность по умолчанию.** Шаблоны сайта рендерятся в sandbox, права разделены по ролям (раздел 11).
|
||||
7. **Детерминированная сериализация.** Порядок ключей и форматирование YAML фиксированы, чтобы диффы в git были читаемыми.
|
||||
8. **Расширение файлами.** Фрагмент, layout или коллекция — это папка или файл, а не код ядра.
|
||||
|
||||
## 3. Модель сущностей
|
||||
|
||||
| Сущность | Что это | Где хранится |
|
||||
|---|---|---|
|
||||
| Site | Настройки сайта: домены, локали, тема, умолчания | `site.yaml` |
|
||||
| Page | Страница, собранная вручную из блоков | `pages/**/*.md` или `*.yaml` |
|
||||
| Layout | Каркас страницы: HTML-оболочка + регионы | `layouts/<id>/` |
|
||||
| Fragment | Блок: шаблон + схема полей + стили/скрипты | `fragments/<категория>/<id>/` |
|
||||
| Block | Экземпляр фрагмента на странице | внутри page или display template |
|
||||
| Collection | Тип контента со схемой (cases, products...) | `collections/<id>.yaml` |
|
||||
| Entry | Запись коллекции | `content/<collection>/<slug>.md` |
|
||||
| Display template | Как запись коллекции превращается в страницу | `display/<collection>.yaml` |
|
||||
| Taxonomy | Словарь терминов (технологии, отрасли, теги) | коллекция с `kind: taxonomy` |
|
||||
| Menu | Навигация | `menus/<id>.yaml` |
|
||||
| Data | Произвольные данные (цены, команда, реквизиты) | `data/*.yaml` |
|
||||
| Form | Определение формы обратной связи | `forms/<id>.yaml` |
|
||||
| Asset | Изображения и файлы | `assets/` |
|
||||
|
||||
### 3.1 Блок и дерево композиции
|
||||
|
||||
Поля блока: `id` (короткий стабильный, например `b_7k2m`), `fragment`, `props`, `slots` (именованные списки вложенных блоков), опционально `hidden`, `anchor`, `visibility` (по локали и датам).
|
||||
|
||||
Layout объявляет **регионы**, фрагмент объявляет **слоты**; и то и другое — упорядоченные списки блоков. Фрагмент может ограничивать допустимых детей (`allow`), максимальную глубину вложенности задаёт ядро (по умолчанию 4).
|
||||
|
||||
Значения `props` бывают четырёх видов: литерал; привязка `{bind: путь}`; ссылка на страницу или запись `{page: slug}` / `{entry: коллекция/slug}`; запрос к коллекции `{collection: ...}` (см. 4.8).
|
||||
|
||||
## 4. Форматы файлов
|
||||
|
||||
### 4.1 Структура каталога сайта
|
||||
|
||||
```
|
||||
site/
|
||||
site.yaml
|
||||
redirects.yaml
|
||||
pages/ # ручные страницы; путь файла = URL
|
||||
index.md
|
||||
about.md
|
||||
services/
|
||||
_section.yaml # настройки раздела: layout, меню, сортировка
|
||||
index.md
|
||||
content/ # записи коллекций
|
||||
cases/clinic-crm.md
|
||||
products/
|
||||
collections/ # схемы коллекций
|
||||
display/ # шаблоны отображения записей
|
||||
layouts/
|
||||
fragments/
|
||||
menus/ forms/ data/ assets/
|
||||
```
|
||||
|
||||
### 4.2 site.yaml
|
||||
|
||||
```yaml
|
||||
schema: 1
|
||||
name: Acme Dev
|
||||
base_url: https://acme.example
|
||||
default_locale: ru
|
||||
locales: [ru, en]
|
||||
theme:
|
||||
tokens:
|
||||
color.primary: '#0b5fff'
|
||||
font.body: 'Inter, system-ui, sans-serif'
|
||||
space.section: 4rem
|
||||
defaults:
|
||||
layout: default
|
||||
seo: {title_suffix: ' — Acme Dev'}
|
||||
menus: {main: main, footer: footer}
|
||||
```
|
||||
|
||||
Фрагменты используют токены темы как CSS-переменные (`var(--color-primary)`), а не зашитые значения: смена оформления не требует правки фрагментов.
|
||||
|
||||
### 4.3 Layout
|
||||
|
||||
```yaml
|
||||
# layouts/default/layout.yaml
|
||||
id: default
|
||||
name: Основной
|
||||
extends: base # необязательно: наследование оболочки
|
||||
regions:
|
||||
- {id: header, fixed: [{fragment: site_header}]} # закреплённые блоки
|
||||
- {id: main, allow: [section, hero, richtext, 'collection_*']}
|
||||
- {id: footer, fixed: [{fragment: site_footer}]}
|
||||
```
|
||||
|
||||
```jinja
|
||||
{# layouts/default/layout.html.j2 #}
|
||||
<!doctype html>
|
||||
<html lang='{{ page.locale }}'>
|
||||
<head>{{ seo_head() }}{{ assets_head() }}</head>
|
||||
<body>
|
||||
{{ region('header') }}
|
||||
<main>{{ region('main') }}</main>
|
||||
{{ region('footer') }}
|
||||
{{ assets_body() }}
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
`fixed`-блоки принадлежат layout и не редактируются на странице; регион с `allow` ограничивает набор фрагментов, которые можно туда ставить.
|
||||
|
||||
### 4.4 Фрагмент
|
||||
|
||||
```yaml
|
||||
# fragments/marketing/hero/fragment.yaml
|
||||
id: hero
|
||||
name: Hero-баннер
|
||||
category: marketing
|
||||
version: 1
|
||||
fields:
|
||||
- {key: title, type: text, required: true, max: 120}
|
||||
- {key: subtitle, type: markdown, inline: true}
|
||||
- {key: image, type: asset, accept: [image]}
|
||||
- {key: cta, type: link}
|
||||
- {key: variant, type: select, options: [light, dark, split], default: light}
|
||||
slots: {}
|
||||
preview: {title: Заголовок страницы, variant: dark}
|
||||
```
|
||||
|
||||
```jinja
|
||||
{# fragments/marketing/hero/template.html.j2 #}
|
||||
<section class='f-hero f-hero--{{ props.variant }}'>
|
||||
<h1>{{ props.title }}</h1>
|
||||
{% if props.subtitle %}<div>{{ props.subtitle|md_inline }}</div>{% endif %}
|
||||
{% if props.cta %}<a class='btn' href='{{ props.cta|href }}'>{{ props.cta.label }}</a>{% endif %}
|
||||
</section>
|
||||
```
|
||||
|
||||
**Состав папки фрагмента:** `fragment.yaml` (манифест), `template.html.j2`, необязательные `style.css` и `script.js`, `preview.yaml` (данные для превью в админке).
|
||||
|
||||
**Типы полей:** `text`, `textarea`, `markdown`, `number`, `boolean`, `select`, `multiselect`, `date`, `datetime`, `color`, `icon`, `slug`, `link` (страница, запись или URL + подпись + target), `asset` (изображение или файл), `ref` и `refs` (ссылки на записи коллекций), `group` (вложенный объект), `list` (повторяемая группа полей), `query` (запрос к коллекции), `json` (только для разработчиков).
|
||||
|
||||
**Контекст шаблона:** `props`, `slots`, `page`, `site`, `entry` (на страницах записей), `block` (id, anchor), хелперы `href`, `md`, `md_inline`, `asset_url`, `image` (адаптивные варианты), `t` (строки интерфейса).
|
||||
|
||||
**CSS и JS:** подключаются на страницу один раз на фрагмент (дедупликация), CSS изолируется префиксом `.f-<id>`; при сборке всё собирается в хешированные бандлы. Фрагменты не должны зависеть от внешних CDN.
|
||||
|
||||
**Версии:** при несовместимом изменении схемы фрагмента увеличивается `version`, рядом кладётся миграция `migrations/1_to_2.py` (или декларативная карта переименований полей); `validate` и админка показывают блоки, требующие миграции.
|
||||
|
||||
### 4.5 Страница
|
||||
|
||||
```markdown
|
||||
---
|
||||
schema: 1
|
||||
title: Заказная разработка
|
||||
layout: default
|
||||
status: published # draft | published | scheduled | archived
|
||||
seo:
|
||||
description: Разработка ПО под ключ
|
||||
og_image: assets/og/services.png
|
||||
regions:
|
||||
main:
|
||||
- id: b_7k2m
|
||||
fragment: hero
|
||||
props:
|
||||
title: Заказная разработка ПО
|
||||
variant: dark
|
||||
cta: {page: contacts, label: Обсудить проект}
|
||||
- id: b_9xq1
|
||||
fragment: collection_list
|
||||
props:
|
||||
source: {collection: services, sort: order, limit: 6}
|
||||
card: service_card
|
||||
- id: b_3d8f
|
||||
fragment: richtext
|
||||
props: {source: body}
|
||||
---
|
||||
Основной текст страницы в Markdown. Он доступен как `page.body`
|
||||
и выводится фрагментом `richtext` с `source: body`.
|
||||
```
|
||||
|
||||
Если у страницы есть тело, но ни один блок его не использует, `validate` выдаёт предупреждение. Страницы без текста могут быть чистыми `.yaml`-файлами с теми же полями.
|
||||
|
||||
### 4.6 Коллекция и запись
|
||||
|
||||
```yaml
|
||||
# collections/cases.yaml
|
||||
id: cases
|
||||
name: Кейсы
|
||||
route: /cases/{slug}/
|
||||
list_page: /cases/
|
||||
display: cases # display/cases.yaml
|
||||
sort: -date
|
||||
body: markdown # тело записи — Markdown
|
||||
fields:
|
||||
- {key: title, type: text, required: true}
|
||||
- {key: summary, type: textarea}
|
||||
- key: client
|
||||
type: group
|
||||
fields:
|
||||
- {key: name, type: text}
|
||||
- {key: industry, type: ref, to: industries}
|
||||
- {key: confidential, type: boolean}
|
||||
- {key: services, type: refs, to: services}
|
||||
- {key: products, type: refs, to: products}
|
||||
- {key: tech, type: refs, to: technologies}
|
||||
- key: metrics
|
||||
type: list
|
||||
fields: [{key: label, type: text}, {key: value, type: text}]
|
||||
- {key: cover, type: asset}
|
||||
- {key: date, type: date}
|
||||
```
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: CRM для сети клиник
|
||||
slug: clinic-crm
|
||||
status: published
|
||||
client: {name: Клиника+, industry: healthcare}
|
||||
services: [web-development, integrations]
|
||||
tech: [python, postgresql, react]
|
||||
metrics:
|
||||
- {label: Сокращение времени записи, value: '−40%'}
|
||||
cover: assets/cases/clinic.webp
|
||||
date: 2026-03-12
|
||||
---
|
||||
## Задача
|
||||
Текст кейса в Markdown...
|
||||
```
|
||||
|
||||
Коллекции с `kind: taxonomy` (технологии, отрасли, теги) — это те же коллекции, но их записи обычно без тела; для них движок сам строит страницы терминов (`/cases/tag/python/`) по настройке `taxonomy_pages`.
|
||||
|
||||
### 4.7 Display template: запись → страница
|
||||
|
||||
```yaml
|
||||
# display/cases.yaml
|
||||
layout: default
|
||||
seo:
|
||||
title: '{{ entry.title }}'
|
||||
description: '{{ entry.summary }}'
|
||||
regions:
|
||||
main:
|
||||
- fragment: entry_header
|
||||
props: {title: {bind: entry.title}, meta: [{bind: entry.client.name}, {bind: entry.date}]}
|
||||
- fragment: entry_facts
|
||||
props: {items: {bind: entry.metrics}}
|
||||
- fragment: richtext
|
||||
props: {source: entry.body}
|
||||
- fragment: related_entries
|
||||
props:
|
||||
source: {collection: cases, related_to: entry, by: [services, tech], limit: 3}
|
||||
- fragment: cta_banner
|
||||
props: {title: Обсудим ваш проект?, cta: {page: contacts, label: Связаться}}
|
||||
overrides: allow # запись может дополнять или заменять блоки своим regions
|
||||
```
|
||||
|
||||
Когда у записи в front matter есть собственный `regions`, он объединяется с шаблоном по id региона в режиме `append`, `prepend` или `replace` (`regions_mode`, по умолчанию `append`). Так типовая страница остаётся типовой, а особый случай получает уникальные блоки без отдельного шаблона.
|
||||
|
||||
### 4.8 Привязки и запросы
|
||||
|
||||
**Привязка** `{bind: путь}` читает значение из контекста: `entry`, `page`, `site`, `data.<файл>`, `params` (параметры пагинации и фильтров). Ссылки `{page: slug}` и `{entry: коллекция/слаг}` при сборке превращаются в URL с учётом локали; битая ссылка — ошибка сборки.
|
||||
|
||||
**Запрос** (`type: query` или `source:`):
|
||||
|
||||
| Ключ | Назначение |
|
||||
|---|---|
|
||||
| `collection` | коллекция-источник |
|
||||
| `where` | условия: `eq`, `in`, `contains`, `gte`, `lte`, `not` по полям записи, в том числе по `refs` |
|
||||
| `sort`, `limit`, `offset` | порядок и срез (`-date` — убывание) |
|
||||
| `paginate` | размер страницы; движок генерирует `/page/2/` и т.д. |
|
||||
| `ids` | ручной выбор записей в нужном порядке |
|
||||
| `related_to`, `by` | похожие записи по общим значениям связей |
|
||||
| `locale` | локаль выборки (по умолчанию текущая) |
|
||||
|
||||
Запросы выполняются при сборке по индексу в SQLite. Зависимости (какая страница читает какие записи) пишутся в граф, чтобы инкрементальная сборка пересобирала только затронутое.
|
||||
|
||||
## 5. Структура сайта и маршрутизация
|
||||
|
||||
### 5.1 Маршруты
|
||||
|
||||
- URL = путь файла в `pages/`: `pages/about.md` → `/about/`, `index.md` → корень раздела. Если имя файла не совпадает с нужным URL (`pages/scenario-legal.md` → `/scenarios/legal/`), адрес задаётся полем `route:` в front matter.
|
||||
- Записи коллекций получают URL из `route` в схеме коллекции, список — из `list_page`.
|
||||
- Служебные маршруты генерирует движок: `/sitemap.xml`, `/robots.txt`, `/404.html`, страницы пагинации, страницы терминов таксономий, `/feed.xml` (по настройке).
|
||||
- Два источника на один URL — ошибка сборки. Слаги латиницей; кириллица в slug автоматически транслитерируется.
|
||||
- Смена slug записывает старый адрес в историю, и редирект создаётся автоматически; ручные правила лежат в `redirects.yaml`.
|
||||
|
||||
### 5.2 Разделы
|
||||
|
||||
Папка с файлом `_section.yaml` — раздел. Он задаёт значения по умолчанию для вложенных страниц и порядок детей:
|
||||
|
||||
```yaml
|
||||
# pages/services/_section.yaml
|
||||
title: Услуги
|
||||
layout: default
|
||||
nav: {menu: main, label: Услуги, order: 10}
|
||||
children_sort: order
|
||||
defaults:
|
||||
seo: {title_suffix: ' — Acme'}
|
||||
plan: {priority: P1}
|
||||
```
|
||||
|
||||
Хлебные крошки строятся из дерева разделов и переопределяются полем `breadcrumb:` страницы.
|
||||
|
||||
### 5.3 Меню
|
||||
|
||||
Меню — файлы `menus/*.yaml` плюс пункты, которые страницы объявляют сами (`nav: {menu: footer, label: ..., order: ...}`). Пункт может быть ссылкой на страницу, запись или внешний URL и поддерживает поля `enabled`, `requires` (условия показа, см. 7.4) и `note`. Выключенный пункт остаётся в файле, но не попадает в HTML: это удобно, когда раздел временно исключён.
|
||||
|
||||
### 5.4 Типовые структуры
|
||||
|
||||
| Структура | Как реализуется |
|
||||
|---|---|
|
||||
| Лендинг из секций | Страница из блоков `section`, якоря через `anchor`, меню по якорям |
|
||||
| Обзор + дочерние страницы | Раздел, а в обзоре `collection_list` с `source: {children: current}` или коллекция |
|
||||
| Каталог: список → карточка | Коллекция + display template, пагинация и фильтры по таксономиям |
|
||||
| Запись с подстраницами | Подмаршруты записи (`/academy/<курс>/program/`), каждый со своим display template |
|
||||
| Юридические документы | Layout `legal`: оглавление, дата и версия редакции |
|
||||
| Служебные страницы | 404, «спасибо» после формы, страница превью, печатная версия |
|
||||
| Несколько языков | Поле `locales`, переводы рядом (`about.en.md`), связь через `translations`, `hreflang` |
|
||||
|
||||
### 5.5 Границы v1
|
||||
|
||||
Один запуск движка обслуживает один сайт (каталог `site/`). Каталог `sites/<имя>/` для нескольких сайтов закладываем в структуру путей, но не реализуем. Мультиязычность в v1 ограничена моделью данных (`locale` у страниц и записей) и генерацией `hreflang`; интерфейс переводов в админке откладываем.
|
||||
|
||||
## 6. Сборка, превью и публикация
|
||||
|
||||
### 6.1 Конвейер сборки
|
||||
|
||||
1. **load** — чтение файлов, парсинг YAML и Markdown, нормализация.
|
||||
2. **validate** — схемы, ссылки, ассеты, уникальность маршрутов, правила сайта (см. 6.5).
|
||||
3. **index** — запись страниц, записей и графа ссылок в SQLite.
|
||||
4. **resolve** — выполнение запросов и привязок, сборка меню и хлебных крошек.
|
||||
5. **render** — Jinja в sandbox, HTML каждой страницы.
|
||||
6. **postprocess** — бандлы CSS/JS с хешами, варианты изображений (webp, srcset), `sitemap.xml`, поисковый индекс.
|
||||
7. **publish** — запись в `dist/<build-id>/` и атомарное переключение символической ссылки `current`; последние N сборок хранятся для отката.
|
||||
|
||||
### 6.2 Инкрементальность и скорость
|
||||
|
||||
Граф зависимостей (какая страница читает какие записи, фрагменты и данные) позволяет пересобирать только затронутое. Ориентир для v1: полная сборка сайта до 500 страниц менее 10 секунд, правка одной страницы менее 1 секунды.
|
||||
|
||||
### 6.3 Превью
|
||||
|
||||
Динамический рендер одной страницы из рабочего каталога без записи в `dist`. Показывает черновики и использует те же CSS и JS, что и сборка. В админке открывается во фрейме; для внешних согласований выдаётся ссылка с токеном и сроком жизни.
|
||||
|
||||
### 6.4 Статусы и история
|
||||
|
||||
`status`: `draft` → `review` → `published` (плюс `scheduled` с датой и `archived`). В публикуемую сборку попадают только `published` и `scheduled`, чей срок наступил (проверка по расписанию). История изменений: если каталог сайта — git-репозиторий, каждое сохранение коммитится с автором (человек или агент); изменения агента могут идти в отдельную ветку `agent/*` и вливаться человеком. Без git используются ревизии в таблице `revisions`.
|
||||
|
||||
### 6.5 Проверки `validate`
|
||||
|
||||
Ошибки блокируют публикацию, предупреждения — нет.
|
||||
|
||||
- **Ошибки:** невалидный YAML; поля не по схеме; неизвестный фрагмент или версия; фрагмент не разрешён в регионе; дубли `id` блоков; битые ссылки на страницы, записи и ассеты; конфликты маршрутов; нарушение правил сайта (см. 7.5).
|
||||
- **Предупреждения:** тело страницы не использовано блоком; нет `seo.description`; у изображения нет `alt`; ассеты без ссылок; блоки на устаревшей версии фрагмента; страницы без входящих ссылок.
|
||||
|
||||
### 6.6 Поиск
|
||||
|
||||
Варианты: статический JSON-индекс с клиентским поиском (без сервера) либо серверный поиск на SQLite FTS5. Решение вынесено в открытые вопросы.
|
||||
|
||||
## 7. Опорный пример: студия ботов, AI-систем и автоматизаций
|
||||
|
||||
Пример взят из карты сайта `SiteMap.md` (черновик v0.1): студия Telegram-ботов, AI-систем и автоматизаций с Академией курсов. Раздел показывает, как реальная карта раскладывается по модели ТЗ и что в модели пришлось дополнить.
|
||||
|
||||
### 7.1 Что ложится в модель как есть
|
||||
|
||||
- Дерево страниц → `pages/` и `_section.yaml`; приоритеты P1/P2 переносятся в поле `plan`.
|
||||
- Шапка и футер → `menus/main.yaml`, `menus/footer.yaml` и фрагменты `site_header`, `site_footer`.
|
||||
- Каркас главной из восьми блоков → `pages/index.md` с блоками в регионе `main`.
|
||||
- Колонки «Задача страницы» и «Куда ведёт дальше» → поля страницы `goal` и `next` (видны в админке, на сайт не выводятся; агент использует их для проверки текстов).
|
||||
|
||||
### 7.2 Коллекции
|
||||
|
||||
| Коллекция | Записи | Маршрут | Заметки |
|
||||
|---|---|---|---|
|
||||
| `services` | bots, ai, automation | `/services/{slug}/` | Три записи, общий display template, у каждой свои блоки через `overrides` |
|
||||
| `scenarios` | legal, real-estate, services | `/scenarios/{slug}/` | Типовые сценарии, а не кейсы: схема без `metrics`, обязательный блок-дисклеймер |
|
||||
| `courses` | по мере появления | `/academy/{slug}/` | Пустая коллекция допустима, поля в 7.6 |
|
||||
| `cases` | — | `/cases/{slug}/` | Схема есть, раздел выключен: `features.cases: false` |
|
||||
| `posts` | — | `/blog/{slug}/` | Схема есть, раздел выключен: `features.blog: false` |
|
||||
|
||||
Ручные страницы: главная, о компании, безопасность и данные, контакты, заявка, политика ПД, оферта, страница «спасибо».
|
||||
|
||||
### 7.3 Каркас главной
|
||||
|
||||
| № | Блок карты | Фрагмент | Особенности |
|
||||
|---|---|---|---|
|
||||
| 1 | Hero | `hero` | CTA: Telegram и заявка |
|
||||
| 2 | Три направления | `collection_list` (`services`, карточка `direction_card`) | Данные из коллекции, дублей нет |
|
||||
| 3 | Живые примеры | `live_examples` | `hidden`, `requires: [feature.demo]` |
|
||||
| 4 | Что уже работает | `feature_grid` | Плашки со сроками, данные `verified` |
|
||||
| 5 | Цифры | `stats` | `hidden`, `requires: [data.stats]` |
|
||||
| 6 | Как идёт работа | `steps` | 5 шагов |
|
||||
| 7 | О нас | `about_teaser` | Ссылка на `/about/` |
|
||||
| 8 | Финальный CTA | `cta_banner` | Telegram и форма |
|
||||
|
||||
Исключённые блоки остаются в файле с прежней нумерацией (`id` стабильны), чтобы вернуть их одной правкой:
|
||||
|
||||
```yaml
|
||||
- id: b_demo
|
||||
fragment: live_examples
|
||||
hidden: true
|
||||
note: Исключён на старте — нет демо
|
||||
requires: [feature.demo]
|
||||
- id: b_stats
|
||||
fragment: stats
|
||||
hidden: true
|
||||
note: Исключён на старте — нет подтверждённых цифр
|
||||
requires: [data.stats]
|
||||
```
|
||||
|
||||
### 7.4 Что добавляем в модель по итогам карты
|
||||
|
||||
| Что в карте | Что добавляем |
|
||||
|---|---|
|
||||
| Приоритеты P1/P2, пометки ➕ и ⛔ | Поле страницы `plan: {priority, state: planned/added/excluded/done, note, data_ready}`. Движок строит отчёт готовности сайта, он же доступен агенту через MCP |
|
||||
| «Исключено на старте, можно вернуть» | Флаги `features` в `site.yaml`; у блока `hidden` и `note`; у пункта меню `enabled`. Возврат — одна правка |
|
||||
| «Включаем, только если есть чем подтвердить» | `requires:` у блока: список ссылок на `feature.*` и `data.*`; блок рендерится, только если все они не пусты |
|
||||
| Имя файла не равно URL | `route:` в front matter (см. 5.1) |
|
||||
| «Сценарий, не кейс», без выдуманных результатов | Отдельная коллекция без `metrics`, обязательный фрагмент `disclaimer` и правило сайта (7.5) |
|
||||
| «Заявка → Благодарность» | У формы `success.page`; страница «спасибо» добавляется в карту |
|
||||
| «Оплата / запись» на курс | CTA-тип `enroll`: внешняя платёжная страница или форма записи; своя оплата вне v1 |
|
||||
| 152-ФЗ и политика ПД | Тип поля формы `consent` (чекбокс, ссылка на политику, версия редакции); факт согласия хранится вместе с заявкой |
|
||||
| «Ждёт данных о курсах» | Пустое состояние `collection_list` (`empty: hide` или `message`); страница `status: draft` с `plan.data_ready: false` |
|
||||
| Telegram как основной канал | Секция `contacts` в `site.yaml` и CTA-тип `contact`; смена ника правится в одном месте; уведомления о заявках уходят в Telegram |
|
||||
| Реквизиты, год и название в футере | `data/company.yaml` и фрагмент `requisites`; год подставляет сборка |
|
||||
|
||||
### 7.5 Правила контента сайта
|
||||
|
||||
Договорённости из карты (без выдуманных результатов, согласие на обработку ПД) превращаются в проверяемые правила в `site.yaml`:
|
||||
|
||||
```yaml
|
||||
rules:
|
||||
- {id: scenario-disclaimer, collection: scenarios, require_fragment: disclaimer, level: error}
|
||||
- {id: verified-numbers, fragments: [stats, feature_grid], require: verified, level: warning}
|
||||
- {id: form-consent, forms: all, require_field: consent, level: error}
|
||||
```
|
||||
|
||||
Правила выполняет `validate`; агент получает их через MCP до правки текстов и не нарушает по неведению.
|
||||
|
||||
### 7.6 Коллекция courses (набросок)
|
||||
|
||||
```yaml
|
||||
id: courses
|
||||
name: Курсы
|
||||
route: /academy/{slug}/
|
||||
list_page: /academy/
|
||||
display: courses
|
||||
body: markdown
|
||||
fields:
|
||||
- {key: title, type: text, required: true}
|
||||
- {key: summary, type: textarea}
|
||||
- {key: audience, type: text}
|
||||
- {key: format, type: select, options: [self-paced, cohort, live]}
|
||||
- {key: duration, type: text}
|
||||
- {key: starts, type: date}
|
||||
- {key: outcomes, type: list, fields: [{key: item, type: text}]}
|
||||
- key: program
|
||||
type: list
|
||||
fields: [{key: module, type: text}, {key: lessons, type: textarea}]
|
||||
- key: price
|
||||
type: group
|
||||
fields: [{key: amount, type: number}, {key: currency, type: text}, {key: note, type: text}]
|
||||
- key: enroll
|
||||
type: group
|
||||
fields: [{key: kind, type: select, options: [link, form]}, {key: url, type: text}]
|
||||
```
|
||||
|
||||
Display template курса: `entry_header` → `feature_grid` (чему научится) → `course_program` → `richtext` → `enroll_block` (цена и запись) → `faq` → ссылка на оферту. Точный состав согласуем, когда появятся данные о курсах.
|
||||
|
||||
### 7.7 Что стоит уточнить в самой карте
|
||||
|
||||
- Нет страницы «спасибо», хотя в таблице задач заявка ведёт на «Благодарность».
|
||||
- Страница курса отсылает к «шаблону ниже», но в файле его нет.
|
||||
- «Сценарии» отмечены P1, но пункта в шапке нет: решить, откуда на них ведут ссылки (главная и страницы услуг?).
|
||||
- «Типовые сроки» в блоке «Что уже работает» — тоже числа: нужен источник или пометка «ориентировочно».
|
||||
|
||||
## 8. Базовый набор фрагментов
|
||||
|
||||
### 8.1 Общие свойства блока
|
||||
|
||||
Эти поля есть у любого блока независимо от фрагмента, во фрагментах их дублировать не нужно: `id`, `anchor`, `hidden`, `note`, `requires`, `visibility` (локали, даты) и `style` (отступы, фон из токенов темы, ширина контейнера).
|
||||
|
||||
### 8.2 Каталог (этап: MVP — первая версия, v1 — следом, позже — по потребности)
|
||||
|
||||
**Структура и заголовки**
|
||||
|
||||
| Фрагмент | Назначение | Ключевые поля | Этап |
|
||||
|---|---|---|---|
|
||||
| `section` | Контейнер секции со слотом `content` | фон, ширина, отступы | MVP |
|
||||
| `columns` | 2–4 колонки, слот на колонку | число колонок, пропорции, выравнивание | MVP |
|
||||
| `hero` | Первый экран | title, subtitle, image, actions, variant | MVP |
|
||||
| `page_header` | Заголовок внутренней страницы | title, lead, breadcrumbs | MVP |
|
||||
| `divider` | Разделитель или отступ | тип, высота | v1 |
|
||||
|
||||
**Контент**
|
||||
|
||||
| Фрагмент | Назначение | Ключевые поля | Этап |
|
||||
|---|---|---|---|
|
||||
| `richtext` | Текст в Markdown | source (`body`, `entry.body` или текст) | MVP |
|
||||
| `image` | Изображение | asset, alt, caption | MVP |
|
||||
| `disclaimer` | Пометка или оговорка | variant (info, warning), text | MVP |
|
||||
| `legal_text` | Юридический текст | оглавление, дата и версия редакции | MVP |
|
||||
| `chat_demo` | Пример диалога в мессенджере (статичный) | messages (from: user или bot), buttons | v1 |
|
||||
| `gallery`, `video_embed`, `quote`, `code_block`, `table` | Типовые контентные блоки | по назначению | v1 |
|
||||
|
||||
**Карточки и списки**
|
||||
|
||||
| Фрагмент | Назначение | Ключевые поля | Этап |
|
||||
|---|---|---|---|
|
||||
| `card_grid` | Сетка карточек | items: title, text, link, icon, badge | MVP |
|
||||
| `feature_grid` | Преимущества или возможности | items: title, text, icon, badge, verified | MVP |
|
||||
| `steps` | Этапы работы | items: title, text | MVP |
|
||||
| `faq` | Вопросы и ответы (разметка FAQ для поиска) | items: q, a | MVP |
|
||||
| `stats` | Цифры | items: value, label, verified | v1 |
|
||||
| `logo_cloud`, `team_grid`, `testimonials`, `pricing_table` | Клиенты, команда, отзывы, тарифы | по назначению | v1 |
|
||||
| `timeline`, `comparison_table` | История и сравнение | по назначению | позже |
|
||||
|
||||
**Коллекции**
|
||||
|
||||
| Фрагмент | Назначение | Ключевые поля | Этап |
|
||||
|---|---|---|---|
|
||||
| `collection_list` | Список записей | source, card, layout, paginate, filters, empty | MVP |
|
||||
| `entry_header` | Шапка страницы записи | title, meta, tags | MVP |
|
||||
| `related_entries` | Похожие записи | source (`related_to`, `by`), limit | v1 |
|
||||
| `collection_featured` | Ручная подборка записей | ids, card | v1 |
|
||||
| `entry_facts` | Ключевые факты записи | items: label, value | v1 |
|
||||
| `entry_nav` | Предыдущая и следующая запись | collection | v1 |
|
||||
| `course_program` | Программа курса | modules | v1 |
|
||||
| `enroll_block` | Цена и запись на курс | price, enroll | v1 |
|
||||
|
||||
**Конверсия и контакты**
|
||||
|
||||
| Фрагмент | Назначение | Ключевые поля | Этап |
|
||||
|---|---|---|---|
|
||||
| `cta_banner` | Призыв к действию | title, text, actions (тип: link, contact, form, enroll) | MVP |
|
||||
| `form` | Форма из `forms/<id>.yaml` | form | MVP |
|
||||
| `contact_block` | Способы связи | берёт `site.contacts` | MVP |
|
||||
| `requisites` | Реквизиты компании | берёт `data.company` | MVP |
|
||||
|
||||
**Навигация и глобальное**
|
||||
|
||||
| Фрагмент | Назначение | Ключевые поля | Этап |
|
||||
|---|---|---|---|
|
||||
| `site_header`, `site_footer` | Шапка и футер | menu, action, источники данных | MVP |
|
||||
| `nav_menu` | Меню по id | menu, orientation | MVP |
|
||||
| `breadcrumbs` | Хлебные крошки | — | MVP |
|
||||
| `pagination` | Постраничная навигация | используется списками | MVP |
|
||||
| `toc`, `announcement_bar`, `cookie_notice` | Оглавление, плашка, уведомление о cookie | по назначению | v1 |
|
||||
| `search_box`, `language_switcher` | Поиск и язык | по назначению | позже |
|
||||
| `embed_html` | Произвольный HTML в sandbox-iframe | code | позже, только роль developer |
|
||||
|
||||
Итого MVP — 22 фрагмента: хватает на сайт-пример (раздел 7) без ручного HTML. Часть сайта-примера (`direction_card`, `about_teaser`, `live_examples`) — это варианты карточек и тематические обёртки поверх базовых; их добавляем как фрагменты сайта, а не ядра.
|
||||
|
||||
### 8.3 Требования к любому фрагменту
|
||||
|
||||
1. Манифест со схемой полей, `preview.yaml` с тестовыми данными, версия.
|
||||
2. Семантическая разметка, `alt` у изображений, управляемый фокус, контраст из токенов темы.
|
||||
3. Только токены темы и классы `.f-<id>`, без внешних CDN и без инлайновых обработчиков.
|
||||
4. Пустые и граничные данные не ломают вёрстку (`hidden_if_empty`, значения по умолчанию).
|
||||
5. Автоматический snapshot-тест рендера на `preview.yaml`.
|
||||
|
||||
## 9. Формы и заявки
|
||||
|
||||
### 9.1 Определение формы
|
||||
|
||||
```yaml
|
||||
# forms/consultation.yaml
|
||||
id: consultation
|
||||
title: Заявка на разговор
|
||||
fields:
|
||||
- {key: name, type: text, label: Имя, required: true}
|
||||
- {key: contact, type: text, label: Telegram или телефон, required: true}
|
||||
- {key: task, type: textarea, label: Расскажите о задаче, hint: Свободная форма, ТЗ не нужно}
|
||||
- {key: consent, type: consent, policy: privacy}
|
||||
success: {page: consultation/thanks}
|
||||
notify:
|
||||
- {kind: telegram, chat: '${TG_CHAT_ID}'}
|
||||
- {kind: email, to: ['${LEADS_EMAIL}']}
|
||||
antispam: {honeypot: true, rate_limit: '5/hour'}
|
||||
store: {retention_days: 365}
|
||||
```
|
||||
|
||||
Секреты (токен бота, адреса) берутся из переменных окружения, в файлах сайта их нет.
|
||||
|
||||
### 9.2 Обработка
|
||||
|
||||
- Форма — единственная динамическая часть статического сайта: `POST /forms/{id}` в FastAPI. Без JS это обычный POST с редиректом на `success.page`; htmx или небольшой скрипт делает отправку без перезагрузки.
|
||||
- Валидация по схеме формы, запись в таблицу `form_submissions` вместе со снимком согласия (время, версия политики), уведомления через очередь с повторными попытками.
|
||||
- Защита: honeypot, лимит запросов, проверка размера, экранирование при показе в админке.
|
||||
|
||||
### 9.3 Персональные данные
|
||||
|
||||
Заявки содержат ПД, поэтому: доступ к ним только у ролей с правом `submissions:read`, срок хранения и автоматическое удаление, экспорт и удаление по запросу, аудит просмотров. Требования закона к хранению и размещению сервера определяет владелец сайта вместе с юристом; движок даёт технические средства (согласие с версией, срок хранения, удаление, журнал).
|
||||
|
||||
### 9.4 Админка заявок
|
||||
|
||||
Список со статусами (`new`, `processed`, `spam`), поиск, заметки, экспорт в CSV.
|
||||
|
||||
## 10. Админка (FastAPI + htmx)
|
||||
|
||||
### 10.1 Экраны
|
||||
|
||||
| Экран | Что делает |
|
||||
|---|---|
|
||||
| Обзор | Отчёт готовности по `plan`: что готово, что ждёт данных, что исключено; ошибки и предупреждения `validate`; последние сборки |
|
||||
| Страницы | Дерево разделов, статусы, фильтры, создание и перенос страниц |
|
||||
| Редактор страницы | Регионы и блоки: добавить, удалить, переместить; форма блока строится из схемы фрагмента; превью во фрейме |
|
||||
| Коллекции | Таблица записей с фильтрами; форма записи; Markdown-редактор |
|
||||
| Фрагменты и layouts | Каталог с превью и схемой полей; правка кода только у роли developer |
|
||||
| Меню и данные | Редактирование `menus/*.yaml` и `data/*.yaml` формами по схемам |
|
||||
| Медиа | Загрузка, подписи (`alt`), поиск неиспользуемых файлов |
|
||||
| Формы и заявки | Список заявок, статусы, экспорт |
|
||||
| Доступ | Пользователи, роли, токены агентов |
|
||||
| Журнал и сборки | Аудит, история публикаций, откат |
|
||||
|
||||
### 10.2 Технические решения
|
||||
|
||||
- Серверный рендер Jinja-партиалами; htmx заменяет регион страницы или форму блока, JS-сборки нет. SortableJS — перенос блоков, EasyMDE — Markdown.
|
||||
- Формы блоков генерируются из схемы фрагмента макросами по типам полей; ошибки валидации возвращаются в ту же форму.
|
||||
- Конфликты редактирования: при открытии запоминается хеш файла, при сохранении он сверяется; при расхождении показывается diff и выбор действия (так человек и агент не затирают друг друга).
|
||||
- Сессионная cookie, CSRF-токен через `hx-headers`, лимит попыток входа.
|
||||
- Два окружения Jinja: админское и сайтовое (sandbox). Шаблоны сайта не получают доступа к объектам админки.
|
||||
|
||||
## 11. Роли, права и безопасность
|
||||
|
||||
### 11.1 Роли
|
||||
|
||||
| Действие | owner | developer | editor | reviewer | agent |
|
||||
|---|---|---|---|---|---|
|
||||
| Страницы, записи, данные, меню | да | да | да | нет | по scope |
|
||||
| Фрагменты, layouts, схемы коллекций | да | да | нет | нет | нет |
|
||||
| Публикация и откат | да | да | да | нет | только если разрешено владельцем |
|
||||
| Согласование и комментарии | да | да | да | да | нет |
|
||||
| Заявки (ПД) | да | нет | по праву `submissions:read` | нет | нет |
|
||||
| Пользователи, токены, настройки | да | нет | нет | нет | нет |
|
||||
|
||||
Токен агента несёт scope (например `read`, `content:write`, `publish`), срок жизни и ограничение по разделам сайта. По умолчанию агент пишет в `draft` или в ветку `agent/*`, публикует человек.
|
||||
|
||||
### 11.2 Меры безопасности
|
||||
|
||||
- Шаблоны сайта рендерятся в Jinja `SandboxedEnvironment`, доступны только разрешённые фильтры и функции; шаблоны читаются только из каталога сайта.
|
||||
- Raw HTML в Markdown выключен по умолчанию; допустимые теги — allowlist, вывод проходит санитизацию. `embed_html` и произвольные скрипты — только роль developer.
|
||||
- YAML читается только безопасным загрузчиком, с лимитами размера, глубины и числа алиасов.
|
||||
- Загрузки: проверка типа по содержимому, лимит размера, санитизация SVG, запрет исполняемых типов; защита от выхода за каталог (path traversal).
|
||||
- Заголовки: CSP, `X-Content-Type-Options`, `Referrer-Policy`; CSRF для админки; лимиты на вход, формы и MCP.
|
||||
- Токены хранятся только в виде хеша; секреты — в переменных окружения; все записи и просмотр заявок попадают в `audit_log` с актором (человек или агент).
|
||||
- Резервные копии: каталог сайта (git или архив) и файл SQLite с проверкой восстановления.
|
||||
|
||||
## 12. MCP-сервер
|
||||
|
||||
Транспорт: Streamable HTTP внутри того же FastAPI-приложения; авторизация Bearer-токеном со scope. Инструменты вызывают сервисный слой, поэтому права и валидация такие же, как в админке.
|
||||
|
||||
### 12.1 Инструменты
|
||||
|
||||
| Группа | Инструменты |
|
||||
|---|---|
|
||||
| Чтение | `get_site_plan`, `get_rules`, `list_pages`, `get_page`, `list_collections`, `list_entries`, `get_entry`, `list_fragments`, `get_fragment_schema`, `list_layouts`, `list_menus`, `list_assets`, `search` |
|
||||
| Запись | `create_page`, `update_page_meta`, `add_block`, `update_block`, `move_block`, `remove_block`, `set_block_visibility`, `create_entry`, `update_entry`, `update_menu`, `update_data`, `upload_asset` |
|
||||
| Контроль | `validate`, `render_preview` (HTML или скриншот), `diff`, `submit_for_review`, `publish`, `list_builds`, `rollback` |
|
||||
|
||||
### 12.2 Принципы
|
||||
|
||||
- Блоки адресуются по `id`, поля — по пути (`regions.main[b_7k2m].props.cta.label`); индексы позиций не используются.
|
||||
- Все записи принимают `dry_run` и `if_match` (хеш версии файла); при конфликте возвращается актуальная версия.
|
||||
- Ошибки валидации приходят структурой: путь к полю, правило, ожидаемое значение, подсказка, как исправить.
|
||||
- Схемы и правила сайта публикуются как MCP-ресурсы; типовые задачи («страница по брифу», «перевод страницы», «проверка текста по карте») — как MCP-промпты.
|
||||
- Агент не может менять фрагменты, layouts и схемы без роли developer.
|
||||
|
||||
## 13. Данные в SQLite (SQLAlchemy)
|
||||
|
||||
Индексные таблицы восстанавливаются командой `reindex`; остальные хранят то, чего нет в файлах.
|
||||
|
||||
| Таблица | Содержимое | Восстанавливается из файлов |
|
||||
|---|---|---|
|
||||
| `pages_index` | путь, маршрут, локаль, статус, layout, `plan`, front matter (JSON), хеш | да |
|
||||
| `entries_index` | коллекция, slug, маршрут, статус, данные (JSON), хеш | да |
|
||||
| `refs` | граф ссылок и зависимостей страниц от записей, фрагментов и данных | да |
|
||||
| `fragments_index`, `assets_index` | фрагменты (версия, схема), ассеты (размер, тип, хеш) | да |
|
||||
| `search_fts` | полнотекстовый индекс FTS5 | да |
|
||||
| `slug_history` | старые адреса для редиректов | нет |
|
||||
| `revisions` | ревизии, если сайт не в git | нет |
|
||||
| `users`, `roles`, `sessions`, `api_tokens` | доступ; токены только в виде хеша | нет |
|
||||
| `audit_log` | действия с актором, объектом, до и после | нет |
|
||||
| `form_submissions` | заявки, согласия, статусы | нет |
|
||||
| `build_runs` | сборки: статус, время, лог, кто запустил | нет |
|
||||
| `locks` | блокировки записи страниц | нет |
|
||||
|
||||
SQLite в режиме WAL, миграции Alembic, синхронный доступ в threadpool.
|
||||
|
||||
## 14. Нефункциональные требования
|
||||
|
||||
- **Производительность:** см. 6.2; отдача сайта — статика, нагрузка на FastAPI только от админки, форм и MCP.
|
||||
- **Надёжность:** атомарная запись файлов (временный файл и rename), атомарная публикация сборки, откат на предыдущую.
|
||||
- **Развёртывание:** один Docker-образ, тома `site/`, `data/` (SQLite), `dist/`; конфигурация через переменные окружения; статику отдаёт nginx или сам FastAPI.
|
||||
- **Доступность и SEO:** базовые фрагменты соответствуют WCAG 2.1 AA; canonical, Open Graph, `sitemap.xml`, разметка schema.org там, где применимо.
|
||||
- **Тестирование:** unit-тесты парсеров и схем; snapshot-тесты рендера каждого фрагмента; сквозной тест сборки сайта-примера; контрактные тесты MCP-инструментов.
|
||||
- **Наблюдаемость:** структурированные логи, журнал сборок, метрики времени сборки и ошибок валидации.
|
||||
|
||||
## 15. Этапы
|
||||
|
||||
| Этап | Состав |
|
||||
|---|---|
|
||||
| M0. Ядро | Парсер md + yaml, схемы (pydantic из манифестов), индекс, рендер, CLI (`build`, `validate`, `serve`, `reindex`), 10 базовых фрагментов; сайт-пример как тестовый набор |
|
||||
| M1. Коллекции и MCP | Коллекции, display templates, запросы, меню, привязки; MCP: чтение и запись, `validate`, превью; формы и заявки |
|
||||
| M2. Админка | Экраны раздела 10, роли, токены, аудит, конфликты редактирования |
|
||||
| M3. Полный MVP-набор | Все 22 фрагмента, тема, инкрементальная сборка, публикация и откат, интеграция с git |
|
||||
| M4. Расширение | Поиск, мультиязычность, медиа-варианты, фрагменты v1 |
|
||||
| Позже | Визуальный редактор на самой странице |
|
||||
|
||||
## 16. Открытые вопросы
|
||||
|
||||
1. История изменений: git обязателен или допускаем только таблицу `revisions`?
|
||||
2. Поиск: статический индекс на клиенте или FTS5 на сервере?
|
||||
3. Мультиязычность: нужна в первой версии или только заложить модель?
|
||||
4. Публикация: кто отдаёт `dist` (nginx или FastAPI) и где живёт сервер?
|
||||
5. Формы: какие каналы уведомлений нужны сразу (Telegram, почта, webhook)?
|
||||
6. Оплата курсов: внешний провайдер ссылкой или форма записи без оплаты?
|
||||
7. Политика JS во фрагментах: разрешён ли собственный JS у фрагментов сайта или только из набора ядра?
|
||||
8. Аутентификация админки: локальные аккаунты или внешний провайдер (SSO)?
|
||||
9. Режим работы агента: прямая запись в `draft` или обязательно через ветку и согласование?
|
||||
10. Название проекта.
|
||||
@@ -0,0 +1,80 @@
|
||||
from playwright.sync_api import sync_playwright
|
||||
from pathlib import Path
|
||||
import json
|
||||
BASE=Path('/mnt/data/site-engine-admin-stage6')
|
||||
CSS=(BASE/'assets/publication.css').read_text()+'\n'+(BASE/'assets/stage6.css').read_text().replace("@import url('publication.css');",'')
|
||||
JS=(BASE/'assets/stage6.js').read_text()
|
||||
def load(page,theme):
|
||||
markup=(BASE/f'modules-{theme}.html').read_text().replace('<link rel="stylesheet" href="assets/stage6.css">','<style>'+CSS+'</style>').replace('<script src="assets/stage6.js" defer></script>','')
|
||||
page.set_content(markup,wait_until='load')
|
||||
page.add_script_tag(content=JS)
|
||||
|
||||
errs=[]
|
||||
with sync_playwright() as p:
|
||||
browser=p.chromium.launch(headless=True,executable_path='/usr/bin/chromium',args=['--no-sandbox','--disable-gpu'])
|
||||
for theme in ['rose-graphite','antirion']:
|
||||
page=browser.new_page(viewport={'width':1440,'height':900})
|
||||
page.on('pageerror',lambda e:errs.append(str(e)))
|
||||
load(page,theme)
|
||||
print(theme,'MEDIA',page.locator('h1').inner_text(),page.locator('.asset-card').count())
|
||||
assert page.locator('.asset-card').count()==8
|
||||
page.locator('[data-action="asset-edit"]').first.click()
|
||||
page.locator('#asset-form input[name="alt"]').fill('Проверочное описание медиафайла')
|
||||
page.locator('#asset-form button[type="submit"]').count() # external button through form attr
|
||||
page.locator('button[form="asset-form"]').click()
|
||||
assert 'Проверочное описание' in page.locator('.module-shell').inner_text()
|
||||
page.locator('[data-nav="structure"]').first.click()
|
||||
assert 'Структура сайта' in page.locator('h1').inner_text()
|
||||
page.locator('[data-action="menu-add"]').first.click()
|
||||
page.locator('#menu-edit-form input[name="title"]').fill('Блог')
|
||||
page.locator('#menu-edit-form input[name="url"]').fill('/blog/')
|
||||
page.locator('button[form="menu-edit-form"]').click()
|
||||
assert 'Блог' in page.locator('.node-rows').inner_text()
|
||||
page.locator('[data-action="structure-tab"][data-id="fragments"]').click()
|
||||
page.locator('[data-action="structure-usage"]').click()
|
||||
assert 'Где используется' in page.locator('#modal-title').inner_text()
|
||||
page.locator('[data-action="close-modal"]').first.click()
|
||||
page.locator('[data-nav="forms"]').first.click()
|
||||
assert page.locator('h1').inner_text()=='Формы и заявки'
|
||||
page.locator('[data-field-enabled="telegram"]').uncheck()
|
||||
page.locator('[data-field-enabled="telegram"]').check()
|
||||
assert 'Telegram' in page.locator('.form-preview').inner_text()
|
||||
page.locator('[data-action="forms-tab"][data-id="leads"]').click()
|
||||
assert 'Мария К.' in page.locator('.module-shell').inner_text()
|
||||
page.locator('[data-action="role-picker"]').click()
|
||||
page.locator('[data-action="role-change"][data-id="reviewer"]').click()
|
||||
assert 'Контакт скрыт' in page.locator('.module-shell').inner_text()
|
||||
assert 'Мария К.' not in page.locator('.module-shell').inner_text()
|
||||
page.locator('[data-action="role-picker"]').click()
|
||||
page.locator('[data-action="role-change"][data-id="owner"]').click()
|
||||
page.locator('[data-nav="settings"]').click()
|
||||
page.locator('[data-action="settings-tab"][data-id="redirects"]').click()
|
||||
page.locator('[data-action="redirect-add"]').click()
|
||||
page.locator('#kv-form input[name="from"]').fill('/old-test/')
|
||||
page.locator('#kv-form input[name="to"]').fill('/test-new/')
|
||||
page.locator('button[form="kv-form"]').click()
|
||||
assert '/old-test/' in page.locator('.table').inner_text()
|
||||
page.locator('[data-nav="journal"]').click()
|
||||
assert 'Журнал действий' in page.locator('h1').inner_text()
|
||||
assert page.locator('[data-action="audit-view"]').count()>0
|
||||
page.locator('[data-action="audit-view"]').first.click()
|
||||
assert 'Событие' in page.locator('#modal-title').inner_text()
|
||||
page.locator('[data-action="close-modal"]').first.click()
|
||||
page.keyboard.press('Control+k')
|
||||
assert 'Быстрый переход' in page.locator('#modal-title').inner_text()
|
||||
page.locator('#command-search').fill('Медиа')
|
||||
page.locator('[data-action="command-nav"][data-id="media"]').click()
|
||||
assert 'Медиабиблиотека' in page.locator('h1').inner_text()
|
||||
page.screenshot(path=str(BASE/'previews'/f'stage6-{theme}-media-1440.png'),full_page=True)
|
||||
for width,height in [(1440,900),(1280,800),(1024,768),(768,1024),(390,844),(360,740)]:
|
||||
page.set_viewport_size({'width':width,'height':height})
|
||||
over=page.evaluate('document.documentElement.scrollWidth - document.documentElement.clientWidth')
|
||||
if over>1:errs.append(f'{theme} {width} overflow {over}')
|
||||
if width==390:
|
||||
page.screenshot(path=str(BASE/'previews'/f'stage6-{theme}-media-390.png'),full_page=True)
|
||||
print('VIEW',theme,width,over)
|
||||
page.close()
|
||||
browser.close()
|
||||
print('ERRORS',errs)
|
||||
(BASE/'docs/STAGE6_QA_TEST_OUTPUT.txt').write_text(json.dumps({'errors':errs,'status':'pass' if not errs else 'fail'},ensure_ascii=False,indent=2))
|
||||
if errs:raise SystemExit(1)
|
||||
@@ -0,0 +1,30 @@
|
||||
from pathlib import Path
|
||||
from playwright.sync_api import sync_playwright
|
||||
import json
|
||||
BASE=Path('/mnt/data/site-engine-admin-stage6');CSS=(BASE/'assets/publication.css').read_text()+'\n'+(BASE/'assets/stage6.css').read_text().replace("@import url('publication.css');",'');JS=(BASE/'assets/stage6.js').read_text()
|
||||
results=[];errors=[]
|
||||
with sync_playwright() as pw:
|
||||
b=pw.chromium.launch(executable_path='/usr/bin/chromium',headless=True,args=['--no-sandbox'])
|
||||
for theme in ['rose-graphite','antirion']:
|
||||
raw=(BASE/f'modules-{theme}.html').read_text().replace('<link rel="stylesheet" href="assets/stage6.css">','<style>'+CSS+'</style>').replace('<script src="assets/stage6.js" defer></script>','')
|
||||
for section in ['media','structure','forms','settings','journal']:
|
||||
page=b.new_page(viewport={'width':1440,'height':900});page.on('pageerror',lambda e:errors.append(str(e)))
|
||||
page.set_content(raw);page.add_script_tag(content=JS)
|
||||
if section!='media':page.locator(f'[data-nav="{section}"]').first.click()
|
||||
page.wait_for_timeout(220)
|
||||
title=page.locator('h1').inner_text()
|
||||
overflow=page.evaluate('document.documentElement.scrollWidth-document.documentElement.clientWidth')
|
||||
if overflow>1:errors.append(f'{theme} {section} desktop overflow {overflow}')
|
||||
page.screenshot(path=str(BASE/'previews'/f'stage6-{theme}-{section}-1440.png'),full_page=True)
|
||||
page.set_viewport_size({'width':390,'height':844});page.wait_for_timeout(390)
|
||||
overflow=page.evaluate('document.documentElement.scrollWidth-document.documentElement.clientWidth')
|
||||
if overflow>1:errors.append(f'{theme} {section} mobile overflow {overflow}')
|
||||
left=page.evaluate('document.querySelector(".side").getBoundingClientRect().right')
|
||||
if left>0:errors.append(f'{theme} {section} sidebar not hidden when mobile: {left}')
|
||||
page.screenshot(path=str(BASE/'previews'/f'stage6-{theme}-{section}-390.png'),full_page=True)
|
||||
results.append(dict(theme=theme,section=section,title=title,desktopOverflow=0,mobileOverflow=overflow))
|
||||
page.close()
|
||||
b.close()
|
||||
report={'checks':results,'errors':errors};(BASE/'docs/STAGE6_VISUAL_QA.json').write_text(json.dumps(report,ensure_ascii=False,indent=2))
|
||||
print('screens',len(results),'errors',errors)
|
||||
if errors:raise SystemExit(1)
|
||||
Reference in New Issue
Block a user