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.
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; не канонический окончательный формат |
Основные границы
- Источник истины — сайт как папка файлов:
pages/,content/,collections/,display/,layouts/,fragments/,menus/,forms/,assets/,data/,site.yaml,redirects.yaml. - SQLite не содержит второй канонической копии контента: в БД — перестраиваемые индексы и служебные сущности (пользователи, сессии, агенты, аудит, заявки, outbox, метаданные сборок).
- Один сервисный слой для админки, CLI и MCP; никаких обособленных проверок прав только в htmx или JS.
- Workspace ≠ Release candidate ≠ Live release. Сохранённый документ не означает, что посетитель увидел изменения.
- Конструктор и Эксперт — два способа работы с одним документом. Ошибочный исходник не перезаписывает последнюю валидную модель.
- Публикация — только валидированный, неизменяемый снимок. Откат переключает live, не затирает workspace.
- Дальнейшие решения из архитектурного ревью — рекомендации, не автоматически утверждённые требования. Они явно вынесены в 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.
- 08_CONTAINER_LAYOUT.md — Boxed / Fluid / Full Width and per-block section/content overrides.