Обзор архитектуры
«Оптима» — сервис единого окна для селлеров Wildberries. Продукт живёт в одном монорепозитории и состоит из четырёх развёртываемых приложений:
| Приложение | Каталог | Стек | Домен (prod) |
|---|---|---|---|
| Веб-приложение | frontend/ | Next.js 16 (App Router), React 19, TanStack Query | https://app.optimawb.ru |
| API | backend/ | NestJS 11 (TypeScript), модульный монолит, PostgreSQL 16 + pgvector, Redis, BullMQ | https://api.optimawb.ru |
| Лендинг | landing/ | Vite + React 19, статическая сборка за nginx | https://optimawb.ru |
| Портал документации | docs-site/ | Docusaurus + Compodoc бэкенда, статика за nginx | https://docs.optimawb.ru |
Все приложения разворачиваются в Coolify на VPS заказчика; PostgreSQL и Redis — управляемые сервисы Coolify. Подробнее — Развёртывание.
Контекстная диаграмма
Ключевые свойства:
- Один бэкенд-процесс обслуживает и HTTP API, и фоновые воркеры BullMQ, и планировщик расписаний (см. Бэкенд, Фоновые задачи).
- Браузер ходит только в API
api.optimawb.ru; в Wildberries и к LLM-провайдеру обращается исключительно бэкенд. Токены кабинетов WB хранятся зашифрованными (AES-256-GCM, см. Безопасность). - Redis используется в трёх ролях: кэш (
CacheService), общие счётчики (rate-limiter WB, лимитер входящих запросов, суточная квота LLM, per-account gate) и брокер очередей BullMQ (на выделенных соединениях). - Контракт API — OpenAPI (
backend/openapi.json, Swagger UI/api/docs); фронтенд генерирует из него типизированный клиент (npm run api:generate).
Фундаментные подсистемы (F1–F8)
Фундамент — эпики Jira, на которые опираются все функциональные модули.
| Эпик | Назначение | Где в коде |
|---|---|---|
| F1 | Платформа и каркас: конфиг, ошибки, валидация, пагинация, health, Swagger | backend/src/core/{config,errors,validation,pagination}, src/health, src/swagger.ts |
| F2 | Аутентификация, RBAC, кабинеты WB, доступ на уровне бренда | modules/auth, modules/users, modules/wb-accounts, modules/brand-access, core/crypto, core/security |
| F3 | Ядро интеграции с WB: API-клиент, лимиты, ретраи, ошибки | modules/wb-api |
| F4 | Платформа данных: схема, миграции, базовые сущности, кэш, партиции, пересчёт агрегатов | core/database, core/redis, core/cache, core/partitioning, core/re-aggregate, modules/catalog |
| F5 | Фоновые задачи и планировщик | core/queue, core/schedule |
| F6 | Логирование, метрики, аудит | core/observability, core/metrics, core/queue-observability, modules/audit-log |
| F7 | Общий слой LLM: провайдер, промпты, RAG | modules/llm, modules/prompt-templates, modules/rag |
| F8 | DevOps: Docker, окружения, CI/CD, секреты | */Dockerfile, docker-compose.yml, .github/workflows/ |
Карта функциональных модулей (ТЗ 5.1–5.15)
| ТЗ | Модуль | Модуль бэкенда (backend/src/modules/…) | Раздел UI (/app/wb/:accountId/…) |
|---|---|---|---|
| 5.1 | Оцифровка продаж и финансовый учёт | digitization | digitization |
| 5.2 | Управление ценами и скидками | pricing (+ общий каталог catalog) | prices |
| 5.3 | Репрайсер | repricer | repricer |
| 5.4 | Автобиддер | autobidder | autobidder |
| 5.5 | Автоответы на отзывы и вопросы, жалобы | autoreply | auto-replies |
| 5.6 | РНП | rnp | rnp |
| 5.7 | Бухгалтерия | accounting | accounting |
| 5.8 | Бронировщик поставок | booking (+ notifications) | slot-booker |
| 5.9 | ИИ-помощник | ai-assistant | ai-assistant |
| 5.10 | ИИ-агент (маркетолог) | ai-agent | ai-agent |
| 5.11 | Товарный учёт | inventory (+ синк карточек в catalog) | inventory |
| 5.12 | Юридический блок (досудебные претензии) | legal | legal |
| 5.13 | Генерация контента | content | content-generation |
| 5.14 | A/B-тестирование | ab-test | ab-testing |
| 5.15 | База знаний | knowledge-base | knowledge-base |
Бизнес-описание каждого модуля — в разделе Возможности.
Разделы архитектуры
- Бэкенд — модульный монолит, список модулей, конвенции, глобальный конвейер.
- Данные — PostgreSQL, миграции, партиции, pgvector, Redis-кэш, основные таблицы.
- Фоновые задачи — все очереди BullMQ и расписания, конкурентность, gate кабинета.
- Интеграция с Wildberries — клиент WB API, token-bucket, 429, ретраи, таймауты.
- ИИ-подсистема — LLM-провайдер, лимиты расхода, RAG, защита от prompt injection.
- Безопасность — аутентификация, сессии, RBAC, шифрование, аудит.
- Наблюдаемость — логи, correlation-id, метрики Prometheus, health-checks.
- Фронтенд — app shell, маршруты, навигация, API-клиент, сессия.
- Развёртывание — окружения, Coolify, GHCR, GitHub Actions.
См. также: журнал архитектурных решений (ADR), справочник API, документация кода — Compodoc.