Архитектура

Fluttrium Market — один общий сервер для всех магазинов платформы. Каждый магазин — отдельный канал на этом сервере со своим токеном, каталогом, заказами, покупателями и настройками. Сайт магазина (витрина) — отдельное приложение, которое ходит на сервер по Fluttrium Shop API (GraphQL).

Части системы

Часть	Адрес	Что делает
Shop API	https://api.fluttrium.store/shop-api	Публичный GraphQL для витрин: каталог, поиск, корзина, оформление, вход покупателя, контент сайта, доставка
Admin API	https://admin.fluttrium.store/admin-api	GraphQL админки. Им пользуется сама админка, витрине он не нужен
Админка	https://admin.fluttrium.store/dashboard	Интерфейс продавца и его сотрудников
Файлы	https://api.fluttrium.store/assets/…	Фото и видео товаров и контента, превью нужного размера
Сервис виджета СДЭК	https://api.fluttrium.store/cdek/widget?channel=<токен>	Пункты выдачи и цены для виджета СДЭК на чекауте
Уведомления банков	/payments/yookassa, /payments/tinkoff на адресе платформы	Приём уведомлений ЮKassa и Т-Банка об оплате и отмене
Реестр пакетов	https://npm.fluttrium.store	@fluttrium/shop-sdk — клиент и типы Shop API, открыт на чтение без логина
Витрина	домен магазина	Next.js-приложение магазина, у каждого своё

На этом же сервере работает фоновый обработчик (воркер). Он выполняет задачи по расписанию и очереди:

Задача	Как часто	Подробнее
Сверка неоплаченных платежей с банком	каждые 5 минут	Платежи
Номера отслеживания новых отправлений СДЭК	каждые 10 минут	СДЭК
Создание отправления СДЭК после оплаты, если продавец включил	сразу, до 8 повторов при сбое	СДЭК
Письма покупателю об оплате и отправке	сразу после события	Почта магазина

Магазин = канал

Магазин выбирается заголовком запроса с токеном канала. Всё, что возвращает Shop API, — только этого магазина: его товары, цены, контент, его заказы.

Запрос без токена не падает

Без заголовка токена сервер отвечает данными канала по умолчанию, а не ошибкой. Пустой каталог в разработке — первое, что стоит проверить. С неверным токеном приходит ошибка CHANNEL_NOT_FOUND.

Аккаунт покупателя общий для всей платформы: один и тот же человек может покупать в разных магазинах под одной почтой. Заказы, адреса в заказах и корзина при этом у каждого магазина свои.

Модули платформы

Модуль	Для продавца	Для витрины (Shop API)
Каталог, заказы, покупатели, акции	Разделы Каталог, Продажи, Клиенты, Маркетинг → Акции	Стандартные запросы: products, collections, search, activeOrder, addItemToOrder и др.
Контент витрины	Маркетинг → Контент витрины	storefrontContent — Контент витрины
Доставка СДЭК	Настройки → Доставка СДЭК	cdekWidgetParams, setCdekDelivery, Order.cdekDelivery — СДЭК
Оплата ЮKassa и Т-Банк	Настройки → Способы оплаты	addPaymentToOrder, checkOrderPayment — Платежи
Вход покупателя по коду	—	requestLoginCode, authenticate — Вход покупателя
Почта магазина	Настройки → Почта магазина	— (письма уходят с сервера)
Сотрудники	Настройки → Сотрудники	—
Маркетплейсы Ozon и Wildberries	Разделы Ozon и Wildberries	— (только админка)

Контент витрины и маркетплейсы магазину включает платформа. СДЭК работает, когда у магазина есть способ доставки СДЭК и ключи продавца. Пока модуль не работает, Shop API отдаёт пустой результат (storefrontContent — пустые списки, cdekWidgetParams — null), а не ошибку.

Как витрина получает данные

1. Сервер витрины (не браузер) делает запрос в Shop API с токеном магазина. Публичные данные — каталог, контент — кешируются на стороне витрины.
2. Корзина и вход живут в сессии покупателя. Сервер платформы выдаёт токен сессии в заголовке ответа, витрина хранит его в httpOnly-cookie и передаёт в каждый запрос. Подробно — Shop API.
3. Картинки берутся напрямую с api.fluttrium.store/assets/ с параметрами превью.
4. Виджет СДЭК в браузере ходит в сервис виджета платформы напрямую.

Заметка

В Shop API ходит сервер витрины, а не браузер покупателя: так сессия живёт в httpOnly-cookie, а публичные запросы кешируются. Из браузера напрямую работает только виджет СДЭК — его сервис для этого и сделан.

Как это сделано в MOSHNA

Витрина MOSHNA — Next.js-приложение на своём сервере. Все запросы к Shop API делает её сервер: публичные — с кешем Next.js, корзина и оформление — без кеша, в сессии покупателя. Устройство витрины разобрано на странице Витрина на Next.js.

Версии

Платформа выходит версиями (semver). Тем же номером публикуется @fluttrium/shop-sdk — схема и типы Shop API именно этой версии. Витрина ставит версию SDK, равную версии платформы на сервере, и после обновления платформы поднимает её: расхождения видны на типах при генерации кода.

Что дальше

Shop APIПодключение, сессия, примеры запросов.

Витрина на Next.jsКак устроена витрина MOSHNA и что в ней настраивается.

Контент витриныСтраницы из блоков, меню, баннеры, тема.

Синхронизация документацииКак документация обновляется вслед за кодом.