ospab.host/PAYMENT_MIGRATION.md

# Миграция оплаты: 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/)