innokassa/mdk

PHP Module Development Kit for Pangaea Server by Innokassa

2.0.0 2022-05-13 08:25 UTC

Requires

• php: >=7.1

Requires (Dev)

• phpstan/phpstan: ^1.5
• phpunit/phpunit: ^9
• squizlabs/php_codesniffer: ^3.6

MIT

• Buturlin Vitaliy (Byurrer)
• Igor Kripak

README

Innokassa Module Development Kit

Innokassa MDK (Module Development Kit) - набор программных средств на PHP для использования API облачной кассы Pangaea V2 от Innokassa, содержащий в себе всю необходимую логику для фискализации заказов интернет-магазинов (ИМ), с поддержкой мультисайтовости.

Для работы библиотеки требуется PHP версии не ниже 7.1 с библиотекой curl.

Описание:

• ОО стиль - все есть объект
• использует PSR-4 автозагрузку классов
• применяется стардарт PSR12
• оснащен Unit/Server/System тестами PHPUnit
• не имеет зависимостей - концепция многократного использования без зависмостей, поэтому можно использовать в без-composer'ной среде

Оглавление

• Установка
• Использование
  • Реализация на стороне клиента
  • Клиент
    • Инициализация
    • Настройки
    • Automatic
    • Pipeline
  • Обработка ошибок
  • Логи
• Разработка
• Issues & Contributing
• License

Установка

Клонирование репозитория:

git clone https://git.innokassa.ru/Byurrer/mdk.git

Через composer:

composer require innokassa/mdk

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

В проектах не использующих composer необходимо подключить автозагрузку классов:

require_once('mdk/src/autoload.php');

Реализация на стороне клиента

Перед использованием необходимо реализовать на стороне клиента:

• SettingsAbstract - получение настроек
• ReceiptStorageInterface - хранилище данных чеков
• ReceiptAdapterInterface - адаптер чеков под заказы, чтобы сервис Automatic мог формировать чек из заказа
• ReceiptIdFactoryInterface - фабрика идентификаторов чеков, есть базовая реализация ReceiptIdFactoryMeta, в которой необходимо переопределить метод getEngine

Для сериализации/десериализации данных чеков БД<=>MDK существует базовый конвертер ConverterStorage. При необходимости можно создать новую реализацию ConverterAbstract.

Для взаимодействия с сервером фискализации используется NetClientCurl. При необходимости можно создать новую реализацию NetClientInterface.

Клиент

В базовом варианте использование MDK осуществляется через класс Client, посредством получения сервисов и лишь в редких случаях через компоненты (например при проверке настроек).

Клиент API Pangaea V2 состоит из:

• сервисов (для каждого сервиса существует базовая реализация):
  • Autmotaic - автоматическая фискализация приходов заказов для выдачи чеков без вмешательства администратора ИМ, например при оплате заказа покупателем
  • Pipeline - обработка очереди чеков когда сервер фискализации пробивает чеки не сразу
  • Connector - проверка введенных настроек на соответсвие данным на кассе
• компонентов (для дополнительного взаимодействия с MDK):
  • Settings
  • Storage

Инициализация

После того как все необходимые интерфейсы реализованы можно создавать объект Client:

// создание компонентов
$settings = new SettingsConcrete();
$storage = new ReceiptStorageConcrete(new ConverterStorage());
$adapter = new ReceiptAdapterConcrete();
$receiptIdFactory = new ReceiptIdFactoryMetaConcrete();

$transfer = new Transfer(
    new NetClientCurl(),
    new ConverterApi()
);

// создание сервисов
$automatic = new AutomaticBase(
    $settings,
    $storage,
    $transfer,
    $adapter,
    $receiptIdFactory
);
$pipeline = new PipelineBase($settings, $storage, $transfer, $receiptIdFactory);
$connector = new ConnectorBase($transfer);

// создание клиента
$mdk = new Client(
    $settings,
    $storage,
    $automatic,
    $pipeline,
    $connector
);

Настройки

Перед сохранением настроек необходимо проверить корректность введенных данных на соответствие данным на кассе:

// ассоциативный массив новых настроек введенных пользователем в интерфейсе сайта
$settings = [
    'actor_id' => 'actor_id',
    'actor_token' => 'actor_token',
    'cashbox' => 'cashbox',
    'site' => 'https://example.com/',
    'taxation' => Taxation::USN,
    'scheme' => SettingsInterface::SCHEME_PRE_FULL,
    'vat_shipping' => Vat::CODE_WITHOUT,
    'type_default_items' => ReceiptItemType::PRODUCT,
    'vat_default_items' => Vat::CODE_WITHOUT,
    'order_status_receipt_pre' => 'payed',
    'order_status_receipt_full' => 'delivered'
];

try {
    // формирование трансфера с указанием минимальных данных для соединения
    $transfer = new Transfer(
        new NetClientCurl(),
        new ConverterApi()
    );

    // создание коннектора и тестирование настроек
    $conn = new ConnectorBase($transfer);
    $conn->testSettings(new SettingsConcrete($settings));
} catch(SettingsException $e) {
    throw new Exception($e->getMessage());
}

Automatic

Автоматическая фискализация действует в контексте конкретного заказа.

Пример использования (список исключений, типы чеков):

try {
    $automatic = $mdk->serviceAutomatic();

    // автоматическое определение типа чека
    $automatic->fiscalize($idOrder);

    // указание конкретного типа чека, например полный расчет в момент передачи товара покупателю
    // automatic->fiscalize($idOrder, 's1', ReceiptSubType::FULL);
} catch(Exception $e) {
    throw $e;
}

Pipeline

Сервер фискализации может не сразу пробить чек по разным причинам, например ответив кодом 202. После чего необходимо узнать текущий статус чеков. Эту задачу решает Pipeline (PipelineBase базовая реализация PipelineInterface), методы которого должны запускаться (каждый в отдельном экземпляре) в планировщике задач (например через cron), желательно каждые 10 минут.

Существует несколько статусов чека, но все чеки со статусом подлежащим фискализации обработаются вместе.

Пример:

$pipeline = $mdk->servicePipeline();

// обновление статусов чеков
$pipeline->update();

Pipeline также обрабатывает 50x коды ответов, ответы подобного рода не должны быть, но для предсказуемости введена обработка.

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

Сервисы и компоненты могут выбрасывать исключения, это однозначно означает что операция не удалась и с теми же данными не пройдет, за исключением проблем со связью. Каждый объект выбрасывает свойственные ему исключения (подробнее в исходном коде интерфейсов/классов).

Ответсвенность за обработку исключений ложится на клиентский код.

Рекомендации:

• при автоматических действиях оповещать пользователя интеграции через email или другими доступными средствами

Разработка

Для разработки потребуется docker compose

Репозиторий содержит docker-compose.dev.yml для организации среды разработки MDK, состоит из двух контейнеров:

• mdk-backend - основан на php:7.1-cli с модификациями, внутри используется xdebug (2.8.1) для отладки и composer (2.2) для установки зависимостей разработки
• mdk-db - основан mysql:5.7 без модификаций (логин:пароль от БД root:root)

Запуск контейнеров:

./dev.sh

После запуска будет развернута изолированная среда со всем необходимым ПО для разработки MDK.

Запуск тестов исходного кода MDK:

./test.sh

Рекомендуемые расширения для VS Code (нужные настройки подгрузятся из конфига в репозитории):

• PHP Debug
• intelephense
• phpcs
• phpstan

Issues и Contributing

Если при использовании библиотеки у вас возникли проблемы, вы можете составить Issue.

Вы можете предложить свои изменения исходного кода, через Issue/Pull request.

Каждые внесенные изменения должны быть протестированы, а соответствующие тесты должны быть внесены в директорию с тестами.

Процент покрытия unit тестами должен составлять >= 98%

License

MIT