PageTrace: все запросы 200 OK, а часть данных потеряна

Все запросы 200 OK, а строк не хватает

Выгрузка заказов или остатков идёт страница за страницей. Каждый ответ 200, цикл завершился, в логах чисто. Через три недели бухгалтерия замечает, что отчёт короче на четыреста строк, а склад показывает лишние остатки. Записи обмена уже нет, воспроизвести ошибку нечем.

Так ломается всё, что забирает данные из маркетплейсов, банков, CRM и 1С: ошибка сидит между двумя соседними запросами. Как устроены сами интеграции с площадками, я описывал в статье про API Wildberries и Ozon, а общий разбор причин поломок есть в материале про то, кто виноват, когда интеграция сломалась. Здесь про узкую задачу: как найти тихую потерю данных по записи запросов.

Что это за проект и что я проверил

Проверял 19.10.2026 по репозиторию, API GitHub и странице на PyPI. Описание проекта: офлайн-проверка записанных трейсов пагинации, без обращения в сеть. Файл LICENSE это MIT, правообладатель указан как «PageTrace maintainers». Репозиторий создан 11.09.2026, не архивирован, 32 коммита, все с одного аккаунта Corner324. Последний коммит 12.09.2026, там же единственный релиз v0.1.0. Звёзд 3, форков нет. Язык Python, нужна версия 3.11 или новее, единственная зависимость это библиотека JSONPath.

В метаданных пакета стоит статус «Pre-Alpha». В pyproject в адресе проекта остался шаблон OWNER вместо имени. В репозитории лежат CLAUDE.md и AGENTS.md, то есть судя по файлам, автор работает с ИИ-агентами. Заявленные 425 тестов я не воспроизводил. Сам инструмент не запускал, всё ниже по README, спецификации и коду.

Как это запускается

Установка: pip install pagetrace, также работают pipx и uv. Запуск: pagetrace check запись.jsonl. Формат JSONL это одна строка на пару запрос и ответ, обязательны поля v и response.status. HAR сохраняется из вкладки Network в браузере, и его нужно сузить до нужных вызовов флагом --url-filter. Запросы OPTIONS и HEAD отбрасываются заранее, иначе предварительный запрос CORS выглядит как зависший клиент.

Типов пагинации четыре, они называются пресетами: cursor (по умолчанию), page, offset и link для заголовка Link с rel="next". Поля в ответе задаются путями JSONPath, у каждого пресета есть значения по умолчанию, их можно переопределить флагами. Если нужного поля в записи нет, инструмент пишет «недостаточно доказательств» и называет флаг, который стоит задать.

HAR хранит живые заголовки Authorization и cookie. По README инструмент оставляет один заголовок ответа (Link), тела не печатает, но сам файл на диске остаётся секретным. Не прикладывайте его к публичным обращениям.

Что он ловит

В спецификации одиннадцать проверок. Главные для выгрузок: страница запрошена токеном, которого предыдущая не возвращала; курсор повторился на соседних страницах; курсор вернулся к уже виденному значению; один и тот же элемент встретился на двух страницах; номер страницы или offset прыгнул; запись оборвалась при has_more=true; заявленный итог не совпал с числом уникальных элементов. Проверки порядка сортировки в списке я не нашёл.

Каждая находка получает два независимых признака. Достоверность: PROVEN (доказано записью), SUSPICIOUS (подходит под баг, но подходит и под безобидное объяснение), INSUFFICIENT_EVIDENCE. И серьёзность, ERROR или WARNING. Коды выхода для CI: 0 если нет находки, одновременно доказанной и с уровнем ERROR, 1 если есть, 2 при неверном входе или настройках. Отчёт бывает в терминале, JSON или JUnit. Для CI автор советует читать JSON, формат терминала не обещан стабильным.

Условный пример

Условный пример, цифры придуманы. Выгрузка по курсору, 3 страницы по 100 строк. API заявляет total 300. Страница 1 отдала строки с 1 по 100 и курсор A. Страница 2 пришла по курсору A: строки 101 по 200 и курсор B. Страница 3 пришла по курсору B, но вернула те же строки 101 по 200 и закончила выгрузку. Клиент насчитал 300 строк, а уникальных 200.

По спецификации здесь ожидаются две находки. Дубликаты между страницами 2 и 3: PROVEN, но WARNING. Расхождение total (300 против 200): SUSPICIOUS, потому что при найденных дублях сравнивать нужно осторожнее. Обе находки уровня WARNING, значит код выхода 0 и сборка не упадёт. Это ожидание из документа, на этой записи я инструмент не гонял. Если бы клиент дважды послал курсор A подряд, зависание курсора считается ошибкой, и код был бы 1. Для первого случая в CI придётся самому проверять в JSON-отчёте код находки о дублях.

Что важно учесть

Проект молодой, один автор, 3 звезды, 0.1.0 и статус Pre-Alpha, последний коммит больше месяца назад. Для рабочего контура это риск: поддержка не гарантирована. Лицензия MIT позволяет форкнуть.

Инструмент видит только запись. Он не знает, сколько строк реально в системе-источнике, поэтому фразу «не хватает N записей» не произнесёт принципиально. Если курсор на самом деле пропустил окно данных и ничего не повторил, запись выглядит чистой. Авторизацию, повторы при ошибках и потоковые API он не проверяет и не воспроизводит.

По таблице автора на его машине 10 тысяч страниц и миллион элементов обрабатываются за 28 секунд, часть своих целевых значений он не достиг.

Что можно сделать уже сейчас

Запишите одну живую выгрузку в HAR или JSONL и прогоните через PageTrace на тестовых данных без реальных ключей.

Если в боевой выгрузке есть поле total, добавьте в сам скрипт сверку: число уникальных идентификаторов против заявленного итога. Это работает без всяких инструментов.

Раз в месяц сверяйте остатки или заказы в вашей учётной системе с тем, что отдаёт площадка. Это то, чего PageTrace не заменяет. Как строить клиента к API, показано в статье про OpenAPI Generator, а если API для вас новая тема, начните с простого объяснения.

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

Частые вопросы

Ходит ли PageTrace в API сам?

Нет, в пакете нет сетевого кода. Он читает только файл, который вы ему дали.

Заменит ли он сверку остатков?

Нет. Он доказывает или не доказывает дефект пагинации в записи, а данные в источнике не видит.

Подходит ли он для боевого CI?

Пока осторожно. Версия 0.1.0 и один автор. Контракт кодов находок и выхода заявлен как публичный начиная с этой версии, но обещание держится на одном человеке.

Коротко о главном

PageTrace по записи запросов показывает зависший курсор, повторы страниц и расхождение итога, не обращаясь к API. Он молодой и лишь анализирует запись, сверка с источником остаётся за вами.

Если выгрузки из маркетплейсов, банка или CRM иногда расходятся с реальностью, напишите мне в Telegram кодовое слово «ПАГИНАЦИЯ». Разберём, где теряются строки, и добавим проверки.