Замена DePay на FreeKassa и удаление системы проверки чеков
- Создан модуль FreeKassa с обработкой платежей, webhook, IP whitelist, MD5 подписью - Переписан frontend billing.tsx для формы оплаты FreeKassa - Удалены файлы и зависимости DePay (depay.routes.ts, @depay/widgets) - Полностью удалена система проверки чеков операторами: * Удален backend модуль /modules/check/ * Удалена frontend страница checkverification.tsx * Очищены импорты, маршруты, WebSocket события * Удалено поле checkId из Notification схемы * Удалены переводы для чеков - Добавлена поддержка спецсимволов в секретных словах FreeKassa - Добавлена документация PAYMENT_MIGRATION.md
This commit is contained in:
275
PAYMENT_MIGRATION.md
Normal file
275
PAYMENT_MIGRATION.md
Normal file
@@ -0,0 +1,275 @@
|
||||
# Миграция оплаты: DePay → FreeKassa
|
||||
|
||||
## ✅ Выполненные изменения
|
||||
|
||||
### Backend
|
||||
|
||||
1. **Создан новый модуль FreeKassa** (`backend/src/modules/payment/freekassa.routes.ts`)
|
||||
- ✅ Endpoint уведомлений: `GET /payment/freekassa/notification`
|
||||
- ✅ Успешная оплата: `GET /payment/freekassa/sucess`
|
||||
- ✅ Неудачная оплата: `GET /payment/freekassa/failure`
|
||||
- ✅ Создание платежа: `POST /payment/freekassa/create-payment`
|
||||
- ✅ История платежей: `GET /payment/freekassa/history`
|
||||
- ✅ IP whitelist проверка (4 IP FreeKassa)
|
||||
- ✅ MD5 подпись для формы и уведомлений
|
||||
|
||||
2. **Обновлен main router** (`backend/src/index.ts`)
|
||||
- ✅ Заменен импорт: `depayRoutes` → `freekassaRoutes`
|
||||
- ✅ Изменен маршрут: `/payment/depay` → `/payment`
|
||||
|
||||
3. **Обновлен .env** (`backend/.env`)
|
||||
- ✅ Удалены переменные DePay: `DEPAY_PUBLIC_KEY`, `DEPAY_FALLBACK_RATE`
|
||||
- ✅ Добавлены переменные FreeKassa (требуют заполнения):
|
||||
```env
|
||||
FK_MERCHANT_ID=YOUR_MERCHANT_ID
|
||||
FK_SECRET_WORD_1=YOUR_SECRET_WORD_1
|
||||
FK_SECRET_WORD_2=YOUR_SECRET_WORD_2
|
||||
```
|
||||
|
||||
4. **Удален старый модуль DePay**
|
||||
- ✅ Удален файл: `backend/src/modules/payment/depay.routes.ts`
|
||||
|
||||
5. **Обновлена схема Prisma** (`backend/prisma/schema.prisma`)
|
||||
- ✅ Удалено поле `checkId` из модели `Notification`
|
||||
- ⚠️ **Требуется миграция БД** (см. раздел "Развертывание")
|
||||
|
||||
6. **Очищены ссылки на систему чеков**
|
||||
- ✅ Удалено событие `check:status` из WebSocket events
|
||||
- ✅ Удалено поле `checkId` из notification controller
|
||||
- ✅ Удален модуль `backend/src/modules/check/`
|
||||
|
||||
### Frontend
|
||||
|
||||
1. **Переписан компонент оплаты** (`frontend/src/pages/dashboard/billing.tsx`)
|
||||
- ✅ Удален DePay виджет
|
||||
- ✅ Добавлена форма для редиректа на FreeKassa
|
||||
- ✅ Динамическое создание формы с подписью
|
||||
- ✅ Открытие оплаты в новой вкладке
|
||||
|
||||
2. **Обновлен package.json** (`frontend/package.json`)
|
||||
- ✅ Удалена зависимость: `@depay/widgets`
|
||||
|
||||
3. **Обновлен .env** (`frontend/.env`)
|
||||
- ✅ Удалена переменная: `VITE_DEPAY_INTEGRATION_ID`
|
||||
|
||||
4. **Удалена система проверки чеков**
|
||||
- ✅ Удален файл: `frontend/src/pages/dashboard/checkverification.tsx`
|
||||
- ✅ Удален импорт и маршрут из `mainpage.tsx`
|
||||
- ✅ Удалена вкладка из панели администратора
|
||||
- ✅ Удалено событие `check:status` из WebSocket
|
||||
- ✅ Удалено поле `checkId` из типов уведомлений
|
||||
- ✅ Удалены переводы для чеков (en.ts, ru.ts)
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Развертывание
|
||||
|
||||
### 1. Заполнить credentials FreeKassa
|
||||
|
||||
Откройте [merchant.freekassa.com](https://merchant.freekassa.com) → **Настройки** → **Магазины**
|
||||
|
||||
В файле `backend/.env` замените:
|
||||
```env
|
||||
FK_MERCHANT_ID=12345 # ID вашего магазина
|
||||
FK_SECRET_WORD_1=your_secret_1 # Секретное слово 1 (для формы)
|
||||
FK_SECRET_WORD_2=your_secret_2 # Секретное слово 2 (для уведомлений)
|
||||
```
|
||||
|
||||
### 2. Настроить URL в FreeKassa панели
|
||||
|
||||
В настройках магазина на FreeKassa укажите:
|
||||
|
||||
- **Result URL** (уведомления): `https://ospab.host/payment/freekassa/notification`
|
||||
- **Success URL**: `https://ospab.host/payment/freekassa/sucess`
|
||||
- **Failure URL**: `https://ospab.host/payment/freekassa/failure`
|
||||
|
||||
⚠️ **Важно**: В скриншоте была опечатка `/frekassa/` вместо `/freekassa/`. Убедитесь, что используете правильный путь!
|
||||
|
||||
### 3. Применить миграцию БД
|
||||
|
||||
После обновления `schema.prisma` нужно создать миграцию:
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
npx prisma migrate dev --name remove_checkid_field
|
||||
```
|
||||
|
||||
Или для production:
|
||||
```bash
|
||||
npx prisma migrate deploy
|
||||
```
|
||||
|
||||
### 4. Переустановить зависимости
|
||||
|
||||
```bash
|
||||
# Frontend
|
||||
cd ospabhost/frontend
|
||||
npm install
|
||||
|
||||
# Backend (если нужно)
|
||||
cd ../backend
|
||||
npm install
|
||||
```
|
||||
|
||||
### 5. Пересобрать проекты
|
||||
|
||||
```bash
|
||||
# Backend
|
||||
cd backend
|
||||
npm run build
|
||||
|
||||
# Frontend
|
||||
cd ../frontend
|
||||
npm run build
|
||||
```
|
||||
|
||||
### 6. Перезапустить сервисы
|
||||
|
||||
```bash
|
||||
# Если используется PM2
|
||||
pm2 restart all
|
||||
|
||||
# Или через systemd
|
||||
sudo systemctl restart ospab-backend
|
||||
sudo systemctl restart ospab-frontend
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Тестирование
|
||||
|
||||
### 1. Проверка создания платежа
|
||||
|
||||
```bash
|
||||
curl -X POST https://api.ospab.host/payment/freekassa/create-payment \
|
||||
-H "Authorization: Bearer YOUR_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"amount": 100}'
|
||||
```
|
||||
|
||||
Ожидаемый ответ:
|
||||
```json
|
||||
{
|
||||
"status": "success",
|
||||
"data": {
|
||||
"merchantId": "12345",
|
||||
"amount": 100,
|
||||
"orderId": "user123_1234567890",
|
||||
"signature": "abc123...",
|
||||
"currency": "RUB",
|
||||
"email": "user@example.com"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Проверка уведомлений (webhook)
|
||||
|
||||
FreeKassa отправит GET запрос на `/payment/freekassa/notification` с параметрами:
|
||||
- `MERCHANT_ID` - ID магазина
|
||||
- `AMOUNT` - сумма платежа
|
||||
- `intid` - ID транзакции FreeKassa
|
||||
- `MERCHANT_ORDER_ID` - ваш order ID
|
||||
- `SIGN` - MD5 подпись
|
||||
|
||||
Backend проверит:
|
||||
1. ✅ IP адрес отправителя (whitelist)
|
||||
2. ✅ MD5 подпись (через SECRET_WORD_2)
|
||||
3. ✅ Уникальность платежа (не был обработан ранее)
|
||||
4. ✅ Создаст запись в CryptoPayment
|
||||
5. ✅ Увеличит баланс пользователя
|
||||
6. ✅ Создаст транзакцию
|
||||
7. ✅ Отправит уведомление
|
||||
8. ✅ Вернет "YES"
|
||||
|
||||
### 3. Ручное тестирование
|
||||
|
||||
1. Войдите в личный кабинет
|
||||
2. Перейдите в раздел "Billing"
|
||||
3. Введите сумму (минимум 50 ₽)
|
||||
4. Нажмите "Пополнить"
|
||||
5. Откроется форма FreeKassa в новой вкладке
|
||||
6. Выберите способ оплаты и оплатите
|
||||
7. После оплаты FreeKassa отправит уведомление на backend
|
||||
8. Баланс должен автоматически обновиться
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Важные замечания
|
||||
|
||||
### Безопасность
|
||||
|
||||
1. **IP Whitelist**: Backend проверяет, что уведомления приходят только с IP FreeKassa:
|
||||
- `168.119.157.136`
|
||||
- `168.119.60.227`
|
||||
- `178.154.197.79`
|
||||
- `51.250.54.238`
|
||||
|
||||
2. **MD5 подпись**: Все уведомления проверяются на валидность подписи
|
||||
|
||||
3. **Идемпотентность**: Повторная обработка одного платежа блокируется
|
||||
|
||||
### Отличия от DePay
|
||||
|
||||
| Параметр | DePay | FreeKassa |
|
||||
|----------|-------|-----------|
|
||||
| Тип интеграции | Виджет (JavaScript) | Форма (POST redirect) |
|
||||
| Валюта | Криптовалюта | RUB |
|
||||
| Открытие | Модальное окно | Новая вкладка |
|
||||
| Callback | WebSocket | GET webhook |
|
||||
| Подпись | RSA | MD5 |
|
||||
|
||||
### База данных
|
||||
|
||||
Используется существующая таблица `CryptoPayment`:
|
||||
- `blockchain` = `'freekassa'`
|
||||
- `token` = `'RUB'`
|
||||
- `status` = `'completed'`
|
||||
|
||||
---
|
||||
|
||||
## 📝 Удаленные функции
|
||||
|
||||
### Система проверки чеков операторами
|
||||
|
||||
✅ **Полностью удалена**:
|
||||
- Backend модуль `/modules/check/`
|
||||
- Frontend страница `checkverification.tsx`
|
||||
- Маршруты и импорты в mainpage
|
||||
- WebSocket события `check:status`
|
||||
- Поле `checkId` в уведомлениях
|
||||
- Переводы для чеков
|
||||
- Вкладка в админ-панели
|
||||
|
||||
---
|
||||
|
||||
## 🔍 Логи для отладки
|
||||
|
||||
Backend логирует все этапы обработки платежа:
|
||||
|
||||
```bash
|
||||
# Посмотреть логи PM2
|
||||
pm2 logs ospab-backend --lines 100
|
||||
|
||||
# Grep для FreeKassa
|
||||
pm2 logs | grep FreeKassa
|
||||
```
|
||||
|
||||
Ключевые логи:
|
||||
- `[FreeKassa] Notification received` - получено уведомление
|
||||
- `[FreeKassa] IP check failed` - неверный IP
|
||||
- `[FreeKassa] Invalid signature` - неверная подпись
|
||||
- `[FreeKassa] Payment already exists` - дубликат
|
||||
- `[FreeKassa] Payment processed successfully` - успешно обработано
|
||||
|
||||
---
|
||||
|
||||
## 📞 Поддержка
|
||||
|
||||
Если возникли проблемы:
|
||||
|
||||
1. Проверьте логи backend: `pm2 logs ospab-backend`
|
||||
2. Проверьте настройки FreeKassa (URL, секретные слова)
|
||||
3. Убедитесь, что миграция БД применена
|
||||
4. Проверьте, что переменные окружения заполнены
|
||||
|
||||
**Документация FreeKassa**: [wiki.freekassa.com](https://wiki.freekassa.com/)
|
||||
Reference in New Issue
Block a user