marketplaces/docs/platform/00-overview.md

# 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.

## Project Editor
- Внутренний Project Editor редактирует только bootstrap-конфигурацию маркетплейса.
- Editor не управляет товарами, категориями, заказами или аналитикой.
- Первичная версия поддерживает секции general, branding, theme, header, footer, homepage, widgets, marketplace features и preview.