PlanSupply — документация

1. Назначение системы

PlanSupply обеспечивает единый контур планирования для ритейла:

мастер-данные и сеть поставок → ассортимент → прогноз спроса → поставки и запасы → финансы.

Бизнес-цели

Повышение точности прогноза, снижение избыточных запасов, ускорение решений через консенсус-план, адаптация ассортимента под локальный спрос.

Горизонты планирования

Оперативный IBP — 3 мес. (неделя); ассортимент — 12 мес.; demand/supply — 1–12 нед. с настраиваемой дискретностью.

Демо-стенд на plansupply.softverno.ru/demo — упрощённый контур для оценки UI и API. Промышленная установка включает полный стек (Kafka, ClickHouse, Keycloak, ML-workers).

2. Функциональные модули

Модуль	Назначение	Ключевые возможности
MDM / Сеть поставок	Мастер-данные и логистическая сеть	Товары, локации, вендоры, матрица, сорсинг-правила, графики поставок, версионность МД
Ассортимент (TP)	Тактическое планирование полки	Кластеры, квоты, наполнение, планограммы, ротация, оптимизация по EBITDA
Спрос (DP)	Прогнозирование	ML-прогноз, cleansing, промо, consensus, what-if, метрики WAPE/bias
Поставки (SP)	Пополнение и заказы	Политики WOS/min-max, потребности, заказы, перемещения, OTB, резервирование
Финансы (FP)	Монетизация планов	P&L, EBITDA, FCF, бюджеты промо, синхронизация с ERP
Аналитика (AN)	Отчётность и ad-hoc	План-факт, heatmap WOS/дефицита, экспорт CSV/XLSX/PDF, push в BI
Коллаборация	Согласование	Задачи, комментарии, workflow, версионность планов
Интеграции (INT)	Обмен с внешними системами	POS, WMS, OMS, ERP, MDM; импорт CSV; Kafka/outbox
Расширяемость (AR)	Кастомизация	Meta-поля, плагины алгоритмов, внешние ML-модели

3. Архитектура

3.1. Контекст (C4 Level 1)

Платформа — система планирования и согласования. Исполнение заказов и учёт остатков остаются во внешних OMS/WMS/ERP; PlanSupply публикует планы и получает факты.

Планировщики · Категорийные менеджеры · Закупки · Финансы │ ▼ ┌─────────────────────┐ │ PlanSupply IBP │ └─────────┬───────────┘ ┌───────────────────┼───────────────────┐ ▼ ▼ ▼ POS/WMS OMS/ERP MDM/BI (продажи, (заказы, (справочники, остатки) учёт) отчётность)

3.2. Контейнеры (C4 Level 2)

React UI (AG Grid + ECharts) │ ▼ API Gateway + Keycloak (OIDC) │ ┌─────────┼─────────┬─────────┬─────────┐ ▼ ▼ ▼ ▼ ▼ MDM Assortment Demand Supply Finance │ │ │ │ │ └─────────┴────┬────┴────┬────┴─────────┘ ▼ ▼ PostgreSQL ClickHouse │ Kafka (шина событий) │ ML-workers · Optimizer · Temporal

3.3. Принципы

Plan-as-data — каждый расчёт и корректировка порождают версию; публикация — отдельный статус.
OLTP / OLAP / Compute — PostgreSQL (транзакции), ClickHouse (факты и метрики), Ray/Temporal (пересчёт).
Integration bus — канонические события показателей; адаптеры не протекают во внутреннюю модель.
Инкрементальный пересчёт — dirty partitions по категории/региону вместо полного cartesian grid.
RBAC + audit — мутации с автором, причиной и неизменяемым журналом.

4. Технологический стек

Слой	Технология	Назначение
Frontend	React 19 + TypeScript + Vite	Planning workbench, админка МД
UI-компоненты	AG Grid, Apache ECharts	Таблицы планирования, графики, heatmap
Backend API	Kotlin 2.x + Spring Boot 3.3+	Domain services, REST/OpenAPI, транзакции
ML / optimize	Python 3.12 + FastAPI	Модели прогноза, квантили, OR-Tools
Оркестрация	Ray + Temporal	Партиционный inference, пайплайны cleanse→forecast→publish
OLTP	PostgreSQL 16 + Flyway	МД, планы, заказы, workflow, audit
OLAP	ClickHouse 24+	Факты sales/stock, WAPE, ad-hoc аналитика
Cache	Redis 7	UI-prefs, distributed locks, кэш справочников
Event bus	Apache Kafka 3.7+	Интеграционная шина, outbox, CDC
Auth	Keycloak (OIDC)	SSO, RBAC по region/category/channel
Object storage	S3 / MinIO	Модели ML, экспорты, файловые импорты
Observability	OpenTelemetry + Prometheus + Grafana	Метрики SLA, трассировка job'ов
Runtime	Kubernetes + Helm / Docker Compose	Prod / dev / demo окружения

5. Системные требования

5.1. Промышленная установка (production, ориентир)

Компонент	Минимум	Рекомендуется
API-сервисы (K8s)	3 nodes × 4 vCPU, 16 GB RAM	5+ nodes, HPA по нагрузке
PostgreSQL	8 vCPU, 32 GB RAM, SSD 500 GB	Primary + replica, Multi-AZ
ClickHouse	8 vCPU, 32 GB RAM, SSD 1 TB	3-node cluster
Kafka	3 brokers × 4 vCPU, 16 GB	SSD, replication factor 3
Redis	2 vCPU, 8 GB RAM	Sentinel / managed Redis
ML-workers	4 vCPU, 16 GB RAM (× N workers)	Auto-scale по очереди задач
Keycloak	2 vCPU, 4 GB RAM	HA pair + внешняя БД

5.2. Демо-стенд (Softverno)

Компонент	Конфигурация
Сервер	1 VM: 4 vCPU, 8 GB RAM, 40 GB SSD
Контейнеры	PostgreSQL 16 + Spring Boot API (монолит mdm-service)
Frontend	Static SPA (Nginx)
Auth	Local JWT
Отключено	Kafka, ClickHouse, Redis, Temporal, ML-workers, Keycloak

5.3. Клиентское рабочее место

Браузер: Chrome 120+, Firefox 120+, Safari 17+, Edge 120+
Разрешение экрана: от 1366×768 (рекомендуется 1920×1080+)
Сеть: HTTPS, latency < 100 ms до API; для BI-export — доступ к ClickHouse/Qlik

5.4. Программное обеспечение (сборка из исходников)

JDK 17+, Gradle 8+
Node.js 20+, npm 10+
Docker 24+ / Docker Compose v2
Python 3.12+ (для ML-workers, опционально)

6. Интеграции

PlanSupply обменивается данными с корпоративным ландшафтом через REST API, файловый импорт и шину событий Kafka.

Система	Направление	Данные
POS	→ PlanSupply	sales_units, sales_revenue (SKU × Location × Day)
WMS	↔ PlanSupply	stock_on_hand, transfers, receipts
OMS (SAP)	↔ PlanSupply	open_order_qty, order_status; push/pull заказов
ERP	↔ PlanSupply	cost, price, P&L sync
MDM	→ PlanSupply	Product, Location, Vendor, hierarchy
BI (Qlik и др.)	← PlanSupply	Export CSV/XLSX/PDF, push schema/events

Канонические Kafka-топики (примеры): int.facts.sales, int.facts.stock, plan.demand.published, plan.supply.published.

Файловый импорт из коробки: CSV (products, locations, matrix, sales, stock) через POST /api/v1/integrations/file-imports.

7. Нефункциональные требования и SLA

ID	Требование	Целевое значение
NF01	Время полного пересчёта прогноза	10 000 SKU × 2 500 магазинов ≤ 15 мин
NF02	Доступность	24×7, RTO ≤ 4 часа
NF03	Масштабирование	Горизонтальное (stateless API, Kafka consumers, HPA workers)
NF04	Безопасность	OIDC, RBAC, immutable audit log
NF05	API	OpenAPI 3, webhooks статусов планов и заказов

8. Безопасность

Аутентификация: OIDC через Keycloak (корпоративный IdP / LDAP federation).
Авторизация: роли (Demand Planner, Assortment Manager, Buyer, Finance, Admin) × scope (region, category, channel).
Audit: все мутации планов и МД — user_id, timestamp, reason_code, snapshot ref.
Секреты интеграций: Vault / cloud secret manager; TLS для всех внешних соединений.
PII: минимизация и маскирование соцдем-атрибутов магазинов в UI.

На демо-стенде используется упрощённая local JWT-аутентификация. Для production обязателен Keycloak и корпоративный IdP.

9. Развёртывание

9.1. Демо (Softverno)

URL: plansupply.softverno.ru/demo
API: /demo/api/v1/, Swagger: /demo/swagger-ui
Стек: Docker Compose (PostgreSQL + Spring Boot JAR + Nginx static)

9.2. Production (целевой контур)

Kubernetes namespace с Helm charts для каждого domain-service
Managed PostgreSQL + ClickHouse cluster + Kafka (3 brokers min)
Keycloak realm, OIDC для UI и API Gateway
CI/CD: GitHub Actions / GitLab CI → container registry → K8s rollout
Observability: Prometheus metrics, Grafana dashboards, Loki logs, OpenTelemetry traces

9.3. Локальная разработка

export JAVA_HOME=/opt/homebrew/opt/openjdk@17
cd services/mdm-service && ./gradlew bootRun

# другой терминал
cd apps/planning-web && npm run dev
# UI: http://localhost:5173

10. Дорожная карта внедрения on-premise

Для заказчиков, планирующих установку PlanSupply в собственном контуре (on-premise / private cloud), подготовлена дорожная карта внедрения: этапы 0–6, календарный план, требования к инфраструктуре, интеграции, RACI, риски и критерии go-live.

Срок типового проекта: 40–56 дней · Объём: до 10 000 SKU × 2 500 магазинов

Скачать PDF Открыть HTML-версию

11. Входные требования к заказчику

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