From cff6ec7216c7f04dda97b45ab35fc998786ea9bf Mon Sep 17 00:00:00 2001 From: slava Date: Mon, 25 May 2026 15:48:53 +0500 Subject: [PATCH] Add README with build instructions, architecture overview, and links to project documentation (docs/, BUILD.md, API specs, mock server, tutorials). Co-Authored-By: Claude Opus 4.7 (1M context) --- README.md | 136 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 136 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..30d217c --- /dev/null +++ b/README.md @@ -0,0 +1,136 @@ +# ARC Desktop + +Десктопное Qt6/C++ приложение для мониторинга и автоматизации Android-приложений мобильных банков через ADB. Принимает задачи с бэкенда (получение профиля/балансов, выписка по транзакциям, создание платежей), исполняет их в реальном приложении банка на подключённом устройстве и возвращает результат. + +> **Репозиторий:** `git@git.brtservice.io:BRT/arc.git` + +--- + +## Быстрый старт + +```bash +git clone git@git.brtservice.io:BRT/arc.git +cd arc + +# macOS +brew install qt tesseract leptonica +mkdir -p build && cd build +cmake .. -DCMAKE_BUILD_TYPE=Release +cmake --build . +./ARCDesktopProject +``` + +Подробнее — см. [BUILD.md](BUILD.md) (macOS + Windows). + +При первом запуске потребуется токен авторизации; настройки лежат в [`config.ini`](config.ini). + +--- + +## Документация + +Все актуальные материалы в каталоге [`docs/`](docs/). Точка входа — [docs/index.md](docs/index.md). + +### Архитектура и фичи + +| Документ | О чём | +|---|---| +| [docs/index.md](docs/index.md) | Общая схема приложения, потоки, технологии | +| [docs/events.md](docs/events.md) | Жизненный цикл задачи: API → БД → выполнение скриптом → отчёт | +| [docs/bank-setup-wizard.md](docs/bank-setup-wizard.md) | `BankSetupWizard` — мастер заведения банковского профиля (Ozon, Black, Dushanbe) | +| [docs/status-sync.md](docs/status-sync.md) | Синхронизация online/offline статусов устройств и сервиса | +| [docs/black_tasks.md](docs/black_tasks.md) | Скрипты для банка Black (Birbank) | +| [docs/ozon_tasks.md](docs/ozon_tasks.md) | Скрипты для Ozon | + +### Backend API + +| Документ | О чём | +|---|---| +| [docs/api/auth.md](docs/api/auth.md) | Логин, refresh, хранение токенов | +| [docs/api/profile.md](docs/api/profile.md) | `bank_profile` и `material` (карты) | +| [docs/api/device.md](docs/api/device.md) | Регистрация десктопов и Android-устройств, отправка скриншотов | +| [docs/api/task.md](docs/api/task.md) | Получение задач, отправка результатов | +| [docs/api/network.md](docs/api/network.md) | Полная карта HTTP-вызовов приложения | +| [docs/api/openapi.json](docs/api/openapi.json) | OpenAPI спецификация бэкенда | + +### Сборка и тесты + +| Документ | О чём | +|---|---| +| [BUILD.md](BUILD.md) | Сборка под macOS и Windows | +| [tests/mock_server/README.md](tests/mock_server/README.md) | Локальный mock-бэкенд для интеграционных тестов | +| [tests/mock_server/WINDOWS.md](tests/mock_server/WINDOWS.md) | Особенности запуска моков на Windows | +| [tutorials/ui_info.md](tutorials/ui_info.md) | Туториал по UI приложения | + +--- + +## Архитектура + +``` +MainWindow (Qt6 GUI) + ├── DeviceScreener (QThread) — опрос ADB-устройств, скриншоты + ├── EventHandler (QThread) — оркестратор задач, запуск bank-скриптов + └── NetworkService (QThread) — REST API + monitoring relay +``` + +``` +android// — автоматизация конкретного банка (ozon, black, dushanbe, ...) + ├── *Script.{h,cpp} — CommonScript, LoginAndCheckAccountsScript, PayByCardScript, GetLastTransactionsScript, ... + └── ScreenXmlParser — парсинг ADB UI dump + +android/adb/ — обёртка над adb (скриншот, tap, swipe, input, uiautomator dump) +android/ocr/ — Tesseract + утилиты поиска текста на скриншоте +android/dump/ — захват UI-дампов + +database/ — SQLite через DatabaseManager (singleton) + DAO-слой + Таблицы: devices → applications → accounts → transactions/events + +models/ — POCO: DeviceInfo, AccountInfo, EventInfo, TransactionInfo, ... +services/ — фоновые потоки (DeviceScreener, EventHandler, NetworkService, AppLogger, LogArchiveSender) +views/ — Qt-виджеты: MainWindow, DeviceWidget, BankSetupWizard, AccountWindow, ... +``` + +Полная диаграмма потоков и сигналов — [docs/index.md](docs/index.md), детально по задачам — [docs/events.md](docs/events.md). + +--- + +## Технологии + +- **Qt 6** (Widgets, Network, Sql, Xml) +- **C++17**, CMake (опционально Ninja) +- **SQLite** (через QtSql) +- **ADB** (платформенные бинари в `tools/adb/`) +- **Tesseract OCR** + Leptonica (`eng.traineddata`, `rus.traineddata`) + +Поддерживаемые банки (в текущем `config.ini`): **Ozon**, **Black** (Birbank), **Dushanbe City Bank**. Список расширяется через `[apps] list=` в [`config.ini`](config.ini). + +--- + +## Конфигурация + +Главный файл — [`config.ini`](config.ini): + +| Секция | Назначение | +|---|---| +| `[common]` | Версия, валюты, токен | +| `[apps] list=` | Активные банки | +| `[db] dbPath=` | Путь к SQLite (`./database/app_data.db`) | +| `[net]` | `apiBase`, пути ручек, мониторинг-релей | +| `[]` | `android_package_name`, `currency`, `country`, `app_version`, ... | + +Схема БД — [`migrations.sql`](migrations.sql) (5 таблиц). + +--- + +## Полезные пути + +- Логи приложения: `application.log` (в корне), архив отправляется через `LogArchiveSender` на `monitoringBase` +- ADB-бинари для Windows: `tools/adb/windows/` +- Тестовые скриншоты/XML: `assets//` +- Иконки и ресурсы: `images/`, `arc.icns`, `arc.ico`, `app.rc` + +--- + +## Скрипты бэкенда и операционные ссылки + +- Backend API (prod): см. `apiBase` в [`config.ini`](config.ini) +- Monitoring relay: `142.93.102.40:8080` — релеит `/monitoring/log` и `/monitoring/dump` в Telegram (systemd `arc-monitoring.service`)