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:
@@ -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 после измерений на целевом железе.
|
||||
|
||||
@@ -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-алгоритмы.
|
||||
@@ -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**. Не создавай оба канонических формата без решения о миграции.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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 проверок доступности.
|
||||
@@ -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`.
|
||||
@@ -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 оценивает безопасность/сложность.
|
||||
|
||||
@@ -3,8 +3,8 @@ title: Telegram-боты
|
||||
slug: bots
|
||||
status: published
|
||||
summary: Автоматизируем диалоги и обращения
|
||||
tagline: Диалоги и автоматизация
|
||||
order: 10
|
||||
services: []
|
||||
cover: assets/bots.webp
|
||||
---
|
||||
Создаём Telegram-ботов под процессы команды.
|
||||
|
||||
|
||||
@@ -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
|
||||
@@ -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
|
||||
Reference in New Issue
Block a user