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,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. Название проекта.
|
||||
Reference in New Issue
Block a user