Files
flexly-cms/design/docs/stage7
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
..

Site Engine — Этап 7: handoff технической реализации

Статус: проект архитектуры для согласования и реализации. Не является работающим backend.
Дата: 12.11.2026. Продукт: Site Engine, отдельно от Flexly AI Core.
Целевая платформа: Python 3.12+, FastAPI, Jinja2, htmx, Pydantic v2, SQLAlchemy 2, SQLite WAL, Alembic; Node.js/SPA не обязательны.

Итог Этапа 7

Завершён технический план переноса утверждённых HTML-прототипов Этапов 1–6 на файловый движок и серверную админку. План охватывает URL/partials, модель документов и сервисов, права, безопасность, совместное редактирование, превью, сборку, публикацию, rollback, формы, MCP/CLI и интеграционные тесты. Реальная интеграция не выполнялась.

Зафиксированные дизайны: 03 Antirion, 04 Antirion Rework, 05 Ember Graphite, 06 Rose Graphite (ранее YuE Studio). Функционально развиваем 04 и 06; 03 и 05 остаются неизменёнными концепциями. У Rose Graphite без скруглений только выбор коллекции в разделе «Контент» — не все таблицы.

Дополнение: Theme Manager / Onboarding

Новая согласованная продуктовая функция: первичная настройка темы публичного сайта через Wizard, готовые пресеты (Minimal, Dark Tech, Editorial, Bold, Natural) и Custom, возможность изменить любой пресет, палитра/шрифты/дизайн-токены и preview. Детали: 07_THEME_MANAGER.md, открытый ADR-007 — adr/ADR-007.md. Это не дизайн-система админки и не новый backend.

Навигация по документам

Файл Для чего нужен
07_THEME_MANAGER.md Тема публичного сайта, Wizard первого входа, presets/Custom, модель theme.yaml, API, acceptance tests (схема предложена до ADR-007)
adr/ADR-007.md Предлагаемый формат хранения темы и миграция от inline site.yaml.theme.tokens
01_ARCHITECTURE.md Общие слои, дерево проекта, модули, владение данными
02_UI_HTMX_MAP.md Каждый экран → Jinja partial, HTTP route, событие htmx, доступ
03_DOCUMENTS_AND_SERVICES.md File-first контракты, операции приложения, DTO, REST/MCP/CLI, concurrency
04_SECURITY_RELEASES.md RBAC, CSRF, preview isolation, build/release/rollback, формы/outbox
05_IMPLEMENTATION_PLAN.md Вертикальные срезы, зависимости, критерии приемки и тест-план
06_PROTO_AUDIT_AND_GAPS.md Точная привязка к исходным HTML/JS и выявленные разрывы между демо и production
adr/ADR_REGISTER.md Решения, утверждение которых необходимо до старта реализации
IMPLEMENTATION_HANDOFF_PROMPT.md Готовое задание для нового чата/кодового агента
examples/ Примеры контрактов и ответов API; не канонический окончательный формат

Основные границы

  1. Источник истины — сайт как папка файлов: pages/, content/, collections/, display/, layouts/, fragments/, menus/, forms/, assets/, data/, site.yaml, redirects.yaml.
  2. SQLite не содержит второй канонической копии контента: в БД — перестраиваемые индексы и служебные сущности (пользователи, сессии, агенты, аудит, заявки, outbox, метаданные сборок).
  3. Один сервисный слой для админки, CLI и MCP; никаких обособленных проверок прав только в htmx или JS.
  4. Workspace ≠ Release candidate ≠ Live release. Сохранённый документ не означает, что посетитель увидел изменения.
  5. Конструктор и Эксперт — два способа работы с одним документом. Ошибочный исходник не перезаписывает последнюю валидную модель.
  6. Публикация — только валидированный, неизменяемый снимок. Откат переключает live, не затирает workspace.
  7. Дальнейшие решения из архитектурного ревью — рекомендации, не автоматически утверждённые требования. Они явно вынесены в ADR.

Источники и приоритет

  • reference_TZ-site-engine.md — первичное ТЗ от 06.11.2026 (черновик), описание системы и форматов.
  • reference_TZ-site-engine-architecture-review.md — архитектурное ревью, предложения с P0/P1.
  • site-engine-admin-design-prompt.md в исходном обсуждении — требования к дизайну, этапам и поведению UI.
  • Реально собранный index.html, assets/*.js, assets/*.css и HTML Этапа 6 — эталон UX, но не production-контракт данных или правил безопасности.

Правило для реализации: если прототип противоречит ТЗ, не копировать случайную структуру JS-state в серверный контракт. Если ревью противоречит черновику ТЗ, оформить ADR и согласовать; в документах этого этапа предложен конкретный стартовый вариант.

Что делать дальше

Согласовать ADR P0, затем начать вертикальный срез V0 из 05_IMPLEMENTATION_PLAN.md: один сайт, одна файловая Page, один Fragment, полный цикл read → edit → validate → atomic save → preview. Остальные подсистемы подключать к тем же сервисам по мере роста, не создавать отдельный «backend для прототипа».

Примечание об объёме

Пакет содержит весь исходный интерактивный проект Этапа 6 без изменения его поведения. Этап 7 добавляет документы и схемы взаимодействия. Исходный HTML-проект не требует установки и по-прежнему открывается из index.html. Для общего localStorage в нескольких вкладках рекомендован локальный HTTP-сервер.

Файловый пример полного сайта

examples/site-studio/ — отдельный исполнимый offline sample: Page + Entry + Collection + Layout + Fragment + Display + Media + Theme + Forms + Menus. Статический preview-dist/ собирается скриптом из YAML/Markdown/Jinja; это не готовый Site Engine backend или production BuildService. Названия и связи нормализованы относительно разных demo-localStorage источников. Система темы в примере остаётся предложением к ADR-007.