From 9a68c083e352c3cd2d2dacb4cce01031137e0e51 Mon Sep 17 00:00:00 2001 From: mguschin Date: Tue, 10 Mar 2026 17:02:14 +0300 Subject: [PATCH] Update README with comprehensive project documentation Co-Authored-By: Claude Sonnet 4.6 --- README.md | 161 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 159 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 23f40f6..94f8986 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,160 @@ -# evo-sync +# ЭВОСИНК (EvoSync) -evo-sync is a command-line synchronization tool that fetches product, group, and store data from the Evo platform and syncs it with VK (VKontakte). +Сервис автоматической синхронизации товарного каталога из [Эвотор](https://evotor.ru) в [ВКонтакте](https://vk.com). + +## Возможности + +- Подключение аккаунта Эвотор через OAuth +- Подключение сообщества ВКонтакте через токен +- Фильтрация по магазинам, группам и товарам (включить/исключить) +- Автоматическая фоновая синхронизация по расписанию +- Создание, обновление и удаление товаров в ВК-магазине +- Личный кабинет с веб-интерфейсом +- Просмотр закешированного каталога товаров + +## Стек технологий + +- **Backend**: FastAPI, SQLAlchemy ORM, Alembic +- **База данных**: MariaDB (драйвер pymysql) +- **Шаблоны**: Jinja2 (интерфейс на русском языке) +- **Аутентификация**: Cookie-сессии, bcrypt +- **Деплой**: Docker Compose + +## Быстрый старт + +### Требования + +- Docker и Docker Compose +- MariaDB/MySQL (можно использовать хост-машину или отдельный контейнер) + +### Настройка + +1. Скопируйте файл переменных окружения: + +```bash +cp .env.example .env +``` + +2. Отредактируйте `.env`: + +```env +# База данных +DATABASE_URL=mysql+pymysql://evosync:evosync@db:3306/evosync + +# Безопасность (обязательно измените в production) +SECRET_KEY=your-random-secret-key-here + +# URL приложения (используется в OAuth-редиректах) +BASE_URL=https://your-domain.ru + +# Эвотор +EVOTOR_APP_ID=your-evotor-app-id +EVOTOR_WEBHOOK_SECRET=your-webhook-secret + +# Для отдельного MySQL-контейнера (опционально) +DB_ROOT_PASSWORD=rootpass +DB_NAME=evosync +DB_USER=evosync +DB_PASSWORD=evosync +``` + +3. Запустите сервис: + +```bash +docker compose up -d +``` + +Приложение будет доступно по адресу `http://localhost:8080`. + +При старте контейнер автоматически применяет миграции базы данных (`alembic upgrade head`). + +## Переменные окружения + +| Переменная | Обязательно | По умолчанию | Описание | +|---|---|---|---| +| `DATABASE_URL` | Да | — | MySQL connection string (pymysql) | +| `SECRET_KEY` | Да | `change-me-in-production` | Ключ для подписи сессий | +| `BASE_URL` | Да | `http://localhost:8080` | Публичный URL (для OAuth-callback) | +| `EVOTOR_APP_ID` | Да | — | ID приложения Эвотор | +| `EVOTOR_WEBHOOK_SECRET` | Да | — | Секрет для верификации вебхуков Эвотор | +| `VK_API_VERSION` | Нет | `5.131` | Версия VK API | +| `VK_DEFAULT_PHOTO_PATH` | Нет | `/app/default_product.png` | Путь к изображению товара по умолчанию | +| `JIVOSITE_WIDGET_ID` | Нет | — | ID виджета Jivosite (онлайн-чат) | +| `SYNC_INTERVAL_SECONDS` | Нет | `3600` | Интервал синхронизации (сек) | +| `CATALOG_REFRESH_INTERVAL_SECONDS` | Нет | `3600` | Интервал обновления каталога (сек) | +| `HEALTH_CHECK_INTERVAL_SECONDS` | Нет | `600` | Интервал проверки соединений (сек) | + +## Структура проекта + +``` +evo-sync/ +├── web/ +│ ├── main.py # FastAPI-приложение, регистрация роутеров, фоновые задачи +│ ├── config.py # Настройки из переменных окружения (pydantic-settings) +│ ├── models.py # SQLAlchemy-модели (User, EvotorConnection, VkConnection, ...) +│ ├── database.py # Движок и сессия SQLAlchemy +│ ├── auth.py # Хеширование паролей, работа с сессиями +│ ├── schemas.py # Pydantic-схемы для форм +│ ├── sync_engine.py # Фоновый движок синхронизации (Эвотор → ВК) +│ ├── routes/ +│ │ ├── auth.py # Регистрация, вход, выход, подтверждение email +│ │ ├── profile.py # Профиль пользователя +│ │ ├── reset.py # Сброс пароля +│ │ ├── evotor.py # OAuth-подключение Эвотор +│ │ ├── vk.py # Подключение ВКонтакте (ввод токена) +│ │ ├── connections.py # Обзор всех подключений +│ │ ├── sync.py # Настройка и управление синхронизацией +│ │ └── catalog.py # Просмотр закешированного каталога +│ ├── templates/ # Jinja2-шаблоны (русский интерфейс) +│ └── migrations/ # Alembic-миграции +├── Dockerfile.web # Docker-образ веб-приложения (Python 3.12-slim) +├── docker-compose.yml # Оркестрация сервисов +├── docker-entrypoint.sh # Скрипт запуска контейнера +├── alembic.ini # Конфигурация миграций +├── requirements.txt # Python-зависимости +└── .env.example # Шаблон переменных окружения +``` + +## Модели базы данных + +| Модель | Таблица | Назначение | +|---|---|---| +| `User` | `users` | Аккаунт пользователя | +| `EvotorConnection` | `evotor_connections` | OAuth-токен Эвотор | +| `VkConnection` | `vk_connections` | Токен сообщества ВКонтакте | +| `SyncConfig` | `sync_configs` | Настройки синхронизации пользователя | +| `SyncFilter` | `sync_filters` | Фильтры по магазинам/группам/товарам | +| `CachedStore` | `cached_stores` | Кеш магазинов Эвотор | +| `CachedGroup` | `cached_groups` | Кеш групп товаров Эвотор | +| `CachedProduct` | `cached_products` | Кеш товаров Эвотор + статус синхронизации | + +## Как работает синхронизация + +1. По расписанию (каждые `SYNC_INTERVAL_SECONDS` секунд) запускается `sync_engine.run_sync()` +2. Для каждого пользователя с активным `SyncConfig` и подключёнными Эвотор и ВК: + - Загружаются товары и группы из Эвотор API + - Применяются фильтры (включить/исключить магазины, группы, товары) + - Загружаются текущие товары и альбомы из ВК + - Создаются/обновляются/удаляются альбомы и товары в ВК-магазине + - В БД обновляется поле `synced_at` у синхронизированных товаров + +**Особенности:** +- Товары на развес (единицы измерения в граммах) получают скорректированную цену (×10) +- Совпадение товаров ВК и Эвотор происходит по нормализованному названию +- Товары с `allow_to_sell=false` не синхронизируются в ВК + +## Разработка + +Для локальной разработки с горячей перезагрузкой кода папка `./web` монтируется в контейнер как volume. После изменения Python-файлов uvicorn перезапустится автоматически. + +Создание новой миграции: + +```bash +docker compose exec web alembic revision --autogenerate -m "описание изменений" +``` + +Применение миграций вручную: + +```bash +docker compose exec web alembic upgrade head +```