Обзор

База данных MySQL 8.0 содержит две таблицы:

Подключение настраивается через env-переменные. Локально — Docker Compose (docker-compose.yml). На Railway — встроенный MySQL plugin с переменными MYSQLHOST, MYSQLPORT, MYSQLUSER, MYSQLPASSWORD, MYSQLDATABASE. Поддерживается также MYSQL_URL / DATABASE_URL как connection string.

Таблица orders

Хранит все заказы. Индексированные колонки позволяют быстро фильтровать по источнику, статусу и дате. Полный JSON объекта заказа хранится в колонке data.

Структура JSON объекта заказа (data)

Структура items[]

Структура extras[]

Пример строки таблицы orders

order_id   : "abc123xyz"
status     : "fulfilled"
webflow    : "SONR Music"
shop       : "SONR Music Shop"
accepted_on: "2026-03-15T10:42:00"
data       : {"orderId":"abc123xyz","status":"fulfilled","webflow":"SONR Music",
              "acceptedOn":"2026-03-15T10:42:00Z","customerPaid":{"value":19900},
              "items":[{"variantId":"abc","product":"SONR Music x2",
              "variant":"Color: Coral","price":16800,"count":1}],
              "extras":[{"type":"shipping","price":3100}],...}

Таблица app_data

Key-value хранилище. Ключ — строка, значение — JSON сериализованный в TEXT. Все операции через ON DUPLICATE KEY UPDATE — безопасный upsert.

Ключи app_data

Пример строки таблицы app_data

key_name: "regions"
value   : [{"name":"Europe","countries":["Austria","Belgium","Bulgaria",...]},
           {"name":"North America","countries":["United States","Mexico",...]},
           ...]

Операции с базой данных

Все операции реализованы в db.js через пул соединений (mysql2/promise, лимит 10 соединений).

Endpoints API

Структура страницы

В шапке — hero-баннер с выбором периода (From / To + кнопка Apply). Под баннером — переключатель вкладок. Apply применяет выбранный период к активной вкладке.

Подробная документация — в отдельных статьях:

• Dashboard · Webflow SONR Music →
• Dashboard · Webflow SONR Coach →
• Dashboard · Shopify →
• Dashboard · Amazon →

Источники данных

Выбор периода

Поля From и To в hero-баннере. По умолчанию — 2026-03-01 → 2026-03-31. После изменения нажмите Apply — все блоки пересчитываются.

Фильтрация по UTC-дате: из acceptedOn берётся slice(0, 10). Базовый фильтр: webflow === "SONR Music" и shop === "SONR Music Shop".

KPI-карточки

Четыре карточки — сводка по всем заказам SONR Music Shop за период.

Расчёт блоков 1–4 · item-by-item с пропорциональным распределением

Блоки SONR Music, SONR Music 2, SONR Music Multisport, SONR Accessories используют единую формулу, реализованную в computeMusicBlockMetrics(orders, mainType):

• Quaiifying orders — заказы где есть хотя бы один SKU нужного типа (Music / Music 2 / Multisport / Accessories соответственно)
• In-block items для блока 1–3 = items типа mainType + items типа "Accessories". Для блока 4 — только "Accessories"
• Block share для каждого заказа = (Σ price in-block items) / (Σ price всех items). Если все items в заказе принадлежат блоку — share=1, иначе меньше
• Product / Accessories revenue, q-ty — только in-block items
• Shipping / Discount Shipping / Tax / Discounts — соответствующий extras[].price × share для каждого заказа
• Gross Revenue = Product + Accessories + Shipping + Tax + Discounts (формула гарантирует баланс тайлов)

Если в заказе есть позиция другого типа (например, регулярный SONR Music внутри Music 2-заказа) — её цена и доля extras уйдут в свой блок, а в текущий не попадут. Items без типа в каталоге попадут в Block 5 (Other Orders).

Секция 1 · Product SONR Music

Включает заказы с хотя бы одним SKU типа "SONR Music". Связь: items[].variantId = skus[].skuId в каталоге.

Прогресс-бар

Процент fulfilled. Справа — абсолютные значения fulfilled и unfulfilled.

Секция 2 · Product SONR Music 2

Заказы с хотя бы одним SKU типа "SONR Music 2". Логика метрик идентична Секции 1. SKU x2/x3 имеют skuid_main_product_qty = 2 или 3.

Секция 3 · Product SONR Music Multisport

Заказы с хотя бы одним SKU типа "SONR Music Multisport". Логика идентична Секциям 1 и 2.

Секция 4 · SONR Accessories

Заказы с типом "Accessories" и без SONR Music / Music 2 / Multisport SKU — чисто аксессуарные заказы.

Секция 5 · Other Orders

Все items из musicShopOrders, чей тип не входит в блоки 1–4 ("SONR Music", "SONR Music 2", "SONR Music Multisport", "Accessories"). Сюда попадают незатегованные SKU и SKU других линеек. Один заказ может одновременно быть в Block 1 и в Block 5.

Клик по строке раскрывает полные детали заказа (items, customer, shipping, extras).

Секция 6 · Products Webflow SONR Coach

Источник: Coach-storefront заказы у которых на странице Coach → Orders Channels вручную выставлено Products In Order = SONR Music. Фильтр в коде:

o.webflow === "SONR Coach"
&& o.shop === "SONR Coach Shop"
&& o.order_products_in_type === "SONR Music"
&& (acceptedOn в выбранном диапазоне)

Зачем: это музыкальные продажи, которые физически прошли через Coach storefront. Видеть их хочется на Music-дашборде вместе с обычными Music-продажами.

Метрики: переиспользуют тот же computeMusicBlockMetrics(coachMusicOrders, "SONR Music") что и Секция 1 — то есть в Product Revenue / Product q-ty попадают только items с skuid_product_type === "SONR Music" (Coach- / Mix- / прочие SKU в этих заказах игнорируются). Tile Accessories revenue / q-ty учитывает аксессуары пришедшие в тех же заказах. Shipping / tax / discount / discount-shipping проратируются по доле Music-items в заказе.

PIO=Mix заказы намеренно исключены — попадают только заказы с PIO ровно равным "SONR Music".

SKU breakdown: две группы — "SONR Music (from Coach orders)" и "SONR Accessories (from Coach orders)". Уникальные groupId и offset чтобы не было коллизий с Секцией 1.

Секция 7 · SONR Orders export

CSV-экспорт по типу заказа. Диапазон дат берётся из top-of-page dashboard-хедера (dashDateFrom / dashDateTo) — отдельных date-input'ов в форме нет, чтобы пользоваться одним общим источником истины и не дублировать UI. Если в хедере не выбран период — кнопка возвращает status-ошибку.

Параметры формы:

• Types — 6 chip-чекбоксов (SONR Music / Music 2 / Multisport / Accessories / Other / Coach (Music)) + мастер All

Источники заказов:

• webflow="SONR Music" && shop="SONR Music Shop" — основная Music-storefront выборка (первые 5 типов)
• webflow="SONR Coach" && shop="SONR Coach Shop" && order_products_in_type="SONR Music" — попадают в выборку только когда активен chip Coach (Music) (data-type=__coach_music__)

Тип заказа = синтетический __coach_music__ для Coach-PIO=Music, иначе тип первого counted item, иначе __other__. В CSV-колонке Type: "Coach (Music)" / "Other" / "SONR Music" и т.д. Колонки: Order ID, Date, Status, Type, Customer, Email, Items, Promo, Subtotal, Total, Shipping, Tax, Discount, Payment. Имя файла: sonr-music-orders-{from}-{to}.csv.

Блок SKU — структура

После каждой секции метрик — два сворачиваемых списка SKU (основной продукт + аксессуары из тех же заказов). Кликните на заголовок группы чтобы раскрыть, на строку SKU — чтобы развернуть таблицу заказов.

SKU summary row (7 tile'ов справа от названия): Units · Total paid · Price (product) · Discount · Disc. Shipping · Tax · Shipping. Каждое значение — сумма соответствующего поля по всем item-rows этого SKU (та же логика что у detail-rows). Discount/Disc. Shipping показывают "—" если сумма ≥ 0.

Таблица заказов (12 колонок): Order ID · Customer · Variant · Status · Date · Units · Total paid · Price (product) · Discount · Discount Shipping · Tax · Shipping. Семантика:

• Units — item.count × (skuid_main_product_qty ?? 1)
• Total paid — order-level customerPaid.value (одно значение на весь заказ — для всех item-rows одно)
• Price (product) — item.price + prorated_discount (нетто после прорированной доли order-level discount по `item.price / Σ item.price`)
• Discount / Discount Shipping — order-level суммы из extras[type=discount] / extras[type=discount-shipping]
• Tax / Shipping — order-level (Σ extras[type=tax] / Σ extras[type.includes(shipping)], последнее уже net — включает discount-shipping)

Tax / Shipping / Discount / Discount Shipping — — если 0 (или не отрицательные для скидок).

Источники данных

Выбор периода

Поля From и To в hero-баннере общие для обоих под-вкладок. По умолчанию — 2026-03-01 → 2026-03-31. После изменения нажмите Apply — все блоки и список Orders Channels пересчитываются.

Фильтрация по UTC-дате: acceptedOn.slice(0, 10). Базовый фильтр всех блоков: webflow === "SONR Coach" AND shop === "SONR Coach Shop".

Под-вкладки

Страница Coach разделена на 2 под-вкладки (pill-tabs):

Sub-tab: Overview — KPI-карточки

Четыре карточки — сводка по всем Coach-заказам за период.

Sub-tab: Overview — Классификация в 7 блоков

Каждый Coach-заказ попадает ровно в один блок. Алгоритм классификации (приоритет сверху вниз) реализован в classifyCoachOrder(order):

1. Если все items в заказе имеют skuid_product_type === "Accessories" → блок 6 SONR Accessories
2. Иначе если order_type в [Direct, Direct Customers, B2B, B2B Customers, Dealers] → соответствующий блок 1–5
3. Иначе → блок 7 Other Orders (без order_type или со значением вне списка 5 каналов)

Сумма заказов всех 7 блоков = Total Orders из KPI-карточек.

Combined views (#7) — это read-only агрегация. Заказы из Direct Customers (блок 2) и SONR Accessories (блок 6) собираются вместе и через тот же computeCoachBlockMetrics считаются общие метрики. Orders count = sum обоих блоков. SKU-разбивка показывает все SKU (Coach + Accessories вместе).

Метрики каждого блока

В каждом блоке отображается единый набор тайлов (некоторые скрыты в блоках 6 и 7 — см. ниже). Расчёт реализован в computeCoachBlockMetrics(blockOrders).

Скрытые тайлы в блоках 6 и 7

Прогресс-бар

Внизу каждого блока — процент fulfilled. Справа абсолютные значения fulfilled и unfulfilled.

SKU-разбивка

Под прогресс-баром — сворачиваемый список SKU из заказов блока. Для блока 6 SONR Accessories — только Accessory SKU. Для блоков 1–5 и 7 — non-Accessory SKU. Клик на строку SKU разворачивает список заказов с Order ID, Customer, Variant, Status, Date, Price.

Блок 8 · SONR Orders export

Под 7 блоками — секция для выгрузки CSV-отчёта по Coach-заказам. Диапазон дат берётся из top-of-page dashboard-хедера (dashDateFrom / dashDateTo) — отдельных date-input'ов в форме нет, чтобы не дублировать UI и иметь один источник истины. Если в хедере не выбран период — кнопка возвращает status-ошибку.

Параметры формы

• Channels — 7 chip-чекбоксов (Direct / Direct Customers / B2B / B2B Customers / Dealers / SONR Accessories / Other Orders) + мастер All
• All — заполненный navy-чип, переключает все 7 chip'ов разом. Если отжать любой chip — All автоматически отжимается

Логика фильтра

Заказ попадает в выгрузку если: webflow === "SONR Coach" AND shop === "SONR Coach Shop" AND acceptedOn в диапазоне AND classifyCoachOrder(order) ∈ выбранные каналы.

CSV-колонки

Имя файла: sonr-coach-orders-{from}-{to}.csv. Если фильтры не дали результатов — статус "No orders match the selected filters", файл не скачивается.

Sub-tab: Orders Channels

Позволяет вручную присвоить канал каждому Coach-заказу. Значение сохраняется в поле order_type через POST /orders/set-order-type (surgical UPDATE — поле сохраняется при последующих Quick/Auto Sync через db.upsertOrders preservation). Список фильтруется по дате из Dashboard-хедера.

Возможные значения order_type

Блок 1 · Unassigned Orders

Список заказов у которых не задано ни order_type, ни order_products_in_type. Колонки: Order ID · Date · Status · Customer · Promo · Amount · Channel · Products In Order. Promo извлекается из extras[].name (regex \(([^)]+)\)).

Batch-режим: в отличие от блоков 2/3/4 (где dropdown сохраняет значение сразу), правки в Unassigned накапливаются в pending state — строка подсвечивается тёплым жёлтым, в тулбаре над списком обновляется счётчик "N pending changes". Кнопка Submit changes сохраняет все изменения параллельно (Promise.all) через POST /orders/set-order-type и POST /orders/set-products-in-type, после чего вызывается renderCoachChannels() и заказы автоматически переезжают в Блок 2 (если задан Channel), Блок 3 (если PIO=SONR Music) или Блок 4 (если PIO=Mix). Если задано и то и другое — заказ появится сразу в нескольких блоках, это разные ортогональные классификации.

Блок 2 · Assigned Orders Coach

Свёрнут по умолчанию — кликом на заголовок раскрывается. Показывает заказы у которых order_type уже задан. В dropdown можно изменить канал или сбросить (выбрать "— select —" — в этом случае поле полностью удаляется из заказа через db.setOrderField).

Блок 3 · Assigned Orders SONR Music

Свёрнут по умолчанию. Фильтр: order_products_in_type === "SONR Music". Заказ может одновременно присутствовать в Блоке 2 (если задан order_type) и в Блоке 3 — это разные ортогональные классификации.

Блок 4 · Assigned Orders SONR Mix

Свёрнут по умолчанию. Фильтр: order_products_in_type === "Mix". Та же логика пересечения с Блоком 2 что и у Блока 3.

Products In Order — допустимые значения

Row expand · детали заказа

Клик по строке (вне dropdown) разворачивает панель с деталями:

• Items — все SKU (product name, variant, variantSKU, qty × count, price)
• Customer — имя, email
• Shipping — полный адрес (line1, city, state, postalCode, country), метод доставки
• Promo code — извлекается из extras[].name (формат Discount (CODE))
• Subtotal · Total — суммы по заказу
• Extras — все записи extras[] (shipping / tax / discount / discount-shipping) с ценами; отрицательные — красным

Повторный клик на строку сворачивает панель. Доступно с клавиатуры: Enter / Space на сфокусированной строке.

API

Сохранение через re-sync

Поля order_type и order_products_in_type входят в PRESERVED_ORDER_FIELDS в db.js и sync-db.js. При Quick / Auto Sync с Webflow существующие пользовательские поля автоматически re-attach'атся к incoming payload — так что заказы не теряют каналы и тип-продуктов при обновлении статуса с upstream.

Источник данных

Заказы с webflow === "SONR Shopify" AND shop === "SONR Shopify Store". Дата заказа: acceptedOn.slice(0,10). По умолчанию открывается за текущий месяц.

Важно: новые поля variantId и extras[] в Shopify заказах появились вместе с этой страницей. Существующие заказы получат их только после Quick Sync через Sync → Shopify → 2. Quick Sync.

KPI-карточки

Четыре карточки — сводка по всем Shopify-заказам за период.

Блоки 1–5 · по типу продукта

Каждый блок использует общий computeMusicBlockMetrics(orders, mainType) — тот же что для Music: per-item revenue + extras prorated by block share. Tile balance сохраняется (Gross = Product + Accessories + Shipping + Tax + Discounts).

Для блоков 1–4 in-block items = {mainType, "Accessories"} — accessories из тех же заказов учитываются в этих блоках. Для блока 5 — только Accessories. Items, не попавшие ни в один блок, идут в Block 6 Other Orders.

Тайлы каждого блока: Gross Revenue (hero), Orders, {mainType} revenue, {mainType} q-ty, Shipping, Discount Shipping, Tax, Discounts, Accessories revenue, Accessories q-ty + прогресс-бар + collapsible SKU-разбивка. Для блока 5 (Acc Only) скрыты product-tiles и Accessories-tiles (там Product = Accessories).

Блок 6 · Other Orders

Items из Shopify-заказов, чей skuid_product_type не входит в {SONR Music, SONR Music 2, SONR Music Multisport, SONR Coach, Accessories} или вообще отсутствует в каталоге. Колонки: Order ID · Date · Status · Product · Variant · Type · Qty · Revenue. Клик по строке раскрывает полные детали заказа.

Чтобы убрать item из Block 6 — задай ему skuid_product_type в Settings → Products Settings → Shopify. Если SKU вообще нет в каталоге — сначала Sync → Shopify → 4. Sync Products чтобы подтянуть его в raw_products, потом Settings → Products Settings → Sync Shopify products.

Блок 7 · SONR Orders export

CSV-экспорт по типу продукта. Диапазон дат — из top-of-page dashboard-хедера (dashDateFrom / dashDateTo); отдельных date-input'ов в форме нет.

• Types — 6 chip-чекбоксов (SONR Music / Music 2 / Multisport / Coach / Accessories / Other) + мастер All

Канал заказа определяется как тип первого counted item (или "Other" если такого нет). CSV-колонки: Order ID, Date, Status, Type, Customer, Email, Items, Subtotal, Total, Shipping, Tax, Discount, Payment. Имя файла: sonr-shopify-orders-{from}-{to}.csv.

Источники данных

Все 7 блоков работают над одним базовым набором: orders в MySQL, отфильтрованные по:

o.webflow === "SONR Amazon"
&& o.shop === "SONR Amazon Store"
&& o.acceptedOn в диапазоне дат из top-of-page header'а

Этот набор передаётся в renderAmazonBlocks(amzOrders), который строит все 6 блоков с метриками и SKU breakdown.

Items в Amazon-заказах

Amazon SP-API возвращает orders и orderItems отдельно. При Quick Sync для каждого заказа дополнительно вызывается /orders/v0/orders/{AmazonOrderId}/orderItems (rate-limit 0.5 req/sec, burst 30). Items маппятся в наш формат через transformAmazonOrder:

Backfill для исторических заказов с пустым items[] — endpoint POST /orders/amazon-backfill-items. Тянет orderItems для каждого пустого заказа, идемпотентный (повторный запуск пропускает уже заполненные), incremental persist каждые 25 заказов, retry-on-error с экспоненциальным backoff'ом. Для 643 заказов — ~18-20 минут.

Каталог продуктов

Амазон-листинги хранятся в app_data['products'] с source: "Amazon". skuId в каталоге равен variantId в order items, что позволяет dashboard'у через skuMap[item.variantId]?.skuid_product_type определить тип продукта. Если у каталог-SKU не задан skuid_product_type — item уйдёт в Block 6 "Other Orders".

KPI Row · 4 карточки

Считаются один раз для всех Amazon-заказов в выбранном диапазоне (до фильтрации по типам).

Блок 1 · SONR Music

Фильтр заказа: заказ попадает в блок если в его items[] есть хотя бы один item чей skuMap[item.variantId]?.skuid_product_type === "SONR Music".

amzOrders.filter((o) =>
  (o.items || []).some((it) =>
    skuMap[it.variantId]?.skuid_product_type === "SONR Music"
  )
)

Один заказ может одновременно попасть в несколько блоков (если у него items разных типов).

Метрики (через computeMusicBlockMetrics(blockOrders, "SONR Music"))

Прорация extras: shipping/tax/discount/discount-shipping order-level. Доля блока = (Σ price items типа SONR Music + Accessories) / (Σ price всех items в заказе). То есть если в заказе SONR Music + Coach по 50% стоимости — каждый блок получает 50% доставки.

Progress bar

Под метриками — % fulfilled (fulfilled / blockOrders.length × 100) с цветными счётчиками N fulfilled / N unfulfilled.

SKU breakdown

Под progress-bar — два сворачиваемых списка SKU:

• SONR Music — все items типа "SONR Music" из заказов блока
• Accessories — все Accessories items из заказов блока

Каждая SKU-строка раскрывается по клику и показывает все item-rows этого SKU с 12 колонками (Order ID · Customer · Variant · Status · Date · Units · Total paid · Price (product) · Discount · Discount Shipping · Tax · Shipping). Подробнее — статья про Music dashboard.

Блок 2 · SONR Music 2

Идентичная Блоку 1 логика, только type = "SONR Music 2". Заказ попадает если ≥1 item с skuid_product_type === "SONR Music 2". Метрики через тот же computeMusicBlockMetrics(blockOrders, "SONR Music 2"). SKU breakdown показывает Music 2 SKUs + accessories.

Блок 3 · SONR Music Multisport

То же что Блок 1/2 для type "SONR Music Multisport". Метрики и SKU breakdown аналогичны.

Блок 4 · SONR Accessories

Этот блок ведёт себя иначе — он показывает заказы где аксессуары пришли сами по себе, без основного продукта.

amzOrders.filter((o) => {
  const items = o.items || [];
  const hasAcc = items.some((it) =>
    skuMap[it.variantId]?.skuid_product_type === "Accessories");
  const hasMain = items.some((it) =>
    AMAZON_PRODUCT_MAIN_TYPES.has(skuMap[it.variantId]?.skuid_product_type));
  return hasAcc && !hasMain;
})

Где AMAZON_PRODUCT_MAIN_TYPES = {"SONR Music", "SONR Music 2", "SONR Music Multisport", "SONR Coach"}.

Зачем такой фильтр

Аксессуары которые приехали с основным продуктом (Music/Coach/etc) уже учитываются в блоке этого продукта (tile "Accessories revenue/q-ty"). Block 4 показывает только чистые accessory-only заказы — кто-то купил исключительно аксессуар.

Метрики

computeMusicBlockMetrics(blockOrders, "Accessories") с isAccBlock = true:

• Product Revenue / q-ty tiles скрыты (для accessory-only они бессмысленны)
• Gross / Shipping / Tax / Discount — обычная прорация
• Tile "Accessories revenue/q-ty" тоже скрыт — здесь Accessories и есть основной продукт

SKU breakdown показывает только Accessories SKUs.

Блок 5 · SONR Coach

Идентичная Блоку 1 логика для type = "SONR Coach". Заказ попадает если ≥1 item с skuid_product_type === "SONR Coach". Метрики через computeMusicBlockMetrics(blockOrders, "SONR Coach"). SKU breakdown — Coach SKUs + accessories.

Блок 6 · Other Orders

Это item-level dump — не агрегированные заказы, а конкретные позиции которые "потерялись".

Что туда попадает

Items из всех Amazon-заказов где:

const type = skuMap[item.variantId]?.skuid_product_type;
if (!type || !AMAZON_COUNTED_TYPES.has(type)) {
  uncountedItems.push({ order, item, type: type || "—" });
}

То есть item попадает если:

• SKU нет в каталоге (skuMap[item.variantId] = undefined) — typically значит что нужно сделать Sync → Amazon → Sync Products чтобы подтянуть свежие листинги, потом Settings → Products → Sync Amazon products
• SKU есть, но без типа (skuid_product_type = пусто) — нужно зайти в Settings → Products → Amazon и проставить тип
• SKU с типом вне 5 counted-types (например "Music Streaming" или "Others") — будет в Block 6 пока не переклассифицирован

AMAZON_COUNTED_TYPES = {"SONR Music", "SONR Music 2", "SONR Music Multisport", "SONR Coach", "Accessories"}.

Отображение

Используется тот же helper renderDashOtherSkus что у Music Block 5. Это таблица с колонками: Order ID · Date · Status · Product · Variant · Type · Qty · Revenue. Клик по строке раскрывает полные детали заказа (items, customer, shipping, extras).

Как "очистить" Block 6

1. Sync → Amazon → 4. Sync Products — подтянуть свежий каталог в raw_products
2. Settings → Products Settings → Sync Amazon products — перенести в рабочий products
3. Settings → Products → Amazon — выбрать skuid_product_type для каждого ASIN. После save — заказы автоматически переедут в нужный блок 1–5 при следующем рендере dashboard'а

Блок 7 · SONR Orders export

CSV-экспорт по типу продукта. Диапазон дат — из top-of-page dashboard-хедера (dashDateFrom / dashDateTo); отдельных date-input'ов в форме нет.

• Types — 6 chip-чекбоксов (SONR Music / SONR Music 2 / SONR Music Multisport / SONR Accessories / SONR Coach / Other) + мастер All (заполненный navy при активности)

Логика фильтра экспорта

Заказ попадает в выгрузку если выполняется ОБА условия:

1. Источник: webflow === "SONR Amazon" && shop === "SONR Amazon Store"
2. Дата в диапазоне
3. И один из двух матчей: (а) хотя бы один item имеет skuid_product_type ∈ выбранные chip'ы, ИЛИ (б) primary type заказа (тип первого counted item, иначе __other__) ∈ выбранные chip'ы

CSV-колонки: Order ID, Date, Status, Type, Customer, Email, Items, Subtotal, Total, Shipping, Tax, Discount, Payment. Type = primary type заказа (или "Other" для __other__). Items = склейка "Product (variant) ×count" через "; ". Filename: sonr-amazon-orders-{from}-{to}.csv.

Per-block Export-кнопки

В шапке каждого блока 1–6 — outlined-navy Export кнопка с download-иконкой (рядом с Wiki-кнопкой). Клик скачивает CSV только этого блока за период из dashboard-header'а. Реализована через delegated event handler с уникальными data-amazon-export-type / data-amazon-export-slug атрибутами (не конфликтует с Music dashboard'ом который использует data-export-type).

Filename: sonr-amazon-{slug}-{from}-{to}.csv. Feedback — toast (success/error).

Workflow при настройке

Чтобы блоки 1–5 заполнились данными:

1. Sync → Amazon → 1. Import / 2. Quick Sync — заказы попадут в orders
2. Sync → Amazon → 4. Sync Products — листинги уйдут в raw_products
3. Settings → Products Settings → Sync Amazon products — raw_products → products
4. Settings → Products → Amazon tab — для каждого ASIN dropdown'ом проставить skuid_product_type: SONR Music / SONR Music 2 / Multisport / Accessories / SONR Coach
5. Save changes
6. Открыть Dashboard → Amazon — все заказы автоматически распределены по блокам

Если в БД уже есть Amazon-заказы с пустым items[] (импорт делался до фикса import flow), нужно дополнительно дёрнуть POST /orders/amazon-backfill-items — иначе заказы попадут в Block 6 (нет items для матчинга). Backfill идемпотентный, безопасно повторно запускать.

Обзор

Страница Sync управляет импортом и синхронизацией заказов из всех подключённых источников данных. Состоит из четырёх вкладок:

Подробное описание каждой вкладки — в отдельных статьях (см. боковое меню).

Статистика (Stats Bar)

В верхней части — 4 KPI-карточки по всем источникам (Coach excluded не применяется — учитываются все):

Ниже — карточки по каждому источнику: SONR Music, SONR Coach, SONR Shopify, SONR Amazon. Каждая карточка показывает Revenue, Orders, прогресс-бар fulfilled % и счётчики fulfilled/unfulfilled.

Таблица заказов

Основной контент вкладки — таблица всех заказов с колонками:

Фильтры и поиск

Экспорт CSV

Кнопка Export CSV доступна только администраторам (role === "admin"). Экспортирует все заказы с применёнными фильтрами. Имя файла включает диапазон дат. Валюта в CSV записывается без пробелов (formatCurrencyRaw()).

Источники

Вкладка содержит два блока — по одному на каждый Webflow сайт:

1. Quick Sync

Забирает заказы из Webflow API за выбранный период, трансформирует в унифицированный формат и сохраняет в MySQL через upsert.

Статус операции отображается под toolbar. При успехе показывается количество добавленных/обновлённых заказов.

2. Auto Sync

Серверный фоновый синк — работает без участия пользователя по расписанию. Управляется через toggle-переключатель.

3. Sync Products

Забирает каталог продуктов из Webflow API и сохраняет в app_data['raw_products']. Доступно для обоих сайтов (SONR Music и SONR Coach). Это сырые данные без пользовательских настроек.

После выполнения — перейдите в Settings → Products Settings и нажмите соответствующую кнопку Sync (SONR Music или SONR Coach), чтобы обновить рабочий каталог app_data['products']. Пользовательские поля (skuid_product_type, skuid_product_color, skuid_main_product_qty, skuid_receivers_count, skuid_radio_count) при этом сохраняются.

Подключение (OAuth)

При первом входе отображается блок Connect Shopify с кнопкой «Connect Shopify Account». Поток авторизации:

1. Кнопка → GET /shopify/auth → редирект на Shopify OAuth.
2. После подтверждения Shopify редиректит на /shopify/callback.
3. Сервер обменивает code на access token, сохраняет в памяти.
4. Страница-подтверждение показывает токен с кнопкой Copy.
5. На Railway токен нужно вставить вручную в Railway Variables → SHOPIFY_ACCESS_TOKEN.

После подключения блок Connect скрывается и появляется блок синхронизации.

1. Import from Shopify

Первичный импорт — загружает сырые заказы из Shopify Admin API (2024-01) в app_data['raw_shopify']. Использует cursor-based пагинацию через Link header. Параметр — дата From.

2. Quick Sync

Трансформирует сырые данные Shopify в унифицированный формат и делает upsert в MySQL. Аналогично Webflow Quick Sync — параметры From и Count.

3. Auto Sync

Аналогичен Webflow Auto Sync. Работает на сервере в фоне по расписанию (1 или 2 часа). Управляется toggle-переключателем.

4. Sync Products

Пулит все продукты из Shopify Admin API (GET /admin/api/2024-01/products.json?limit=250) с cursor-based пагинацией (Link header) и сохраняет в raw_products с source: "Shopify".

Трансформация transformShopifyProduct:

Импорт — только в raw_products. Чтобы применить в каталог — используйте Settings → Products Settings → Sync from Shopify.

Конфигурация

Подключение

Amazon SP-API не использует OAuth flow из браузера. Credentials задаются вручную через ENV переменные (локально в .env, на Railway — в Variables).

Если credentials не заданы — отображается блок-заглушка «Add your Amazon credentials to .env». После добавления и перезапуска появляется блок синхронизации.

Access token кешируется в памяти сервера и автоматически обновляется за 5 минут до истечения.

1. Import from Amazon

Загружает сырые заказы из Amazon Orders API (/orders/v0/orders) в app_data['raw_amazon']. Items каждого заказа загружаются отдельно через /orders/v0/orders/{orderId}/orderItems с rate limiting. Параметр — дата From (обязательная для SP-API, CreatedAfter).

2. Quick Sync

Трансформирует сырые данные Amazon в унифицированный формат и делает upsert в MySQL. Параметры — From и Count.

3. Auto Sync

Фоновый серверный синк по расписанию (1 или 2 часа). Управляется toggle-переключателем. Аналогичен Webflow Auto Sync.

4. Sync Products

Тянет все listings продавца через SP-API GET /listings/2021-08-01/items/{sellerId} и сохраняет в app_data['raw_products'] с source: "Amazon". Постранично через pagination.nextToken (pageSize=20). Каждый listing маппится в product-record c одним SKU внутри (Amazon не моделирует варианты как Webflow/Shopify — каждый ASIN/SKU отдельный листинг). Поля product: productId: "amazon-{sku}", name (из summaries[].itemName), один SKU с sku, asin, image (summaries[].mainImage.link), price (если в offers[] есть запись для текущего marketplace).

Merge в raw_products идёт по ключу productId:source — повторный sync обновляет записи in-place, не дублирует. Endpoint: POST /sync-products-amazon.

Источники данных

Страница работает с заказами из MySQL, отфильтрованными по условию webflow === "SONR Music" и shop === "SONR Music Shop". Используются те же данные что в Dashboard Block 1.

Фильтр по дате

В верхней части страницы — поля From и To + кнопка Apply. По умолчанию выставляется первый день текущего месяца → сегодня (UTC). Все отчёты пересчитываются при нажатии Apply.

KPI карточки

Фильтр по статусу

Перед таблицами — строка chip-фильтров: Unfulfilled, Fulfilled, Refunded, Disputed, Dispute-lost. Можно выбрать несколько. Все активные чипы применяются к отчётам одновременно. Если ни один не выбран — показываются все статусы.

Вкладки отчётов

Обзор

Страница Settings доступна только администраторам. По умолчанию открывается вкладка Overview с карточками-навигаторами к трём разделам:

Таблица пользователей

По умолчанию отображается список всех пользователей. Нажмите + Add User в правом углу заголовка — форма создания раскроется ниже. Нажмите Cancel или снова «+ Add User» чтобы свернуть.

Все поля в таблице редактируемые — кнопка Edit справа. Правила безопасности:

• Нельзя удалить себя
• Нельзя удалить последнего администратора
• Нельзя понизить роль последнего администратора

Форма Add New User

Раскрывается по кнопке + Add User. Обязательные поля — Username и Password. После создания форма автоматически сворачивается.

Хранение

Пользователи хранятся в app_data['users'] (таблица app_data, ключ users). Пароли хранятся в открытом виде в JSON — не используйте критичные пароли.

Назначение

Регионы используются на странице Statistics в отчёте Country — страны группируются по регионам для отображения на SVG-чарте.

Управление регионами

Кнопка + Add Region создаёт новый регион. Клик по названию региона — переименование. Под каждым регионом список стран с возможностью добавления (+ Add Country) и удаления (×).

Данные хранятся в app_data['regions'].

Sync from Webflow / Shopify / Amazon

Четыре кнопки для импорта продуктов из app_data['raw_products'] в app_data['products']:

Все четыре сохраняют пользовательские настройки SKU (skuid_product_type, skuid_product_color, skuid_main_product_qty и пр.) при обновлении.

Перед sync нужно сначала получить сырые данные — через Sync → Webflow → Sync Products для Music/Coach, Sync → Shopify → Sync Products для Shopify, или Sync → Amazon → Sync Products для Amazon.

Переключение источника

Над списком продуктов расположены четыре переключателя — SONR Music, SONR Coach, Shopify, Amazon. Они фильтруют список по полю product.source на клиенте. Все продукты хранятся в одной таблице app_data['products'], переключение не меняет данные.

Список продуктов

Список всех SKU выбранного источника, сгруппированных по skuid_product_type. Набор полей зависит от активного источника.

SONR Music:

SONR Coach:

Изменения не сохраняются автоматически. После редактирования одного или нескольких SKU появляется кнопка Save changes — нажмите её чтобы сохранить все изменения разом. Данные отправляются одним запросом POST /products/save-skus, который обновляет только явно изменённые поля, не трогая остальные.

Sync from Webflow — сохранение настроек

При повторной синхронизации SONR Music продуктов из Webflow все три поля (skuid_product_type, skuid_product_color, skuid_main_product_qty) сохраняются — они не затираются сырыми данными из Webflow.

Связь с Dashboard

При загрузке страницы Dashboard строится skuMap — словарь variantId → { skuid_product_type, skuid_product_color, skuid_main_product_qty }. Все блоки Dashboard используют этот словарь для классификации товаров в заказах. После изменения настроек SKU нужно перезагрузить страницу Dashboard для применения изменений.