Download the PHP package geekcodev/laravel-commercejson without Composer

Laravel CommerceJSON

Пакет для интеграции с CommerceJSON API v1.0.8 в Laravel 13. Предназначен для обмена данными с системами 1С и другими ERP-системами, поддерживающими стандарт CommerceJSON.

Оглавление

• Возможности
• Установка
• Использование
  • Быстрый старт
  • Использование сервисов
  • Console-команды
• Архитектура
  • Структура пакета
  • Таблицы базы данных
• Тестирование
  • Покрытие кода
• Документация
  • Доступные методы
  • События
• Конфигурация
• Синхронизация
  • Полная синхронизация
  • Инкрементальная синхронизация
  • Планирование синхронизации
• Обработка ошибок
• Очереди заданий
• Чеклист для production
• История версий
• Лицензия
• Поддержка
• Ссылки

Возможности

• HTTP-клиент с поддержкой повторных запросов, идемпотентности (X-Idempotency-Key) и пагинации
• 23 модели Eloquent с UUIDv4, SoftDeletes и отношениями
• 24 миграции базы данных с оптимизированными индексами
• 49 Spatie Data DTO для строгой валидации
• 6 сервисов для HTTP-клиента (классы для интеграции с ERP)
• 7 очередей заданий для асинхронной обработки
• 7 Artisan-команд для CLI-работы
• 11 событий для интеграции с приложением
• CQRS-архитектура: CommandBus (Laravel Bus) + QueryBus (in-memory)
• Репозитории через RepositoryInterface (инкапсуляция Eloquent)
• Rate limiting и идемпотентность на API-роутах
• Фабрики и сидеры для тестирования

Установка

После установки пакета и публикации конфига, маршруты автоматически регистрируются в CommerceJsonServiceProvider:

Готовые REST API endpoints становятся доступны по префиксу /api/commercejson (настраивается через config('commercejson.api_routes.prefix')).

Публикация конфигурации и миграций

Переменные окружения

Добавьте в файл .env:

Использование

Быстрый старт

Два способа работы с пакетом

1. REST API (Headless CMS) — рекомендуется для frontend

Пакет предоставляет готовые REST API endpoints. Используйте HTTP запросы из вашего frontend приложения:

Преимущества:

• ✅ Готовые endpoints из коробки
• ✅ Не нужно писать контроллеры
• ✅ Идеально для React/Vue/Next.js frontend
• ✅ Мобильные приложения получают доступ к API
• ✅ CQRS архитектура внутри контроллеров

2. Сервисы — для кастомной бизнес-логики

Если вам нужна кастомная логика, используйте сервисы напрямую:

Тестирование

Использование factory для Data-классов

Console-команды

Архитектура

Пакет использует архитектурные паттерны CQRS (Command Query Responsibility Segregation) и Repository для разделения операций чтения и записи, что обеспечивает:

• Чёткое разделение ответственности — команды для записи, запросы для чтения
• Тестируемость — легко мокировать зависимости через интерфейсы
• Масштабируемость — независимое масштабирование чтения/записи
• Поддерживаемость — понятная структура кода
• Headless CMS — готовые REST API контроллеры и роуты из коробки

Готовые REST API endpoints

Пакет автоматически регистрирует маршруты в соответствии с OpenAPI спецификацией CommerceJSON v1.0.8. Все эндпоинты (кроме /handshake) защищены аутентификацией, rate limiting и идемпотентностью.

Важно: POST /orders/bulk должен быть объявлен до GET /orders/{id}.

Пагинация: query-параметр limit (не per_page). Ответ: {entity: [...], pagination: {page, limit, total, has_next}}.

Пример запроса:

Архитектура

Подробное описание архитектуры (CQRS, SOLID, Repository pattern, DTO конвенции, security) — в AGENTS.md.

Структура пакета

Компоненты архитектуры

1. HTTP Client Layer

2. Command/Query Bus

3. Services (бизнес-логика)

4. Controllers (API endpoints)

5. Middleware

API-роуты защищены слоем middleware:

• Аутентификация — auth:commercejson для всех эндпоинтов кроме /handshake
• Rate limiting — throttle на всех auth-роутах (конфиг rate_limit/rate_limit_decay, по умолч. 60/мин)
• Идемпотентность — IdempotencyMiddleware кеширует ответ POST/PATCH по X-Idempotency-Key + fingerprint запроса ( TTL из конфига)
• Rate limiting — throttle:rate_limit,rate_limit_decay на всех write-роутах (по умолч. 60/мин)

6. Exceptions

Таблицы базы данных

24 таблицы:

• categories — категории товаров (иерархия)
• price_types — типы цен (розница, опт, дилер)
• warehouses — склады
• property_definitions — свойства товаров
• property_values — значения свойств
• counterparties — контрагенты
• contacts — контактная информация
• bank_accounts — банковские счета
• representatives — представители
• products — каталог товаров
• product_variants — варианты товаров
• product_images — изображения товаров
• offers — торговые предложения
• offer_prices — цены предложений
• stocks — остатки на складах
• orders — заказы клиентов
• order_items — позиции заказов
• order_item_taxes — налоги позиций
• status_history_entries — история статусов
• custom_attributes — пользовательские атрибуты
• signatories — подписанты документов
• product_analogues — аналоги товаров
• product_components — комплектующие
• order_linked_documents — связанные документы

Тестирование

Документация по генерации большого объёма данных для нагрузочного тестирования: TESTING.md.

После генерации HTML отчёта, откройте coverage/index.html в браузере.

Покрытие кода

Текущее покрытие:

49 тестов, 230 assertions. Покрытие требует расширения — см. CODE_AUDIT.md (Фазы 2–5) и COVERAGE.md.

Документация

Доступные методы

ProductService

OrderService

События

Конфигурация

Синхронизация

Полная синхронизация

Инкрементальная синхронизация

Планирование синхронизации

Добавьте в app/Console/Kernel.php:

Обработка ошибок

HTTP исключения

Бизнес исключения

Очереди заданий

Чеклист для production

• [ ] Опубликовать конфигурацию: php artisan vendor:publish --tag=commercejson-config
• [ ] Опубликовать миграции: php artisan vendor:publish --tag=commercejson-migrations
• [ ] Запустить миграции: php artisan migrate
• [ ] Настроить worker очередей для асинхронных операций
• [ ] Настроить планирование синхронизации в Kernel.php
• [ ] Настроить мониторинг неудачных заданий
• [ ] Настроить канал логирования
• [ ] Проверить соединение: php artisan commercejson:handshake
• [ ] Запустить начальную полную синхронизацию: php artisan commercejson:sync --full

История версий

1.0.0 (2026-04-24)

• Начальный выпуск
• Поддержка CommerceJSON v1.0.8
• 24 миграции
• 23 модели
• 49 Data-классов
• 6 сервисов
• 7 очередей заданий
• 7 console-команд
• 11 событий
• Полное тестовое покрытие

Лицензия

Пакет распространяется под лицензией MIT.

Поддержка

• Email: [email protected]
• Issues: GitHub Issues
• Документация: Wiki

Ссылки

• Packagist
• GitHub
• Спецификация CommerceJSON