Files
flexly-cms/design/docs/stage7
phelex 88ac95dd19 Integrate Antirion admin with FastAPI and htmx
Add the shared document API, constructor and expert editors, isolated preview, and fragment catalog metadata with typed block IDs.

Include design references, specification 001, QA scripts, project guidance, and cached Docker dependency installation. Leave example sites for a separate commit.
2026-11-12 21:55:36 +03:00
..

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

Актуальные границы работ и поправки: сопоставление с 001. При расхождении применять спецификацию 001 и действующие файловые контракты.

Статус: проект архитектуры для согласования и реализации. Не является работающим 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 без скруглений только выбор коллекции в разделе «Контент» — не все таблицы.

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

Файл Для чего нужен
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-сервер.