# Бриф интеграции — заполненный учебный пример

Версия 1.0, 31.10.2026. Все системы, идентификаторы, количества и условия ниже вымышлены. Это проект требований к обмену ERP-A → WMS-B, а не описание работающей интеграции Skirbo. Испытания не выполнялись: во всех строках приёмки факт — «не проверено».

## 1. Задача и scope

Менеджер сейчас переносит подтверждённый заказ из ERP-A в черновик задания на подбор WMS-B. Требуемый результат: один черновик с правильным владельцем, складом и составом; менеджер сверяет его по внешнему номеру заказа.

Scope: один учебный владелец TEST-A, склад TEST-WH-1, немаркированный товар DEMO-SKU-01, единица «шт.». Обмен односторонний: создание, обновление состава и отмена черновика до начала работы. Черновик не резервирует и не списывает товар, не выпускает документы, не отправляет уведомления клиенту. Внешний номер — строка, ведущие нули не теряются.

Не входит: автоматический выпуск задания в работу, обратная синхронизация, оплаты, юридические документы, маркировка, заказы других клиентов. Способ передачи и доступ к тестовому API сначала должны подтвердить технические владельцы обеих систем. Текущий статус готовности — неизвестно, нужна проверка.

## 2. Источник истины

ERP-A управляет составом и ревизией заказа до передачи в работу. WMS-B управляет созданным заданием и фактом выполнения. Физический остаток остаётся в контуре WMS-B; событие ERP-A не меняет его. После начала подбора изменение заказа требует отдельного разбора. Бизнес-владелец — руководитель склада; технические владельцы — ответственные ERP-A и WMS-B; принимает результат руководитель вместе с менеджером смены.

## 3. Событие и поля

Учебный вход:

| Поле | Значение | Правило |
|---|---|---|
| source | ERP-A | Пространство внешних идентификаторов |
| owner_id | TEST-A | Разрешённый владелец; нельзя брать из свободного текста |
| external_order_id | DEMO-001042 | Ключ заказа: source + owner_id + external_order_id |
| event_id | EVT-017 | Ключ доставки: source + owner_id + event_id |
| revision | 3 | Монотонная целая ревизия заказа; требование к источнику, пока не доказано |
| type | order.ready | Создать либо актуализировать разрешённый черновик |
| occurred_at | 2026-10-30T09:00:00+03:00 | Время события; время получения хранится отдельно |
| warehouse | TEST-WH-1 | Только согласованное сопоставление склада |
| lines[0].line_id | L1 | Идентификатор строки в пределах заказа |
| lines[0].sku | DEMO-SKU-01 | Сопоставление с конкретным вариантом, не поиск по названию |
| lines[0].variant | blue-M | Учебный цвет и размер |
| lines[0].quantity | 3 | Целое положительное число, единица «шт.» |

Подтверждение приёма означает сохранённую запись о событии. Бизнес-результат подтверждается отдельно: один черновик и читаемый состав из трёх единиц. Сообщение «получено» ещё не означает «черновик создан».

## 4. Исключения

1. EVT-017 с тем же содержимым приходит повторно: возвращается прежний результат, второй черновик не создаётся.
2. EVT-017 с количеством 4: конфликт содержимого, исходный результат не переписывается; нужно новое согласованное событие с новой ревизией.
3. Новый event_id, но тот же заказ и ревизия 3: сравниваются значимые поля события с принятой бизнес-ревизией. Одинаковые данные считаются повтором без второго задания; изменённые данные — конфликтом, прежний состав сохраняется. Новый event_id сам по себе не разрешает переписать ревизию.
4. Ревизия 2 приходит после 3: помечается устаревшей, состав не откатывается. Если источник не гарантирует ревизии, доработка правил порядка остаётся блокером; время компьютера не считается достаточной заменой.
5. Тайм-аут после сохранения: перед повтором проверяется результат по ключу. Не создавать новый event_id, чтобы «запрос прошёл».
6. Неизвестный SKU или другой owner_id: ничего не подставлять автоматически. Событие в очередь разбора; предмет ошибки и ответственный видны менеджеру без чужих данных.
7. Отмена до начала подбора: отменяется только черновик. После начала работы — отдельная остановка задания и сверка; автоматическое удаление истории запрещено.
8. Пакет из двух событий, одно невалидно: учебный контракт допускает независимый результат по каждой строке. Успешное событие не переисполняется. Обычная повторная доставка возвращает сохранённый статус. Если исправили внешнюю причину (например, добавили согласованное сопоставление), ответственный запускает отдельную повторную обработку незавершённого события с прежним ключом и неизменным содержимым; параллельное исполнение одной записи блокируется. Если поменяли само содержимое источника, отправляют новое событие с новым event_id и увеличенной ревизией; исходное событие остаётся неизменным. Если реальный API требует атомарного пакета, этот пункт необходимо заменить до реализации.
9. Новая ревизия 4 до начала подбора: обновляется тот же черновик; история принятой ревизии 3 сохраняется. Событие отмены `order.cancelled` с ревизией 5 до начала работы отменяет этот черновик. После начала подбора оба события попадают на разбор без автоматической перезаписи состава или удаления задания.

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

## 5. Приёмка: ожидаемый результат, не протокол выполненных тестов

| ID | Вход | Ожидание | Проверка факта | Факт/итог |
|---|---|---|---|---|
| A01 | EVT-017, ревизия 3, 3 шт. | Один черновик TEST-A / TEST-WH-1, 3 шт.; остаток не изменён | Прочитать черновик и журнал, сопоставить внешний ключ | Не проверено |
| A02 | Повтор EVT-017 без изменений | По-прежнему один черновик, 3 шт. | Сосчитать объекты и побочные действия | Не проверено |
| A03 | EVT-017 с 4 шт. | Конфликт; прежний состав 3 шт. сохранён | Ошибка видна; второй объект отсутствует | Не проверено |
| A04 | Разрыв связи после сохранения | Результат найден по ключу; нет нового задания | Сверить журнал и черновик после восстановления связи | Не проверено |
| A05 | owner_id TEST-B | Нет чтения/создания чужого задания | Отказ прав на сервере, без раскрытия чужих данных | Не проверено |
| A06 | Ревизия 2 после 3 | Черновик остаётся на ревизии 3 | Сверить ревизию, состав и запись причины пропуска | Не проверено |
| A07 | Валидный + неизвестный SKU; затем исправлено внешнее сопоставление и разрешена повторная обработка прежнего незавершённого события | Сначала создан только валидный, ошибка адресная; после восстановления создан ровно один ранее отсутствовавший черновик. Ранее принятая строка не выполнена снова | Сверить оба результата до/после; при обычном дубле возвращается статус, при разрешённом возобновлении нет параллельного или повторного эффекта | Не проверено |
| A08 | Остановить обмен, восстановить | Новые записи запрещены на время остановки; очередь сводится без дублей | Реестр непринятых, принятых и завершённых событий | Не проверено |
| A09 | Новый event_id, заказ/ревизия 3 прежние: сначала 3 шт., затем отдельный вариант с 4 шт. | Одинаковое содержание — повтор; иное — конфликт; прежний черновик не изменён | Сравнить значимые поля, количество объектов и журнал решений | Не проверено |
| A10 | Новая ревизия 4, 4 шт., черновик ещё не в работе | Тот же черновик обновлён до 4 шт.; ревизия 3 сохранена в истории; остаток не изменён | Прочитать состав, версию, историю и количество задач | Не проверено |
| A11 | order.cancelled, ревизия 5, черновик ещё не в работе | Один отменённый черновик с историей, без движения товара | Прочитать статус, исходный ключ и движения | Не проверено |
| A12 | Обновление или отмена заказа после допуска задания в работу | Адресное исключение для ответственного; выполненная работа и история не удалены | Контрольное исходное состояние задаёт владелец теста; сверить до/после | Не проверено |

## 6. Решение

Готово к обсуждению объёма, не готово к запуску. Следующий шаг — подтвердить доступные методы, поля, ревизии, область прав и поведение повтора в тестовой среде. После этого оценить настройку/разработку и заполнить условия сопровождения.

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