Конвейер обработки документов

Назначение

Все документы WMS (33 типа) проходят через единый конвейер обработки при создании, обновлении и удалении. Конвейер гарантирует: валидацию, формирование движений по регистрам, ведение истории статусов и публикацию событий.

Ключевые классы

Базовые абстракции

Класс	Пакет	Роль
BaseDoc	model.entity.document	Абстрактная JPA-сущность, базовый класс всех документов. Таблица wms_doc_base, наследование JOINED, дискриминатор по полю type
BaseDocItem	model.entity.document	Абстрактная JPA-сущность позиций документов. Таблица wms_doc_base_item, наследование JOINED
BaseDocManager<D, S, ES>	service.entity.document	Абстрактный менеджер документа. Содержит конвейер обработки
BaseDocItemManager<I, D, S, ES>	service.entity.document	Абстрактный менеджер позиции документа
DocManager	service.entity	Реестр всех менеджеров. Универсальная точка входа save(document, modifiers)

Сервисы доступа к данным

Класс	Роль
BaseDocEntityService<D, S, R>	Сервис данных документа. save/delete заблокированы — бросают IllegalStateException. Сохранение только через менеджер
BaseDocItemEntityService<I, D, S, R>	Аналогично для позиций
DocStatusHistoryEntityService	Сервис истории статусов

Поля BaseDoc

Основные поля, доступные у всех документов:

Поле	Тип	Описание
humanId	String	Уникальный читаемый идентификатор (генерируется HumanIdGenerator)
externalId	String	Внешний идентификатор (из ERP или Merchant API)
date	LocalDate	Дата документа
status	String	Строка, маппится на enum конкретного документа
merchant	Merchant	Мерчант (мультитенантность)
warehouse	Warehouse	Склад
employee	Employee	Ответственный сотрудник
workspace	WarehouseWorkspace	Рабочее пространство
parent	BaseDoc	Ссылка на родительский документ
isDeleted	Boolean	Мягкое удаление

Конвейер сохранения (BaseDocManager.saveInner)

save(document, modifiers)
  │
  ├─ 1.  beforeSave()                    — hook: подготовка перед сохранением
  ├─ 2.  Фиксация изменений              — извлечение карты изменённых полей из EntityChanges
  ├─ 3.  validate()                       — валидация документа
  ├─ 4.  validateItems()                  — валидация позиций
  ├─ 5.  saveToDB()                       — первичное сохранение (flush для новых документов)
  ├─ 6.  validateRelatedDocuments()       — валидация связанных документов
  ├─ 7.  updateAdditionalItems()          — обновление доп. позиций (SkuItems и т.п.)
  ├─ 8.  processMovements()               — MovementManager: проводки по регистрам
  ├─ 9.  additionalBusinessLogic()        — hook: доп. бизнес-логика
  ├─ 10. processStatusHistory()           — запись истории статуса + DocStatusChangedEvent
  ├─ 11. validateAfterProcessing()        — финальная валидация
  ├─ 12. publishEvent()                   — BaseDocSavedEvent
  ├─ 13. afterAllSaved()                  — пост-обработка (пул серийных номеров)
  └─ 14. Сохранение snapshot полей        — changes.saveValues для следующего сравнения

Hook-методы для переопределения

Метод	Когда переопределять
beforeSave()	Подготовка данных, установка значений по умолчанию
validate()	Бизнес-валидация документа
validateItems()	Валидация позиций
validateRelatedDocuments()	Проверка связанных документов
updateAdditionalItems()	Обновление SkuItems, серийных номеров
additionalBusinessLogic()	Основная бизнес-логика. Если возвращает true — повторное сохранение в БД
createDocSavedEvent()	Создание типизированного события

Модификаторы обработки (ProcessingModifier)

Enum ProcessingModifier позволяет тонко управлять поведением конвейера:

Модификатор	Действие
FORCE_MOVEMENTS_PROCESSING	Принудительная обработка движений
DISABLE_MOVEMENTS_PROCESSING	Пропуск обработки движений
DISABLE_BUSINESS_LOGIC	Пропуск additionalBusinessLogic
DISABLE_ADDITIONAL_ITEMS_UPDATE	Пропуск updateAdditionalItems
DISABLE_PUBLISH_EVENT	Пропуск публикации события
POSTPONE_RELATED_DOCS_VALIDATION	Отложенная валидация связанных документов

Взаимоисключающие модификаторы (FORCE + DISABLE для одного шага) вызывают IllegalArgumentException.

Массовое сохранение (saveAll)

При сохранении коллекции документов оптимизация:

1. Все документы проходят через saveInner с DISABLE_MOVEMENTS_PROCESSING + DISABLE_PUBLISH_EVENT
2. Движения обрабатываются одним вызовом movementManager.processDocument для всей коллекции
3. События публикуются в конце

Защита от рекурсии

ThreadLocal<Map<D, Integer>> saveCounter — подсчёт вложенных вызовов save для одного документа. При превышении лимита (wms.docs.nested-save-limit) — DocumentProcessingException.

Транзакционность

Метод save оборачивает saveInner в TransactionTemplate с PROPAGATION_REQUIRED. При исключении транзакция маркируется для отката.

Автоматическая регистрация менеджеров

DocManager при старте приложения:

1. Сканирует classpath пакета service.entity.document
2. Находит все конкретные (не абстрактные) наследники BaseDocManager и BaseDocItemManager
3. Строит маппинг Class → Manager
4. Предоставляет save(document, modifiers) — делегирует нужному менеджеру по типу

Таблица типов документов

DocumentType	Класс	Название	Назначение
ADDITIONAL_PROCESSING	AdditionalProcessingDoc	Доп. обработка	Маркировка, стикеровка
BUNDLE	BundleDoc	Обработанный набор	Результат сборки набора
BUNDLE_ORDER	BundleOrderDoc	Заказ на обработку набора	Заказ на сборку набора
BUNDLE_ORDER_BATCH	BundleOrderBatchDoc	Батч наборов	Группа заказов на наборы
CHANGE_STOCK	ChangeStockDoc	Изменение остатков	Корректировка остатков
INVENTORY	InventoryDoc	Инвентаризация	Управляющий документ
INVENTORY_DISCREPANCY	InventoryDiscrepancyDoc	КТО	Расхождения
INVENTORY_FACT	InventoryFactDoc	Инвентаризация, факт	Фактические данные
INVENTORY_PLAN	InventoryPlanDoc	Инвентаризация, план	Плановые данные
LOADING	LoadingDoc	Погрузка	Погрузка в ТС
MOVEMENT	MovementDoc	Перемещение	Внутрискладское перемещение
MOVEMENT_CONTROL	MovementControlDoc	Блокировка	Блокировка операций
NON_CONFORMANCE	NonConformanceDoc	Несоответствия	Фиксация брака/потерь
ORDER	OrderDoc	Заказ	Заказ на отгрузку
ORDER_BATCH	OrderBatchDoc	Батч	Группа заказов
ORDER_PACKING	OrderPackingDoc	Упаковка заказа	Обработка на рабочем месте
PACKAGING_UNIT	PackagingUnitDoc	Грузовое место	Коробка/паллет с товарами
PICKING	PickingDoc	Отбор	Отбор с хранения
PLACING	PlacingDoc	Размещение	Размещение на хранение
PRODUCT_QUALITY_LAB_CONTROL	ProductQualityLabControlDoc	Лабораторный контроль	Лабораторная проверка
PRODUCT_QUALITY_VISUAL_CONTROL	ProductQualityVisualControlDoc	Визуальный контроль	Визуальная проверка
RECEIPT	ReceiptDoc	Приходный ордер	Фактическая приёмка
REPLENISHMENT	ReplenishmentDoc	Подпитка	Пополнение зон отбора
RETURNING	ReturningDoc	Возврат	Приёмка возвратов
RETURNING_ORDER	ReturningOrderDoc	Возврат заказа	Возврат по заказу
SERIAL_NUMBER_GENERATION	SerialNumberGenerationDoc	Эмиссия серийных номеров	Генерация серийных номеров
SKU_PACKAGING_UNPACKING	SkuPackagingUnpackingDoc	Распаковка	Разбор заводских упаковок
SORTING	SortingDoc	Сортировка	Сортировка по заказам
SUPPLY	SupplyDoc	Поставка	Ожидаемая поставка
TRANSPORTATION	TransportationDoc	Перевозка	Перевозка груза
TRANSPORT_RUN	TransportRunDoc	Рейс	Рейс ТС
TRANSPORT_UNIT	TransportUnitDoc	Транспортное место	Группа грузовых мест
UNLOADING	UnloadingDoc	Разгрузка	Разгрузка ТС
WORKFLOW_PLAN	WorkflowPlanDoc	План обработки	Маршрут контейнера

Иерархия документов

Документы связаны в дерево через поле parent:

SupplyDoc
 └── ReceiptDoc
      └── PlacingDoc

OrderBatchDoc
 ├── PickingDoc
 ├── SortingDoc
 └── OrderDoc
      └── OrderPackingDoc
           └── PackagingUnitDoc
                └── TransportUnitDoc
                     └── LoadingDoc

InventoryDoc
 ├── InventoryPlanDoc
 └── InventoryFactDoc
      └── InventoryDiscrepancyDoc

BundleOrderBatchDoc
 └── BundleOrderDoc
      └── BundleDoc

Кэширование: DocCacheWrapper (родитель) и DocChildrenCacheWrapper (дочерние) минимизируют запросы к БД.