init

2026-03-27 03:36:08 +03:00
parent 8a97ce6d54
commit cda36918e8
225 changed files with 35641 additions and 0 deletions
--- a/docs/BACKUP.md
+++ b/docs/BACKUP.md
@@ -0,0 +1,49 @@
+# PostgreSQL Auto Backup
+
+В проект добавлен сервис `postgres-backup` в [docker-compose.yml](/C:/Users/vlad/Documents/Projects/alpinbet-parser/docker-compose.yml).
+
+Что делает сервис:
+
+- по расписанию запускает `pg_dump` основной БД
+- при `BACKUP_INCLUDE_CHAT_DB=true` также архивирует chat-БД
+- сохраняет архивы в папку `./backups`
+- удаляет архивы старше `BACKUP_RETENTION_DAYS`
+
+Настройки в `.env`:
+
+```env
+BACKUP_TZ=Europe/Moscow
+BACKUP_INTERVAL_SECONDS=86400
+BACKUP_RETENTION_DAYS=7
+BACKUP_GZIP_LEVEL=6
+BACKUP_INCLUDE_CHAT_DB=true
+```
+
+Запуск:
+
+```bash
+docker compose up -d postgres-backup
+```
+
+Проверка логов:
+
+```bash
+docker compose logs --tail=100 postgres-backup
+```
+
+Проверка архивов:
+
+```bash
+ls -lah backups
+```
+
+Имена файлов:
+
+- `backups/main_YYYY-MM-DD_HH-MM-SS.sql.gz`
+- `backups/chat_YYYY-MM-DD_HH-MM-SS.sql.gz`
+
+Ручной backup при необходимости:
+
+```bash
+docker compose exec -T postgres pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" | gzip > backups/manual_$(date +%F_%H-%M-%S).sql.gz
+```
--- a/docs/COMMERCIAL_PROPOSAL.md
+++ b/docs/COMMERCIAL_PROPOSAL.md
@@ -0,0 +1,118 @@
+# Коммерческое предложение
+
+## Проект
+
+Система сигналов на базе Alpinbet с парсером, backend API, PWA-клиентом, push-уведомлениями и административной панелью.
+
+## 1. Цель проекта
+
+Разработка системы для получения сигналов из источника Alpinbet, их обработки и доставки пользователям в режиме, близком к реальному времени, с разграничением доступа по подписке и по ботам.
+
+## 2. Состав работ
+
+### 2.1 Backend
+
+Будет реализовано:
+- регистрация и авторизация пользователей;
+- роли пользователей и базовое разграничение прав;
+- система подписок с датой окончания и проверкой доступа;
+- разграничение доступа к ботам;
+- API для PWA-клиента и административной панели;
+- прием и обработка сигналов от парсера;
+- логика отправки уведомлений;
+- базовое логирование системных событий.
+
+Ограничения:
+- backend не гарантирует 100% доставку уведомлений, так как доставка зависит от внешних push-провайдеров и настроек устройства пользователя;
+- при изменении бизнес-логики доступа, тарифов или ролей требуется отдельная доработка.
+
+### 2.2 Интеграция с Alpinbet
+
+Будет реализовано:
+- подключение к источнику данных Alpinbet по учетным данным заказчика;
+- регулярный опрос страниц с интервалом около 20 секунд;
+- сохранение сигналов в систему;
+- защита от дублирования сигналов;
+- привязка сигнала к конкретному боту/источнику;
+- поддержка встроенного списка ботов в парсере.
+
+На текущем этапе в парсер зашиваются следующие боты:
+- `raketafon` — `https://alpinbet.com/dispatch/antigol/raketafon`
+- `pobeda-1-comand` — `https://alpinbet.com/dispatch/antigol/pobeda-1-comand`
+- `raketabas` — `https://alpinbet.com/dispatch/antigol/raketabas`
+- `sol-1www` — `https://alpinbet.com/dispatch/antigol/sol-1www`
+- `fon-stb` — `https://alpinbet.com/dispatch/antigol/fon-stb`
+
+Важно:
+- доступ к Alpinbet, учетные данные и фактическая структура страниц находятся на стороне заказчика;
+- при изменении API, HTML-структуры, механизма авторизации или адресов страниц Alpinbet требуется отдельная доработка;
+- при недоступности источника система не генерирует сигналы;
+- качество и стабильность парсинга напрямую зависят от стабильности внешнего источника.
+
+### 2.3 Push-уведомления
+
+Будет реализовано:
+- отправка уведомлений при появлении новых сигналов;
+- регистрация устройства пользователя;
+- доставка через web push;
+- базовая обработка невалидных push-подписок.
+
+Ограничения:
+- на iPhone push-уведомления работают через PWA и зависят от Safari, разрешений пользователя и системных настроек;
+- уведомления могут приходить с задержкой;
+- гарантируется попытка отправки уведомления, но не гарантируется фактическое получение на устройстве.
+
+### 2.4 Клиентское приложение (PWA)
+
+Будет реализовано:
+- доступ через браузер как web-приложение;
+- установка на телефон как PWA;
+- авторизация пользователя;
+- просмотр списка сигналов;
+- просмотр срока действия подписки;
+- отображение доступных пользователю ботов;
+- работа с push-уведомлениями в рамках возможностей браузера.
+
+Ограничения:
+- приложение является PWA, а не нативным приложением;
+- публикация в App Store и Google Play не входит в данный этап;
+- функциональность ограничена возможностями браузера и платформенных ограничений PWA.
+
+### 2.5 Административная панель
+
+Будет реализовано:
+- просмотр списка пользователей;
+- управление сроками доступа и подписками;
+- выдача и продление доступа;
+- управление доступом к ботам;
+- базовый просмотр сигналов и статусов доставки уведомлений.
+
+Не входит:
+- сложная аналитика;
+- финансовая отчетность;
+- CRM-функции и продвинутая история изменений.
+
+### 2.6 Запуск системы
+
+Будет выполнено:
+- настройка серверного окружения;
+- деплой проекта;
+- базовая проверка работоспособности backend, parser, frontend и push-механизма;
+- проверка получения сигналов из подключенных ботов.
+
+## 3. Что не входит в проект
+
+- публикация в App Store / Google Play;
+- интеграция платежных систем;
+- юридические документы и правовая часть;
+- техническая поддержка сторонних сервисов и поставщиков;
+- доработки, вызванные изменениями на стороне Alpinbet, Firebase, браузеров или операционных систем;
+- SLA на внешние сервисы и гарантии бесперебойной работы источника данных.
+
+## 4. Технические ограничения и допущения
+
+- система работает по модели best effort для внешних интеграций;
+- парсер зависит от доступности Alpinbet и сохранности учетной сессии;
+- при изменении структуры страниц могут потребоваться срочные корректировки селекторов и логики парсинга;
+- скорость появления сигнала у пользователя зависит от источника, интервала опроса, сети, браузера и push-провайдера;
+- доступ к ботам, список ботов и учетные данные предоставляются заказчиком.
--- a/docs/DEPLOY.md
+++ b/docs/DEPLOY.md
@@ -0,0 +1,194 @@
+# Deploy Runbook
+
+Короткая инструкция по выкладке проекта на сервер.
+
+## 1. Подготовка сервера
+
+- Установить `git`, `docker`, `docker compose`.
+- Открыть наружу только порты `80` и `443`.
+- Закрыть наружу `5432`, `6379`, `3000`, `4000`, `4010`, `8080`.
+- Создать каталог проекта, например:
+
+```bash
+mkdir -p ~/alpinbet-parser
+cd ~/alpinbet-parser
+```
+
+## 2. Получение кода
+
+Если репозиторий уже инициализирован:
+
+```bash
+git remote -v
+git pull
+```
+
+Если это первый деплой:
+
+```bash
+git clone git@gitlab.com:talorr/alpinbet-parser.git ~/alpinbet-parser
+cd ~/alpinbet-parser
+```
+
+## 3. Настройка секретов
+
+Скопировать шаблон env:
+
+```bash
+cp .env.example .env
+```
+
+Заполнить в `.env`:
+
+- `POSTGRES_DB`
+- `POSTGRES_USER`
+- `POSTGRES_PASSWORD`
+- `JWT_SECRET`
+- `PARSER_INTERNAL_SECRET`
+- `NUXT_PUBLIC_API_BASE`
+- `APP_PUBLIC_URL`
+- `CORS_ORIGIN`
+- `SMTP_*`
+- `VAPID_*`
+- `FIREBASE_*`
+
+Важно:
+
+- Не оставлять `change_me_*`.
+- Использовать длинные случайные значения для `JWT_SECRET` и `PARSER_INTERNAL_SECRET`.
+- `adminer` и `dockmon` должны оставаться закомментированными в `docker-compose.yml`.
+
+## 4. Доступ к Traefik Dashboard
+
+Создать файл с логином и паролем:
+
+```bash
+mkdir -p traefik/secrets
+cp traefik/secrets/dashboard-users.example traefik/secrets/dashboard-users
+```
+
+Сгенерировать `htpasswd`:
+
+```bash
+htpasswd -nb admin 'CHANGE_ME_STRONG_PASSWORD' > traefik/secrets/dashboard-users
+```
+
+## 5. Проверка конфига
+
+Перед запуском проверить итоговый compose:
+
+```bash
+docker compose config
+```
+
+Если здесь ошибка, не запускать деплой, пока она не исправлена.
+
+## 6. Первый запуск
+
+Собрать и поднять стек:
+
+```bash
+docker compose up -d --build
+```
+
+Применить схему базы:
+
+```bash
+docker compose exec backend npx prisma db push
+```
+
+Проверить статус:
+
+```bash
+docker compose ps
+docker compose logs --tail=100 backend
+docker compose logs --tail=100 frontend
+docker compose logs --tail=100 parser
+```
+
+## 7. Smoke Check После Деплоя
+
+Проверить:
+
+```bash
+curl https://api.antigol.ru/health
+```
+
+И вручную в браузере:
+
+- `https://antigol.ru`
+- логин
+- открытие сигналов
+- админка, если нужна
+
+## 8. Бэкап Базы
+
+Создать sql-бэкап:
+
+```bash
+docker compose exec -T postgres pg_dump -U postgres -d betting_signals > backup_$(date +%F_%H-%M-%S).sql
+```
+
+Или сразу архив:
+
+```bash
+docker compose exec -T postgres pg_dump -U postgres -d betting_signals | gzip > backup_$(date +%F_%H-%M-%S).sql.gz
+```
+
+Если имена БД и пользователя другие, подставить свои значения из `.env`.
+
+Скачать бэкап на локальную машину:
+
+```bash
+scp root@your-server:~/alpinbet-parser/backup_2026-03-25_20-30-00.sql.gz .
+```
+
+## 9. Обновление Проекта
+
+Обычный порядок после `git pull`:
+
+```bash
+git pull
+docker compose build backend frontend parser forecast-ocr
+docker compose up -d
+docker compose exec backend npx prisma db push
+```
+
+Если менялись только env или Traefik:
+
+```bash
+docker compose up -d
+```
+
+## 10. Полезные Команды
+
+Логи:
+
+```bash
+docker compose logs -f backend
+docker compose logs -f parser
+docker compose logs -f traefik
+```
+
+Перезапуск одного сервиса:
+
+```bash
+docker compose restart backend
+docker compose restart parser
+```
+
+Остановить проект:
+
+```bash
+docker compose down
+```
+
+## 11. Минимальный Продовый Чеклист
+
+- `.env` заполнен реальными значениями
+- `dashboard-users` создан
+- `docker compose config` проходит без ошибок
+- наружу открыты только `80` и `443`
+- `adminer` и `dockmon` не включены
+- после запуска проходит `/health`
+- сделан свежий backup БД