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:
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,82 @@
|
||||
# План 002 — Site Studio и Theme Manager
|
||||
|
||||
Дата: 2026-11-13. Основание — [спецификация](spec.md), выполнение — [задачи](tasks.md), проверка текущего этапа — [verification.md](verification.md).
|
||||
|
||||
Этапы 4 и 5 выполнены последовательно по отдельным поручениям пользователя. Этап 4 принят; приёмка Theme Manager — отдельный шаг.
|
||||
|
||||
Этапы 2 и 3 взяты и выполнены вместе по прямому поручению пользователя. Их совместная приёмка — [verification-stages-2-3.md](verification-stages-2-3.md); переход к этапу 4 остаётся отдельным решением.
|
||||
|
||||
## Архитектурные решения
|
||||
|
||||
- Каталог обнаруживает манифесты рекурсивно; идентичность фрагмента и категория — разные свойства. Сохранены глобальные ID и запрет затенения builtin.
|
||||
- Категория пути вычисляется в registry. API остаётся проекцией ядра; русские подписи и объединение прежних категорий относятся только к HTML-представлению.
|
||||
- Файловый theme.yaml — единственный реализованный формат темы с этапа 2. Это выбранное пользователем решение, без инфраструктуры миграции; прежний inline runtime отклоняется диагностикой.
|
||||
- Валидация/разрешение темы и ширины живут в ядре с dataclass. API использует Pydantic DTO, вызывает сервисы вне event loop и сохраняет существующие обработчики ошибок. Предпросмотр, CLI и build используют один resolver.
|
||||
- Theme Manager переносится из исходников Antirion. Моки и localStorage заменяются API; новый интерфейс и независимые frontend-алгоритмы темы не создаются.
|
||||
- Каждая стадия готовится отдельно для пользовательской приёмки. Запуск проекта с новым SITE_ROOT и коммиты examples в этот план не входят.
|
||||
|
||||
## Этап 1 — Категории и каталог (реализован, ожидает приёмки)
|
||||
|
||||
1. В загрузчике вычислить категорию из первого каталога для вложенного размещения, сохранив плоскую структуру и рекурсивный поиск.
|
||||
2. Загрузить optional preview.yaml, проверить envelope/props, объединить поверх inline preview по ключам, оставить плоскую форму API.
|
||||
3. Перенести 15 builtin по категориям, изменить только category в манифестах. Сверить ID и байты шаблонов/ресурсов.
|
||||
4. Показать категории в существующем каталоге, добавить поиск по коду и подписи, объединить legacy labels, сохранить описание/allow/ID. Синхронизировать фильтр после HTML swap.
|
||||
5. Проверить смешанный сайт и реальный путь login → HTML → внутренний API → transform/preview/save. Повреждённый preview должен быть виден в workspace/publish, отказ не меняет live.
|
||||
6. Проверить wheel вне checkout, браузер desktop/mobile и регрессии; обновить AGENTS/README и отчёт.
|
||||
|
||||
Выход: действующие сайты используют прежние ссылки на фрагменты; пользователь видит категории в добавлении блока. Ни тема, ни оформление публичных фрагментов на этой стадии не меняются.
|
||||
|
||||
## Этап 2 — Ядро файловой темы и публикация (реализован, ожидает приёмки)
|
||||
|
||||
1. Добавить dataclass-модель ThemeDocument/EffectiveTheme, валидатор и каталог immutable preset@version в runtime-пакете. Перенести значения и разрешённые шрифты из дизайн-JS, зафиксировать диапазоны из spec.
|
||||
2. Site читает theme.file; registry разрешает документ и добавляет диагностику в общий Report. Отсутствующая настройка использует minimal@1 в памяти; явная плохая ссылка и legacy tokens дают ошибку.
|
||||
3. Обновить конфигурации примеров/фикстур в исходниках под theme.yaml. Сохранять цвета существующих примеров через новые семантические/custom токены, не переписывая их страницы.
|
||||
4. Подключить effective tokens к bundle и preview через общий renderer. Токены применяются после defaults; CSS-потребители builtin используют согласованную таблицу переменных. Не менять палитру админки.
|
||||
5. Дополнить manifest релиза разрешённой темой и preset/version. Учитывать theme/preset/render resources при fingerprint; не перезаписывать исторический релиз другим результатом. Сохранять атомарный current и независимость rollback от workspace.
|
||||
6. Проверить воспроизводимость, все preset/Custom, контраст-warning, недопустимый ввод, сохранность старого live при ошибке и правильную тему после rollback. Набор пресетов и данные темы должны попадать в wheel.
|
||||
|
||||
Выход: CLI/build/preview читают один новый контракт и одинаково формируют оформление. API/UI управления темой добавляются на этапе 5.
|
||||
|
||||
## Этап 3 — Ширина сайта и блока (реализован, ожидает приёмки)
|
||||
|
||||
1. Добавить BlockLayout в модель, разрешённые ключи YAML, общий валидатор и resolver наследования. Явно проверить объекты и enum; числовой legacy container не включать.
|
||||
2. Передать layout через снимки, существующие операции блока, API DTO, формы и parse/serialize. Метаданные не должны теряться при редактировании props, добавлении, дублировании и переносе блока.
|
||||
3. Применять ширину к собственным корням и контейнерам фрагмента, исключая утечку правил в nested blocks. Сохранить sticky-header, anchors, slots и preview markers без нарушающих геометрию wrappers.
|
||||
4. Перенести контролы ширины инспектора из обновлённого дизайна и связать с transform. Обновление preview асинхронное; сохранить выделение/scroll и локальный выбор секции.
|
||||
5. Проверить global modes, пары внешней/внутренней ширины, responsive gutters и границы 699/700/1023/1024 px. Сверить Конструктор ↔ Эксперт, fixed/Display/slots и отсутствие overflow на 360 px.
|
||||
|
||||
Выход: штатный renderer и конструктор понимают layout из нового примера.
|
||||
|
||||
## Этап 4 — Общие компоненты и examples/site-studio
|
||||
|
||||
1. Сопоставить seed и текущие полноценные схемы по ST-01/02. Сохранить ID и проверенные названия/описания, перенести HTML/CSS компонентов из источника.
|
||||
2. Добавить builtin content/steps с title/items, исключив локальный дубликат ai-studio в том же обновлении исходников. Сохранить поддержку прежнего card_grid.variant: steps.
|
||||
3. Добавить data/entry_card и универсальный ref `to: '*'`, value collection/slug: парсинг, валидация, resolver, выбор в формах, проверки published target. Фиксированные ref/refs не изменяются.
|
||||
4. Дополнить entry_header и form необязательными полями из spec. Перенести общие стили, связывая литералы дизайна с effective tokens, сохраняя исходное оформление при значениях seed.
|
||||
5. Создать новый examples/site-studio: данные/ассеты из seed, адаптированные Page/Entry/Collection/Display/Menu/Form/Redirect, layouts с engine hooks. Не копировать повторные builtin manifests или mini-renderer.
|
||||
6. Описать запуск отдельно от рабочего сайта. Проверить 13 опубликованных страниц, отсутствие draft booking в live, ссылки/ассеты/редиректы, формы без ложного успеха, отключённые коллекции и совместимость прежних примеров.
|
||||
7. Проверить публичные страницы и общие компоненты относительно design preview на desktop/mobile. Документировать различия из-за данных и штатных SEO/assets hooks; не заменять визуальную проверку HTTP 200.
|
||||
|
||||
Выход: отдельный пример проходит стандартный validate/build, общие компоненты сохраняют функциональные возможности.
|
||||
|
||||
## Этап 5 — ThemeService, Theme Manager и onboarding
|
||||
|
||||
1. ThemeService предоставляет get/list_presets/resolve/validate/save; OnboardingService — status/skip/restart. Подключить JSON и HTML endpoints из API-01 без обходов внутреннего API.
|
||||
2. API DTO: ThemeSnapshot, ThemeUpdate, ThemePreviewRequest, ThemeDiagnostics, OnboardingState. Snapshot содержит document/etag/effective_tokens/diagnostics/workspace_revision/live_build_id; ErrorEnvelope допускает текущий снимок темы при 409. If-match для создания — ABSENT.
|
||||
3. Save проходит через ContentService с точным разрешённым путём, SiteLock, CAS, проверку, историю, atomic write и аудит. Изменения после Save не публикуются. Конфликт и 5xx сохраняют пользовательский ввод; неожиданные ошибки коррелируются через request_id.
|
||||
4. Расширить существующий PreviewStore overlay темы без сохранения файлов сайта, сохранив CSP/origin/nonce/immutable snapshots. Стенд из дизайн-макета и фактическая страница используют один token resolver; ответы связаны с revision.
|
||||
5. Перенести исходные HTML/CSS/JS Theme Manager в существующий Antirion shell. Подключить четыре шага, reset/skip/repeat, YAML/export, диагностику, desktop/mobile и ссылки настройки. Сохранять рабочее состояние вкладки до явного Save; не переносить auto-localStorage или beforeunload.
|
||||
6. Состояние мастера хранить атомарно в SITE_STATE_DIR/theme-onboarding.json под блокировкой сайта; в нём нет canonical palette. Инициализацию различать по наличию настроенной темы/релиза, текущему admin разрешить как владельцу. Save завершает workflow, skip/restart независимы от live.
|
||||
7. Выполнить серверные проверки ETag/CSRF/доступа, сбои диска/аудита/сети, два одновременных редактора, рестарт, существующий/новый сайт, skip/repeat, publish/rollback и отсутствие потери правок.
|
||||
|
||||
Выход: экран из дизайна управляет настоящим файлом и превью, существующая публикация остаётся отдельным действием.
|
||||
|
||||
## Общая проверка и передача этапов
|
||||
|
||||
После каждого функционального этапа: целевые unit/integration checks → штатные validate/build → реальный FastAPI и browser → installed wheel для новых ресурсов → отчёт с ограничениями → пользовательская приёмка.
|
||||
|
||||
Для нового Theme Manager обязательна сверка с оригиналом на 1440/1280/1024/768/390/360 px, клавиатура и фокус, отсутствие native dialogs, JS/CSP/HTTP-ошибок, горизонтального переполнения и изменения skin админки. Для общих компонентов повторить проверки старых примеров и функциональности больше трёх steps/items.
|
||||
|
||||
Пользовательские изменения examples/studio-site/pages/index.md не исправляются ради тестов. При необходимости базовая фикстура извлекается из HEAD во временный каталог; отчёт явно отличает такую регрессию от проверки текущего пользовательского сайта.
|
||||
|
||||
Изменения runtime требуют пересборки образа. Root examples не коммитятся, рабочий SITE_ROOT не переключается, live не публикуется автоматически. Завершение всей 002 отмечается только после выполнения и приёмки всех этапов.
|
||||
@@ -0,0 +1,143 @@
|
||||
# Runtime 002 — файловая тема и ширина блоков
|
||||
|
||||
Реализованы этапы 1–3. Версия схемы сайта, страниц и темы — 1. Интерфейс Theme Manager, его endpoints и новый `examples/site-studio` относятся к этапам 4–5 и пока отсутствуют.
|
||||
|
||||
## Загрузка и источник истины
|
||||
|
||||
`site.yaml` содержит `theme: {file: theme.yaml}`; путь относительный, внутри корня сайта. Файл темы обязателен при явной ссылке. Неверные YAML/тип/путь, symlink наружу и inline-настройки дают диагностику с путём; ошибка блокирует build/preview. Если настройка темы вообще отсутствует, используется minimal@1 в памяти, файл не создаётся.
|
||||
|
||||
```yaml
|
||||
schema: 1
|
||||
preset: minimal
|
||||
preset_version: 1
|
||||
overrides:
|
||||
colors:
|
||||
primary: '#4255b9'
|
||||
ui:
|
||||
container:
|
||||
mode: boxed
|
||||
max_width: 1080
|
||||
gutter: {desktop: 36, tablet: 24, mobile: 16}
|
||||
```
|
||||
|
||||
`core/theme.py` предоставляет dataclass `ThemeDocument`, `EffectiveTheme`, `ContainerSettings`, `Gutters`, функции `preset_catalog`, `font_catalog`, `resolve_theme`, `load_theme`, `theme_css`. Ядро не требует Pydantic. Registry содержит вычисленную `theme`; `Site` содержит только ссылку `theme_file`.
|
||||
|
||||
Пресеты minimal/dark/editorial/bold/natural/custom и каталог шрифтов скопированы из `design/assets/theme-studio.js` в `builtin/themes/v1/*.json`. Runtime не читает design и не хранит отдельную палитру в БД/JS. Каталог отдаёт независимые копии; определения опубликованной версии не изменяются. Будущие изменения пресета требуют отдельной версии и поддержки этой версии в resolver.
|
||||
|
||||
Переопределения объединяются глубоко, поэтому изменение mobile gutter сохраняет desktop/tablet. `custom_colors` и явно заданный `gradients.definitions` заменяют соответствующую карту целиком: удалённые определения не возвращаются из defaults. Custom требует полный набор colors/type/ui, включая вложенный container/gutter. Дополнительные цвета и градиенты необязательны.
|
||||
|
||||
## Валидация
|
||||
|
||||
| Поле | Контракт |
|
||||
|---|---|
|
||||
| colors | background/surface/text/muted/primary/secondary/accent/border, HEX #RRGGBB |
|
||||
| type | pair из каталога или custom, heading/body только разрешённые системные стеки |
|
||||
| type.scale / line | числа 0.85–1.3 / 1.3–1.9 |
|
||||
| type.headingWeight | целое 100–900 |
|
||||
| ui.radius / spacing | числа 0–24 px / 0.8–1.4 |
|
||||
| ui.shadow / button | none/soft/medium и solid/outline |
|
||||
| ui.container | объект mode/max_width/gutter; старое число отклоняется |
|
||||
| max_width / gutters | целое 720–1920 / целые 0–96 px |
|
||||
| custom_colors | до 24 HEX; имена `[a-z][a-z0-9_]{1,31}`, без конфликтов с зарезервированными токенами |
|
||||
| gradients | enabled: boolean, до 12 именованных linear definitions |
|
||||
| definition | angle 0–360, 2–5 stops `{at: 0..100, color: HEX}`, позиции строго возрастают |
|
||||
|
||||
Неизвестные ключи, null вместо объекта, boolean вместо числа, строки с CSS/URL/Jinja и нечисловые/бесконечные значения отклоняются. Ошибки используют коды `E_THEME_*`. Проверяются контрасты text/background, text/surface, muted/surface; `W_THEME_CONTRAST` не блокирует публикацию. Включённые градиенты добавляют предупреждение о проверке контраста по всей поверхности.
|
||||
|
||||
## CSS и релиз
|
||||
|
||||
Порядок общего бандла: base.css → стили использованных фрагментов → вычисленные переменные → containers.css. Встроенные компоненты используют семантические переменные; дополнительных CSS из пользовательских данных нет.
|
||||
|
||||
| Токены | CSS |
|
||||
|---|---|
|
||||
| colors.name | `--color-name`; background также `--color-bg` |
|
||||
| custom_colors.hero_ink | `--color-hero-ink`, адресное использование шаблоном |
|
||||
| type | `--font-heading`, `--font-body`, `--type-scale`, `--type-line`, `--heading-weight` |
|
||||
| ui | `--radius`, `--spacing`, `--shadow`, `--button-background`, `--button-text` |
|
||||
| container/gutter | `--container`, `--container-max`, `--gutter-desktop/tablet/mobile`, responsive `--active-gutter` |
|
||||
| gradients.definitions.name | `--gradient-name`; для hero/button/cta также `--hero-gradient`, `--button-gradient`, `--cta-gradient` |
|
||||
|
||||
Градиенты применяются адресно: тёмный Hero, основная solid-кнопка и CTA используют соответствующие роли. При отключении возвращаются однотонные значения, outline-кнопка остаётся прозрачной. Публичные CSS находятся в релизе/iframe, на skin админки не влияют.
|
||||
|
||||
Manifest содержит прежние source_hash/routes/fragments/page_sources и новые `render_hash`, `fingerprint`, `theme: {document, effective_tokens}`. ID строится из времени и общего fingerprint файлов сайта, кода ядра/сборки/парсинга, builtin-ресурсов, пресетов и загруженных фрагментов. При одинаковом ID существующий релиз переиспользуется только при побайтово одинаковом результате; несовпадение даёт `E_RELEASE_COLLISION` и сохраняет историю. Ошибка не переключает current. Rollback переключает готовый релиз и не меняет theme.yaml/контент workspace.
|
||||
|
||||
## Layout блока и конструктор
|
||||
|
||||
```yaml
|
||||
- id: hero_home
|
||||
fragment: hero
|
||||
layout:
|
||||
section_width: full
|
||||
content_width: boxed
|
||||
props:
|
||||
title: Пример
|
||||
```
|
||||
|
||||
Оба поля допускают inherit/boxed/fluid/full. Отсутствующий layout у hero/cta_banner/site_header/site_footer означает full/inherit; у остальных — inherit/inherit. Явный пустой объект или явно заданный inherit наследует глобальную ширину. Неизвестные ключи и режимы дают `E_BLOCK_LAYOUT`; молчаливого исправления нет.
|
||||
|
||||
Boxed ограничивает секцию до `min(available - 2*gutter, max_width)`, fluid убирает max_width, full занимает всю доступную ширину без gutter. Внутренний boxed-контейнер имеет max_width и padding, fluid — только padding, full — без ограничения и padding. Внешняя секция ограничивает внутреннюю. Gutters переключаются на 700 и 1024 px; для слишком узкого вложенного контейнера padding ограничен его доступной шириной.
|
||||
|
||||
Renderer ставит `data-engine-block`, `data-section-width`, `data-content-width` на существующие корни и `data-engine-container` на собственные `.f-container`/`.container`. Область вложенного блока исключается из обработки родителем. Для разделения фона и содержимого собственный шаблон должен иметь внешний корень и внутренний контейнер. Richtext/image/columns builtin получили собственные внутренние контейнеры; общий wrapper вокруг всех фрагментов не добавляется, sticky-header остаётся корнем. Preview markers добавляются отдельно; публикация их не содержит.
|
||||
|
||||
Один парсер применяется к Page, Display, Entry regions, fixed и slots. Снимки передают layout без потери данных. Transform меняет сырой YAML; props edit, duplicate, move, toggle, Save и reopen сохраняют layout. На API-границе `BlockLayoutDTO` объявляет enum в OpenAPI, `BlockValues` ограничивает поля, явный null для anchor/note сохраняет значение очистки. `schema.container` отдаёт глобальные настройки.
|
||||
|
||||
Контролы инспектора перенесены из `design/assets/builder.js:blockWidthControls`: те же названия, варианты, классы и пояснение. Обновление использует существующий HTML → внутренний JSON API → DocumentService; debounce и preview остаются асинхронными. Выбор секции локальный; изменение до Save не создаёт черновик на диске. Выделение и scroll preview сохраняются.
|
||||
|
||||
## Проверка и запуск
|
||||
|
||||
```bash
|
||||
PYTHONPATH=src python -m unittest discover -s tests -p 'test_theme.py' -v
|
||||
PYTHONPATH=src python -m unittest discover -s tests -p 'test_block_layout.py' -v
|
||||
PYTHONPATH=src python scripts/qa_theme_002.py
|
||||
PYTHONPATH=src python scripts/verify_package_001.py --site /path/to/isolated-site
|
||||
```
|
||||
|
||||
Нужна пересборка образа/установка нового пакета. Рабочий SITE_ROOT не переключается автоматически; примеры обновлены только в исходниках. Root examples не коммитятся. Проверки и артефакты — в [отчёте](verification-stages-2-3.md).
|
||||
|
||||
## Этап 4: публичный builtin и отдельный Site Studio
|
||||
|
||||
Источник разметки/CSS — design/examples/site-studio/fragments и assets/site.css. Общие примитивы перенесены в builtin/base.css, правила компонентов — в их style.css. Служебные f-классы сохранены для существующих локальных шаблонов. Штатный сборщик добавляет тему и containers.css после этих правил. Готовый пакет не читает design/.
|
||||
|
||||
Добавлены content/steps (прежний title/items из ai-studio, локальный дубликат удалён) и data/entry_card. `entry_header` дополнен summary/image/image_alt, `form` — title/description. Метки Hero, шапки, записи, заголовок richtext и описание collection_list задаются опциональными props; тексты нового примера не захардкожены в общие шаблоны. Списки произвольной длины, slots, columns/page_header и card_grid.variant:steps сохранены.
|
||||
|
||||
`ref` с `to: '*'` использует collection/slug. Парсер/валидатор проверяют форму; Resolver различает E_REF_FORMAT, E_REF_COLLECTION, E_REF_MISSING, E_REF_UNPUBLISHED. Опубликованная карточка с недоступной целью блокирует build; preview показывает диагностику. Универсальные ссылки в данных коллекций проверяются и без использования в display, включая вложенные group/list/refs. Обычные ref/refs сохраняют slug и прежнюю семантику. Document schema предоставляет дополнительный choices.published_entries; generic datalist включает только эти записи, fixed datalist использует прежний choices.entries. Save/ETag/буфер не изменены.
|
||||
|
||||
Collection теперь поддерживает необязательный `requires: [feature.<имя>]` (schema остаётся 1). Неизвестное требование — E_REQUIRES_UNKNOWN. При выключенной feature записи сохраняются в workspace, не публикуются, не попадают в query или generic choices и не требуют release-полноты. Маршрут такой записи недоступен для generic ref. Без requires поведение прежнее. В новом примере courses/posts связаны с features courses/blog.
|
||||
|
||||
`examples/site-studio/` содержит адаптированные данные/ассеты/пять layouts с seo/assets hooks; штатный build создаёт 13 страниц и два редиректа. Сохранены 8 записей, 4 из которых draft. Намеренно отсутствующая обложка booking диагностируется в preview, не мешает live. Форма выполняет настоящий POST и показывает HTTP 501 без очистки ввода или перехода на thank-you. Нового FormService/доставки нет.
|
||||
|
||||
Отдельный запуск — examples/site-studio/README.md; QA — scripts/qa_site_studio_002.py; результаты — [verification-stage-4.md](verification-stage-4.md). Рабочие SITE_ROOT/data не изменяются.
|
||||
|
||||
|
||||
## Этап 5: Theme Manager, API и мастер первого входа
|
||||
|
||||
Экран `/admin/theme` («Дизайн сайта») и `/admin/setup/theme` используют исходные HTML-композицию, CSS и контролы `design/theme-studio-antirion.html` / `design/assets/theme-studio.{css,js}`. Сохраняется принятый shell админки. Стили исходного экрана и его импортированные button/chip-примитивы ограничены `.theme-content`; публичные CSS остаются в iframe. Палитра темы сайта не меняет skin админки. Нативных browser dialogs и palette-localStorage нет.
|
||||
|
||||
JSON API (внутренние credentials, существующая request-scoped авторизация UI):
|
||||
|
||||
| Метод | `/admin/api/v1` | Результат |
|
||||
|---|---|---|
|
||||
| GET | `/theme` | ThemeSnapshot |
|
||||
| GET | `/theme/presets` | 6 preset definitions, их документы/effective tokens, font catalog |
|
||||
| PATCH | `/theme` | Save: `{document, if_match, revision}` → ThemeSnapshot |
|
||||
| POST | `/theme/validate` | `{document, revision}` → ThemeSnapshot или 422 с diagnostics в error.issues |
|
||||
| POST | `/theme/preview` | `{document, revision, target: sample\|page, page_id?, device: desktop\|phone, viewport_width?: 320..3840}` → immutable Preview |
|
||||
| GET | `/theme/onboarding` | `{status, needs_setup, can_manage}` |
|
||||
| POST | `/theme/onboarding/skip` | skipped |
|
||||
| POST | `/theme/onboarding/restart` | in_progress |
|
||||
|
||||
HTML-адаптер принимает обычные form POST с `csrf` и `payload` (JSON DTO): `/admin/theme/save|validate|preview`; workflow — `/admin/setup/theme/skip|restart`. Он возвращает JSON-проекцию результата внутреннего AdminApi, не обращаясь к сервису/файлам напрямую. Внешние credentials браузеру не выдаются. Вход в экран выполняется обычной навигацией; htmx-переход получает HX-Redirect для корректной загрузки исходных ресурсов.
|
||||
|
||||
ThemeSnapshot: document, etag, effective_tokens, diagnostics, workspace_revision, live_build_id, revision; также path, yaml, css и contrast для UI. workspace_revision — хеш конфигурации сайта и ETag темы; это версия темы в workspace, не счётчик правок всех страниц. `revision` относится к состоянию текущей вкладки. Контракт экспортирован в `specs/001-antirion-admin/openapi.json` штатной командой export-openapi.
|
||||
|
||||
Клиент получает пресеты/шрифты/effective tokens с backend. Он редактирует доступные поля, отправляет полный документ (полный overrides допустим и для обычных пресетов). Второго JS resolver/валидатора/CSS-генератора темы нет. После паузы ввода идут серверная проверка и preview; это не Save. Переключение шага сохраняет iframe и не записывает контент. Desktop/Mobile и выбор реальной страницы создают новый snapshot. Устаревшие ответы отбрасываются по sequence/revision/target/device; ошибочная revision ответа также отклоняется. Неверная тема оставляет последнее корректное превью с явным статусом. YAML/export формирует и проверяет сервер.
|
||||
|
||||
Сохранение ограничено точным `site.yaml.theme.file`; разрешён отдельный относительный YAML внутри root без symlink alias/escape, не site.yaml. Если тема не настроена, используется minimal в памяти, target — theme.yaml. GET/preview не создают тему. Save получает `if_match: absent` при создании. ContentService.update_files под SiteLock перечитывает/проверяет версии и путь, валидирует весь документ, сохраняет историю и атомарно пишет файл. При первом Save также сохраняется ссылка в site.yaml с проверкой его версии. Все версии/валидация проверяются до записи; обычный отказ второго файла восстанавливает первый. Несколько rename не являются общей crash-atomic транзакцией: аварийное завершение процесса между ними может оставить несвязанный theme.yaml, который не применяется до появления ссылки. Настроенная тема сохраняется одним файлом.
|
||||
|
||||
409 возвращает `error.current: ThemeSnapshot`. UI оставляет пользовательские значения и предлагает принять новую основу либо явно загрузить серверную тему. Принятие основы само не пишет файл; повторный Save снова проверяет ETag. 5xx/сеть/401/403 видимы с code/message/request_id. Сбой аудита или workflow после успешной записи возвращает 500 `theme_after_commit` с `error.committed`: UI учитывает новую версию и сообщает проблему. Неожиданные исключения логируются общей границей со стеком и request_id.
|
||||
|
||||
PreviewStore хранит immutable HTML и необходимые ассеты вне canonical workspace. Стенд Hero/Buttons/Cards/Typography перенесён из исходника; его CSS использует core.theme.theme_css через алиасы переменных. Фактическая страница рендерится штатным Renderer с reg.theme overlay. Для стенда ассеты сайта не копируются. viewport_width передаёт только ширину окна редактора для responsive-правил оригинального стенда; числовые границы проверяются API, это не токен темы. Пассивный iframe не разрешает scripts; при настроенных разных origin действуют прежние signature/TTL/auth_epoch, CSP, nonce bridge, immutable assets. Скрипты сайта не исполняются. Текст/контролы админки не получают CSS публичной темы.
|
||||
|
||||
OnboardingService атомарно хранит только `{schema: 1, status}` в SITE_STATE_DIR/theme-onboarding.json под SiteLock. Без state тема в конфигурации или live-релиз означают existing; без обоих — new и redirect с обзора на setup. Текущий single-admin имеет право управления. Skip → skipped, Repeat → in_progress и первый шаг, Save → completed. Skip/Repeat не меняют тему и live; workflow переживает рестарт. Сессия не создаёт персональный мастер для каждого редактора. Повтор доступен на экране дизайна из навигации настроек.
|
||||
|
||||
Визуальная и функциональная приёмка — `scripts/qa_theme_manager_002.py`; серверные отказы/ETag/workflow/release — `tests/test_theme_manager.py`; отчёт — [verification-stage-5.md](verification-stage-5.md). Рабочий SITE_ROOT и live не переключались.
|
||||
@@ -0,0 +1,109 @@
|
||||
# 002 — Site Studio: категории фрагментов, тема и Theme Manager
|
||||
|
||||
Дата: 2026-11-13. Статус: этапы 1–5 реализованы; пользователь принял этап 4 и разрешил этап 5. Theme Manager подготовлен к отдельной пользовательской приёмке; вся 002 ещё не закрыта. Связанные документы: [план](plan.md), [задачи](tasks.md), [проверка этапа 1](verification.md), [проверка этапов 2–3](verification-stages-2-3.md), [runtime](runtime.md), [проверка этапа 4](verification-stage-4.md), [проверка этапа 5](verification-stage-5.md).
|
||||
|
||||
## 1. Цель и источники
|
||||
|
||||
Перенести новый файловый пример `design/examples/site-studio/` на штатный движок, обновить общие фрагменты, добавить категории, файловую тему, ширину секций и полноценный Theme Manager. Сохранить схему версии **1** и существующую архитектуру: браузер/htmx → HTML UI → внутренний JSON FastAPI → сервисы → ядро/файлы.
|
||||
|
||||
Источники оформления и поведения:
|
||||
|
||||
- Theme Manager — `design/theme-studio-antirion.html`, `design/assets/theme-studio.css` и `theme-studio.js`.
|
||||
- Настройки ширины в конструкторе — обновлённый `design/assets/builder.js` и соответствующий Antirion-макет.
|
||||
- Публичный сайт — `design/examples/site-studio/`: шаблоны, стили, контент и подготовленные превью.
|
||||
- Контекст — `design/docs/stage7/07_THEME_MANAGER.md`, `08_CONTAINER_LAYOUT.md`, `THEME_MANAGER_QA.md` и ADR-007.
|
||||
|
||||
Разметка, CSS, композиция, контролы и сценарии Theme Manager переносятся из исходников. Замена mock-данных и хранилища на API не является поводом для самостоятельного редизайна. Браузерный прототип не заменяет сервисы, валидацию и публикацию.
|
||||
|
||||
## 2. Исходное состояние
|
||||
|
||||
Новый seed содержит 9 ручных страниц, 8 записей, 15 фрагментов, 5 layouts и 13 HTML-страниц автономного превью. Собственные проверки seed и контейнеров проходят. Штатные проверки workspace и release CMS до переноса обнаруживают суммарно 137 ошибок со встроенными фрагментами, включая 13 повторных ID; без builtin остаются 44 ошибки. Это исходная сверка, а не критерий совместимости после реализации.
|
||||
|
||||
Загрузчик уже рекурсивно ищет `fragment.yaml`, но категория бралась только из YAML. Отдельный `preview.yaml`, `Block.layout` и внешний `theme.yaml` прежде не использовались. Темы работали через `site.yaml.theme.tokens`. Changeset, публичный приём заявок и расширенный RBAC не являются готовыми сервисами.
|
||||
|
||||
## 3. Фрагменты и каталог
|
||||
|
||||
**FR-01.** Одновременно поддерживаются плоское `fragments/<folder>/fragment.yaml` и категоризированное `fragments/<category>/<folder>/fragment.yaml` размещение, в том числе смешанное в одном сайте. Поиск рекурсивный; каталог без манифеста не становится фрагментом. Повреждённый найденный манифест даёт диагностику.
|
||||
|
||||
**FR-02.** ID берётся из `fragment.yaml:id`, не из пути. Он глобально уникален, одинаково адресуется из Page, Display, Layout и slots. Категория не входит в ID. Дублирование builtin и локальных ID запрещено и возвращает `E_FRAGMENT_DUP`.
|
||||
|
||||
**FR-03.** Если путь каталога фрагмента относительно `fragments/` содержит не менее двух компонентов, категория — первый компонент. Иначе применяется YAML `category` или `misc`. Каталог имеет приоритет над YAML; дополнительная вложенность не меняет категорию. Это правило одинаково для builtin и компонентов сайта. Дополнительные категории допустимы.
|
||||
|
||||
**FR-04.** Встроенные фрагменты размещаются так:
|
||||
|
||||
| Категория | Фрагменты этапа 1 |
|
||||
|---|---|
|
||||
| content | card_grid, columns, disclaimer, faq, richtext, section |
|
||||
| data | collection_list, entry_header |
|
||||
| forms | form |
|
||||
| marketing | cta_banner, hero, page_header |
|
||||
| media | image |
|
||||
| system | site_header, site_footer |
|
||||
|
||||
На этапе 1 меняется размещение и категория; шаблоны и ресурсы сохраняются. На этапе публичных компонентов добавляются общие `steps` и `entry_card`; `columns` и `page_header` остаются.
|
||||
|
||||
**FR-05.** Соседний `preview.yaml` необязателен: `{name?: string, props: object}`. `props` переопределяют inline `fragment.yaml:preview` по верхним ключам; затем формы используют defaults полей. Значения `false`, `0` и явно заданные пустые значения не теряются. Имя preview не переименовывает фрагмент. API сохраняет плоский словарь `Fragment.preview`. Неверный YAML, форма envelope, неизвестные props и неверные типы дают диагностику с путём; ссылки в образце не разрешаются во время загрузки каталога.
|
||||
|
||||
**FR-06.** Каталог сохраняет название и описание под ним, добавляет видимую категорию, поиск по ID/названию/описанию/категории и фильтры. Стандартные подписи: Контент, Данные, Формы, Маркетинг, Медиа, Системные; `misc` — Прочее. Неизвестные категории показываются по имени. API отдаёт исходную вычисленную категорию; только UI объединяет прежние русские подписи с новыми группами. «Компоновка» относится к content, «Первый экран»/«Конверсия» — к marketing, «Каркас» — к system. Остальные прежние подписи сопоставляются одноимённым категориям.
|
||||
|
||||
**FR-07.** Ограничения allow региона/слота продолжают действовать независимо от фильтра. Фильтр и подсвеченная кнопка согласованы после обновления HTML. Добавление, выбор секции и preview не создают сохранённый черновик; запись страницы происходит только по Save. Формат новых ID остаётся `<fragment_id>_<5 случайных символов>`.
|
||||
|
||||
## 4. Принятое решение по теме
|
||||
|
||||
**TH-01.** Для реализации 002 выбран файловый вариант ADR-007: `site.yaml.theme.file: theme.yaml`, отдельный документ `{schema: 1, preset, preset_version, overrides}`. Это решение пользователя уточняет Proposed ADR в исходниках дизайна; сами исходники дизайна не переписываются. Переход сразу на новый контракт: механизм миграции и совместимость с inline `theme.tokens` не создаются. Старый формат получает явную диагностику. Конфигурации примеров и фикстур обновляются в исходниках вместе с реализацией.
|
||||
|
||||
**TH-02.** Отсутствие настройки темы у нового сайта означает безопасный preset minimal@1 без автоматической записи. Целевой файл по умолчанию — корневой `theme.yaml`; новые примеры задают ссылку явно. Явная ссылка на отсутствующий/некорректный файл диагностируется. Чтение и запись не выходят за root сайта.
|
||||
|
||||
**TH-03.** Preset definitions minimal, dark, editorial, bold, natural, custom версии 1 переносятся из дизайна в пакет приложения. Опубликованные определения неизменяемы. Сервер вычисляет effective tokens через валидируемое глубокое объединение preset и overrides. Custom сохраняет полный набор overrides. Клиент получает каталог с сервера, отдельной канонической копии пресетов в JS/SQLite нет.
|
||||
|
||||
**TH-04.** Типизированный контракт включает восемь `colors.*`, `type.pair/heading/body/scale/line/headingWeight`, `ui.radius/container/spacing/shadow/button`, `custom_colors` и `gradients`. Числовые ограничения и списки берутся из исходного дизайна: scale 0.85–1.3, line 1.3–1.9, radius 0–24 px, spacing 0.8–1.4; shadow none/soft/medium, button solid/outline. Heading weight — целое 100–900. Шрифты — системные стеки из разрешённого каталога дизайна; pair может быть custom при ручном выборе. Произвольные CSS, URL, Jinja и JS не принимаются.
|
||||
|
||||
**TH-05.** Семантические цвета — HEX #RRGGBB. Дополнительных именованных цветов не более 24; имя `[a-z][a-z0-9_]{1,31}`, без конфликтов зарезервированных токенов. Градиенты выключены по умолчанию, не более 12 linear definitions, угол 0–360, 2–5 stop с HEX и строго возрастающими позициями 0–100. Применение именованных цветов и градиентов адресное; отключение градиентов возвращает однотонные fallback.
|
||||
|
||||
**TH-06.** Неверный контракт блокирует сохранение/сборку. Недостаточный контраст — предупреждение в редакторе и публикации, а не блокировка релиза. Минимальные проверки: основной текст на background/surface и muted на surface; для градиентов диагностика не обещает полную проверку произвольного изображения или композиции.
|
||||
|
||||
**TH-07.** Общий resolver ядра используется CLI, сервисами, API, preview и build. Ядро остаётся без обязательного Pydantic; API DTO не дублируют алгоритм разрешения. CSS темы не перекрывается более поздними значениями по умолчанию. Админка не наследует публичные токены.
|
||||
|
||||
## 5. Ширина сайта и блоков
|
||||
|
||||
**WD-01.** `overrides.ui.container` — объект: `mode: boxed|fluid|full`, `max_width` — целое 720–1920 px, `gutter.desktop/tablet/mobile` — целые 0–96 px. Breakpoints: desktop ≥1024, tablet 700–1023, mobile <700. Старый числовой container не является поддерживаемым production-форматом.
|
||||
|
||||
**WD-02.** `Block.layout` содержит только `section_width` и `content_width`, значения `inherit|boxed|fluid|full`. Отсутствующий объект: hero, cta_banner, site_header, site_footer получают full/inherit; остальные — inherit/inherit. Явное inherit разрешается в глобальный mode. Ошибки не заменяются молча безопасными значениями.
|
||||
|
||||
**WD-03.** Внешняя ширина управляет фоном секции, внутренняя — её содержимым. Boxed ограничен max_width и gutter, fluid сохраняет gutter без max_width, full заполняет доступную ширину без gutter. Внешняя секция ограничивает внутреннее содержимое. Вложенные блоки, сетки и sticky-header не ломаются от служебных wrappers или CSS предков.
|
||||
|
||||
**WD-04.** Layout одинаково работает в Page, Display, fixed-блоках и вложенных slots. Инспектор использует контролы дизайна. Конструктор/Эксперт, изменение props, добавление, дублирование, сохранение и повторное открытие сохраняют layout. Не теряются выделение и scroll preview; выбор блока не требует сетевого запроса.
|
||||
|
||||
## 6. Общие фрагменты и Site Studio
|
||||
|
||||
**ST-01.** Оформление общего builtin переносится из seed с сохранением возможностей: типизированные actions/links/query, bindings, slots, неограниченные тремя элементами списки. Сопоставление: heading → title; card1…3/step1…3/FAQ → items; button/buttonUrl → actions; collection/sort/limit → source.query; Markdown body → `{bind: page.body}` / `{bind: entry.body}`. Нужные статические подписи из дизайна становятся данными, а не захардкоженными текстами всех сайтов.
|
||||
|
||||
**ST-02.** `entry_header` получает необязательные summary, image и image_alt, сохраняя title/meta. `form` получает необязательные title/description, сохраняя ссылку form. `steps` использует существующий контракт title/items из ai-studio. `entry_card` использует title и обязательный entry типа ref с `to: '*'`, значение `collection/slug`. Фиксированные ref/refs сохраняют прежний контракт slug + to; универсальный ref проверяет collection, slug и доступность публикации. Встроенный каталог форм редактора даёт соответствующий выбор записей.
|
||||
|
||||
**ST-03.** Рабочий результат размещается отдельно в `examples/site-studio/`. Данные и статусы из seed сохраняются, схемы адаптируются к CMS: полные fields/of/options/to, SEO bindings, ID страниц в меню, существующий формат redirects, поля формы с key. Выключенные courses/posts описываются согласованно с features/requires. Намеренно неполный draft booking не входит в релиз и не мешает публикации остальных материалов.
|
||||
|
||||
**ST-04.** Layout использует seo_head(), assets_head(), assets_body() и region(). Не создаётся второй renderer или новая template API из mini-renderer. Повторные определения builtin из seed не копируются. При добавлении общего steps локальный дубликат ai-studio заменяется использованием builtin в том же изменении исходников; его контент и ID блоков сохраняются.
|
||||
|
||||
**ST-05.** Формы переносятся как схема и оформление. Приём/хранение заявок, Telegram, outbox и новая модель ролей не входят в 002. Существующий HTTP 501 показывается честно, ложного успеха нет. Новый пример должен проходить штатные validate/build, воспроизводить 13 страниц seed и не выводить черновики в live.
|
||||
|
||||
## 7. Theme Manager, API и сохранение
|
||||
|
||||
**UI-01.** Переносится исходный Antirion Theme Manager: четыре шага, шесть карточек, палитра/дополнительные цвета/градиенты, типографика, токены и ширина, Desktop/Mobile, YAML/export, reset/skip/repeat, собственные dialogs и toast. Исходные HTML/CSS/JS остаются эталоном. Нативные alert/confirm/prompt/beforeunload из переносимого runtime исключены; frontend-сборка не добавляется.
|
||||
|
||||
**API-01.** JSON API под `/admin/api/v1`: GET `/theme`, GET `/theme/presets`, PATCH `/theme`, POST `/theme/preview`, POST `/theme/validate`, GET `/theme/onboarding`, POST `/theme/onboarding/skip`, POST `/theme/onboarding/restart`. HTML: GET `/admin/theme`, GET `/admin/setup/theme`, POST `/admin/theme/save|preview|validate`, POST `/admin/setup/theme/skip|restart`. HTML runtime использует серверный API-клиент; прямого обхода сервисов нет.
|
||||
|
||||
**API-02.** Snapshot темы содержит document, etag, effective_tokens, diagnostics, workspace_revision и live_build_id. PATCH передаёт полный document, if_match и revision; для отсутствующего файла используется существующий ABSENT. Preview передаёт документ и revision без записи; запоздалый ответ не заменяет новое состояние. Не добавляется скрытый auto-draft или canonical localStorage.
|
||||
|
||||
**API-03.** Save использует ThemeService и ContentService с ограничением на целевой файл: SiteLock → reread/CAS → полная проверка → история → atomic_write → аудит. Конфликт 409 возвращает текущий ThemeSnapshot и сохраняет пользовательский ввод. Ошибки используют общий `{error:{code,message,request_id,…}}`, диагностические пути и логирование неожиданных исключений со стеком. UI показывает ошибку и не теряет введённую тему при 5xx/сети.
|
||||
|
||||
**UI-02.** Preview использует серверный resolver и существующее изолированное preview-хранилище/origin. Стенд Hero/Buttons/Cards/Typography сохраняет композицию исходника; его токены формирует backend. Preview страницы строится тем же штатным renderer с overlay темы. Скрипты сайта в preview не исполняются; служебные токены не попадают в браузерный API-клиент.
|
||||
|
||||
**UI-03.** В текущем single-admin режиме admin выполняет роль владельца. Состояние мастера хранится в `SITE_STATE_DIR/theme-onboarding.json`, отдельно от палитры. Новый сайт без настроенной темы и релиза получает setup при первом входе; существующий сайт с темой/релизом не получает принудительный redirect. Skip сохраняется между сессиями, успешный Save завершает настройку, Repeat открывает первый шаг без перезаписи рабочей темы. Перезапуск сервера не сбрасывает workflow.
|
||||
|
||||
## 8. Публикация, границы и приёмка
|
||||
|
||||
**RL-01.** Save изменяет только workspace. Build использует зафиксированную разрешённую тему, включает CSS и сведения preset/version/tokens в артефакт. Отпечаток сборки учитывает тему, preset definitions и используемые ресурсы рендера; одинаковый старый build_id не используется для перезаписи исторического релиза с другим оформлением. Rollback возвращает готовый релиз, не перезаписывая рабочую тему.
|
||||
|
||||
**AC-01.** Приёмка идёт по этапам плана; следующий функциональный этап начинается после пользовательской приёмки предыдущего. Готовая документация не означает готовую функциональность. Рабочий SITE_ROOT не переключается автоматически; root `examples/` не включается в коммиты. Исходники дизайна и пользовательские данные не перезаписываются.
|
||||
|
||||
**AC-02.** Проверки включают ядро, API/сервисы, установленный wheel, реальные FastAPI/preview процессы, сравнение с источниками в браузере и текущие регрессии. Theme Manager проверяется на 1440, 1280, 1024, 768, 390, 360 px: все действия, desktop/mobile, клавиатура/фокус, диалоги, отсутствие переполнения, JS/CSP-ошибок, потерянных правок и нативных диалогов. Снимки и ограничения среды прикладываются к отчёту каждого этапа.
|
||||
@@ -0,0 +1,82 @@
|
||||
# Задачи 002 — Site Studio и Theme Manager
|
||||
|
||||
Дата: 2026-11-13. Основание: [spec.md](spec.md), порядок и зависимости: [plan.md](plan.md), фактическая проверка этапа 1: [verification.md](verification.md).
|
||||
|
||||
Отметка `[x]` означает выполненную работу. Пользовательская приёмка отмечается отдельной задачей; готовая спецификация не закрывает последующие этапы разработки. Следующий функциональный этап начинается после приёмки предыдущего, кроме явно разрешённого пользователем объединения этапов. Этапы 2–3 выполнены вместе по его поручению; ручная приёмка на сервере не подменяется разрешением продолжить.
|
||||
|
||||
## Документация
|
||||
|
||||
- [x] T001 Зафиксировать полный согласованный объём, источники дизайна и правила поэтапной приёмки.
|
||||
- [x] T002 Зафиксировать решение theme.yaml/new-only без миграции, schema 1, отдельный Site Studio и формы только как схема/оформление.
|
||||
- [x] T003 Описать архитектуру, API, состояния мастера, совместимость и проверки.
|
||||
|
||||
## Этап 1 — Категории и каталог
|
||||
|
||||
- [x] T010 Сохранить рекурсивное обнаружение по fragment.yaml и глобальные ID.
|
||||
- [x] T011 Вычислять категорию по пути, сохранив flat/YAML/misc и смешанные каталоги.
|
||||
- [x] T012 Добавить preview.yaml:props, приоритет по ключам, диагностику envelope/props/YAML, не менять имя фрагмента и форму API preview.
|
||||
- [x] T013 Разложить 15 builtin по шести категориям, сохранить columns/page_header, сверить шаблоны и ресурсы с HEAD.
|
||||
- [x] T014 Показать категории в каталоге, сохранить названия/описания/ID и ограничения allow.
|
||||
- [x] T015 Добавить поиск по категории, объединить прежние русские подписи в UI, синхронизировать активный фильтр после HTML swap.
|
||||
- [x] T016 Проверить плоский/вложенный/смешанный сайт, произвольные категории и глубину, несовпадение имени папки и ID, дубликаты и повреждённые файлы.
|
||||
- [x] T017 Проверить API/HTML, sidecar false/0/defaults, add/preview без записи, save/reopen, ограничения slots/regions и экранирование.
|
||||
- [x] T018 Проверить видимость повреждённого preview в JSON/publish/HTML и сохранность live при отказе.
|
||||
- [x] T019 Проверить wheel с вложенными ресурсами и настоящий FastAPI/preview вне checkout.
|
||||
- [x] T020 Проверить браузером desktop/mobile, фильтры/поиск/фокус, CSS в релизе, отсутствие JS/native-dialog/credential утечек; приложить скриншоты.
|
||||
- [x] T021 Обновить AGENTS/README и отчёт о проверках; не менять дизайн и рабочие данные.
|
||||
- [ ] T022 Пользовательская приёмка этапа 1 на новой сборке.
|
||||
|
||||
## Этап 2 — Файловая тема и релиз (реализован по поручению пользователя)
|
||||
|
||||
- [x] T030 Добавить ThemeDocument/EffectiveTheme, загрузку theme.file и диагностику старого inline-формата.
|
||||
- [x] T031 Перенести шесть immutable preset@1 и разрешённые шрифты из дизайна в runtime-пакет.
|
||||
- [x] T032 Реализовать единые validation/deep merge/Custom/CSS mapping с ограничениями токенов, цветов и градиентов.
|
||||
- [x] T033 Реализовать безопасный default для нового сайта и ошибки явной плохой ссылки; не писать файл автоматически.
|
||||
- [x] T034 Обновить конфигурации примеров и фикстур под новый формат в исходниках, сохранив контент.
|
||||
- [x] T035 Подключить тему к bundle и всем preview, исключить перекрытие токенов defaults и влияние на админку.
|
||||
- [x] T036 Зафиксировать тему/preset/version в релизе, расширить fingerprint ресурсами рендера, сохранить исторические релизы и rollback.
|
||||
- [x] T037 Проверить все пресеты, Custom, воспроизводимость, контраст-warning, invalid input, installed wheel и отказ сборки без переключения current.
|
||||
- [x] T038 Обновить runtime, документацию и отчёт о проверке этапа 2.
|
||||
- [ ] T039 Пользовательская приёмка этапа 2 на новой сборке.
|
||||
|
||||
## Этап 3 — Ширина сайта и секций (реализован вместе с этапом 2)
|
||||
|
||||
- [x] T040 Добавить ContainerSettings и BlockLayout, строгие типы/enum/диапазоны/defaults и наследование.
|
||||
- [x] T041 Провести layout через Page/Display/fixed/slots, снимки, API, формы и операции дерева.
|
||||
- [x] T042 Перенести контролы инспектора из дизайна; сохранить Конструктор ↔ Эксперт, props edits, дублирование и YAML round-trip.
|
||||
- [x] T043 Подключить рендер ширины без поломки вложенных блоков, sticky-header, anchors, preview markers и scroll.
|
||||
- [x] T044 Проверить все режимы и пары ширины, gutters/breakpoints, mobile 360 px, отсутствие overflow и локальный выбор секции.
|
||||
- [x] T045 Обновить runtime, OpenAPI и отчёт о проверке этапа 3.
|
||||
- [ ] T046 Пользовательская приёмка этапа 3 на новой сборке.
|
||||
|
||||
## Этап 4 — Общие фрагменты и Site Studio (реализован по отдельному поручению пользователя)
|
||||
|
||||
- [x] T050 Перенести разметку/CSS публичных фрагментов из seed, сохранив ID, поля, описания, типизированные источники и slots.
|
||||
- [x] T051 Добавить общий steps title/items, убрать локальный дубликат ai-studio и сохранить старый card_grid.variant:steps.
|
||||
- [x] T052 Реализовать entry_card и generic ref to:'*' collection/slug в парсере, resolver, валидаторе и формах, не меняя фиксированные ref/refs.
|
||||
- [x] T053 Дополнить entry_header и form необязательными полями из спецификации и подключить semantic tokens.
|
||||
- [x] T054 Создать отдельный examples/site-studio с исходными данными/ассетами и адаптированными схемами, SEO, меню, формами и редиректами.
|
||||
- [x] T055 Использовать штатные layout hooks, renderer/build; не копировать дубли builtin или mini-renderer.
|
||||
- [x] T056 Проверить 13 страниц, статусы/битый draft, выключенные коллекции, ссылки/ассеты/redirects, схему форм и честный отказ отправки.
|
||||
- [x] T057 Сравнить публичный сайт с design preview на desktop/mobile, проверить прежние примеры и списки более трёх элементов.
|
||||
- [x] T058 Документировать отдельный запуск без переключения SITE_ROOT; обновить отчёт.
|
||||
- [x] T059 Пользователь принял результат этапа 4 и разрешил этап 5: «Ну вот! Хоть какой то действительно хороший вариант получился. Давай теперь 5 этап.»
|
||||
|
||||
## Этап 5 — Theme Manager и onboarding (реализован; ожидает пользовательской приёмки)
|
||||
|
||||
- [x] T060 Реализовать ThemeService и OnboardingService, JSON endpoints/DTO и HTML-адаптер через текущий серверный API-клиент.
|
||||
- [x] T061 Обеспечить Save через ContentService: точный путь, SiteLock/CAS/валидация/история/atomic write/аудит; создание с ABSENT.
|
||||
- [x] T062 Реализовать ThemeSnapshot и ошибки 409 с текущим снимком, request_id, сохранением пользовательского ввода при 5xx/сети.
|
||||
- [x] T063 Добавить overlay темы в изолированный PreviewStore, связать ответы с revision, сохранить CSP/origin/nonce и запрет JS сайта.
|
||||
- [x] T064 Перенести Theme Manager из исходных HTML/CSS/JS Antirion: все четыре шага, пресеты, цвета/градиенты, шрифты/токены/ширину, desktop/mobile, YAML/export и диалоги.
|
||||
- [x] T065 Заменить mock/localStorage API, исключить native alert/confirm/prompt/beforeunload, не создавать самостоятельный дизайн или frontend-сборку.
|
||||
- [x] T066 Добавить серверный onboarding state, распознавание нового/существующего сайта, skip/restart/Save-complete и доступ текущего admin как владельца.
|
||||
- [x] T067 Проверить два редактора/ETag/CSRF, рестарт/skip/repeat, сбои записи/аудита/сети, workspace/live/publish/rollback и отсутствие потери правок.
|
||||
- [x] T068 Сверить UI с оригиналом на 1440/1280/1024/768/390/360 px, проверить клавиатуру/фокус, отсутствие переполнения, JS/CSP/HTTP-ошибок и влияния на skin админки.
|
||||
- [x] T069a Проверить установленный пакет, полную регрессию, обновить OpenAPI/runtime/отчёт этапа 5.
|
||||
- [ ] T069 Пользовательская приёмка Theme Manager на новой сборке. Проверки разработчика не заменяют её.
|
||||
|
||||
## Завершение
|
||||
|
||||
- [ ] T070 Сверить все FR/TH/WD/ST/UI/API/RL/AC требования с проверками и отметить ограничения без ложных заявлений.
|
||||
- [ ] T071 Обновить документацию фактического runtime и статус 002 после всех приёмок. Не коммитить root examples и не публиковать/переключать рабочий сайт без отдельной задачи.
|
||||
@@ -0,0 +1,78 @@
|
||||
# Проверка этапа 4 — публичные фрагменты и Site Studio
|
||||
|
||||
Дата: 2026-11-13. Этап выполнен по отдельному поручению пользователя после этапов 2–3. Реализация готова к пользовательской приёмке; Theme Manager остаётся этапом 5.
|
||||
|
||||
## Результат
|
||||
|
||||
Отдельный `examples/site-studio/` перенесён из `design/examples/site-studio/` на штатные registry/validation/Jinja/build. Сохранены 9 ручных страниц, 8 записей, их статусы, тексты и изображения, пять layouts и два редиректа. Сборка создаёт **13 опубликованных страниц**. Локальных копий builtin, preview-dist и mini-renderer в новом примере нет. Независимый запуск описан в его README; рабочий SITE_ROOT не переключался.
|
||||
|
||||
HTML и CSS общего builtin взяты из исходных фрагментов и assets/site.css. Общие примитивы находятся в builtin/base.css, компонентные правила — в style.css соответствующего фрагмента. Сохранены f-классы для совместимости локальных шаблонов и штатный механизм layout-маркеров без дополнительной обёртки вокруг sticky-header. Типографика, кнопки, цвета, карточки, границы и контейнеры используют токены. Отдельный короткий assets/site.css примера сохраняет вес крупных заголовков 750 из исходного дизайна; обычные заголовки используют вес темы. Shadow примера задан none, поскольку исходные карточки не имеют теней; общий builtin поддерживает изменение этого токена.
|
||||
|
||||
Каталог содержит **17 встроенных фрагментов**. `content/steps` использует прежний title/items; локальная копия ai-studio удалена, данные и ID блоков не изменены. `data/entry_card` имеет обязательный generic ref `entry`, `to: '*'`, значение collection/slug. Фиксированные ref/refs сохраняют slug + to и прежнюю семантику. Generic picker получает только опубликованные записи включённых коллекций с публичными страницами; taxonomy без страницы исключается. Ссылки проверяются также во вложенных group/list/refs данных коллекции, даже если display их не использует. Resolver создаётся для workspace, а не заново для каждой записи.
|
||||
|
||||
`entry_header` дополнен summary/image/image_alt; `form` — title/description. Неограниченные списки, typed actions/query/bindings, slots, columns/page_header и прежний card_grid.variant:steps работают. Дополнительные подписи Hero/Entry, описания списков и знак бренда заданы данными примера.
|
||||
|
||||
Collection поддерживает `requires: [feature.<имя>]`, схема остаётся **1**. Выключенные courses/posts согласованы с features courses/blog; записи выключенной коллекции не попадают в query, релиз и generic picker. Некорректные/неизвестные requirements диагностируются. Структурная проверка workspace сохраняется; release-полнота отключённой коллекции не требуется.
|
||||
|
||||
## Проверки
|
||||
|
||||
| Проверка | Результат |
|
||||
|---|---|
|
||||
| Полная unittest-регрессия | **338 тестов, 0 ошибок, 0 падений, 0 пропусков** |
|
||||
| Новые целевые тесты | 18: generic ref/refs, parser, published-target/feature checks, fixed compatibility, picker, taxonomy, сохранность current при отказе, вложенные ссылки, новый пример и списки длиннее трёх |
|
||||
| Site Studio validate/build | 0 ошибок; **13 страниц**, два редиректа, все локальные ссылки и ассеты доступны |
|
||||
| Предупреждение нового примера | Одно ожидаемое W_THEME_GRADIENT_CONTRAST; визуальная оценка градиентов остаётся необходимой |
|
||||
| AI Studio | validate без ошибок/предупреждений; **14 страниц**, 18 сценариев QA, 70 проверок адаптивности |
|
||||
| Тема/ширины после переноса CSS | Все 8 групп прежней browser QA: 6 пресетов, типографика/кнопки/градиенты, 243 геометрические комбинации, gutters, nested/sticky, конструктор/буфер/Save |
|
||||
| Установленный wheel | Сборка, все пресеты, HTML/API, локальная статика и отдельный preview origin вне checkout, без design/ |
|
||||
| Статические проверки | Ruff по изменённому Python и git diff --check прошли |
|
||||
|
||||
Полная регрессия использует **HEAD-версию** examples/studio-site во временном каталоге с актуальными site.yaml/theme.yaml. Пользовательский examples/studio-site/pages/index.md не менялся ради тестов. Это проверка базовой фикстуры, не заявление о проверке текущей пользовательской композиции. Независимый новый пример и ai-studio проверены в актуальном состоянии.
|
||||
|
||||
## Браузерная сверка с исходником
|
||||
|
||||
`scripts/qa_site_studio_002.py` запускает настоящий FastAPI для изолированной копии нового примера и отдельный сервер исходного preview-dist. Chromium сравнивает 6 страниц (`/`, `/about/`, `/services/`, `/services/bots/`, `/request/`, `/privacy/`) на **1440/1280/1024/768/390/360 px**, всего **36 сравнений**. Для секций проверяются горизонтальная геометрия и фон; для страниц без расширенной формы также высоты и вертикальные координаты с допуском менее 1 px. Скриншоты desktop/mobile дополнительно просмотрены визуально.
|
||||
|
||||
Проверены отсутствие горизонтального переполнения, открытие FAQ с клавиатуры, отсутствие JS-ошибок, native dialogs и неожиданных HTTP-ошибок. Админка открывает новый пример; добавление entry_card предлагает ровно четыре опубликованные цели, сохраняет изменение в буфере до Save и восстанавливает его после Save/reopen.
|
||||
|
||||
Форма отличается от статического seed поведением и необходимым consent: используются настоящие action/method, версия схемы, honeypot и поле согласия со ссылкой на политику. Реальный POST возвращает **HTTP 501**, сообщение отображается рядом с формой; ввод сохраняется, перехода на thank-you нет. Backend приёма/доставки заявок не добавлялся. Статусы active/draft схем форм сохранены. Намеренно отсутствующая обложка draft booking видна как E_ASSET_MISSING в preview; черновик не блокирует релиз.
|
||||
|
||||
Артефакты в `/tmp/site-engine-studio-002/`: browser.json, unittest.log, package.log, public/source-{home,about,services,services-bots,request,privacy}-{1440,390}.png, constructor-1440.png; результаты прежних проверок — ai-studio/ и theme-regression/. Финальная сборка — dist/current/.
|
||||
|
||||
## Повторный запуск
|
||||
|
||||
```bash
|
||||
PYTHONPATH=src python -m site_engine.cli validate examples/site-studio
|
||||
PYTHONPATH=src python -m site_engine.cli build examples/site-studio --out /tmp/site-studio-dist
|
||||
PYTHONPATH=src:tests python -m unittest test_site_studio -v
|
||||
PYTHONPATH=src python scripts/qa_site_studio_002.py
|
||||
PYTHONPATH=src python scripts/qa_ai_studio.py
|
||||
PYTHONPATH=src python scripts/qa_theme_002.py
|
||||
PYTHONPATH=src python scripts/verify_package_001.py --site examples/site-studio
|
||||
```
|
||||
|
||||
Для полной регрессии с сохранением пользовательского контента:
|
||||
|
||||
```python
|
||||
import sys
|
||||
import tempfile
|
||||
import unittest
|
||||
from pathlib import Path
|
||||
|
||||
sys.path[:0] = ['tests', 'scripts']
|
||||
import helpers
|
||||
from qa_fragments_002 import baseline
|
||||
|
||||
with tempfile.TemporaryDirectory() as tmp:
|
||||
helpers.EXAMPLE = baseline(Path(tmp))
|
||||
suite = unittest.defaultTestLoader.discover('tests')
|
||||
result = unittest.TextTestRunner(verbosity=2).run(suite)
|
||||
if not result.wasSuccessful():
|
||||
raise SystemExit(1)
|
||||
```
|
||||
|
||||
Запускать с PYTHONPATH=src после установки server/dev. В этом окружении shell запускался с эскалацией из-за недоступности bwrap namespace; проверки выполнялись локально, внешние сервисы не использовались.
|
||||
|
||||
## Передача на приёмку
|
||||
|
||||
Runtime-изменения требуют пересборки Docker-образа. Рабочие data/env, пользовательский design и страница studio-site не изменялись, live не публиковался. Коммитов этой работой нет; root examples остаются вне коммита. Пользовательская проверка на новой сборке — отдельная T059. После неё можно брать Theme Manager из исходных HTML/CSS/JS в этап 5.
|
||||
@@ -0,0 +1,79 @@
|
||||
# Проверка этапа 5 — Theme Manager и onboarding
|
||||
|
||||
Дата: 2026-11-13. Этап реализован по разрешению пользователя после приёмки этапа 4. Подготовлен к отдельной пользовательской проверке; T069 и закрытие всей 002 остаются открытыми.
|
||||
|
||||
## Результат
|
||||
|
||||
`/admin/theme` / «Дизайн сайта» и `/admin/setup/theme` предоставляют четыре шага исходного Antirion Theme Manager. Перенесены композиция/HTML/CSS/контролы из `design/theme-studio-antirion.html` и `design/assets/theme-studio.{css,js}`: шесть пресетов в исходном порядке, палитра, дополнительные цвета, роли/точки градиентов, пары и выбор шрифтов, scale/line/headingWeight, radius/spacing/shadow/button, контейнеры/gutters, desktop/mobile, YAML/export, reset/skip/repeat и собственные подтверждения.
|
||||
|
||||
Сохраняется принятый shell админки. CSS исходного экрана и необходимые button/chip-примитивы ограничены `.theme-content`. Стенд Hero/Buttons/Cards/Typography перенесён в серверный шаблон; рядом доступна реальная страница сайта. Оба используют core resolver/theme_css и immutable PreviewStore. Ширина внешнего окна передаётся как проверяемая viewport-метаинформация, чтобы исходные responsive-правила стенда не переключались из-за узкого изолированного iframe. Высота окна не пересоздаёт snapshot.
|
||||
|
||||
Backend: ThemeService, OnboardingService, восемь JSON endpoints, DTO и form/CSRF HTML adapter через AdminApi. Тема сохраняется через ContentService с точным путём, SiteLock/CAS, валидацией, историей, atomic write и аудитом. При первом Save добавляется ссылка из site.yaml. Ошибка после записи возвращает committed snapshot; 409 — current snapshot. Правки/preview не сохраняют файл; Save не публикует. Workflow хранится отдельно от палитры и переживает рестарт. Новому сайту предлагается setup, существующему — обычный обзор.
|
||||
|
||||
## Серверные проверки
|
||||
|
||||
Полная регрессия: **359 unittest-тестов**, успешно, без ошибок/пропусков. В этом этапе добавлен **21 тест** в `tests/test_theme_manager.py`:
|
||||
|
||||
- Snapshot, каталог и все шесть пресетов совпадают с core resolver; YAML формирует backend.
|
||||
- Validate, стенд и реальная страница не пишут canonical theme и workflow.
|
||||
- Два редактора, CAS/409/current, история и аудит; новый файл только с ABSENT.
|
||||
- Отдельный настроенный путь, его повторная проверка под блокировкой, запрет соседнего пути, site.yaml и symlink escape.
|
||||
- Ошибки типов/цветов/контейнеров, NaN, контраст как warning с допустимым Save.
|
||||
- Реальные ошибки записи и журнала: traceback/request_id, сохранность файла; committed snapshot при отказе аудита/workflow после записи.
|
||||
- Обычный отказ записи site.yaml восстанавливает первый файл при первоначальном сохранении.
|
||||
- Новый/существующий сайт, сайт с релизом без настройки, skip/restart/завершение и повторная инициализация сервиса/приложения.
|
||||
- Авторизация, отзыв сессии, CSRF/origin, отказ внутреннего API без прямого fallback к сервису.
|
||||
- Подпись/TTL/auth_epoch immutable preview и неизменность старого снимка после Save.
|
||||
- Save → publish → rollback: опубликованная версия и рабочая тема независимы.
|
||||
- Responsive-метаданные стенда и строгие границы viewport_width.
|
||||
|
||||
Регрессия исходного `studio-site` запускалась на извлечённой из HEAD временной базовой фикстуре с текущим контрактом темы. Пользовательский `examples/studio-site/pages/index.md` не переписывался ради тестов. Новый Site Studio проверялся на отдельной временной копии.
|
||||
|
||||
## Браузер и исходный дизайн
|
||||
|
||||
`scripts/qa_theme_manager_002.py`: настоящий FastAPI, Chromium, отдельный static server оригинала, временная копия Site Studio. **9 групп приёмки**, **96 сравнений компонентов**: 4 шага × 6 ширин (1440/1280/1024/768/390/360) × 4 элемента. Сравниваются font-size, padding, border-radius заголовков, шагов, карточек/подзаголовков. Дополнительно сверяются responsive padding Hero и видимость его навигации с исходным стендом. Приложены парные полные снимки всех 24 состояний.
|
||||
|
||||
Проверены:
|
||||
|
||||
1. Все шаги и Desktop/Mobile на шести ширинах без горизонтального переполнения.
|
||||
2. Все шесть пресетов, подтверждение замены, отсутствие автосохранения.
|
||||
3. Запоздавший ответ preview не заменяет новое состояние; выбор шага сохраняет тот же DOM iframe.
|
||||
4. Палитра/именованные цвета/градиенты/точки, шрифты, fluid/outline/нулевой gutter, overlay реальной страницы; клавиатура, замыкание фокуса, Escape.
|
||||
5. Серверный YAML/export текущих несохранённых значений.
|
||||
6. Невалидный ввод/восстановление; две реальные вкладки, конфликт, сохранность ввода, явное принятие основы и повторный Save без публикации.
|
||||
7. HTTP 500 с request_id и обрыв транспорта: видимая ошибка, ввод и сохранённый файл не теряются.
|
||||
8. Отмена перехода, повтор/пропуск мастера без перезаписи рабочей темы, сохранение workflow.
|
||||
9. Пассивный и отдельный origin preview с nonce bridge; сохранённый skin админки; отсутствие palette-localStorage.
|
||||
|
||||
Итог: **0 JS/CSP-ошибок, 0 native dialogs, 0 неожиданных HTTP-ошибок**. Преднамеренные 422/409/500 учитываются отдельно. Это сверка перенесённых компонентов и поведения, а не заявление о попиксельном равенстве двух целых экранов: runtime использует существующий shell, настоящие данные/статусы, серверную диагностику и изолированный iframe. Типографика и отключённые градиенты стенда подчиняются общему контракту темы, включая headingWeight и однотонный fallback; жёстко заданные обходы прототипа не создают второй resolver.
|
||||
|
||||
Артефакты: `/tmp/site-engine-manager-002/`:
|
||||
|
||||
- `browser.json`, `browser.log`, `unittest.log`, `package.log`;
|
||||
- `manager-{width}-step{1..4}.png` и `source-{width}-step{1..4}.png`;
|
||||
- `preset-{minimal,dark,editorial,bold,natural,custom}.png`;
|
||||
- `manager-{width}-preview.png` — видимое превью в viewport (Chromium может не рисовать находящийся вне экрана пассивный iframe в full-page снимке);
|
||||
- `real-page-overlay.png`, `conflict-keeps-input.png`, `separate-origin.png`.
|
||||
|
||||
Desktop и mobile снимки просмотрены визуально; проверен загруженный стенд внутри iframe.
|
||||
|
||||
## Установленный пакет и контракт
|
||||
|
||||
`scripts/verify_package_001.py --site examples/site-studio`: wheel собран и установлен вне checkout, каталога design/ нет. Проверены все пресеты, штатная сборка, прежний конструктор/API/bridge, CSS/JS Theme Manager, серверный шаблон стенда, validate и отдельный preview origin. Runtime не читает исходники дизайна. Штатный CLI validate examples/site-studio: 0 ошибок, одно ожидаемое W_THEME_GRADIENT_CONTRAST. Ruff для изменённых Python и `git diff --check` проходят. OpenAPI обновлён штатным export-openapi.
|
||||
|
||||
Воспроизведение:
|
||||
|
||||
```bash
|
||||
PYTHONPATH=src python -m unittest discover -s tests -p test_theme_manager.py -v
|
||||
PYTHONPATH=src python scripts/qa_theme_manager_002.py
|
||||
python scripts/verify_package_001.py --site examples/site-studio
|
||||
site-engine export-openapi --out specs/001-antirion-admin/openapi.json
|
||||
```
|
||||
|
||||
При пользовательском изменённом studio-site полный suite требует описанной выше базовой фикстуры, как на предыдущем этапе.
|
||||
|
||||
## Границы передачи
|
||||
|
||||
Рабочие data/.env/SITE_ROOT, live, пользовательские design/ и docker-run.sh не менялись. Коммит/переключение примера/публикация не выполнялись. Для просмотра runtime на сервере нужна пересборка контейнера. Ручная серверная приёмка пользователем остаётся открытой.
|
||||
|
||||
Первый Save включает два отдельных atomic rename (theme.yaml и site.yaml) под одним SiteLock с восстановлением при обычном отказе. Это не общая crash-atomic транзакция нескольких файлов: при аварийном завершении процесса между rename может остаться несвязанный файл темы. Он не применяется без ссылки. Настроенная тема обновляется одним файлом. Отказ аудита/workflow после записи явно сообщает committed snapshot; запись не маскируется как неуспешная без последствий.
|
||||
@@ -0,0 +1,68 @@
|
||||
# Проверка 002 — этапы 2 и 3
|
||||
|
||||
Дата: 2026-11-13. Этапы выполнены вместе по прямому поручению пользователя. Реализация подготовлена к пользовательской приёмке; развёртывание на рабочем сервере и этапы 4–5 не выполнялись. Контракт — [runtime.md](runtime.md), задачи — [tasks.md](tasks.md).
|
||||
|
||||
## Реализовано
|
||||
|
||||
- Файловая тема через site.yaml.theme.file, schema 1, шесть точных preset@1 из исходного дизайна и каталог разрешённых шрифтов в runtime-пакете. Inline tokens получают явную ошибку; отсутствие настройки у нового сайта использует minimal@1 без записи.
|
||||
- Единый resolver dataclass-ядра для валидации, CLI/build и обоих режимов preview. Глубокие overrides, строгие числовые диапазоны/типы, HEX, дополнительные цвета и линейные градиенты, полноценный Custom; диагностика контраста — warning.
|
||||
- Семантические CSS-переменные подключены после defaults. Базовая типографика, кнопки, карточки, поверхности, подписи и границы используют токены. Градиенты Hero/button/CTA применяются адресно и отключаются к однотонному fallback; outline не становится solid. Палитра админки не изменяется.
|
||||
- Manifest фиксирует document/effective_tokens, source_hash/render_hash/fingerprint. Воспроизводимый ID учитывает ресурсы движка и пресеты. Коллизия не перезаписывает исторический каталог, ошибки не переключают current, rollback не меняет workspace.
|
||||
- ContainerSettings и BlockLayout: inherit/boxed/fluid/full, max_width, адаптивные gutters и границы 700/1024. Одно поведение для Page/Entry/Display/fixed/slots, собственные контейнеры вложенных блоков и sticky корни.
|
||||
- Контролы ширины инспектора перенесены из design/assets/builder.js: те же подписи, варианты, классы и пояснение. Существующая цепочка htmx → HTML → JSON API → DocumentService сохраняется. API объявляет BlockLayoutDTO в OpenAPI. Обновление полей до Save не записывает страницу; props/duplicate/move/toggle и Конструктор ↔ Эксперт сохраняют layout.
|
||||
- Исходные конфигурации studio-site и ai-studio переведены на theme.yaml с сохранением основных цветов и тёмного Hero. Пользовательские страницы и design не менялись этой работой. Новый examples/site-studio остаётся этапом 4.
|
||||
|
||||
## Автоматические и интеграционные проверки
|
||||
|
||||
Полная регрессия: **320 тестов, 0 ошибок, 0 падений, 0 пропусков**. Для старых тестов использован git HEAD `examples/studio-site`, извлечённый во временный каталог, с наложенными актуальными site.yaml/theme.yaml. Это исключает зависимость от пользовательских изменений рабочего pages/index.md. Новые проверки используют самостоятельный файловый сайт из tests/theme_fixture.py.
|
||||
|
||||
Новые **21 проверки темы** охватывают все пресеты, независимость копий каталога, deep merge и Custom, invalid shapes/enums/ranges/boolean/NaN/Inf/огромные числа, запрещённые CSS/URL/Jinja/шрифты, limits/reserved names, stops и отключение градиентов, пути/YAML/symlink, контраст, общий CSS, manifest, воспроизводимость, изменение ресурсов без изменения source_hash, защиту live/истории и rollback. После исправления обработки огромных чисел эти 21 проверки запущены повторно.
|
||||
|
||||
Ещё **11 проверок ширины и HTTP-интеграции** охватывают строгий BlockLayout, все режимы/наследование, отсутствие общих wrappers и утечек в nested containers, Page/Entry/Display/fixed/slots, схему snapshot/OpenAPI, операции дерева, явное сохранение и reopen, очистку nullable-полей, настоящий HTML → API transform, invalid widths, распространение ошибок темы в API/HTML/preview/publish без переключения live.
|
||||
|
||||
Штатный validate актуального ai-studio: **0 ошибок, 0 предупреждений**; build: **14 страниц**. Отдельная базовая фикстура собирается и в установленном пакете. Проверки wheel подтверждают наличие containers.css, всех шести пресетов, fonts.json и вложенных фрагментов. Wheel установлен вне checkout и запущен без design/: разрешение всех пресетов, сборка, админская статика/шаблоны/API, ширина и отдельный preview origin с nonce bridge проходят.
|
||||
|
||||
Ruff изменённых модулей и git diff --check проходят. Прежние broad assertRaises(Exception) в test_security.py не изменялись и проверены с исключением существующего правила B017; изменённая проверка инъекции использует новый theme.yaml/E_THEME_COLOR. OpenAPI повторно экспортирован в specs/001-antirion-admin/openapi.json.
|
||||
|
||||
## Настоящий браузер
|
||||
|
||||
`scripts/qa_theme_002.py` запускает изолированные FastAPI admin/public и отдельный preview origin; данные и учётная запись временные. **Chromium 158, 8 групп приёмки**:
|
||||
|
||||
1. Все шесть пресетов: фактические background/text, heading weight, radius кнопки; применение и отключение градиента проверены через computed styles.
|
||||
2. Три глобальных режима × девять пар section/content × девять ширин: **243 проверки геометрии пар** на 1440/1280/1024/1023/768/700/699/390/360 px. Проверены gutters, max-width, вложенная секция, sticky-header и отсутствие горизонтального overflow. Дополнительно gutters 0 и 96 на 360 px.
|
||||
3. Контролы инспектора сверены с оригинальным design/builder-antirion.html: варианты/value/подписи и computed font/color/background/border/radius/height/padding совпадают.
|
||||
4. Выбор секции в дереве локальный, без POST; в preview появляется выделение.
|
||||
5. Изменение ширины обновляет immutable preview, сохраняя выбранную секцию и scroll (расхождение менее 3 px), файл страницы не записывается.
|
||||
6. Конструктор ↔ Эксперт сохраняет исходник; изменение props сохраняет layout; Save и reload возвращают те же значения.
|
||||
7. Админка проверена на 1440/1280/1024/768/390/360 px, без горизонтального overflow.
|
||||
8. Нет неожиданных JS/console ошибок, нативных диалогов или внутренних API credentials в запросах браузера.
|
||||
|
||||
Скриншоты desktop/mobile просмотрены: контролы соответствуют исходному дизайну, preview загружен и показывает выделение. Публичный тестовый сайт проверяет поведение движка; он не является переносом нового Site Studio и не подменяет визуальную приёмку этапа 4.
|
||||
|
||||
## Артефакты и воспроизведение
|
||||
|
||||
`/tmp/site-engine-theme-002/`:
|
||||
|
||||
- browser.json — браузерный отчёт и измерения;
|
||||
- constructor-1440.png, constructor-390.png, reference-controls-1440.png;
|
||||
- public-1440.png, public-390.png, public-360.png;
|
||||
- unittest.json и unittest.log — полная регрессия;
|
||||
- ai-studio-dist/current/ — штатная сборка актуального примера;
|
||||
- baseline/examples/studio-site/ — изолированная базовая фикстура с новыми конфигурациями темы.
|
||||
|
||||
```bash
|
||||
PYTHONPATH=src python -m unittest discover -s tests -p 'test_theme.py' -v
|
||||
PYTHONPATH=src python -m unittest discover -s tests -p 'test_block_layout.py' -v
|
||||
PYTHONPATH=src python scripts/qa_theme_002.py
|
||||
PYTHONPATH=src python scripts/verify_package_001.py --site /path/to/isolated-site
|
||||
PYTHONPATH=src python -m site_engine.cli validate examples/ai-studio
|
||||
PYTHONPATH=src python -m site_engine.cli build examples/ai-studio --out /tmp/ai-studio-dist
|
||||
```
|
||||
|
||||
В этой среде использовался `/tmp/flexly-cms-htmx-check/bin/python`. Обычный запуск полной регрессии использует рабочий пример; его результаты могут отличаться при пользовательских изменениях. Системный sandbox bwrap недоступен, поэтому команды выполнялись разрешённым инструментом вне bwrap; браузер работал с loopback и без прокси.
|
||||
|
||||
## Пользовательская приёмка
|
||||
|
||||
Для проверки на сервере нужна пересборка Docker-образа. Если рабочий сайт всё ещё содержит inline theme.tokens, конфигурацию нужно явно перевести на файловый контракт; автоматической миграции нет согласно принятому решению. Изменения текущих рабочих данных, переключение SITE_ROOT, публикация на сервер и коммиты не выполнялись. Root examples не коммитились.
|
||||
|
||||
Проверить в конструкторе «Макет блока · ширина», пары Full/Boxed и Fluid/Full, вложенный блок, переключение Конструктор ↔ Эксперт, Save/reopen. Проверить файловую тему на своём контенте и отдельную публикацию/откат. Пользовательская приёмка отмечается отдельно; новый Site Studio и Theme Manager к этим этапам не относятся.
|
||||
@@ -0,0 +1,44 @@
|
||||
# Проверка 002 — этап 1: категории фрагментов
|
||||
|
||||
Дата: 2026-11-13. Реализация этапа 1 подготовлена к пользовательской приёмке. Следующие этапы — тема, ширина блоков, перенос публичных компонентов, отдельный Site Studio и Theme Manager — этим отчётом не закрываются.
|
||||
|
||||
Это отчёт состояния на момент завершения этапа 1. Последующая реализация темы и ширины описана отдельно в [проверке этапов 2–3](verification-stages-2-3.md); актуальный контракт — [runtime.md](runtime.md).
|
||||
|
||||
## Реализованное поведение
|
||||
|
||||
- Обнаружение рекурсивное, по `fragment.yaml`; имя каталога не подменяет ID манифеста. Плоское, категоризированное и смешанное размещение работают одновременно.
|
||||
- Для вложенного фрагмента категория — первый каталог относительно `fragments/`, для плоского — YAML `category` или `misc`. Путь имеет приоритет над YAML, дополнительная вложенность категорию не меняет. Допустимы произвольные категории сайта.
|
||||
- Все 15 builtin разложены по шести категориям: `content` (6), `data` (2), `forms` (1), `marketing` (3), `media` (1), `system` (2). Их ID, шаблоны, CSS и JS сохранены; побайтовое сравнение перемещённых шаблонов и ресурсов с HEAD прошло. `columns` и `page_header` сохранены.
|
||||
- API продолжает отдавать строку `schema.fragments[id].category` и плоский словарь `preview`. Ссылки на фрагменты остаются без префиксов категорий; повторные ID запрещены.
|
||||
- Необязательный соседний `preview.yaml` имеет форму `{name?: string, props: object}`. Его `props` переопределяют inline preview по ключам; отсутствующие значения берутся из defaults полей. `name` из preview не меняет имя фрагмента. Некорректные файлы дают диагностику с путями, а не исключения из `.get()` при рендере формы.
|
||||
- В каталоге видны категория, название и назначение. Поиск учитывает ID, название, описание, код категории и прежнюю русскую подпись. Прежние категории объединяются со стандартными только при отображении: исходное значение API и файла сохраняется.
|
||||
- Добавление блока и предпросмотр не записывают страницу. Явное сохранение, ETag, CSRF, ограничения регионов/слотов и формат новых ID сохранены.
|
||||
|
||||
## Выполненные проверки
|
||||
|
||||
1. Полный набор Python-проверок: **288 тестов, 0 ошибок, 0 падений, 0 пропусков**. Фикстура `examples/studio-site` взята из HEAD во временный каталог, поскольку рабочий `pages/index.md` изменён пользователем; исходный пример не менялся. Машиночитаемый результат: `/tmp/site-engine-fragments-002/unittest.json`, подробный лог — `unittest.log` в том же каталоге.
|
||||
2. Новые проверки ядра: **23 теста** для обнаружения, приоритета категории, глобальных ID, дубликатов, preview и его диагностики. **7 интеграционных тестов** используют самостоятельную временную файловую модель и настоящую цепочку login → HTML → внутренний API, включая экранирование пользовательских категорий, диагностику повреждённого preview в workspace/JSON/HTML и сохранность опубликованного релиза при отказе.
|
||||
3. Валидация текущего `examples/ai-studio`: **0 ошибок, 0 предупреждений**. Штатная сборка: **14 страниц** в `/tmp/site-engine-fragments-002/ai-studio-dist/current/`.
|
||||
4. Проверка упаковки: wheel содержит все файлы вложенных builtin. Установка wheel во временный каталог и запуск FastAPI вне checkout прошли: статика, шаблоны, API, изолированное превью и bridge работают без каталога `design/`.
|
||||
5. Браузер: настоящий FastAPI и отдельный preview origin, Chromium 158, **1440×960 и 390×844**, **8 групп приёмки**. Проверены категории, русские подписи, поиск, пустая выдача, ограничения региона/слота, клавиатурный фокус, sidecar defaults с `false`/`0`, добавление/превью без записи, согласованность активного фильтра после HTML swap, явное сохранение/повторное открытие, CSS вложенных и плоских фрагментов в опубликованном бандле. Неожиданных JS-ошибок, нативных диалогов и передачи внутренних credentials браузеру нет.
|
||||
6. Проверены Ruff для изменённого Python-кода и `git diff --check`.
|
||||
|
||||
Браузерный отчёт и скриншоты находятся в `/tmp/site-engine-fragments-002/`: `report.json`, `catalog-desktop.png`, `mobile.png`. При проверке ответы runtime `builder-adapter.css` и `builder.js` сравниваются с текущими исходниками; их SHA-256 записывается в отчёт. Скриншоты просмотрены: категории видимы, горизонтального переполнения каталога нет.
|
||||
|
||||
## Воспроизведение
|
||||
|
||||
```bash
|
||||
PYTHONPATH=src python -m unittest discover -s tests -p 'test_fragment_catalog*.py' -v
|
||||
PYTHONPATH=src python scripts/qa_fragments_002.py
|
||||
PYTHONPATH=src python -m site_engine.cli validate examples/ai-studio
|
||||
PYTHONPATH=src python -m site_engine.cli build examples/ai-studio --out /tmp/ai-studio-dist
|
||||
PYTHONPATH=src python scripts/verify_package_001.py
|
||||
```
|
||||
|
||||
Браузерный сценарий самостоятельно получает базовую фикстуру через `git archive HEAD`, не читая и не изменяя рабочий `examples/studio-site/pages/index.md`. Обычные команды полной проверки и `verify_package_001.py` используют рабочий пример: при наличии пользовательских изменений его результаты могут отличаться. Для описанной проверки установленного wheel использовалась временная копия актуальных `src/`, `pyproject.toml`, `README.md` и базовая фикстура из HEAD.
|
||||
|
||||
## Развёртывание и приёмка
|
||||
|
||||
Рабочий `SITE_ROOT`, файлы сайта и исходники `design/` не переключались и не менялись. Коммиты и публикация на сервер не выполнялись. Изменения builtin, загрузчика и админки требуют пересборки Docker-образа; bind-mount каталога сайта их не обновляет.
|
||||
|
||||
После установки новой сборки открыть конструктор → «Добавить блок»: проверить подписи шести категорий, фильтрацию и существующие локальные фрагменты. Далее этап 1 принимает пользователь; переход к ядру темы выполняется после этой приёмки согласно согласованному плану.
|
||||
Reference in New Issue
Block a user