feat(core): add payment attempt lifecycle and webhook callback

[Ibochkarev]

Описание

У заказа был только status_id. Async-провайдеру некуда было сохранить external_id, и в core не было общего webhook-входа.

Появились таблицы ms3_payment_attempts и ms3_payment_attempt_events (уникальные (payment_method_id, provider, external_id) и (attempt_id, event_type, provider_event_id)), сервис PaymentLifecycleService (DI ms3_payment_lifecycle) и публичный POST /api/v1/payment/webhook/{payment_method_id} без customer token. Тело только raw JSON, не $_POST. Невалидный JSON даёт 400, необработанный Throwable — 500 и запись в лог.

Смена статуса заказа идёт только через OrderStatusChanger. Провайдеры не пишут status_id. Повторный успешный callback идемпотентен: unique event в одной транзакции с UPDATE попытки (writeWithEvent), затем ensure(). Если заказ уже в целевом статусе, ensure() не вызывает change() — replay paid на fixed-статусе не даёт 409.

Статусы попытки: pending, authorized, paid, failed, cancelled, refunded, partially_refunded. DefaultPayment attempt не создаёт: в send() нет payment_id / external_id. Политики ms3_payment_on_failed_status и ms3_payment_on_refunded_status (по умолчанию 5, 0 оставляет заказ).

getPaymentLink идёт через PaymentService::resolvePaymentLink: ссылка открытой попытки этого метода (pending/authorized), иначе send() + initiate(). Если initiate() после успешного send() упал, checkout получает success => false и ms3_err_payment_attempt_record. apply() и refund() коммитят одинаково: writeWithEvent → ensure().

Webhook paid / refunded / partially_refunded требуют non-empty externalId и paid ещё amount. Если в webhook есть currency, она должна совпасть с attempt. Paid amount = attempt amount, attempt amount = текущий order.cost. Refund требует provider event id. Over-refund не режется молча. external_id чужого метода не закрывает текущую попытку. Attempt на callback не создаётся с нуля. resolveAttempt только читает: external_id пишется в commit.

Секреты msPayment.properties убраны из OrdersPageService, ms3_get_order и писем (PaymentPublicFields). Эталонный HMAC: PaymentWebhookHmac и Payment::verifyWebhookHmac() (secret из properties secret / secret_key / webhook_secret, затем ms3_payment_secret). Конкретный эквайер в этот PR не входит.

Тип изменений

• Новая функциональность (non-breaking change)

Связанные Issues

Closes #590

Как это было протестировано?

Локальный CI-гейт (без полной установки MODX/MySQL):

cd core/components/minishop3
composer ci:php
# php -l 648 files, exit 0
# smoke 90, exit 0
# PHPUnit 294 tests, 708 assertions, 9 skipped (@group mysql without DSN), 2 deprecations, exit 0

composer stan:prepare && composer stan
# [OK] No errors, exit 0

Vue не менялся, npm run lint:ci не запускался.

• Автоматические тесты (composer ci:php, composer stan)
• Ручное тестирование webhook с реальным провайдером
• Тестирование на разных версиях PHP/MODX

Конфигурация тестирования:

• MiniShop3: ветка feat/issue-590-payment-lifecycle от beta (коммиты 11721446, e7dcb7b0, b2ccc755)
• MODX: не поднимался
• PHP: 8.4.17

Скриншоты (если применимо)

N/A, backend/API.

Чеклист

• Код соответствует стилю проекта
• Добавлены/обновлены комментарии в сложных местах
• Изменения не ломают существующую функциональность (PaymentProviderInterface и DefaultPayment без изменений контракта send/receive)
• Лексиконы добавлены на двух языках (ru/en)
• PHPStan проходит без новых ошибок (composer stan)
• ESLint (npm run lint:ci) — N/A, Vue не тронут
• CHANGELOG.md — не трогал, запись на релиз

Дополнительные заметки

Контракт провайдера: PaymentWebhookHandlerInterface::verifyWebhook($rawBody, $payload, $headers, $method) + PaymentLifecycleService. Старые провайдеры с собственным webhook продолжают работать. Новый вход opt-in.

Fenom-чанки, которые читали payment.properties, больше не получают секреты. Это цель AC.

Follow-up b2ccc755 закрывает blocker/high из ревью #604: replay на fixed, атомарный commit, currency, stale cost, externalId для финансовых событий, read-only resolveAttempt, без partialRefund().

Вне scope этого issue: конкретный эквайер, 3DS, UI попыток в менеджере, timeout pending, #569 payment/list.

[AgelxNash]

Этот PR включён в тестовую интеграционную сборку всех открытых PR MiniShop3: AgelxNash/MiniShop3, ветка integration/open-prs-20260906 (28/28 открытых).

Сборка нужна, чтобы проверить совместимость взаимозависимых серий PR до их мержа — при последовательном слиянии они конфликтуют друг с другом. Это не ревью и не конкурирующий PR: авторство сохранено (1 PR = 1 коммит с исходным автором), ветка пересобирается по мере обновления PR.

Как вошёл в сборку: Конфликт разрешён: ensure() добавлен — OrderStatusService реализует контракт OrderStatusChanger поверх lifecycle gate #596 и inventory #603; в карте зависимостей ms3_payment_lifecycle → ms3_order_status; docblock-пример Payment::receive() переключён на PaymentLifecycle API (сторона этого PR).

[AgelxNash]

Привет! Просто пожелание: удачи с этим PR 🚀 Работа нужная — пусть рассмотрят и смержат как можно скорее. Успехов!