ERP Platform Docs

Overview

время чтения ~3 мин.

Декомпозиция BR 3.4 — Catalog Sync ERP ↔ PayKeeper

Источник

BR 3.4

Большинство вопросов PK закрыты прецедентом Koala

9 исходных вопросов к техподдержке (BR §9) почти полностью закрыты изучением работающей реализации в Koala_TG_app (Laravel) + koala_backend (Java). Уточнены:

  • База ims-api: https://ims-api.paykeeper.ru/api/v1 (единый глобальный хост).
  • Auth: JWT через GET /info/settings/service-token?service=ims-api.paykeeper.ru&user={login} на {tsp}.server.paykeeper.ru.
  • Endpoints: POST /products, GET /product/{id}, GET /products?limit&start_from, PATCH /product/{id}, DELETE /product/{id}.
  • Payload: {"product": {name, price, item_type, tax, sku, description, barcode, item_code_is_mandatory, tru_code}}.
  • Категорий нет → префикс в имени.
  • Модификаторов нет → раскрываем в отдельные товары.
  • Тестовый аккаунт: переиспользуем ЛК Koala (активен, ims-api включён).

Открыты только: обратный webhook PK → ERP (ждём реализации на стороне PK, в v1 не нужен), картинки товара (не поддерживается ims-api).

Затронутые сервисы / репозитории

СервисПортРепоЗадачи
Catalog Service:3004erp-catalog-serviceCatalog Service
Paykeeper Adapter:3015erp-paykeeper-adapterPaykeeper Adapter
Admin BFF:3020erp-admin (bff/)Admin BFF
Admin Franchise web:3020erp-admin (web/)Admin Franchise
User Service:3002erp-user-service— изменений нет (adapter использует существующий GET /internal/legal-entities/{id} для резолва franchise_id)
Order Service:3005erp-order-service— изменений нет (каталог sync не пересекается с платёжным flow BR 3.3)
Store Service:3003erp-store-service— изменений нет
Infrastructure—erp-infrastructure— изменений нет (paykeeper-adapter уже задеплоен, cron и consumer внутри процесса)

POS (erp-pos-desktop, erp-pos BFF) — не трогаем. Catalog sync — бэкенд-только задача.

Последовательность выполнения

  1. Catalog Service (≈ 1 день) — CatalogEventPublisher с transactional outbox, hook’и в ProductService/CategoryService/ModifierGroupService, GET /internal/catalog/full-snapshot. Блокер для Paykeeper Adapter — без событий в Kafka adapter’у нечего потреблять.
  2. Paykeeper Adapter (≈ 2-3 дня) — 4 миграции (paykeeper_products, paykeeper_categories, paykeeper_modifier_groups, pk_catalog_sync_runs), PayKeeperImsClient (feature-flag до ответа PK), CatalogEventConsumer, расширение PkOutboxWorker новыми op_type, CatalogReconcileJob (cron 03:00), CatalogSyncController с 4 admin-эндпоинтами. Самая тяжёлая часть.
  3. Admin BFF (≈ 0.5 дня) — 4 прокси-роута в paykeeper.ts, shared TypeScript types.
  4. Admin Franchise web (≈ 1 день) — блок «Каталог в PayKeeper» в существующем PaykeeperTab, модалка «Журнал прогонов», обновление api/paykeeper.ts.

Итого: 4.5-5.5 дней работы после разблокировки вопросов к PK.

Риски / открытые вопросы

Закрыты прецедентом Koala (см. callout выше).

Остались только два — и оба не блокируют реализацию v1:

  1. Обратный webhook PK → ERP — ждём анонс от PK. В наш mapping (paykeeper_products.pk_product_id UNIQUE + полная тройка erp-ids) уже заложена готовность к reverse lookup. Обработка события — отдельный BR после того как PK выкатит.
  2. Dedup конфликтов имён при первичном онбординге — если в ЛК PK уже есть товары с нашими именами (ручное заведение до sync’а), мы их skip’ним, но в pk_catalog_sync_runs.errors_json их стоит явно размечать как NAME_CONFLICT. UI-индикация в модалке журнала.

Прогресс

  • Catalog Service — publisher + outbox + snapshot endpoint
  • Paykeeper Adapter — миграции + ims-client + consumer + worker + cron + controllers
  • Admin BFF — 4 прокси-роута + shared types
  • Admin Franchise web — блок «Каталог в PayKeeper» + модалка «Журнал прогонов»
  • Deploy на VPS — ждёт доступа к koala-test ims-api

Sandbox credentials

Те же что для BR 3.3 (см. 07-Tasks/Decomposition/3.3 PayKeeper Adapter P0/Overview.md). Дополнительно требуется включение ims-api на этом же аккаунте — запросить у PK.

Ссылки

Вид графа

Обратные ссылки