Система движений и регистров

Назначение

Система движений — ядро складского учёта WMS. Каждое действие, влияющее на остатки, положение контейнеров, серийные номера или блокировки, порождает движения. Движения применяются к регистрам (числовым накопителям) и объектам (перемещаемым сущностям).

Вызывается из конвейера обработки документов на шаге 8 (BaseDocManager.saveInner → MovementManager.processDocument).

Базовые интерфейсы

Movement<C, O>                          — корневой интерфейс всех движений
 ├── RegistryMovement<C, O extends Registry>  — регистровые (изменение числовых значений)
 └── ObjectMovement<C, O extends MovableObject> — объектные (перемещение объектов)

Registry<C, O>                          — числовой регистр (координата → значения)
 ├── RegistryWithSplitter               — с поддержкой параллельных записей
 ├── RegistryWithHistory                — с историческими снимками
 └── RegistryWithGroupValidation        — с групповой валидацией

MovableObject<C, O>                     — перемещаемый объект (координата → объект)

Типы движений

Тип	Категория	Регистр/Объект	Назначение
`StorageRegistryMovement`	Registry	`StorageRegistry`	Остатки товара (quantity + reserved) на складских местах. Основной регистр. Поддерживает splitter и историю
`WorkflowRegistryMovement`	Registry	`WorkflowRegistry`	Товары/контейнеры в рабочих процессах. Отслеживание "в работе" по задачам. Поддерживает splitter
`ControlRegistryMovement`	Registry	`ControlRegistry`	Блокировка складских операций. Хранит флаг `blocked`. Максимально широкая координата
`ShipmentControlRegistryMovement`	Registry	`ShipmentControlRegistry`	Контроль этапов отгрузки по заказам. Поддерживает splitter
`ContainerMovement`	Object	`BaseContainer`	Перемещение контейнеров между местами
`SerialNumberMovement`	Object	`SerialNumber`	Перемещение серийных номеров (маркировка, ЧЗ)

Координаты

Координата — value-object, определяющий уникальную позицию в регистре. Имеет корректные equals/hashCode.

StorageRegistryCoordinate

Поле	Тип	Описание
`skuPackagingId`	UUID	Упаковка товара
`skuBatchId`	UUID	Партия
`condition`	Enum	Кондиция (годный, брак, карантин)
`warehouseSpace`	WarehouseSpace	Складское место
`sourceDocumentId`	UUID	Документ-источник

WorkflowRegistryCoordinate

Поле	Тип	Описание
`containerId`	UUID	Контейнер
`skuPackagingId`	UUID	Упаковка
`skuBatchId`	UUID	Партия
`condition`	Enum	Кондиция
`warehouseSpaceId`	UUID	Место
`workflowTaskId`	UUID	Задача workflow

ControlRegistryCoordinate

Максимально широкая координата — блокировка на любом уровне иерархии:

Поле	Описание
`skuId`	Конкретный товар
`merchantId`	Мерчант
`skuBatchId`	Партия
`skuCategoryId`	Категория товара
`containerId`	Контейнер
`warehouseSpaceId`	Складское место
`warehouseId`	Склад целиком
`warehouseZoneId`	Зона склада
`warehouseTopology`	Топология
`warehouseOperation`	Тип операции

ShipmentControlRegistryCoordinate

Поле	Описание
`orderDocId`	Заказ
`skuId`	Товар
`skuBatchId`	Партия
`containerId`	Контейнер
`stage`	Этап отгрузки (ShipmentStage)

ContainerCoordinate

Поле	Описание
`reserved`	Признак резервирования
`warehouseSpace`	Место размещения
`reservedForDocumentId`	Для какого документа

SerialNumberCoordinate

Поле	Описание
`condition`	Кондиция
`warehouseSpace`	Место размещения

Сервисы

Сервис	Роль
`MovementManager`	Центральный сервис. `processDocument` — извлекает движения из документов, обрабатывает по типам
`StockService`	Запросы складских остатков. Нативный SQL к `wms_storage_registry` с гибкой группировкой
`MovementScheduleManager`	Планировщик: исторические снимки, удаление незавершённых перемещений
`*MovementEntityService`	По одному на каждый тип движения: поиск, удаление, подготовка данных
`RegistryEntityService` / `MovableObjectEntityService`	По одному на каждый тип регистра/объекта

Алгоритм обработки (`MovementManager.processDocument`)

processDocument(documents, items)
  │
  ├─ 1. Сбор движений из GenerateMovements и HasItemsWithMovements
  │     (для удалённых документов движения не генерируются)
  │
  ├─ 2. Проверка блокировок (checkMovementIsNotBlocked)
  │     StorageRegistryMovement и ContainerMovement проверяются в ControlRegistry
  │     Исключение: полная инвентаризация игнорирует блокировки
  │
  ├─ 3. Последовательная обработка по типам (строгий порядок):
  │     ControlRegistryMovement      → первыми (предотвращение недопустимых операций)
  │     ContainerMovement            → перемещение контейнеров
  │     StorageRegistryMovement      → изменение остатков
  │     WorkflowRegistryMovement     → учёт в процессах
  │     SerialNumberMovement         → перемещение серийных номеров
  │     ShipmentControlRegistryMovement → контроль отгрузки
  │
  ├─ 4. Проверка резервов:
  │     • quantity >= reserved (по складу, типу зоны, товару, кондиции)
  │     • quantity >= reserved (по каждой корневой ячейке)
  │     • Ограничения на смешивание товаров/партий в ячейках
  │
  └─ 5. Публикация ContainerContentChangedEvent (если затронуты контейнеры)

Обработка регистровых движений (`processRegistryMovements`)

Загрузка старых движений документа из БД
Инвертирование старых движений (from↔to) для отмены предыдущей проводки
Сохранение новых движений в БД
Загрузка записей регистра по координатам (с SELECT ... FOR UPDATE для splitter-регистров)
Создание новых записей регистра, если не существуют (нулевые значения)
Для регистров с историей — создание снимков на каждый месяц в периоде
Применение apply() каждого движения ко всем подходящим временным срезам
Удаление пустых регистров (все значения = 0)
Групповая валидация: записи группируются по validationGroupHash, суммируются, проверяются на неотрицательность
Удаление старых движений из БД

Обработка объектных движений (`processObjectMovements`)

Аналогичная схема "отмена старых + применение новых":

Проверка на дублирование: один объект → одни координаты — несколько раз = ошибка
Оптимизация: идентичные движения (тот же объект, те же координаты) не перепроводятся
После применения — validateAll для проверки корректности

Механизм Splitter

Проблема: конкурентный доступ к одной координате регистра → конфликт блокировок.

Решение: при LockTimeoutException на SELECT ... FOR UPDATE:

Инкрементируется значение splitter
Попытка заблокировать запись с новым splitter
Если записи нет — создаётся новая
Несколько потоков модифицируют один регистр через разные строки
При валидации — строки с одной координатой, но разными splitter, суммируются

Исторические снимки

Для StorageRegistry ведутся снимки на начало каждого месяца:

Запись с dateTime = null — актуальное значение
Запись с конкретным dateTime — снимок на начало месяца
MovementScheduleManager ежедневно создаёт снимки на следующий месяц
При движении с датой в прошлом — создаются недостающие промежуточные снимки

Генерация движений в документах

Документы и позиции реализуют интерфейс GenerateMovements:

getMovements() — список движений, определяемых состоянием документа
getMovementTypes() — набор поддерживаемых классов движений

Для документов с позициями — HasItemsWithMovements.getMovementsFromItems() агрегирует движения из всех неудалённых позиций.

Особенности

Идемпотентность: При повторном сохранении старые движения полностью откатываются, новые проводятся заново
Двойная проводка: Регистровое движение с обеими координатами вычитает из "откуда" и прибавляет к "куда"
Retry: ConstraintViolationException → DataIntegrityViolationException → перехват @RetryIfOptimisticLock
Каскадное обновление контейнеров: ContainerContentChangedEvent → обновление агрегатов SkuItems

Система движений и регистров

Назначение​

Базовые интерфейсы​

Типы движений​

Координаты​

StorageRegistryCoordinate​

WorkflowRegistryCoordinate​

ControlRegistryCoordinate​

ShipmentControlRegistryCoordinate​

ContainerCoordinate​

SerialNumberCoordinate​

Сервисы​

Алгоритм обработки (MovementManager.processDocument)​

Обработка регистровых движений (processRegistryMovements)​

Обработка объектных движений (processObjectMovements)​

Механизм Splitter​

Исторические снимки​

Генерация движений в документах​

Особенности​