# Журнал разбора остатка и резерва

Версия 1.1, 31.10.2026. Общая методика для операционного менеджера и специалиста по обмену данными. Пустые CSV предназначены для заполнения; файлы example содержат исключительно учебные данные, помеченные SYNTHETIC_NOT_REAL.

## Файлы

- `m11-incident-template.csv` — пустой паспорт одного инцидента.
- `m11-events-template.csv` — пустой журнал, одна строка на факт или попытку доставки.
- `m11-incident-example.csv` — вывод по учебному инциденту DEMO-INCIDENT-01.
- `m11-events-example.csv` — 12 учебных событий: два заказа, один внутренний резерв, отказ второму резерву, повтор сообщения, позднее чтение нуля и отклонённое устаревшее задание.

CSV: UTF-8 с BOM, разделитель — запятая, десятичная точка; текст с запятыми заключён в двойные кавычки. Импортируйте через «Данные → Из текста/CSV». Идентификаторы, артикулы, версии и временные отметки назначьте текстовыми колонками: это сохраняет ведущие нули и исходный часовой пояс. В LibreOffice при импорте снимите автоматическое распознавание специальных чисел. Сохраните исходную копию до изменения.

## Быстрое применение

1. Заполните паспорт: один владелец, физический склад, вариант и единица, начало/конец окна. Не объединяйте одинаковый артикул разных владельцев или разные размеры.
2. Запишите исходный пересчёт и определения чисел. В шаблоне годный физический остаток включает зарезервированные годные единицы. Активный резерв и отдельный блок не должны пересекаться. Карантин не входит в годный остаток.
3. Скопируйте относящиеся к этому ключу факты без изменения исходных журналов. Одно получение, один commit, одна попытка отправки и один ответ — отдельные строки. Не помещайте запрос и ответ в одну временную отметку.
4. Сначала заполните время наблюдения, вид события, источник, заказ/событие/запрос и ссылку на доказательство. Остальные технические поля дополните с ответственным за интеграцию.
5. Сверьте количество внутренних резервов и их изменения. Затем отдельно проверьте отправленный остаток, ответ API и значение при последующем чтении.
6. В паспорте разделите доказанные факты, статус причины, неизвестное, временное действие, следующую проверку и ответственного. В `order_resolution` перечислите каждый `order_id` с решением и основанием либо `pending` и следующим действием. Гипотеза остаётся гипотезой, пока нет подтверждения.

## Значения и неизвестное

Пустая ячейка означает «не получено или неприменимо»; поясните причину в `interpretation`. Она не равна нулю. Ноль количества означает проверенное нулевое значение. Не заполняйте отсутствующие часы, номера версий и резерв площадки догадками.

`source_event_at` — исходная временная отметка события, если она есть. `observed_at` — время, когда журнал или специалист увидел факт. Используйте ISO 8601 с часовым поясом, например `2026-10-31T10:00:04.100+03:00`. Если источник не содержит зоны, сохраните исходную запись и явно укажите неизвестную зону в `time_basis`; не придумывайте смещение. При переводе в UTC сохраняйте исходную запись в доказательстве.

В учебном примере время наблюдения принадлежит одному условному журналу. Часы площадок не сверены. Из времён источников нельзя вывести точный межсистемный порядок с точностью до миллисекунд.

## Паспорт: поля

| Поле | Что вносить |
|---|---|
| record_kind | Для собственных данных — WORKING_RECORD; учебные строки оставляйте SYNTHETIC_NOT_REAL |
| incident_id | Собственный постоянный номер разбора |
| owner_id, physical_warehouse_id | Владелец товара и фактическое место хранения |
| canonical_variant_id, variant, unit | Подтверждённый внутренний вариант, его признаки, единица количества |
| window_start, window_end | Границы рассматриваемого периода с часовым поясом |
| log_timezone, clock_note | Зона журнала, источник часов, проверенность синхронизации и её точность |
| initial_physical_good | Подтверждённый годный физический остаток до события, включая резерв |
| initial_reserved | Действующие резервы, уже включённые в годный физический остаток |
| initial_blocked, initial_buffer | Отдельно заблокированные годные единицы и буфер; без пересечения с резервом |
| mapping_evidence | Основание связи вариантов площадок с внутренним вариантом и владельцем |
| observed_orders | Число различных заказов, а не число сообщений о них |
| order_resolution | По каждому order_id: результат и основание либо pending с конкретным следующим действием. Отказ внутреннего резерва не означает отмену внешнего заказа |
| confirmed_facts | Только доказанные события с номерами строк/ссылками |
| root_cause_status | Установленная причина либо явно отмеченная гипотеза |
| unknowns | Какие факты ещё не получены и что они могут изменить |
| containment | Адресное временное действие с нужными полномочиями |
| next_check, assignee | Следующая проверка и ответственный за неё |
| closure_criterion | Какие доказательства и решения нужны для закрытия |

## Журнал: поля

| Поля | Смысл |
|---|---|
| record_kind, incident_id, row_id | Тип набора, связь с паспортом и уникальный номер строки. Повтор сообщения получает новую строку, но прежний event_id |
| event_type, source_system | Что произошло и где: получение заказа, commit резерва, отправка, ответ, readback, повтор, отклонённая старая запись |
| source_event_at, observed_at, time_basis | Два времени и основание их сравнения |
| seller_account_id, marketplace_warehouse_id, source_variant_id | Конкретные кабинет, склад площадки и вариант. Для внутреннего события могут быть неприменимы |
| order_id | Идентификатор заказа с сохранением принадлежности кабинету |
| event_id | Идентификатор исходного события, если существует. При отсутствии составной ключ должен назначить ответственный за интеграцию |
| request_id | Идентификатор конкретной попытки запроса либо локальный correlation ID. Это не обещание поддержки такого параметра площадкой |
| stock_version, version_scope | Версия состояния/задания и система, в которой она имеет смысл. Локальную версию нельзя сравнивать с версией другого источника |
| qty, qty_kind | Количество и его точный смысл: заказано, отправлено как абсолютный остаток, прочитано, запрошено в резерв |
| physical_good, active_reserved, blocked_good, safety_buffer | Снимок локальных количеств на событие по определениям паспорта; если не известен, оставьте пустым |
| available_raw | Годный физический минус активный резерв, отдельный блок и буфер. Отрицательное число сохраняйте для диагностики |
| reserve_delta | Фактическое изменение подтверждённого локального резерва: плюс — создание, минус — освобождение. Получение заказа само по себе не изменение резерва |
| transport_status | HTTP-код, тайм-аут либо иной транспортный результат; он не подменяет результат по товару |
| business_result | Фактический результат операции/строки ответа или «применение неизвестно» |
| evidence_ref | Доступная уполномоченному проверяющему ссылка/номер исходного журнала, ответа, пересчёта. DEMO-ссылки примера обозначают вымышленные доказательства |
| writer | Система или исполнитель, записывающий остаток/резерв |
| interpretation | Краткий вывод и предел доказательства; отдельно от исходного факта |

## Числовая сверка

В этой модели: `available_raw = physical_good - active_reserved - blocked_good - safety_buffer`.

Начало примера: `1 - 0 - 0 - 0 = 1`. После E05: `1 - 1 - 0 - 0 = 0`. Второй заказ E08 и отказ E09 не создают второй резерв. Повтор E10 не меняет состояние. Позднее задание E12 содержит старое значение 1, но не отправлено и не становится остатком.

Если исходная система уже возвращает свободный остаток после резерва, не вычитайте резерв повторно. Сначала договоритесь о смысле поля, затем переносите данные в эту модель. Все величины относятся к одному владельцу, варианту, складу, единице и срезу времени.

## Что доказывает пример

Подтверждены внутри учебного сценария два заказа и только один принятый внутренний резерв. Последовательные чтения E02 и E03 вернули 1 в API каждого канала в свой момент; одновременная доступность покупателю не установлена. В 10:00:06 API WB вернул ноль. Не установлены точный момент применения отправленного нуля, причина изменения остатка на площадке и момент его видимости покупателю. Поведение учебной WMS/очереди не является проверкой Skirbo или конкретной интеграции.

В `order_resolution` оба заказа примера остаются `pending`: A имеет резерв, но дальнейшее исполнение не подтверждено; B не получил резерв и ожидает решения ответственного по правилам площадки. Автоматическая отмена не выполнялась.

## Отмена и уже отгруженный товар

Если товар ещё на складе, различайте отмену до подбора и после упаковки; состояние упаковки может требовать отдельного блока до проверки. Если товар уже отгружен, отмена заказа или статус ожидаемого возврата не увеличивает годный физический остаток. Сначала подтвердите фактическую обратную приёмку, владельца/вариант и пригодность товара. Неизвестное или повреждённое поступление остаётся в разборе; повтор уведомления не создаёт новый приход.

## Сохранение результата

Оставьте неизменяемую копию исходных файлов и рабочую копию разбора. Для передачи поддержке исключите API-ключи, cookies и персональные данные покупателей; сохраните нужные технические идентификаторы и обезличенные ссылки на доказательства. Доступ к исходному заказу передавайте через штатные права кабинета.

Методика и официальные источники: статья «Два заказа на последний экземпляр: диагностика остатка и резерва» на Skirbo. Протокол не отправляет запросы и не меняет остатки.