# Проверка интеграции QR API перед запуском

Применяйте этот список к своей площадке, сайту или Telegram-боту. Рабочий API:
`https://api.cashwellpay.com/api/v1`, полное руководство —
[API_INTEGRATION.md](../../API_INTEGRATION.md).

Первые проверки выполняйте без реальных запросов:

```sh
cd examples/partner_api/dart
dart pub get
dart analyze
dart run test/contract_test.dart
dart run bin/lifecycle_demo.dart
dart run test/lifecycle_demo_test.dart
```

Офлайн-сценарий использует MockClient и учебный `.example`-адрес. Рабочий
`bin/telegram_bot.dart`, напротив, создаёт настоящий счёт при запуске с production
ключом. Для проверки живого сервиса заранее согласуйте реальные данные и сумму.

## 1. Получение доступа и хранение заявки

- [ ] API-ключ находится в окружении backend; браузер, чат, ссылка изображения и
  платёжная страница его не получают. Секрет webhook хранится отдельно.
- [ ] Владелец локальной заявки определяется по проверенной пользовательской
  сессии или Telegram ID. При повторной выдаче проверяется эта же привязка.
- [ ] Исходный JSON, `external_id` и `Idempotency-Key` сохранены **до** первого POST.
  Эти значения восстанавливаются после остановки процесса.
- [ ] Один внешний ID никогда не используется для другой оплаты. Повторное
  нажатие «Получить QR» открывает сохранённую заявку.
- [ ] Полученный API `id` записывается в исходную локальную запись. HTTP `202`
  проверяется вместе с полем `status`: повтор может вернуть уже `ready` или `paid`.
- [ ] Предупреждение, полные ФИО, банк и сумма показаны пользователю до отправки.

## 2. Сценарии, которые должны пройти

| Проверка | Ожидаемый результат |
| --- | --- |
| Одинаковое подтверждение отправлено дважды | Один API `id`, одно локальное намерение и один платёжный счёт. |
| Сервер принял POST, ответ потерялся | Повтор прежнего тела и обоих ID возвращает тот же `id`. |
| Тот же ID отправлен с изменённой суммой | `409`; приложение предлагает сверить сохранённые данные, не подменяет ключ автоматически. |
| Новый Idempotency-Key с прежним external_id и теми же данными | Возвращается существующая заявка; новый ключ сам по себе не означает новый платёж. |
| Ответ `creating` | Пользователь видит ожидание; повторный счёт не создаётся. |
| Ответ `ready`, payment_url существует | Backend скачивает защищённый PNG; пользователю видны QR и кнопка оплаты. |
| Ответ `ready`, payment_url=null | Пользователь видит QR; нерабочей кнопки нет. |
| QR URL указывает на другой хост или отдаёт redirect | Bearer не пересылается; загрузка отклоняется. |
| Ответ `paid` | QR и кнопка убраны, заявка подтверждена, владельцу запланировано уведомление. |
| Оплаченный статус имеет generation_status=ready | Он всё равно считается оплаченным по основному `status`. |
| Дубликат корректно подписанного webhook | Событие подтверждено после устойчивой записи, повторного бизнес-действия нет. |
| Более старый sequence пришёл позже нового | Он не откатывает состояние заявки. |
| Два разных события paid для одной заявки | Обновляется одна проекция, второй независимой выплаты не создаётся. |
| paid → needs_review → paid | Удержание/сверка меняет ту же заявку; повторного основания на выплату нет. |
| expired, затем поздний paid | Сохранённая заявка обновляется и подтверждается, новый QR не создаётся. |
| Неверная подпись или старый timestamp | Событие не меняет заявку и расчёт. |
| БД недоступна при получении webhook | Возвращается временная ошибка, событие не помечено обработанным до COMMIT. |
| Процесс остановился после COMMIT, до ответа webhook | Повтор восстанавливается через уникальный event ID без второго действия. |
| Платёжное уведомление пришло раньше ответа исходного POST | Есть сохранённое намерение; событие сопоставляется с ним по своей интеграции и external_id. |
| Открыта чужая локальная заявка | Backend отклоняет доступ до скачивания QR и запроса статуса. |

Для сценариев с разрывом соединения, ошибками и повторными событиями используйте
тестовую подмену HTTP и подписанные фикстуры. Не создавайте неопределённые
повторные рабочие счета ради проверки.

## 3. Лимиты и восстановление

- [ ] Общий планировщик соблюдает текущие пределы: 120 аутентифицированных запросов
  на ключ в минуту и 20 новых принятых созданий в минуту. Учтены GET и PNG.
- [ ] `429` останавливает повтор до `Retry-After`; сетевые ошибки и `503` повторяются
  в фоне с теми же идентификаторами и ограниченной частотой.
- [ ] На одну заявку одновременно выполняется один опрос. Новый вход пользователя
  не порождает ещё один таймер.
- [ ] Перезапуск восстанавливает незавершённые POST, задачи GET, webhook-inbox и
  локальный outbox уведомлений.
- [ ] На lease стоит токен и срок; поздний ответ потерявшего аренду воркера не
  перезаписывает состояние. Событие во время GET помечает результат для повторной
  сверки.
- [ ] `needs_review` удерживает заявку и не вызывает автоматическую замену.
- [ ] После смены webhook URL/секрета выполнена сверка GET по своим сохранённым
  ID. Переключение webhook не считается полной выгрузкой истории.
- [ ] Пагинация offset используется для поиска и сверки, а не как единственный
  надёжный курсор изменений: новые заявки сдвигают страницы.

## 4. Расчёты

- [ ] Рубли, курс и USDT хранятся точными десятичными значениями либо целыми
  минимальными единицами; `double` не участвует в учёте денег.
- [ ] Для заявки используется её `expected_usdt`. Текущий `GET /rate` не меняет
  историческую цену; коэффициент 1,06 не применяется повторно к `trader_rate`.
- [ ] Неоплаченная заявка не увеличивает подтверждённый долг площадке.
- [ ] Поле `complete=false` ответа `GET /balance` отображается как неполный итог. Поля `null`
  не превращаются в ноль, известная часть не выдаётся за полный остаток.
- [ ] `complete=true` не означает, что все заявки закрыты: активные неоплаченные
  могут оставаться в системе без подтверждённого долга.
- [ ] Подтверждение оплаты, фактические выплаты платформы площадке и выплаты
  площадки своим трейдерам учитываются отдельно.
- [ ] Получение `paid` или webhook само не запускает незащищённый повторяемый
  перевод USDT. У фактического исполнения своя уникальность по заявке и журнал.

## 5. Наблюдаемость и первый рабочий запуск

В журнале достаточно ID своей интеграции/заявки, публичного API ID, кода ошибки,
номера попытки, event ID, sequence и возраста задачи. Не записывайте Bearer,
секрет webhook, Telegram-токен и полные заголовки запроса. Состояние файловых
примеров храните вне публичного каталога; для нескольких процессов применяйте
транзакционную БД из основного руководства.

Первый согласованный рабочий прогон завершён, когда выполняется вся цепочка:
сохранённое намерение → один API `id` → `ready` → PNG и корректная кнопка →
проверенный `paid` → одно локальное подтверждение → уведомление правильному
владельцу → сверка `/balance`. В журнале нет второго счёта и нет повторного
финансового исполнения после перезапуска.
