arc/tests/mock_server/WINDOWS.md

# Запуск тестов на Windows

## Оглавление

1. [Быстрый старт](#1-быстрый-старт)
2. [Вспомогательные скрипты](#2-вспомогательные-скрипты)
3. [Генерация FETCH_TRANSACTIONS задач](#3-генерация-fetch_transactions-задач)
4. [Ручной запуск (пошагово)](#4-ручной-запуск-пошагово)
5. [Мониторинг и отчёт](#5-мониторинг-и-отчёт)
6. [Ручной инжект задач](#6-ручной-инжект-задач)
7. [ADB на Windows](#7-adb-на-windows)
8. [Типовые проблемы](#8-типовые-проблемы)
9. [Быстрый чеклист](#9-быстрый-чеклист)

---

## 1. Быстрый старт

```powershell
cd tests\mock_server
powershell -ExecutionPolicy Bypass -File setup.ps1
```

Скрипт `setup.ps1` автоматически:
1. Проверяет / устанавливает **Python 3.12+** (через winget)
2. Устанавливает **Flask**
3. Создаёт вспомогательные скрипты `gen_transactions.ps1` и `run_server.ps1`
4. Находит `config.ini` и проверяет **базу данных**
5. Удаляет старые сгенерированные данные (профиль + scenarios, пул не трогает)
6. Генерирует `default_profile.json` и FETCH_PROFILE scenarios из БД
7. Если порт занят — убивает старый процесс
8. Переключает `config.ini` на mock (`apiBase=http://127.0.0.1:8888`)
9. Показывает сводку: устройства, профили, материалы, пул транзакций
10. Запускает mock-сервер и открывает HTML-отчёт в браузере

При первом логине ARC мок автоматически ставит **FETCH_PROFILE** задачи
на каждый материал. **FETCH_TRANSACTIONS** задачи нужно генерировать отдельно
(см. [раздел 3](#3-генерация-fetch_transactions-задач)).

### Параметры

| Параметр | По умолчанию | Описание |
|---|---|---|
| `-Port` | 8888 | Порт mock-сервера |
| `-FtPerMaterial` | 3 | FETCH_TRANSACTIONS на материал при бутстрапе (из пула) |
| `-Banks` | все | Банки через запятую: `ozon`, `dushanbe_city_bank`, `black` |
| `-SkipInstall` | — | Пропустить установку Python/Flask |
| `-GenerateOnly` | — | Только сгенерировать данные, не запускать сервер |
| `-Clean` | — | Также очистить пул транзакций (`scenarios/pool/`) |

### Примеры

```powershell
# Всё автоматически (установка + генерация + запуск)
.\setup.ps1

# На другом порту с 5 транзакциями на материал
.\setup.ps1 -Port 9999 -FtPerMaterial 5

# Только Ozon
.\setup.ps1 -Banks ozon

# Только Dushanbe, по 2 транзакции
.\setup.ps1 -Banks dushanbe_city_bank -FtPerMaterial 2

# Ozon + Dushanbe
.\setup.ps1 -Banks ozon,dushanbe_city_bank

# Пропустить установку (Python/Flask уже есть)
.\setup.ps1 -SkipInstall

# Только подготовить данные, сервер не запускать
.\setup.ps1 -GenerateOnly

# Полная очистка (включая пул транзакций)
.\setup.ps1 -Clean
```

---

## 2. Вспомогательные скрипты

После первого запуска `setup.ps1` в папке `tests\mock_server\` появляются
скрипты с зашитым путём до Python — искать `python.exe` вручную не нужно:

| Скрипт | Назначение | Запуск |
|---|---|---|
| `gen_transactions.ps1` | Генерация FETCH_TRANSACTIONS с устройства | `powershell -ExecutionPolicy Bypass -File gen_transactions.ps1` |
| `run_server.ps1` | Запуск mock-сервера | `powershell -ExecutionPolicy Bypass -File run_server.ps1` |
| `setup.ps1` | Полная установка + генерация + запуск | `powershell -ExecutionPolicy Bypass -File setup.ps1` |

Скрипты принимают дополнительные аргументы, которые передаются в Python-скрипт:

```powershell
# Генерация с явным серийником
powershell -ExecutionPolicy Bypass -File gen_transactions.ps1 --serial 28291FDH300712

# Запуск сервера на другом порту
powershell -ExecutionPolicy Bypass -File run_server.ps1 --port 9999
```

---

## 3. Генерация FETCH_TRANSACTIONS задач

FETCH_TRANSACTIONS задачи генерируются **только вручную** с живого устройства.
Скрипт подключается по ADB, проходит по списку транзакций на экране
(тап -> снятие суммы/даты -> назад) и сохраняет JSON-файлы в `scenarios/pool/`.

### Подготовка

1. Подключите устройство по USB
2. Убедитесь что ADB видит устройство:
   ```powershell
   tools\adb\windows\adb.exe devices
   # Должно показать серийник со статусом "device"
   ```
3. Откройте на устройстве банковское приложение на экране **списка транзакций**
   - Ozon: раздел "Операции" -> список переводов/пополнений
   - Dushanbe City Bank: раздел "Операции" -> список P2P операций

### Запуск

```powershell
# Через вспомогательный скрипт (рекомендуется)
cd tests\mock_server
powershell -ExecutionPolicy Bypass -File gen_transactions.ps1

# Или напрямую (если Python в PATH)
python tests\mock_server\gen_fetch_transactions.py
```

Скрипт:
1. Покажет меню с активными материалами:
   ```
   Available materials (3):
     1. Pixel 7 / ozon / Галина Терехина (material 30bc106c... serial=28291FDH30xxxx)
     2. Pixel 7 / dushanbe_city_bank / Мехрубон (material 61d967d1...)
     3. TECNO KM4 / ozon / Владислав Касаткин (material 49001bb5...)
   Pick [1-3] or 'all':
   ```
2. Выберите нужный материал (номер) или `all` для всех
3. Скрипт попросит подтвердить что список транзакций открыт -> нажмите **Enter**
4. Автоматически пройдёт по каждой транзакции на экране (**не трогайте телефон!**)
5. Сохранит задачи в `scenarios/pool/`
6. Если mock-сервер запущен — сразу инжектнёт задачи в него

### Флаги

| Флаг | Описание |
|---|---|
| `--serial 28291FDH30xxxx` | Явный ADB-серийник (если несколько устройств) |
| `--kopecks 100` | Множитель суммы (по умолчанию 100: рубли -> копейки) |
| `--config path` | Путь к config.ini |

### Примеры

```powershell
# Интерактивный выбор материала
powershell -ExecutionPolicy Bypass -File gen_transactions.ps1

# Для конкретного устройства
powershell -ExecutionPolicy Bypass -File gen_transactions.ps1 --serial 28291FDH300712

# С другим config
powershell -ExecutionPolicy Bypass -File gen_transactions.ps1 --config cmake-build-debug\config.ini
```

### Результат

После генерации в `scenarios/pool/` появятся файлы вида:
```
pixel_7_ozon_ft_01_plus_15000_143022.json
pixel_7_ozon_ft_02_minus_500_150133.json
tecno_km4_ozon_ft_01_plus_3000_091500.json
```

Каждый файл содержит задачу с реальной суммой (в копейках) и временем (UTC):
```json
{
  "bank_name": "ozon",
  "material_id": "30bc106c-6935-4f4b-85f3-f1a06adc5c13",
  "type": "FETCH_TRANSACTIONS",
  "body": {
    "amount": 1500000,
    "created_at": "2026-04-10T11:30:22Z"
  }
}
```

При следующем запуске `setup.ps1` пул сохраняется (если не указать `-Clean`),
и мок будет раздавать задачи из него при бутстрапе.

---

## 4. Ручной запуск (пошагово)

Если не хотите использовать `setup.ps1`:

### 4.1. Установка зависимостей

```powershell
# Python 3.9+ (если нет — скачать с python.org, включить «Add to PATH»)
python --version

# Flask
pip install flask
```

### 4.2. Подготовка config.ini

В `config.ini` (рядом с `ARC.exe`) переключить `apiBase`:

```ini
[net]
apiBase=http://127.0.0.1:8888
```

> Совет: держите копию `config.ini.mock`, а перед тестом
> `copy config.ini.mock config.ini`.

### 4.3. Генерация профиля из БД

```powershell
# Из корня проекта
python tests\mock_server\gen_mock_data.py
```

Создаёт `default_profile.json` и FETCH_PROFILE scenarios.

### 4.4. Генерация пула транзакций (опционально)

См. [раздел 3](#3-генерация-fetch_transactions-задач).

### 4.5. Запуск mock-сервера

```powershell
cd tests\mock_server
python mock_server.py --port 8888
```

Должны увидеть:
```
[mock] state cleared — starting fresh
[mock] loaded default_profile.json: 3 bank_profiles, 3 materials
[mock] loaded pool: 19 FETCH_TRANSACTIONS across 3 materials
 * Running on http://127.0.0.1:8888
```

### 4.6. Запуск ARC

В отдельном терминале:

```powershell
cd build\Release
ARC.exe
```

Или через CLion: Run -> ARC.

При логине мок автоматически ставит задачи:
- 1 x FETCH_PROFILE на каждый материал (всегда)
- N x FETCH_TRANSACTIONS из пула (если пул не пуст)

Задачи раздаются по 1 на material за поллинг — следующая только
после результата предыдущей.

---

## 5. Мониторинг и отчёт

```powershell
# Открыть отчёт в браузере (авто-обновление каждые 2 сек)
start http://127.0.0.1:8888/_admin/report/html

# Счётчики
curl -s http://127.0.0.1:8888/_admin/state

# Полный JSON-отчёт
curl -s http://127.0.0.1:8888/_admin/report
```

Если `curl` нет, используйте PowerShell:

```powershell
# Счётчики
(Invoke-WebRequest http://127.0.0.1:8888/_admin/state).Content | ConvertFrom-Json

# Полный отчёт в файл
Invoke-WebRequest http://127.0.0.1:8888/_admin/report -OutFile report.json
```

На главной странице отчёта (`/_admin/report/html`) отображаются:
- Счётчики задач (всего / выполнено / в очереди)
- **Загруженные данные** — устройства, профили, материалы с количеством задач в пуле (группировка по устройствам)
- Задачи с результатами, сгруппированные по устройствам

---

## 6. Ручной инжект задач

```powershell
# Одна задача из файла
curl -X POST http://127.0.0.1:8888/_admin/inject ^
  -H "Content-Type: application/json" ^
  --data-binary @scenarios\pixel_7_ozon_fetch_profile.json

# N случайных из пула
python inject_random.py --count 5

# Повторный бутстрап (1 FP + N FT на material)
curl -X POST http://127.0.0.1:8888/_admin/bootstrap

# Сброс (очистка очереди + результатов)
curl -X POST http://127.0.0.1:8888/_admin/reset
```

---

## 7. ADB на Windows

ARC использует ADB из `tools\adb\windows\`. Проверка:

```powershell
tools\adb\windows\adb.exe devices
```

Должно показать устройства в статусе `device`.

Если ADB занят другим процессом (Android Studio, scrcpy):
```powershell
tools\adb\windows\adb.exe kill-server
tools\adb\windows\adb.exe start-server
tools\adb\windows\adb.exe devices
```

---

## 8. Типовые проблемы

| Проблема | Решение |
|---|---|
| `python` не найден | Запустите `setup.ps1` — установит автоматически. Или используйте скрипты `gen_transactions.ps1` / `run_server.ps1` — в них путь уже зашит |
| Порт 8888 занят | `setup.ps1` убивает старый процесс автоматически. Вручную: `netstat -ano \| findstr :8888` -> `taskkill /PID <pid> /F` |
| `curl` нет | `Invoke-WebRequest` (PowerShell) или `winget install curl` |
| Firewall блокирует | Разрешить `python.exe` в Windows Firewall. Мок слушает только `127.0.0.1` |
| ARC не видит устройства | Проверить USB-драйверы, включить USB debugging, подтвердить RSA-ключ |
| Кракозябры в консоли | `chcp 65001` перед запуском (UTF-8). Скрипты `.ps1` делают это автоматически |
| BOM в config.ini | `setup.ps1` пишет без BOM. Если правили вручную — пересохраните в UTF-8 без BOM (VS Code) |
| No active materials | БД пустая. Запустите ARC с боевым сервером, залогиньтесь, добавьте устройства |
| Пул транзакций пуст | Сгенерируйте: [раздел 3](#3-генерация-fetch_transactions-задач) |
| `No ADB devices match` | Устройства не подключены или serial не совпадает с БД. Проверьте `adb devices` |
| SSL ошибки при сборке | OpenSSL DLL копируются автоматически через CMake post-build |

---

## 9. Быстрый чеклист

```
[ ] powershell -ExecutionPolicy Bypass -File setup.ps1
[ ] Устройства в adb devices -> device
[ ] (опционально) powershell -ExecutionPolicy Bypass -File gen_transactions.ps1
[ ] ARC.exe запущен (отдельный терминал)
[ ] Браузер: http://127.0.0.1:8888/_admin/report/html
[ ] Дождаться completed = всего в отчёте
[ ] Вернуть config.ini: apiBase=http://93.183.75.134:8005
```