Files
flexly-cms/specs/002-site-studio-theme/plan.md
T
phelex 0d171915d7 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.
2026-11-13 14:04:49 +03:00

83 lines
15 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# План 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 отмечается только после выполнения и приёмки всех этапов.