Как написать драйвер

Новая интеграция платёжного провайдера — это код в smartcore-pci-software/drivers, написанный по единому контракту (см. Слой драйверов). Руками эту интеграцию с нуля никто не пишет: в репозитории есть агентский скилл /new-driver, который проводит задачу от постановки до страницы в Confluence, и его задача — не ускорить написание кода, а не дать его переписывать. Большинство переделок в старых интеграциях случались не из-за кода, а из-за вопроса, который не задали до него: коллекция Postman появлялась после кода, конвенция жила в голове ревьюера, авторизация у эндпоинта отличалась от заявленной в задаче.

Как запустить

Открываете задачу PROC на интеграцию провайдера или метода оплаты/выплаты в репозитории drivers и говорите агенту /new-driver (или просто «сделай драйвер под эту задачу» — скилл подхватывается и по описанию). Дальше скилл ведёт диалог сам: часть шагов он делает самостоятельно, часть — прямо спрашивает у вас, и от полноты этих ответов зависит, сколько раз код придётся переписывать на ревью.

Что скилл делает по шагам

Сначала контекст, а не код. Скилл читает AGENTS.md репозитория и, если провайдер уже встречался, страницу docs/providers/<provider>.md — она главный источник, если есть. Саму задачу читает через Jira MCP, включая подзадачи и комментарии: критерии приёмки почти всегда там, а не в основном описании.

Спрашивает исходные данные одним сообщением, до первой строки кода. Документация провайдера и её OpenAPI/Swagger, Postman-коллекции с примерами запросов (кладутся в docs/postman/ с вычищенными ключами), доступы в песочницу, две отдельные задачи DevOps на инфраструктуру PCI (домены провайдера в Network Firewall и IP колбэков в Cloudflare — по шаблонам из docs/templates/), и границы задачи: какие методы, валюты, стадийность, нужен ли refund/void.

Строит матрицу авторизации по эндпоинтам, не по провайдеру целиком. У одного API разные операции нередко авторизуются по-разному — платёж через Bearer-токен, выплата через OAuth 1.0a с RSA-подписью, и то же самое слово «токен» в задаче не гарантирует, что подойдёт один механизм на всё. Эту таблицу скилл показывает вам до того, как начнёт писать код: от неё зависит, сколько HTTP-клиентов нужно и как выглядит секрет гейта.

Согласует план стека PR до кода. Стандартная разбивка: отдельный PR на транспорт (DTO, авторизация, вызовы, тесты на моках — без лимита строк, если там нет бизнес-логики), отдельный на сам драйвер (initPayment, checkTransaction, processCallback, маппинг статусов), отдельные на дополнительные операции вроде refund или второго метода. Порядок PR и правила стека — общие для всех репозиториев, см. Как начать кодить.

Пишет код по конвенциям репозитория — драйвер живёт одним файлом, сумма и валюта берутся строго из processingFields, вебхук провайдера — только повод переспросить статус, а не источник финального результата, и так далее; полный список конвенций скилл держит в голове и проверяет перед каждым PR прогоном тестов конкретного провайдера.

Фиксирует формат секрета письменно — JSON с реальными именами полей, что обязательно и что опционально, команды для генерации ключей — в описание последнего PR и в docs/providers/, чтобы не отвечать на этот вопрос в чате повторно.

После мержа последнего PR — страница в Confluence (пространство PSP) — что интегрировано, флоу каждой операции, маппинг статусов, песочница, обе задачи DevOps на инфраструктуру, найденные грабли. Это и есть тот самый docs/providers/<provider>.md, вынесенный в общее пространство, где его увидят не только разработчики. До этого шага, впереди — ревью и тесты на стенде, см. ниже.

Перед ревью: единая ветка и тестовый стенд

Стек PR из предыдущего шага собран для удобства ревью, а не для того, чтобы так и уехать в main: несколько мелких PR ревьюер видит по отдельности, а протестировать интеграцию можно только целиком. Поэтому прежде чем отдавать задачу на ревью:

1. Соберите весь стек в одну ветку. Верхняя ветка стека уже содержит все нижние — слейте в неё main, если он успел уйти вперёд, и откройте из неё один PR в main. Промежуточные PR стека можно закрыть без мержа, как только этот финальный PR открыт и содержит весь их диф.
2. Разверните тестовый стенд с драйверами на этой ветке — как именно, описано в Создание тестового стенда.
3. Проведите операции на тестовых доступах провайдера — теми методами, которые интегрированы: платёж, 3DS, возврат, выплата. Если у провайдера нет песочницы, тестируют на реальных, но минимальных продовых доступах.
4. Только после успешных тестов отдавайте интеграцию на ревью. Ревьюер смотрит код, а не проверяет, работает ли она вообще, — эти вещи разделены сознательно.

Что от вас ожидается

Отвечать на вопросы скилла честно и полно, особенно на первом шаге: документация, Postman и доступы в песочницу, которых не хватило, догоняются на ревью гораздо дороже, чем если отдать их сразу. Матрицу авторизации стоит один раз прочитать целиком, а не пролистать — по ней проверяется вся дальнейшая реализация. Всё остальное — вопрос терпения: стек из нескольких PR рецензируется по частям, и это нормально, лимит на размер PR общий для всего workspace.