Анализ: wms-autodoc (бизнес) vs реальная кодовая база WMS
Дата анализа: 2026-03-27
Версия WMS: Spring Boot 3.4.2, Java 21
Источники: кодовая база wms, бизнес-документация wms-autodoc (Docusaurus)
1. Концепция: два контура документации
wms-autodoc — бизнес-документация
Аудитория: операторы склада, менеджеры, бизнес-аналитики, интеграторы (Merchant API). Цель: описать ЧТО делает система, КАК с ней работать, КАКИЕ процессы автоматизирует. Формат: Docusaurus-сайт, русский язык, Mermaid-диаграммы, сценарии, роли.
wms/docs/ — техническая документация
Аудитория: разработчики, архитекторы, DevOps. Цель: описать КАК система устроена внутри, какие паттерны и абстракции используются, как добавлять новый функционал. Формат: Markdown в репозитории, привязка к коду, примеры классов и API.
Принцип разделения: бизнес-документация не должна содержать имён классов, пакетов, технических деталей реализации. Техническая документация не должна дублировать бизнес-сценарии и описания ролей. Но обе должны быть фактически корректны — описывать одну и ту же систему с разных ракурсов.
2. Анализ wms-autodoc: фактические несоответствия коду
Ниже — ошибки и расхождения в бизнес-документации, которые нужно исправить, не меняя бизнес-стиль документов.
2.1 Типы документов — пропущены 6 типов
autodoc описывает ~27 типов документов. В реальной системе их 33. Следующие типы отсутствуют в бизнес-документации и должны быть добавлены:
| Тип документа | Бизнес-название | Что нужно описать |
|---|---|---|
| Доп. обработка | Дополнительная обработка | Маркировка, стикеровка, переупаковка товаров |
| Документ несоответствий | Акт несоответствий | Фиксация брака и потерь при операциях |
| Эмиссия серийных номеров | Генерация серийных номеров | Выпуск серийных номеров / честный знак |
| Распаковка упаковок | Распаковка | Разбор заводских упаковок на единицы товара |
| План обработки контейнера | План обработки | Маршрут контейнера через рабочие места |
| Рейс | Рейс транспорта | Объединение перевозок в один рейс |
2.2 Некорректные/устаревшие названия
| Что в autodoc | Как в системе | Рекомендация |
|---|---|---|
| "Визуальный контроль" (один документ) | Разделён на 2: Визуальный контроль + Лабораторный контроль | Описать оба типа отдельно |
| "Cargo Place" (англ. название) | Грузовое место (PackagingUnit) | Привести к единому русскому названию |
| "Batch Sets" (англ. название) | Батч наборов (BundleOrderBatch) | Привести к единому русскому названию |
| ЧЗ (Честный знак) помечен "under redesign" | В коде реализован и работает | Убрать пометку, описать актуальный процесс |
2.3 Merchant API — расхождения с реальностью
Верно описаны (7 групп):
- Склады, Контрагенты, Службы доставки, Договоры доставки, Товары (SKU), Поставки, Заказы
Отсут ствуют в autodoc, но есть в API:
- Возвраты (
/merchant-api/returning) — полный цикл возврата товаров - Перемещения (
/merchant-api/movement) — движения товаров - Отгрузка/доставка (
/merchant-api/delivery) — информация о доставке - Наборы (
/merchant-api/bundle) — комплектация - Статусы поставок — неполное описание жизненного цикла (в коде больше статусов)
Конкретные фактические ошибки:
- Base URL
http://wms-api.dev.sigmation.ai/— нужно проверить актуальность - Статусы поставки: в autodoc 5 статусов (NEW, AWAITING_RECEIPT, RECEIVING, RECEIVED, DONE), в коде может быть больше — нужна сверка с enum
2.4 Справочники — неполный список
autodoc перечисляет 6 групп справочников. Пропущены:
- Типы упаковки товара (SkuPackaging) — критически важный справочник для операций
- Партии товара (SkuBatch) — учёт по партиям, срокам годности
- Кондиции товара — состояние товара (годный, брак, карантин)
- Типы контейнеров — вложенность, допустимые зоны
- Рабочие пространства (Workspace) — логические зоны работы сотрудников
- Типы зон склада — хранение, отбор, приёмка, отгрузка и т.д.
- Правила размещения — алгоритмы выбора ячеек
2.5 АРМы — фактические пробелы
Отсутствующие АРМы (есть в системе, нет в документации):
- АРМ дополнительной обработки (маркировка, стикеровка)
- АРМ управления транспортными местами
- АРМ мониторинга заказов (OrderMonitoring)
- АРМ управления контейнерами
Описанные АРМы с неполными сценариями:
- Отбор (picking) — не описаны алгоритмы формирования маршрута, работа с контейнерами
- Упаковка (packing) — не описан процесс формирования грузовых мест
- Сортировка — не описана связь с батчами и контейнерами
- Подпитка — не о писаны правила автоматического запуска
2.6 Отчёты — ссылки вместо содержания
Отчёты описаны списком со ссылками на Google Sheets. Проблемы:
- Внешние ссылки могут стать недоступны
- Нет описания параметров фильтрации
- Нет описания бизнес-смысла показателей
- Нет примеров использования отчётов
2.7 Интеграции — неполная картина для бизнеса
В autodoc описана только интеграция через Merchant API. Для бизнес-аудитории также важно знать:
- Интеграция с ERP-системой (синхронизация данных)
- Интеграция с курьерскими службами через ApiShip
- Уведомления через Telegram (какие события, кому)
- Печать этикеток и документов (ZPL-принтеры, PDF-формы)
3. Что НЕ нужно добавлять в wms-autodoc
Следующее относится к технической документации и не должно появляться в бизнес-доке:
- Имена Java-классов, пакетов, аннотаций
- Архитектурные паттерны (BaseDocManager pipeline, Movement system, конструктор форм)
- Описание базы данных, миграций, ORM
- Event-driven архитектура, Spring Events
- Механизмы конкурентности (splitter, optimistic locking)
- Кеширование, метрики, DevOps
- Employee API endpoints (это внутренний API, не для бизнеса)
- System API
4. Что нужно в технической документации (wms/docs/)
Полный список тем, которые отсутствую т в autodoc и не должны там быть, но критичны для разработчиков:
4.1 Архитектура ядра
| Тема | Приоритет | Описание |
|---|---|---|
| Конвейер обработки документов | Критический | BaseDocManager pipeline, 14 шагов, hooks, модификаторы |
| Система движений и регистров | Критический | 6 типов движений, 5 регистров, координаты, splitter |
| Конструктор форм | Высокий | ListTemplate/EditTemplate, авто-рефлексия, ParamType |
| Доменная модель | Высокий | Иерархия BaseDoc/BaseDocItem, 33 типа документов, 378 сущностей |
| Event-driven архитектура | Высокий | 103 типа событий, паттерны подписки |
| State Machine | Средний | Spring Statemachine для workflow документов |
4.2 Инфраструктура
| Тема | Приоритет | Описание |
|---|---|---|
| Технологический стек | Высокий | Spring Boot 3.4.2, Java 21, PostgreSQL, и т.д. |
| Модель безопасности | Высокий | JWT, 3 filter chains, роли, привилегии, multi-tenancy |
| API (Employee, Merchant, System) | Высокий | Все endpoint'ы, auth, форматы запросов/ответов |
| База данных | Средний | Liquibase, схема, ключевые таблицы |
| Кеширование | Средний | Caffeine конфигурация |
| Интеграции | Средний | ERP, ApiShip, S3, Telegram, Serial Numbers |
4.3 Руководства для разработчиков
| Тема | Приоритет | Описание |
|---|---|---|
| Как добавить новый тип документа | Критический | Пошаговое руководство |
| Как добавить новый тип движения | Высокий | Создание Movement, Registry, координат |
| Как создать форму (List/Edit Template) | Высокий | Конструктор форм, примеры |
| Как добавить справочник | Средний | Entity, Repository, Service, Template |
| Соглашения разработки | Средний | conventions.md + дополнения |
| Локализация | Низкий | 17 файлов .properties, правила именования |
5. Сводная таблица: два контура
| Тема | wms-autodoc (бизнес) | wms/docs/ (техническая) |
|---|---|---|
| Обзор системы | Бизнес-возможности, ценность | Архитектура, стек, компоненты |
| Документы | Бизнес-назначение, сценарии | BaseDoc иерархия, pipeline, hooks |
| АРМы | Роли, процессы, диаграммы | Контроллеры, API-вызовы, state machines |
| Справочники | Что хранится, зачем нужно | Entity-классы, поля, связи, валидации |
| Отчёты | Какие данные, для кого | JasperReports шаблоны, параметры |
| Интеграции | Бизнес-партнёры, возможности | HTTP-клиенты, форматы, retry |
| API | Merchant API (для интеграторов) | Все 3 API с техническими деталями |
| Движения/регистры | — | Полное описание системы учёта |
| Безопасность | — | JWT, роли, привилегии |
| Конструктор форм | — | ListTemplate/EditTemplate framework |
| Events | — | Типы событий, подписки |
| Руководства | Как работать с АРМами | Как добавлять новый функционал |
6. План действий
Фаза 1: Исправления в wms-autodoc
- Добавить 6 пропущенных типов документов
- Исправить устаревшие названия
- Убрать пометку "under redesign" с ЧЗ
- Дополнить Merchant API недостающими endpoint'ами
- Добавить пропущенные справочники
- Добавить пропущенные АРМы
- Проверить и обновить Base URL
Фаза 2: Техническая документация (wms/docs/)
- Обзор системы (стек, структура проекта, сборка)
- Архитектура (конвейер документов, движения, конструктор форм)
- Доменная модель (документы, сущности, регистры)
- API reference (Employee, Merchant, System)
- Безопасность (JWT, роли, multi-tenancy)
- Руководства разработчика (как добавить документ, движение, форму)
- Интеграции (ERP, ApiShip, S3, Telegram)
- Инфраструктура (БД, кеширование, мониторинг)