Сервер юнит-экономики: Kaspi Магазин + Ozon + Wildberries (деплой на Vercel)

Backend (Node.js/TypeScript/Express/Prisma) + встроенный веб-дашборд для расчёта юнит-экономики магазина, продающего на Kaspi.kz (Магазин), Ozon и Wildberries. Разворачивается на Vercel бесплатно.

Сервер автоматически подтягивает заказы через официальные API площадок, считает себестоимость по вашей карточке товара, вычитает комиссии/логистику/ рекламу и показывает выручку, прибыль, маржу и ROI — по товарам, по площадкам и в динамике. Также умеет автоматически снижать цену на Kaspi, не опускаясь ниже заданного минимума (см. раздел про автобот ниже).

Возможности

• 🔄 Автосинхронизация заказов из Kaspi Shop API, Ozon Seller API и Wildberries Statistics API
• 💰 Учёт себестоимости товара (в т.ч. упаковки) с привязкой к SKU каждой площадки
• 📊 Расчёт: выручка, COGS, комиссия площадки, логистика, реклама, чистая прибыль, маржа %, ROI %, средний чек
• 🧾 Ручной ввод расходов на рекламу и прочих операционных затрат
• 📈 Дашборд: сводка, waterfall-диаграмма «выручка → прибыль», график динамики, разбивка по товарам, лента заказов
• ⭐ Отзывы, быстрый калькулятор маржи по ссылке, накладные для Kaspi Доставки
• 🤖 Автобот снижения цены на Kaspi (честный способ через официальный XML-прайс-лист)
• ☁️ Развёртывание на Vercel бесплатно, база данных — Neon (serverless Postgres, тоже бесплатно)

Стек

Node.js + TypeScript + Express + Prisma ORM + PostgreSQL (Neon). Дашборд — статический HTML/CSS/JS (без сборки), график на Chart.js. Хостинг — Vercel (serverless-функции + статика), без Docker.

---

Часть 1. Как задеплоить на Vercel — пошагово для новичка

Понадобится: аккаунт на vercel.com (можно войти через GitHub) и аккаунт на neon.tech (тоже можно через GitHub). Оба — бесплатно, без карты.

Шаг 1. Выложи код на GitHub

Vercel разворачивает проекты из Git-репозитория, поэтому сначала код нужно загрузить на GitHub (если ещё не там).

1. Зайди на github.com → New repository → дай любое имя, например kaspi-ozon-unit-economics → Create repository.
2. Загрузи туда содержимое этого архива. Проще всего — через сайт GitHub: открой созданный репозиторий → Add file → Upload files → перетащи все файлы и папки из архива → Commit changes. (Если умеешь пользоваться git в терминале — можно и так, разницы нет.)

Шаг 2. Создай бесплатную базу данных на Neon

1. Зайди на neon.tech → Sign up (можно через GitHub) → Create a project.
2. Дай проекту любое имя (например kaspi-unit-economics), регион выбери ближайший к себе (например Europe), нажми Create project.
3. Neon сразу покажет строку подключения (Connection string) — она понадобится на следующем шаге. Открой вкладку Connection Details:
   • Найди переключатель "Pooled connection" — включи его, скопируй эту строку — это будет DATABASE_URL.
   • Выключи "Pooled connection" — скопируй строку без пулинга — это будет DIRECT_URL.
   • Обе строки выглядят примерно так: postgresql://user:[email protected]/neondb?sslmode=require (у "pooled" в адресе будет ещё -pooler перед .region).

Сохрани обе строки куда-нибудь рядом — они понадобятся через минуту.

Шаг 3. Импортируй проект в Vercel

1. Зайди на vercel.com → Add New… → Project.
2. Выбери Import рядом с твоим репозиторием kaspi-ozon-unit-economics (если не видно — нажми Adjust GitHub App Permissions и разреши доступ к репозиторию).
3. На экране настроек:
   • Framework Preset — оставь Other (или он определится сам, не важно).
   • Build and Output Settings — трогать не нужно, всё уже настроено в файле vercel.json внутри проекта.
4. Раскрой блок Environment Variables и добавь переменные — по одной, имя слева, значение справа (можно вставлять построчно через "Bulk Edit", если такая кнопка есть — тогда сразу вставь блок из .env.example, заполненный своими значениями):

Имя переменной	Что вписать
DATABASE_URL	"pooled" строка из Neon (шаг 2)
DIRECT_URL	строка без пулинга из Neon (шаг 2)
KASPI_API_TOKEN	токен из кабинета Kaspi (см. Часть 2 ниже)
KASPI_MERCHANT_UID	ваш merchant ID Kaspi
OZON_CLIENT_ID	Client-Id из кабинета Ozon
OZON_API_KEY	Api-Key из кабинета Ozon
WB_API_TOKEN	токен категории "Статистика" из кабинета Wildberries
PRICE_FEED_SECRET	придумайте любую длинную случайную строку
CRON_SECRET	придумайте ещё одну длинную случайную строку (другую)
KASPI_DEFAULT_DELIVERY_ZONE	kazakhstan (или city/express)

Площадки, которых у вас пока нет (например, ещё не продаёте на Ozon) — можно оставить пустыми или не добавлять вовсе, сервер просто пропустит их синхронизацию с предупреждением в логах, ничего не сломается.

5. Нажми Deploy. Подожди 1-2 минуты — Vercel соберёт проект (в том числе выполнит prisma generate и prisma migrate deploy, это уже прописано в vercel.json, ничего вручную запускать не нужно).

Шаг 4. Проверь, что всё работает

1. После деплоя Vercel покажет ссылку вида https://kaspi-ozon-unit-economics-xxxx.vercel.app. Открой её — должен открыться дашборд.
2. Проверь, что API отвечает: открой в браузере https://ваш-проект.vercel.app/api/health — должно показать {"ok":true,...}.
3. На дашборде нажми кнопки синхронизации (↻ Kaspi / ↻ Ozon / ↻ WB) — если токены вписаны верно, заказы подтянутся.

Если что-то не открылось — зайди в Vercel → твой проект → вкладка Deployments → открой последний деплой → Logs, там будет видна причина.

🛠 Если некоторые адреса (например /api/orders/meta, /api/sync/status, /api/margin-calculator/categories) отвечают 404, а другие (например /api/products) работают: это значит, что на Vercel сейчас лежит не полностью актуальная версия кода — скорее всего, в один из прошлых разов на GitHub были заменены не все файлы (например, только один-два файла точечно, а не весь проект целиком). Самое надёжное решение — не точечные правки, а полная замена всех файлов разом: удали всё содержимое репозитория на GitHub и загрузи архив заново целиком (см. Шаг 1 выше). Смешивание старых и новых файлов между собой — самая частая причина таких "частичных" поломок.

🛠 Если конкретно /api/cron/warm (или /api/cron/sync, /api/cron/reprice) отвечает 404, хотя остальной дашборд работает: в этой версии проекта у каждого cron-эндпоинта теперь свой отдельный файл (api/cron/warm.ts, api/cron/sync.ts, api/cron/reprice.ts) вместо одного общего catch-all файла [...slug].ts — у именных файлов в Vercel нет неоднозначности с маршрутизацией вложенных путей. Если после обновления 404 всё ещё появляется — почти наверняка на GitHub опять не дошли какие-то файлы: убедись, что в папке api/ на GitHub есть все четыре файла: [...slug].ts, cron/sync.ts, cron/reprice.ts, cron/warm.ts, и папка _lib/cronAuth.ts.

🛠 Если увидишь ошибку prisma: command not found (exit code 127) в Build Logs: с июля 2026 npm по умолчанию блокирует установочные скрипты пакетов (новая защита от вредоносных зависимостей). В этом проекте это уже исправлено — в package.json есть поле allowScripts, разрешающее нужные пакеты (prisma, @prisma/client, @prisma/engines, esbuild), а команда сборки в vercel.json использует npx prisma ... вместо голого prisma .... Если ошибка всё равно появится с другим пакетом — в логах будет фраза вида N packages have install scripts not yet covered by allowScripts со списком имён; добавь их в allowScripts в package.json ("имя-пакета": true) и задеплой заново.

🛠 Если увидишь ошибку No entrypoint found which imports express: Vercel иногда сам решает, что у вас «голое» Express-приложение (просто увидев express в зависимостях), и пытается сам найти файл-точку входа по стандартным именам — вместо того чтобы использовать нашу serverless- функцию api/[...slug].ts. В этом проекте это уже исправлено: в vercel.json явно прописано "framework": null, что отключает это авто-определение. Если ошибка всё же повторится — зайди в Vercel → твой проект → Settings → General → Framework Preset и вручную выбери Other, затем передеплой (Deployments → ⋯ → Redeploy).

🛠 Про алиасы путей (@/...) и ошибку Cannot find module: в исходном коде проекта больше вообще нет алиасов @/... — все импорты переписаны на обычные относительные пути (./utils/logger, ../services/sync.service и т.п.). Раньше алиасы использовались для удобства чтения кода, но Vercel не умеет надёжно разворачивать их при сборке TypeScript-функции "на лету", что приводило к падению всего API с ошибкой Cannot find module '@/...'. Теперь эта проблема невозможна структурно — убирать нечего. Плюс api/[...slug].ts по-прежнему подключает не сырые исходники из src/, а уже собранный JavaScript из dist/ (создаётся командой npm run build в buildCommand) — двойная защита от подобных ошибок.

🛠 Если увидишь ошибку Ошибка конфигурации .env в Runtime Logs: значит какая-то переменная окружения задана некорректно (лишний пробел, кавычки, опечатка). Для большинства настроек (типа KASPI_DEFAULT_DELIVERY_ZONE) сервер теперь сам аккуратно подставит значение по умолчанию вместо того, чтобы падать целиком — но для по-настоящему обязательных переменных (DATABASE_URL) ошибка всё равно покажется, это осознанно: без базы данных сервер работать не может. Текст ошибки в логах точно укажет, какая именно переменная не в порядке — проверь её в Vercel → Settings → Environment Variables.

🛠 Если запросы к /api/products и другим эндпоинтам, работающим с базой, зависают и возвращают 504 Gateway Timeout: классическая проблема связки Vercel (serverless) + Prisma + Neon — подключения к базе не переиспользовались между запросами и быстро исчерпывали маленький бесплатный лимит одновременных подключений Neon, из-за чего новые запросы зависали в ожидании свободного подключения. В этой версии проекта это уже исправлено в src/db/prisma.ts (подключение теперь всегда кэшируется, а не только в режиме разработки) — плюс сервер сам добавляет параметры pgbouncer=true&connection_limit=1 к DATABASE_URL, даже если их нет в самой переменной в Vercel. Ничего вручную менять не нужно. Если ошибка всё же повторится — проверь в Neon Dashboard, что используешь именно "pooled" строку подключения для DATABASE_URL (в адресе должно быть -pooler перед .region), а не "direct".

Шаг 5. Настрой автоматический запуск фоновых задач

Это самая важная часть, про которую нужно знать честно.

У Vercel на бесплатном тарифе встроенный Cron работает максимум 1 раз в сутки. Это ограничение Vercel, а не наше — на платном тарифе (Pro, $20/мес) можно чаще. В vercel.json уже настроены два ежедневных запуска "по умолчанию":

• /api/cron/sync — синхронизация заказов, раз в сутки в 03:00 UTC
• /api/cron/reprice — автобот цены на Kaspi, раз в сутки в 04:00 UTC

Это будет работать "из коробки" без каких-либо действий с твоей стороны — но раз в сутки для автобота цены маловато, если хочется, чтобы цена подстраивалась в течение дня. Чтобы это работало чаще — бесплатно, без перехода на платный тариф Vercel — используй внешний планировщик:

1. Зайди на cron-job.org → зарегистрируйся бесплатно.
2. Create cronjob:
   • Title: Kaspi/Ozon/WB sync
   • URL: https://ваш-проект.vercel.app/api/cron/sync?secret=ЗНАЧЕНИЕ_CRON_SECRET (подставь то же значение, что вписал в CRON_SECRET в Vercel)
   • Schedule: например, каждые 30 минут
   • Save.
3. Создай второй cronjob точно так же, но:
   • Title: Kaspi repricer
   • URL: https://ваш-проект.vercel.app/api/cron/reprice?secret=ЗНАЧЕНИЕ_CRON_SECRET
   • Schedule: например, каждые 15 минут
4. Создай третий cronjob — он важен для скорости работы сайта, не только для автобота:
   • Title: DB warmup
   • URL: https://ваш-проект.vercel.app/api/cron/warm?secret=ЗНАЧЕНИЕ_CRON_SECRET
   • Schedule: каждые 4 минуты
   • Зачем: бесплатная база Neon "засыпает" примерно через 5 минут простоя. Первый запрос после этого просыпается несколько секунд — вместе с холодным стартом самой функции на Vercel это может привести к ошибке 504 Gateway Timeout на обычных страницах сайта (например, при добавлении товара). Этот cronjob не даёт базе "засыпать", регулярно её "трогая" лёгким запросом, который ничего не делает — просто держит её в рабочем состоянии.

Готово — теперь синхронизация, автобот цены и "подогрев" базы данных будут запускаться сами по расписанию, полностью бесплатно, без Docker и без постоянно работающего сервера.

⚠️ Даже если настроить проверку каждую минуту — сам Kaspi обновляет цены на сайте по XML-прайс-листу примерно раз в час (это ограничение самого Kaspi, см. раздел про автобот ниже). Более частая проверка ускорит реакцию на изменение цен конкурентов, но не ускорит появление новой цены на сайте Kaspi быстрее, чем позволяет сам Kaspi.

🛠 Если запросы (например, добавление товара) всё равно иногда падают с 504 Gateway Timeout даже после настройки "подогрева": у Vercel Hobby (бесплатного) есть фактическое ограничение на время выполнения функции около 10 секунд — это ограничение платформы, не нашего кода, и оно не снимается настройками. Сочетание "холодный старт функции + Neon просыпается от простоя" иногда всё равно может упереться в это время при первом запросе после долгого простоя сайта. Если такое случается часто, а не изредка — единственный полный "снятие" ограничения — платный тариф Vercel Pro ($20/мес, лимит времени вырастает до 60 сек по умолчанию). Для личного использования с редкими заходами это обычно не требуется — "подогрев" из шага 4 закрывает проблему в большинстве случаев.

🛠 Если 504 продолжается даже после "подогрева" — как диагностировать по-настоящему (а не гадать):

1. Открой в браузере напрямую: https://ваш-проект.vercel.app/api/cron/warm?secret=ЗНАЧЕНИЕ_CRON_SECRET — должно быстро (за секунды) вернуть {"ok":true,"ms":...}. Если и этот простейший запрос висит или падает — проблема не в "холодном старте", а в самом подключении к базе (неверный DATABASE_URL, база на паузе/удалена, регион и т.п.).
2. Зайди в cron-job.org → открой созданный cronjob DB warmup → посмотри историю выполнений. Если там красные крестики (ошибки), а не зелёные галочки — "подогрев" не работает, и нужно чинить его настройку (неверный URL или секрет), а не сам сервер.
3. Zайди в Neon Dashboard → убедись, что проект не приостановлен/не удалён, и что используемая в DATABASE_URL строка — это именно "pooled" вариант (с -pooler в адресе).
4. После следующего деплоя открой Vercel → Logs и найди строки, начинающиеся с 🐢 [DB], ❌ [DB] или ⏱ ТАЙМАУТ — теперь сервер сам пишет в лог, сколько именно миллисекунд занял каждый запрос к базе, и что именно зависло. Эта информация — самая полезная для дальнейшей диагностики, если проблема не решится.

---

Часть 2. Как получить доступы к API

Kaspi.kz «Магазин»

Способ 1 (рекомендуется) — через интерфейс дашборда:

1. Зайдите в кабинет продавца на kaspi.kz → раздел Магазин на Kaspi.kz → Настройки → API → сгенерируйте токен (X-Auth-Token).
2. Откройте дашборд → Настройки → Магазин Kaspi → заполните форму «Добавить магазин» (название, БИН — необязательно, токен — обязательно) → Сохранить магазин.
3. Готово — токен сохраняется в базе данных и используется для всех запросов к Kaspi API. Это удобнее переменных окружения: не нужно передеплоивать сервер при смене токена.

Способ 2 — через переменные окружения (как раньше): впишите токен в KASPI_API_TOKEN в Environment Variables Vercel. Используется, только если магазин не добавлен через дашборд.

Подробная документация партнёра: https://guide.kaspi.kz/partner/ru/shop/api

✅ Комиссия и логистика Kaspi считаются автоматически. У Kaspi нет эндпоинта, который отдаёт размер удержанной комиссии по заказу напрямую — поэтому сервер считает её сам по официальной тарифной таблице Kaspi (src/integrations/kaspi.categories.ts, ставки по всем категориям 1-го уровня + точечные исключения для Аптеки/Аксессуаров/Телефонов/Товаров для животных) и тарифам Kaspi Доставки (src/integrations/kaspi.delivery.ts). Для точного расчёта укажите у каждого товара в разделе «Товары» его категорию Kaspi и вес — без этого комиссия по такому товару будет считаться нулевой, чтобы не искажать отчёт неверной ставкой.

⚠️ Честно про «синхронизацию каталога». У официального API Kaspi нет метода «отдай список всех моих товаров» — раздел «Товары» в Kaspi Гид содержит только методы добавления новых товаров, не чтения уже существующих. Поэтому кнопка «Синхронизировать каталог» на самом деле запускает синхронизацию заказов — а товары, которых ещё нет в базе, создаются автоматически по факту продажи (себестоимость по умолчанию 0, обязательно укажите её вручную). Это единственный честный способ получить каталог через официальный API, без логина в личный кабинет.

Ozon Seller API

1. Личный кабинет продавца Ozon → Настройки → Seller API.
2. Создайте API-ключ, скопируйте Client-Id и Api-Key.
3. Впишите их в Environment Variables Vercel как OZON_CLIENT_ID и OZON_API_KEY.
4. Документация: https://docs.ozon.ru/api/seller

Сервер получает заказы через /v3/posting/fbs/list и реальные удержания (комиссия, логистика, доп. услуги) через /v3/finance/transaction/list — это даёт фактические суммы, а не оценочные.

Wildberries Statistics API

1. Личный кабинет продавца → Профиль → Настройки → Доступ к API.
2. Создайте токен категории «Статистика» (не «Стандартный» — методы заказов и отчётов доступны только по нему).
3. Впишите его в Environment Variables Vercel как WB_API_TOKEN.
4. Документация: https://dev.wildberries.ru/en/docs/openapi/reports

⚠️ Устройство API у Wildberries заметно отличается от Kaspi/Ozon:

• Один заказ = одна строка = один товар (WB не группирует несколько товаров в один "заказ", как это делают Kaspi и Ozon).
• Статус заказа у WB здесь — упрощённый (NEW или CANCELLED): их Statistics API не отдаёт полный жизненный цикл заказа, в отличие от Kaspi.
• Комиссия и логистика берутся из отдельного отчёта о реализации (reportDetailByPeriod) и сопоставляются с заказами по полю srid. Свежие заказы могут попасть в этот отчёт не сразу — тогда комиссия по ним будет временно 0 и подтянется сама при следующей синхронизации.

---

Часть 3. Как пользоваться сервером

Как настроить себестоимость

Юнит-экономика считается только для товаров, у которых указана себестоимость.

Для ~1000 товаров — массовая загрузка (быстрее всего):

1. Раздел «Товары» → блок «Массовая загрузка (Excel/CSV)».
2. Подготовь файл (Excel .xlsx или .csv) с колонками:
   • sku — внутренний SKU (обязательно)
   • name — название товара (обязательно)
   • kaspiSku — артикул на Kaspi (для сопоставления с заказами)
   • costPrice — себестоимость
   • kaspiTopCategory — категория Kaspi, должна дословно совпадать с одним из значений выпадающего списка в форме добавления товара (например Электроника, а не электроника или Электроника )
3. Загрузи файл — сервер сам разберёт хоть тысячу строк, отправляя их партиями по 150 (чтобы не упереться в лимиты времени выполнения на Vercel). Товар с уже существующим SKU обновится (не задублируется), новый — создастся.
4. Названия колонок регистронезависимы (SKU, Sku, sku — не важно).

Для единичных товаров:

1. Откройте дашборд → раздел «Товары» → форма «Добавить товар».
2. Добавьте товар: внутренний SKU, название, себестоимость, а также артикул Kaspi, offer_id Ozon и/или артикул WB (supplierArticle) — это то, как товар называется на площадке (нужно для сопоставления при синхронизации заказов).
3. При следующей синхронизации заказы с этим SKU автоматически получат себестоимость.

Если товар ещё не заведён вручную — при синхронизации заказов Kaspi он создастся автоматически (себестоимость 0 по умолчанию — обязательно проставь её позже, иначе юнит-экономика будет считать нулевую себестоимость для таких товаров).

Автобот снижения цены на Kaspi

Сервер умеет автоматически следить за ценами конкурентов на карточке товара и подстраивать твою цену, чтобы быть первым в списке продавцов — но не дешевле заданной тобой минимальной цены. Работает только для Kaspi — для Ozon и Wildberries автобота нет и не планируется.

Как это работает:

1. При каждом запуске /api/cron/reprice (см. Часть 1, шаг 5) сервер читает публичную страницу товара на Kaspi и находит самую низкую цену конкурента.
2. Считает новую цену: цена конкурента минус небольшой шаг (repriceStep). Если эта цена ниже твоей minPrice — бот останавливается на minPrice и не уходит в убыток.
3. Новая цена сохраняется у товара и появляется в файле /api/kaspi/price-feed.xml.
4. Важно: Kaspi не даёт мгновенно обновить цену через API — только через XML-прайс-лист, который сам Kaspi проверяет по расписанию (обычно раз в час). Поэтому изменение цены на сайте применится не сразу, а с задержкой.

Как настроить:

1. В разделе «Автобот цены на Kaspi» на дашборде укажи для товара ссылку на его карточку на kaspi.kz, минимальную цену и шаг, включи бота.
2. Скопируй ссылку вида https://ваш-проект.vercel.app/api/kaspi/price-feed.xml?token=ЗНАЧЕНИЕ_PRICE_FEED_SECRET и один раз укажи её в кабинете Kaspi: Товары → Загрузить прайс-лист → автоматическая загрузка.

Честное предупреждение: чтение цен конкурентов идёт через обычную публичную страницу товара (так же, как её видит покупатель в браузере) — у Kaspi нет официального API "цены конкурентов" для продавцов, и хранение пароля от кабинета Kaspi нигде не используется. Разметка страницы может со временем измениться, тогда парсер в src/integrations/kaspi.scraper.ts нужно будет поправить.

Отзывы и быстрый калькулятор маржи

• Отзывы: сервер читает рейтинг и число отзывов с публичной страницы товара. Работает для товаров, у которых указана ссылка kaspiProductUrl.
• Быстрый калькулятор маржи: вставляешь ссылку на товар Kaspi → сервер подтягивает текущую цену → выбираешь категорию и вводишь себестоимость → сразу видишь комиссию, логистику, чистую прибыль и маржу.

Накладные для Kaspi Доставки

В списке «Последние заказы» есть действия для заказов Kaspi:

1. «Принять» — переводит новый заказ в статус ACCEPTED_BY_MERCHANT.
2. «Накладная» — переводит заказ в статус ASSEMBLE, указав количество мест.

Печатную накладную для курьера всё равно нужно скачать и распечатать в личном кабинете Kaspi — API отдаёт только смену статуса, не готовый PDF.

🛠 Если запросы к товарам/заказам падают с 500 (не 504!), а /api/cron/warm при этом отвечает быстро и успешно ({"ok":true}): дело не в скорости подключения к базе, а в том, что в самой базе данных физически нет нужных таблиц. Так бывает, если ни разу не была применена ни одна миграция — prisma migrate deploy просто нечего было применять (файлов миграций не было). В этой версии проекта такой файл уже есть (prisma/migrations/20260101000000_init/) — при следующем деплое он создаст все таблицы автоматически. Важно на будущее: если сам будешь менять schema.prisma (добавлять поля и т.п.) — для каждого такого изменения нужно создавать новый файл миграции, иначе Vercel не узнает, что нужно поменять в реальной базе. Локально это делается командой npm run prisma:migrate (см. Часть 4 ниже) — она подключается к базе, сравнивает её с schema.prisma и сама создаёт нужный SQL-файл; после этого файл нужно закоммитить вместе с остальными изменениями.

---

Часть 4. Локальная разработка (необязательно)

Если хочешь дорабатывать сервер у себя на компьютере перед тем, как заливать изменения на GitHub/Vercel:

npm install
cp .env.example .env
# впиши в .env те же DATABASE_URL/DIRECT_URL от Neon (можно тот же проект,
# что и для продакшена — Neon поддерживает несколько "веток" базы бесплатно)
npm run prisma:migrate
npm run dev

Дашборд откроется на http://localhost:3000. Фоновые задачи (синхронизация, автобот цены) в режиме npm run dev по-прежнему работают через встроенный планировщик (node-cron) — это удобно для локальных тестов. На самом Vercel эта часть не используется, там всё через /api/cron/*, см. Часть 1.

---

Структура проекта

kaspi-ozon-unit-economics/
  vercel.json                — конфигурация деплоя (cron, сборка, статика)
  api/
    [...slug].ts               — catch-all: весь дашборд (товары, заказы и т.д.) через Express
    cron/
      sync.ts                    — отдельный файл-маршрут: POST /api/cron/sync
      reprice.ts                  — отдельный файл-маршрут: POST /api/cron/reprice
      warm.ts                      — отдельный файл-маршрут: POST /api/cron/warm
    _lib/
      cronAuth.ts                   — общая проверка секрета (папка с "_" — не маршрут, служебный код)
  src/
    expressApp.ts                — Express-приложение (общее для локалки и Vercel)
    server.ts                     — точка входа ТОЛЬКО для локальной разработки
    cron/handlers.ts               — логика фоновых задач (синхронизация, репрайсер, прогрев БД)
    config/env.ts                   — загрузка и валидация .env
    db/prisma.ts                      — подключение к БД
    integrations/
      kaspi.client.ts                  — клиент Kaspi Shop API (заказы, статусы, накладные)
      kaspi.categories.ts               — справочник комиссий Kaspi по категориям
      kaspi.delivery.ts                  — тарифы Kaspi Доставки
      kaspi.scraper.ts                    — чтение цен конкурентов / рейтинга с публичной страницы
      ozon.client.ts                       — клиент Ozon Seller API
      wb.client.ts                          — клиент Wildberries Statistics API
    services/
      sync.service.ts                     — сохранение заказов в БД + расчёт комиссий/логистики
      analytics.service.ts                 — расчёт юнит-экономики
      repricer.service.ts                   — логика автобота снижения цены
    routes/                                  — REST API
    jobs/scheduler.ts                         — node-cron планировщик (только для локальной разработки)
  prisma/schema.prisma                          — модель данных (PostgreSQL)
  public/                                         — дашборд (index.html, styles.css, dashboard.js)

REST API

Метод	Путь	Описание
GET	/api/analytics/summary?from=&to=&marketplace=	Сводка юнит-экономики
GET	/api/analytics/by-product?from=&to=	Разбивка по товарам
GET	/api/analytics/timeseries?from=&to=&groupBy=day|week|month	Динамика по периодам
GET/POST/PUT/DELETE	/api/products	Товары и себестоимость
GET	/api/orders?from=&to=&marketplace=	Список заказов
GET/POST/DELETE	/api/expenses/ad-spend, /api/expenses/manual	Расходы на рекламу / прочее
POST	/api/sync/kaspi?days=7	Запустить синхронизацию Kaspi вручную
POST	/api/sync/ozon?days=7	Запустить синхронизацию Ozon вручную
POST	/api/sync/wb?days=7	Запустить синхронизацию Wildberries вручную
GET	/api/sync/logs	Журнал синхронизаций
GET	/api/kaspi/price-feed.xml?token=...	XML-прайс-лист для автообновления цен в кабинете Kaspi
POST	/api/cron/sync?secret=...	Фоновая синхронизация всех площадок (для внешнего планировщика)
POST	/api/cron/reprice?secret=...	Фоновый цикл автобота цены Kaspi (для внешнего планировщика)

---

Дальнейшие шаги, которые стоит продумать под ваш бизнес

• Уточнить формулу комиссии Kaspi под ваши товарные категории
• Добавить учёт возвратов/отмен отдельной строкой в юнит-экономике
• Добавить авторизацию в дашборд, если ссылка Vercel будет кому-то ещё известна
• Если вырастет число заказов/товаров — рассмотреть платный тариф Vercel Pro (более частый встроенный Cron, больше времени на выполнение функций)