# 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//fragment.yaml` и категоризированное `fragments///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 остаётся `_<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-ошибок, потерянных правок и нативных диалогов. Снимки и ограничения среды прикладываются к отчёту каждого этапа.