Перейти к основному содержимому

Известные особенности и ограничения

Живой список ведётся в репозитории — docs/known-quirks.md. Это диагностический файл: он существует, чтобы одну и ту же ловушку не расследовали дважды. Здесь — карта того, что в нём лежит, и несколько ограничений уровня архитектуры.

Что описано в docs/known-quirks.md​

МойСклад. Реальный API строже моков по заголовкам, ключу сопоставления и лимиту запросов.

ApiShip и СДЭК.

  • «Тестовый режим» — это три разных независимых переключателя, а не один.
  • Пустой список тарифов или ПВЗ в чекауте не всегда означает проблему у ApiShip.
  • Тариф до ПВЗ у ApiShip исчезает, если в корзине сохранён адрес с улицей.
  • getListPoints и калькулятор ApiShip не привязаны к конкретному подключению.
  • ApiShip отдаёт один и тот же тариф несколькими записями.
  • POST /orders у СДЭК отвечает uuid раньше, чем реально проверит заказ.

Локальные миграции. Ошибка site_link does not exist обычно означает загрязнённую БД, а не сломанную миграцию.

Витрина. Чтение event.currentTarget внутри updater-функции setState роняет форму.

Ограничения уровня архитектуры​

Medusa вырезает улицу из контекста ценообразования доставки. Перед вызовом фулфилмент-провайдеров core применяет fieldsForPricingContext/filterObjectByKeys и удаляет shipping_address.address_1/address_2. Калькулятор видит только city, country_code, province, postal_code — дом и квартира до него не доходят никогда. Это общее поведение core, а не специфика ApiShip: учитывайте в любой новой интеграции с расчётом доставки.

Кэш ПВЗ у ApiShip не смотрит на фильтр. Шаг getApishipPointsWorkflow кэширует строго по переданному key, игнорируя строку filter. Добавляя новый фильтр по этому API, обязательно включайте его значение в ключ кэша — иначе кэш отдаст чужие данные.

Статус доставки ApiShip не имеет фиксированного enum. Он маппится эвристикой по ключевым словам в упрощённый статус (placed / preparing / in_transit / delivered / cancelled). Это принятое допущение до получения реального доступа к ApiShip.

Чекаут жёстко блокируется, а не деградирует молча. Если у корзины есть shipping-профиль с доступной опцией ApiShip, но реальный shipping method к нему не прикреплён, prepareCatalogCheckoutShippingOptionsStep отвечает 409. Это защита от обращения к API в обход заблокированной кнопки, а не подсказка для UX.

Баги апстрима патчатся через patch-package. Патчи лежат в patches/@gorgo+medusa-fulfillment-apiship+*.patch и переустанавливаются на npm install. Новый баг того же рода — тот же механизм, а не форк пакета.

Сброс пароля покупателя всегда отвечает 201. POST /auth/customer/emailpass/reset-password не сообщает, существует ли email — это намеренная защита от перебора в core. Витрина обязана показывать одинаковое сообщение в любом случае. На невалидный или уже использованный токен POST /auth/customer/emailpass/update отвечает 401 с message: "Invalid token" — точное совпадение строки остаётся единственным сигналом для состояния «ссылка недействительна».

Каталог отдаёт максимум 1000 товаров при просмотре — ограничение maxTotalHits Meilisearch. При большем каталоге часть товаров недостижима перелистыванием (но находится поиском).

Как пополнять​

Правило из самого файла: попал в ловушку, потратил время на диагностику — запиши. Формат — короткий заголовок с симптомом и абзац с причиной.