# 💳 Skill: safe-paymaster (v3.0 - Universal SBP Controller)

**`safe-paymaster`** — это специализированный модуль «Финансового контролера», отвечающий за безопасное завершение процесса покупки. Скилл ориентирован на работу с Системой быстрых платежей (СБП), обеспечивая пользователю максимальное удобство оплаты при нулевом риске компрометации банковских карт.

## 1. Роль в системе
Скилл является «Кассиром», который вступает в работу только после того, как «Бухгалтер» (`universal-shopper`) подтвердил состав корзины и зафиксировал контракт в файле `/app/workspace/cart_state.json`.

## 2. Ключевые принципы

### 🌍 Универсальность (Any-Merchant Support)
В отличие от предыдущих версий, текущая архитектура позволяет агенту работать на **любом легитимном интернет-магазине**, выбранном пользователем. Безопасность перенесена с фильтрации магазинов на строгую валидацию **платежных шлюзов**.

### 🤝 Протокол сосуществования (Card & SBP Coexistence)
Агент обучен корректно вести себя на современных платежных страницах:
*   **Игнорирование:** Наличие полей для ввода данных банковских карт (номер, CVC, срок действия) на одной странице с выбором СБП воспринимается как нормальное поведение сайта.
*   **Фокус:** Агент целенаправленно ищет и активирует только методы оплаты через СБП, Mir Pay или кнопку "Оплатить через приложение банка".
*   **Hard Stop:** Агенту КАТЕГОРИЧЕСКИ запрещено вводить любые символы в поля ввода реквизитов карт.

### 🔍 Глубокий поиск SBP-данных (Deep Discovery)
Поскольку Исполнитель (`internet_browser`) работает без Vision (зрения), извлечение ссылки на оплату происходит комбинированным методом:
1.  **DOM Parsing:** Поиск ссылки `https://qr.nspk.ru/...` в скрытых атрибутах кнопок и тегах `<script>`.
2.  **Python OCR Fallback:** Если ссылка скрыта внутри QR-кода (картинка/canvas), агент делает скриншот и «под капотом» использует Python-библиотеку `pyzbar` для мгновенного декодирования изображения в текстовый URL.
3.  **Результат:** Пользователь получает в Telegram готовую кликабельную ссылку, которая открывает банковское приложение в один тап.

## 3. Трехуровневая защита (Last Mile Security)

1.  **Валидация шлюза:** Проверка домена платежной страницы по белому списку доверенных банковских систем (`*.nspk.ru`, `*.sberbank.ru`, `*.tinkoff.ru` и др.).
2.  **Контроль суммы:** Финальная сверка суммы «Итого» прямо с экрана оплаты. Если сумма на шлюзе превышает максимально одобренную (`pricing.standard`) из файла состояния, транзакция немедленно блокируется.
3.  **Изоляция данных:** Агент никогда не видит и не запрашивает СМС-коды подтверждения. Оплата через СБП подразумевает подтверждение пользователем в его собственном банковском приложении.

## 4. Цифровая гигиена (History & Cleanup)

Скилл полностью автоматизирует управление историей покупок:
*   **Архивация:** После успешной отправки ссылки в Telegram, текущий файл состояния копируется в директорию `/app/workspace/orders_history/` с уникальной меткой времени.
*   **Обнуление:** Основной файл `cart_state.json` очищается, что переводит систему в статус `EMPTY` и готовит агента к новому циклу поиска товаров без конфликта данных.

## 5. Взаимодействие с пользователем
Агент минимизирует технический шум. Финальное сообщение содержит только:
*   Подтвержденную сумму к списанию.
*   Прямую ссылку на оплату СБП.
*   Статус сохранения заказа в историю.

---
**Окружение:** WSL2 / Docker / Qwen 3.5-122b