Add Site Studio themes and Theme Manager

Support categorized fragments, theme presets, block widths, and server-backed theme editing with onboarding and preview.

Include Site Studio, design sources, specification and verification reports; remove the legacy studio-site example.
This commit is contained in:
2026-11-13 14:04:49 +03:00
parent 231490bb7c
commit 0d171915d7
408 changed files with 11812 additions and 550 deletions
@@ -23,6 +23,10 @@ YAML front matter + Markdown body. Общие поля: `schema`, `title`, `layo
- Menu и Redirect — YAML; `rename_page` атомарно переносит Page, правит связи/меню/redirects через changeset (не обязательно автоматически переписывать каждую внешнюю ссылку).
- Asset path — относительный и нормализованный; metadata/alt/caption — нужен отдельный ADR по размещению sidecar (файловый canonical) vs индекс DB; пользовательские тексты не должны исчезать после `reindex`.
### Theme Manager / ThemeDocument (новое требование UX)
Подтверждено: пользователь впервые настраивает **публичную** тему через пресеты или Custom, далее редактирует её в `Настройки → Тема`. Существующее ТЗ §4.2 пока содержит `site.yaml.theme.tokens`. Предложение `site.yaml.theme.file: theme.yaml` + `theme.yaml {schema,preset,preset_version,overrides}` **ожидает ADR-007**. Сервисы `ThemeService.list_presets/get_workspace/resolve/patch_theme/validate` + `OnboardingService.status/complete/skip`. Только file-first canonical данные, `if_match`/409, RBAC/CSRF и полноценная release validation. Подробности — `07_THEME_MANAGER.md`.
## 2. Два уровня валидации
| Уровень | Условия | Итог |
@@ -73,6 +77,7 @@ ActionContext:
| `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 |
| `ThemeService` + `OnboardingService` | `list_presets/get/resolve/patch_theme/validate`, `status/complete/skip` | изменения публичной темы как файл, read/preview draft, `if_match`, publish только через ReleaseService; ADR-007 до окончательного контракта |
| `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 |
@@ -121,6 +126,9 @@ ActionContext:
| `/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/theme` | GET/PATCH | текущая тема/сохранение workspace с `if_match`; proposed ADR-007 |
| `/api/v1/theme/presets` | GET | неизменяемый каталог версионированных пресетов |
| `/api/v1/theme/preview` | POST | разрешённые токены + diagnostics для предпросмотра без записи |
| `/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 |
@@ -8,6 +8,8 @@
**Приёмка:** единая модель файлов не зависит от браузерного localStorage; `reindex` из чистого сайта воспроизводит маршруты/редиректы; не существует неоднозначного определения `source/bind`.
**Новая задача V0 для темы:** согласовать ADR-007, `ThemeDocument` (presets/overrides), миграцию inline `site.yaml.theme.tokens` и тесты resolve + parse/serialize + reproducible CSS, не делать вторую модель в SQLite.
## 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 от данных.
@@ -26,12 +28,16 @@
**Приёмка:** workspace → validate → candidate → publish → live, immutable snapshot, без частично опубликованных результатов; ошибка сборки не переключает live, rollback не затирает workspace, повтор publish idempotent. Список изменений и diff относятся к конкретным hashes, а не fake seed.
**Зависимость V3 для Theme Manager:** build/candidate должен включать зафиксированные разрешённые CSS-токены и версию пресета; rollback восстанавливает визуальную тему публикации без перезаписи рабочего draft.
## 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.
**Дополнение к V4 — Theme Manager и onboarding:** серверный owner-only первый вход для нового сайта (skip/complete), экран выбора готового пресета/Custom, палитра, шрифты, дизайн-токены, htmx preview, `if_match`/409, предупреждение контраста, интеграция в `Настройки → Тема`, доступность локального font fallback. Покрыть `THEME-01..05`.
## V5 — Публичные формы, заявки, outbox
**Делать:** versioned schema формы, публичный POST с валидацией, SQLite submissions/outbox, worker Telegram, UI форм и заявок, access control на ПД, retry/audit/retention. Не подключать дополнительные провайдеры уведомлений до надёжной доставки одного.
@@ -71,6 +77,11 @@
| `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 |
| `THEME-01` | unit | preset@version + overrides детерминировано дают тот же набор CSS-переменных, после reindex результат совпадает |
| `THEME-02` | integration | saved theme draft не меняет live; candidate и rollback возвращают правильные theme tokens |
| `THEME-03` | integration | два редактора одновременно, mismatch по `if_match` → 409; сохранение без потерянных правок |
| `THEME-04` | browser | setup только новому owner, можно skip, preset→custom overrides, preview desktop/mobile, можно вернуться в настройки |
| `THEME-05` | security/a11y | запрет произвольного CSS, проверка HEX/font/контраста, admin skin не зависит от public palette |
| `OPS-01` | chaos | crash mid-build / mid-outbox / mid-commit и recovery |
**Не обещать соответствие SLA:** исходное ТЗ задаёт ориентиры до 500 страниц / 10 секунд, single page / 1 секунда. Это гипотезы для benchmark; принимать реальные performance SLO после измерений на целевом железе.
+179
View File
@@ -0,0 +1,179 @@
# Site Engine — Theme Manager: пресеты, Custom, первый вход
**Тип документа:** дополнение к архитектурному ТЗ и handoff Этапа 7. **Функциональное решение согласовано пользователем 13.11.2026; файловый контракт и API ниже — предлагаемые, до ADR-007.** Это управление **публичным сайтом**, не цветовой схемой админки. Реального backend пока нет.
## 1. Задача
При первом входе **owner** в новый, ещё не настроенный инстанс Site Engine, показывать короткий Wizard с готовыми решениями и опцией **Custom**. Пользователь может выбрать пресет целиком либо использовать его как отправную точку, затем настроить цвета, типографику и дизайн-токены. Все параметры должны быть доступны позднее в `Настройки → Тема сайта / Дизайн сайта`, включая повторное открытие мастера.
**UX:** пошагово, не требуется знание YAML или CSS. На каждом шаге — правдоподобное интерактивное превью `Hero + Buttons + Cards + Typography`. Изменения сохраняются в **workspace draft**, никогда не публикуются автоматически. Система позволяет пропустить мастер; при пропуске используется безопасная дефолтная тема, а возможность завершить настройку сохраняется.
## 2. Путь пользователя
| Шаг | Доступные действия | Пример | Правила |
|---|---|---|---|
| 1. Пресет | `Minimal`, `Dark Tech`, `Editorial`, `Bold`, `Natural`, `Custom` | выбрано `Dark Tech` | выбор нового пресета показывает предупреждение при несохранённых изменениях; любые значения можно изменить позднее |
| 2. Цвета | `background`, `surface`, `text`, `muted`, `primary`, `secondary`, `accent`, `border` | `#1D2430` | HEX; желательно W3C contrast check: WCAG AA 4.5:1 для обычного текста; предупреждения в draft, строгие release checks по договорённости |
| 3. Типографика | четыре готовые пары шрифтов или ручной выбор heading/body из разрешённых семейств; `font.scale`, `line_height` | System UI / Georgia / Arial | браузерный прототип не скачивает шрифты; возможность upload `.woff2` и лицензирование — отдельная задача |
| 4. Дизайн-токены | скругления, ширина контейнера, коэффициент отступов, тени, стиль кнопок | `radius: 8`, `container: 1180` | ограничения фиксированы схемой; не принимаем arbitrary CSS/Jinja/JS от editor |
**Дополнительно:** Desktop/Mobile-preview, подсветка выбранного пресета, Draft/Live статусы, просмотр и экспорт YAML (в дизайне), сохранение, возврат к пресету, повтор onboarding. Любой шаг можно открывать повторно, не теряя текущую валидную форму.
### Состояния
- `new`: тема не настраивалась; у нового сайта работает базовый предустановленный пресет.
- `in_progress`: пользователь меняет токены; значения не обязаны быть публикационно валидными.
- `saved_draft`: синтаксически корректная тема сохранена в workspace. Live по-прежнему прежний.
- `skipped`: мастер закрыт по явному решению owner; тема по умолчанию остаётся активной, мастер доступен из настроек.
- `completed`: первоначальная настройка завершена как workflow, но факт завершения **не означает** live-публикацию.
В реальной CMS статус мастера должен храниться на сервере, а не в `localStorage`. Рекомендуется отделить факт `completed/skipped` от `published_theme_version`; не запускать onboarding для каждого нового редактора на существующем сайте. Управление темой — отдельный permission, по умолчанию owner/developer, editor — только по grant.
## 3. Каноническая модель: предложенный вариант
В исходном `TZ-site-engine.md` раздел 4.2 содержит inline `site.yaml.theme.tokens`. Ранее в обсуждении согласовано направление **`theme.yaml` + ссылка из `site.yaml`**, поэтому необходимо ADR-007 о переносе/миграции. До утверждения ADR источником истины остаётся первичное ТЗ; **не хранить параллельно два разных канонических набора токенов**.
**Предложение для одного сайта на инстанс:**
```yaml
# site.yaml · ссылается на публичную тему, не дублирует токены
schema: 1
name: Studio
base_url: https://studio.example
theme:
file: theme.yaml
```
```yaml
# theme.yaml · file-first, переносимый вместе с сайтом
schema: 1
preset: "dark"
preset_version: 1
overrides:
colors:
primary: "#a48bfa"
accent: "#e6aa81"
type:
heading: "Georgia, \"Times New Roman\", serif"
ui:
radius: 6
```
Пресеты — версионированные **immutable definitions** в библиотеке приложения (например `site_engine/themes/presets/dark.v1.yaml`). При вычислении: `effective_tokens = validated_deep_merge(preset@preset_version, overrides)`. Пресет в шаблоне — только baseline, пользовательские изменения — diff-overrides. Для `Custom` хранить полный набор токенов в overrides либо специальный `custom` base с version 1. Старые релизы фиксируют точные разрешённые токены + соответствующую версию пресета или embed resolved CSS, чтобы переиздание пресета не меняло исторический релиз.
**Namespace токенов:** базовые `colors.background/surface/text/muted/primary/secondary/accent/border`, `type.heading/body/scale/line/headingWeight`, `ui.radius/container/spacing/shadow/button`. При build отображаются в типизированные CSS custom properties (`--color-primary`, `--font-body`, `--space-section` и т. п.), которые использует Layout/Fragment. CSS-фрагменты и Jinja-код не изменяются от смены темы.
### Ограничения и безопасность
- Проверять имена и типы токенов строгой Pydantic-схемой; запрещать неизвестные/произвольные CSS expressions, URL, `@import`, inline JS, неразрешённые шрифты; escape HTML/CSS.
- Палитра: HEX `#RRGGBB`; контраст `text` на `background` и `surface`; проверка фокуса и ссылок; ошибка схемы блокирует создание кандидата.
- Типографика: сперва перечень локальных/system fallback font stacks, пользовательские `woff2` — отдельная проверенная медиатека (MIME, CSP, размер, права, лицензия).
- `theme.yaml` входит в workspace snapshot. Тема может менять сотни страниц → **полная** сборка MVP (кеш и incremental только по benchmark).
- Редактор может сохранять допустимый draft с warning по контрасту; политикой publish определяется, что блокирует релиз. Независимый `ThemeService` не должен обходить ReleaseService.
- Theme Manager не меняет **тему админки**: Antirion Rework и Rose Graphite — отдельные UI themes.
## 4. Сервисы, роли, API и интеграция htmx (предложения)
| Use case | Service | Admin route / partial | Гарантии |
|---|---|---|---|
| Список пресетов | `ThemeService.list_presets()` | `GET /admin/theme/presets` → `_preset_grid.html` | versioned, approved catalog |
| Текущий draft | `ThemeService.get_workspace()` | `GET /admin/theme` → `theme/index.html` | effective tokens + ETag + warnings |
| Смена основы | `ThemeService.resolve(preset_id, overrides)` | `POST /admin/theme/preview` → `_site_preview.html` | preview draft without save, cached safe resolution |
| Сохранить | `ThemeService.patch_theme(if_match, changes)` | `PATCH /api/v1/theme` / `hx-post /admin/theme/save` | RBAC, CSRF, `if_match`, atomic file write, audit, `409` |
| Проверить | `ThemeService.validate(strict)` | `POST /admin/theme/validate` | field-path diagnostics, release checks |
| Стартовый мастер | `OnboardingService.get/complete/skip` | `GET /admin/setup/theme`, `POST /admin/setup/theme/complete` | только новый сайт + owner; skipped ≠ published |
| Публикация | существующий `ReleaseService` | `/admin/publication/*` | candidate incorporates theme hash and resolved assets |
**Граница доверия:** preview — отдельный изолированный origin/path с CSP и noindex, не iframe с произвольным контентом администратора. Сохранение конфигурации ограничено editor roles, а изменение исполняемого CSS/Jinja остаётся developer-only с review.
**DTO:** `ThemeSnapshot {preset_id, preset_version, overrides, effective_tokens, etag, diagnostics, workspace_revision, live_build_id}`. Для `409` возвращать `current_snapshot`, `expected_etag`, `changed_paths`, без тихого перетирания чужого изменения.
## 5. Реализация по вертикальным срезам
- **V0:** ADR-007 и schema `ThemeDocument`, `PresetCatalog`, token resolution, CSS output, migration/compatibility с inline `site.yaml.theme.tokens`.
- **V1:** прочитать текущую тему из файла, показать в Jinja, save draft с ETag/CSRF/RBAC; preview без потери состояния.
- **V3:** включить `theme.yaml` в candidate snapshot и live; rollback точно возвращает тему соответствующего релиза.
- **V4:** полный UI Theme Manager и first-run Wizard, системные шрифты, typed color/font/spacing tokens, серверные настройки; portal с редактором и валидатором.
- **V7:** end-to-end и accessibility: mobile/desktop, контраст, шрифтовые fallback, безопасность загрузки шрифтов (если добавлены), изменение темы без изменения админки.
## 6. Критерии приёмки
1. Первый owner login на новом сайте → мастер, на существующем сайте → обычная админка.
2. Выбор любого пресета сразу влияет на preview; изменение цвета/шрифта на шаге 2/3 не сбрасывает базовый пресет.
3. Выбор нового пресета при несохранённом предупреждает; после возврата к мастеру draft сохраняется.
4. `Save draft` не меняет public live. Сборка candidate использует только зафиксированный snapshot и строгие проверки.
5. Одновременное редактирование темы из двух сессий → один `409`, правки не теряются.
6. `theme.yaml` + `site.yaml` переносятся и воспроизводят preview после чистой установки и reindex, без SQLite-копии палитры.
7. Rollback восстанавливает именно опубликованную тему старого build, не затирает новую черновую палитру.
8. Renderer, preview и опубликованный сайт используют согласованную типизацию токенов. Админка не наследует пользовательскую палитру.
9. В UI доступна страница пресетов/Custom с Desktop/Mobile preview, переходом из `Настройки → Тема` и разрешённым пропуском onboarding.
## 7. Статус прототипа
Файлы `theme-studio-antirion.html`, `theme-studio-rose-graphite.html` + `assets/theme-studio.css/.js` — **design prototype**. Примеры демо, браузерный `localStorage`, экспорт YAML для ознакомления. **Не** настоящий запуск onboarding, не `ThemeService`, не storage сайта и не полноценное превью всех Layout/Fragment. Никакая кнопка не изменяет публичный сайт или текущий live release.
Ссылки на документацию: `03_DOCUMENTS_AND_SERVICES.md`, `05_IMPLEMENTATION_PLAN.md`, `adr/ADR-007.md`.
## 8. Дополнение: дополнительные цвета, именованные градиенты и диалоги UI
**Согласовано в UX:** браузерные `alert()`, `confirm()`, `prompt()` не используются. Уведомления отображаются как toast/inline messages, опасные действия требуют доступного собственного модального диалога с явным подтверждением и отменой. Это правило распространяется на всю админку, не только Theme Manager.
В палитре есть обязательные восемь семантических цветов `colors.*`; можно добавлять до 24 **именованных `custom_colors`** для нестандартных секций и фрагментов. Имена: `[a-z][a-z0-9_]{1,31}`; запрет пересечения с зарезервированными token names, цвета HEX `#RRGGBB`. Вывод — типизированные CSS переменные `--color-promo-highlight` и т.п. Не разрешать произвольные CSS-выражения, URLs и JS.
Градиенты **необязательны**: `gradients.enabled` по умолчанию `false`, что означает использование однотонных базовых цветов. При включении используются **именованные** `gradients.definitions`: `hero`, `button`, `cta` и дополнительные имена пользователя; до 12 градиентов на сайт, для каждого 2–5 stop с позициями 0–100, угол 0–360, тип `linear` в MVP. Применение должно быть адресным, а не массовым. Проверять контраст текста поверх gradient и fallback при отключении. Градиенты не должны автоматически перекрашивать админку.
```yaml
schema: 1
preset: minimal
preset_version: 1
overrides:
custom_colors:
promo_highlight: '#e978a5'
section_dark: '#17202d'
gradients:
enabled: true
definitions:
hero:
type: linear
angle: 145
stops:
- {at: 0, color: '#1e2735'}
- {at: 100, color: '#31344a'}
button:
type: linear
angle: 105
stops:
- {at: 0, color: '#d4beff'}
- {at: 100, color: '#b5abf9'}
```
**Пример содержимого:** [`examples/site-studio`](../../examples/site-studio/README.md) включает `site.yaml`, `theme.yaml`, Pages, Entries, Layouts, Fragments, Display templates, assets и offline-preview. Это данные для переноса на сервисы, не окончательный контракт `ADR-007`. Важно: независимые browser-localStorage редакторов на данном этапе не читают этот filesystem seed.
## Обновление — режимы ширины контейнера (2026-11-13)
Тема публичного сайта хранит `overrides.ui.container` как объект:
```yaml
ui:
container:
mode: boxed # boxed | fluid | full
max_width: 1080 # px, диапазон 720–1920
gutter:
desktop: 36 # px (>=1024)
tablet: 24 # px (700–1023)
mobile: 16 # px (<700)
```
- **Boxed** — ограничение `max_width` и боковые отступы.
- **Fluid** — вся доступная ширина, но с боковыми отступами.
- **Full Width** — без внешних отступов.
- Глобальный режим — значение по умолчанию; `regions.*[].layout.section_width` и `content_width` могут переопределять его (`inherit | boxed | fluid | full`).
- Внешняя ширина определяет размер фона секции; внутренняя — ограничение вложенного `.container`.
- `Hero`: `section_width: full`, `content_width: boxed` — типовой пример.
- При смене режима не изменяются CSS/дизайн самой админки. Изменения оформляются как draft и публикуются вместе с релизом.
- Числовое старое `ui.container: 1080` читается в демо как `boxed / 1080`, но экспорт всегда использует новый объект.
### Архитектурная граница
Для реального сервера реализовать строгую проверку режимов и чисел, CSS escaping и тесты адаптивности. `ThemeService`, `PageService` и `BuildService` должны использовать один контракт, а не различные JS/Python-алгоритмы.
+66
View File
@@ -0,0 +1,66 @@
# Width modes — layout and containers (design prototype)
This is an agreed **public-site** feature; admin UI widths remain unchanged. The implementation is a browser-only design prototype and standalone sample renderer, not an integrated server API.
## Contract
`theme.yaml` → `overrides.ui.container`:
```yaml
mode: boxed # boxed | fluid | full
max_width: 1080 # px, 720..1920
# distance from viewport left/right (not a maximum width)
gutter:
desktop: 36 # >= 1024px
tablet: 24 # 700..1023px
mobile: 16 # <700px
```
The values apply **globally by default**. In Page or Display template YAML, each Block may override them:
```yaml
regions:
main:
- id: hero_home
fragment: hero
layout:
section_width: full # width of colored background / outer section
content_width: boxed # inner content container
props:
title: Example
```
Allowed per-field values: `inherit`, `boxed`, `fluid`, `full`. `inherit` resolves to global `ui.container.mode`. If the outer section is narrower than the inner content's selected width, content is constrained by that outer section; it does not overflow. Header/footer are fixed blocks with full-width backgrounds and inherited content mode by default.
## Rendering semantics
- `boxed`: `width: min(100% - 2 * gutter, max_width)` for outer sections, and `max-width` + gutter padding for inner `.container`.
- `fluid`: all available width minus outer gutter for sections, or unbounded inner `.container` with gutter padding.
- `full`: entire available width without horizontal gutter.
- `section_width` controls the **region of the background**. `content_width` controls the **content inside**. Hero full + boxed is the canonical combination.
- Responsive gutters use CSS media queries. No arbitrary CSS or user-supplied CSS expression is accepted in the selectors.
## Backwards compatibility
The Theme Manager reads old numeric `ui.container: 1080` from browser storage as `boxed/max_width=1080`; exports always write a structured value. The standalone Python preview renderer accepts numeric form as migration input. Production backend must implement equivalent migration, Pydantic validation, and versioning.
## Relevant files
- `assets/theme-studio.js`, `assets/theme-studio.css` — initial wizard, token editing, YAML export.
- `assets/builder.js` — block inspector, iframe preview, shared Constructor/Expert model.
- `examples/site-studio/theme.yaml`, `pages/index.md` — canonical example values.
- `examples/site-studio/assets/site.css` — style implementation.
- `examples/site-studio/tools/render_preview.py` — offline example renderer.
## Future backend API / schema
Define a typed `ContainerSettings` and `BlockLayout` validator shared by ThemeService, PageService, BuildService, CLI and MCP. Resolve inheritance once on the server for rendering and dependency detection. `PATCH /pages/{id}` must validate both modes, enforce `if_match`, and record changes in Workspace, not Live. Invalid/unrecognized modes are errors, not silent fallbacks.
## QA checklist
- Global Boxed / Fluid / Full Width and all three gutters; mobile viewport 360 px.
- Hero full background with boxed text, fluid services listing, full CTA with boxed text.
- Constructor ↔ Expert round-trip without losing `layout` fields, validation and diff.
- Preview retains scroll position when changing width settings.
- Old numeric theme setting migration works; CSS is bounded by typed values.
- No browser `alert()`, `confirm()` or `prompt()` for feedback.
@@ -11,6 +11,8 @@
- `docs/stage7/04_SECURITY_RELEASES.md`
- `docs/stage7/05_IMPLEMENTATION_PLAN.md`
- `docs/stage7/06_PROTO_AUDIT_AND_GAPS.md`
- `docs/stage7/07_THEME_MANAGER.md`
- `docs/stage7/adr/ADR-007.md`
- `docs/stage7/adr/ADR_REGISTER.md`
- `docs/stage7/reference_TZ-site-engine.md`
- `docs/stage7/reference_TZ-site-engine-architecture-review.md`
@@ -35,3 +37,9 @@
## Следующий срез (V1), после утверждения V0
FastAPI app, безопасная сессия, PageService с `if_match`, Jinja shell + htmx list/editor/inspector, один рабочий шаблон и preview. Критерий: изменить title Hero → save → reload → увидеть изменение из canonical YAML; одновременно открытые сессии обнаруживают 409.
---
## Новое функциональное дополнение: Theme Manager (13.11.2026)
При реализации учти `07_THEME_MANAGER.md`: отдельная тема публичного сайта (не админки), первый вход владельца нового сайта → optional Wizard, пять preset + Custom, изменение любого preset через overrides, настройка палитры, шрифтов и дизайн-токенов, live preview. Сохранённый `theme.yaml` — workspace draft, publish/rollback только через ReleaseService. Исходное ТЗ использует inline `site.yaml.theme.tokens`; перенос в `theme.yaml` со ссылкой **предлагается, но требуется ADR-007**. Не создавай оба канонических формата без решения о миграции.
+12 -2
View File
@@ -1,7 +1,5 @@
# 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 не обязательны.
@@ -12,10 +10,16 @@
**Зафиксированные дизайны:** 03 Antirion, 04 Antirion Rework, 05 Ember Graphite, 06 Rose Graphite (ранее YuE Studio). Функционально развиваем **04 и 06**; 03 и 05 остаются неизменёнными концепциями. У Rose Graphite без скруглений только выбор коллекции в разделе «Контент» — не все таблицы.
## Дополнение: Theme Manager / Onboarding
**Новая согласованная продуктовая функция**: первичная настройка темы публичного сайта через Wizard, готовые пресеты (`Minimal`, `Dark Tech`, `Editorial`, `Bold`, `Natural`) и `Custom`, возможность изменить любой пресет, палитра/шрифты/дизайн-токены и preview. Детали: **`07_THEME_MANAGER.md`**, открытый ADR-007 — **`adr/ADR-007.md`**. Это не дизайн-система админки и не новый backend.
## Навигация по документам
| Файл | Для чего нужен |
|---|---|
| `07_THEME_MANAGER.md` | Тема публичного сайта, Wizard первого входа, presets/Custom, модель `theme.yaml`, API, acceptance tests (схема предложена до ADR-007) |
| `adr/ADR-007.md` | Предлагаемый формат хранения темы и миграция от inline `site.yaml.theme.tokens` |
| `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 |
@@ -52,3 +56,9 @@
### Примечание об объёме
Пакет содержит весь исходный интерактивный проект Этапа 6 без изменения его поведения. Этап 7 добавляет документы и схемы взаимодействия. **Исходный HTML-проект не требует установки и по-прежнему открывается из `index.html`.** Для общего localStorage в нескольких вкладках рекомендован локальный HTTP-сервер.
## Файловый пример полного сайта
[`examples/site-studio/`](../../examples/site-studio/README.md) — отдельный исполнимый offline sample: Page + Entry + Collection + Layout + Fragment + Display + Media + Theme + Forms + Menus. Статический `preview-dist/` собирается скриптом из YAML/Markdown/Jinja; это **не** готовый Site Engine backend или production BuildService. Названия и связи нормализованы относительно разных demo-localStorage источников. Система темы в примере остаётся предложением к ADR-007.
- [08_CONTAINER_LAYOUT.md](08_CONTAINER_LAYOUT.md) — Boxed / Fluid / Full Width and per-block section/content overrides.
+30
View File
@@ -0,0 +1,30 @@
# QA — Theme Manager (13.11.2026)
## Автоматизированная проверка интерактивного прототипа
Chromium через Playwright, две темы админки `antirion`/`rose`, разрешения:
- 1440×900
- 1280×800
- 1024×768
- 768×1024
- 390×844
- 360×740
**Результат:** на всех двенадцати проверенных сочетаниях `document.scrollWidth <= window.innerWidth`; ошибок JavaScript не обнаружено.
Проверены: 6 preset cards, переход к шагам, изменение основного цвета и CSS-переменной превью, выбор сочетания шрифтов, изменение radius, сохранение в локальном workspace, Mobile-preview, экспорт `theme.yaml` и сохранение структуры draft в localStorage-совместимое состояние.
Проверен переход из старой вкладки Stage 6 `Настройки → Тема` в соответствующий HTML Theme Manager для обеих тем.
**Ограничение среды теста:** загрузка Chromium непосредственно по `file://`/URL запрещена административной политикой окружения. Для проверки интерактивного DOM HTML/CSS/JS были встроены в тестовую вкладку; API localStorage эмулировался минимальным синхронным хранилищем. Это проверяет UI-логику, но не является полноценным end-to-end тестом реального персистентного сервера. В архиве сохранены оригинальные локальные файлы, которые можно открыть браузером или через `python -m http.server`.
## Не реализовано (осознанно)
- Реальный login/проверка owner/new-site, вместо этого доступен демо-сценарий первого входа `?setup=1`.
- ThemeService, аутентификация, RBAC, CSRF, серверный `if_match` и обработка `409`.
- Каноническое файловое сохранение `theme.yaml`/`site.yaml` и импорт произвольного YAML.
- Реальная публикация и rollback темы, сравнение с серверным live и полноценный site-render preview.
- Загрузка шрифтов, лицензии, автоматические webfont subset/оптимизация.
До production реализации необходим ADR-007 по формату хранения темы, согласование статусов onboarding, схемы токенов и release-level проверок доступности.
+28
View File
@@ -0,0 +1,28 @@
# ADR-007 — Каноническое хранение тем и Preset/Custom
**Статус: PROPOSED / ожидает архитектурного утверждения.** Функциональный запрос владельца Site Engine — **подтверждён**: мастер первичной настройки, готовые пресеты, Custom и изменение готовой основы, палитра, шрифты, дизайн-токены. Но окончательное хранение и миграция ещё не утверждены отдельным ADR.
## Проблема
Первичное ТЗ §4.2 показывает `site.yaml.theme.tokens` как inline-набор. В обсуждении новой функции предложен внешний `theme.yaml` со ссылкой в `site.yaml`. Нельзя одновременно поддерживать два независимых источника истины без правил приоритета.
## Рассматриваемые варианты
- **A (рекомендуется):** `site.yaml.theme.file: theme.yaml`, переносимый canonical `theme.yaml` с `preset`, `preset_version`, `overrides`. Версионированный catalog preset в коде, детерминированное разрешение и заморозка resolved tokens в snapshot релиза. Мигрировать существующий inline `site.yaml.theme.tokens` в `theme.yaml` через проверенный changeset, оставив readable backup.
- **B:** оставить только inline `site.yaml.theme.tokens` (не требует миграции, но большой набор токенов перегружает общий конфиг и усложняет версионирование пресетов).
- **C:** хранить темы в SQLite (отвергается: противоречит file-first, усложняет переносимость).
## Рекомендация
A, для одного сайта на инстанс. Один вход сервиса для UI/CLI/MCP. По `if_match` защищать `theme.yaml`, изменения файла вести по атомарному changeset при одновременном изменении `site.yaml`. Preset definitions immutable; новые версии получают новые IDs. Custom — через полный список валидируемых overrides. Сохранение = workspace; публикация через существующий ReleaseService.
## Необходимо утвердить
1. Выделение `theme.yaml` из текущего inline `theme.tokens` и миграция.
2. Версионирование preset catalog и старых release snapshots.
3. Минимальный реальный набор theme tokens, лицензии на загружаемые шрифты и пороги проверки контраста в release.
4. Нужен ли `Theme Manager` Editor по отдельному grant или только Owner/Developer.
До решения ADR-007 **не реализовывать физическую миграцию** и не объявлять предложенный YAML окончательным production-контрактом.
**Дополнение (не утверждено отдельно):** в `theme.yaml` предлагается объект `ui.container` с `mode`, `max_width`, `gutter`; индивидуальные блоки могут задавать `layout.section_width` и `layout.content_width`. См. `07_THEME_MANAGER.md`.
+4
View File
@@ -56,6 +56,10 @@
**Решение требуется:** точный MVP fragment list, поддерживаемые формы/уведомления, приоритеты UI modules.
## ADR-007 — Тема публичного сайта и Presets/Custom
**Функция UX подтверждена**, но формат хранения ещё **PROPOSED**. Предложение: `site.yaml.theme.file: theme.yaml`, `theme.yaml {preset,preset_version,overrides}`, immutable preset catalog и разрешённые токены, миграция из текущего inline `site.yaml.theme.tokens` через changeset. Сравнить с сохранением inline-варианта и запретить два конкурирующих канонических источника. Подробно — [`ADR-007.md`](ADR-007.md) и [`../07_THEME_MANAGER.md`](../07_THEME_MANAGER.md).
## Process
1. Архитектор фиксирует альтернативы и аргументы; reviewer оценивает безопасность/сложность.
+2 -2
View File
@@ -3,8 +3,8 @@ title: Telegram-боты
slug: bots
status: published
summary: Автоматизируем диалоги и обращения
tagline: Диалоги и автоматизация
order: 10
services: []
cover: assets/bots.webp
---
Создаём Telegram-ботов под процессы команды.
+6 -7
View File
@@ -1,7 +1,7 @@
---
schema: 1
title: Главная
layout: default
layout: landing
status: published
seo:
title: Разработка Telegram-ботов и AI-систем
@@ -18,16 +18,15 @@ regions:
fragment: collection_list
props:
source:
query:
collection: services
sort: order
limit: 6
collection: services
sort: order
limit: 6
- id: body_home
fragment: richtext
props:
content:
source:
bind: page.body
---
Наша студия разрабатывает Telegram-ботов, AI-системы и автоматизацию.
Пример действующей сериализации Page, проверяемый относительно examples/studio-site.
Это пример **предлагаемой** сериализации Page, а не окончательно утверждённый контракт (ADR-002).
@@ -0,0 +1,6 @@
# PROPOSED site.yaml fragment, subject to ADR-007
schema: 1
name: Studio
base_url: https://studio.example
theme:
file: theme.yaml
+12
View File
@@ -0,0 +1,12 @@
# PROPOSED Theme Manager format, subject to ADR-007
schema: 1
preset: "dark"
preset_version: 1
overrides:
colors:
primary: "#a48bfa"
accent: "#e6aa81"
type:
heading: "Georgia, \"Times New Roman\", serif"
ui:
radius: 6