docs

docs/platform/00-overview.md

@@ -0,0 +1,88 @@
+# 00. Обзор платформы
+
+## Master Summary
+Платформа представляет собой многоарендный SaaS-конструктор маркетплейсов, в котором витрина, структура страниц, виджеты, темы и навигация формируются из конфигурации, а не из кастомного кода под каждого клиента. Каждый магазин (tenant) определяется строго по доменному имени, после чего frontend загружает bootstrap.json и строит UI динамически.
+
+### Что это за платформа
+- Конфигурационно-управляемая marketplace-платформа для запуска нескольких магазинов на единой кодовой базе.
+- Визуальная и функциональная сборка витрины выполняется через bootstrap.json и связанные JSON-модули.
+- Backend предоставляет данные домена: категории, товары, остатки, цены, медиа и справочники.
+
+### Как создается новый маркетплейс
+1. Регистрируется домен нового клиента и на backend настраивается tenant-конфигурация.
+2. Готовится bootstrap.json (страницы, секции, виджеты, тема, маршруты, feature flags).
+3. Подключаются API-эндпоинты каталога, категорий и карточек товаров.
+4. Выполняется smoke-проверка: tenant resolution, загрузка bootstrap, рендер главной, каталог, карточка товара.
+
+### Что должен сделать клиент для запуска нового магазина
+- Предоставить домен и бренд-материалы (логотип, цвета, шрифты, иконки).
+- Утвердить структуру страниц и навигации.
+- Подтвердить каталогные правила (категории, витрины, карточки, фильтры).
+- Подтвердить статический контент (о компании, политика, доставка, возвраты).
+
+### Что обязаны реализовать backend-команды
+- Доменную идентификацию tenant и выдачу tenant-aware bootstrap-конфигурации.
+- API для категорий, товаров, карточек и связанных коллекций.
+- Гарантированную стабильность контрактов JSON и версионирование schemaVersion.
+- SLA по доступности и времени ответа, достаточные для runtime-инициализации UI.
+
+## Назначение документа
+Документ описывает бизнес-границы платформы, обязательные принципы архитектуры и процесс запуска нового tenant без изменения frontend-кода.
+
+## Обязательные JSON-поля платформенного bootstrap
+- schemaVersion: версия контракта конфигурации.
+- tenant: идентификатор и параметры арендатора.
+- theme: токены темы (цвета, типографика, радиусы, тени).
+- pages: список страниц с секциями и виджетами.
+- apiEndpoints: карта backend-эндпоинтов.
+
+## Опциональные JSON-поля
+- featureFlags: флаги включения функциональности.
+- localization: список языков и словарей.
+- seo: SEO-конфигурация страниц.
+- permissions: роли и разрешения для административных зон.
+
+## Строгие правила
+- Нельзя хардкодить tenant-логику во frontend.
+- Tenant определяется только по домену.
+- UI генерируется из bootstrap.json; ручная сборка страниц запрещена.
+- Виджеты не вызывают API напрямую.
+- Layout управляется только конфигурацией.
+- Изменения контрактов выполняются только через версионирование schemaVersion.
+
+## Пример JSON (сокращенно)
+```json
+{
+  "schemaVersion": "1.0.0",
+  "tenant": {
+    "id": "tenant-acme",
+    "slug": "acme",
+    "host": "shop.acme.com",
+    "defaultLocale": "ru"
+  },
+  "theme": {
+    "themeId": "acme-light",
+    "palette": {
+      "primary": "#1F6B5C",
+      "backgroundPrimary": "#FFFFFF"
+    }
+  },
+  "pages": [
+    {
+      "id": "home",
+      "route": { "path": "/" },
+      "sections": []
+    }
+  ]
+}
+```
+
+## Ответственность Frontend
+- Разрешить tenant по домену и загрузить bootstrap-конфигурацию.
+- Валидировать обязательные поля и безопасно обрабатывать отсутствие опциональных.
+- Построить страницы, секции и виджеты без tenant-specific условных веток.
+
+## Ответственность Backend
+- Возвращать валидный bootstrap JSON для каждого tenant.
+- Поддерживать согласованные API-контракты каталога.
+- Обеспечивать обратную совместимость либо явно повышать schemaVersion.