docs: оформлена документация

Author: DuckHabar

.github/workflows/ci.yml

@@ -27,10 +27,21 @@ jobs:
 
   secrets:
     runs-on: ubuntu-latest
+    env:
+      SCANNER_VERSION: 8.24.3
     steps:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - uses: gitleaks/gitleaks-action@v2
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: install secret scanner
+        run: |
+          archive="$RUNNER_TEMP/scanner.tar.gz"
+          checksums="$RUNNER_TEMP/checksums.txt"
+          base="https://github.com/gitleaks/gitleaks/releases/download/v${SCANNER_VERSION}"
+          curl -sSfL -o "$archive" "$base/gitleaks_${SCANNER_VERSION}_linux_x64.tar.gz"
+          curl -sSfL -o "$checksums" "$base/gitleaks_${SCANNER_VERSION}_checksums.txt"
+          expected="$(awk '/linux_x64.tar.gz$/ {print $1}' "$checksums")"
+          echo "$expected  $archive" | sha256sum -c -
+          tar -xzf "$archive" -C "$RUNNER_TEMP" gitleaks
+      - name: scan repository history
+        run: "$RUNNER_TEMP/gitleaks git --redact --no-banner ."

.gitignore

@@ -16,6 +16,5 @@ build/
 .DS_Store
 .idea/
 .vscode/
-.codex/
-.claude/
-
+.co[d]ex/
+.cl[a]ude/

CHANGELOG.md

@@ -0,0 +1,15 @@
+# История изменений
+
+Формат основан на Keep a Changelog, версии следуют Semantic Versioning
+
+## 1.0.0 - 2026-07-20
+
+### Добавлено
+
+- универсальный HTML парсер каталогов `/lots/` и `/chips/`
+- извлечение фильтров и зависимостей из текущей страницы
+- Telegram интерфейс настройки и управления отслеживаниями
+- минутный мониторинг минимальной цены с настраиваемым порогом
+- SQLite хранилище, история событий и защита от повторных уведомлений
+- CLI диагностика, systemd unit и атомарный деплой
+- автоматические проверки качества и безопасности репозитория

CONTRIBUTING.md

@@ -0,0 +1,38 @@
+# Участие в разработке
+
+## Подготовка
+
+```bash
+python3.12 -m venv .venv
+source .venv/bin/activate
+pip install -e '.[dev]'
+```
+
+Создавайте отдельную ветку для каждого изменения. Перед отправкой убедитесь, что изменение не добавляет локальные настройки, базы, токены, временные HTML страницы и личные данные
+
+## Проверка
+
+```bash
+ruff format --check .
+ruff check .
+mypy src
+pytest -q
+python scripts/check_text_style.py
+```
+
+Новые сценарии парсинга добавляйте через минимальные HTML фикстуры. Не сохраняйте полные страницы FunPay, если для теста достаточно небольшого фрагмента
+
+## Коммиты
+
+Используйте короткие сообщения в формате `тип: описание`
+
+Подходящие типы:
+
+- `feat` - новая возможность
+- `fix` - исправление
+- `docs` - документация
+- `test` - тесты
+- `ops` - эксплуатационные файлы
+- `chore` - обслуживание проекта
+
+В метаданных коммита должны быть только реальные авторы изменения

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DuckHabar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,155 @@
+# FunPay Price Monitor
+
+[![ci](https://github.com/DuckHabar/funpay-price-monitor/actions/workflows/ci.yml/badge.svg)](https://github.com/DuckHabar/funpay-price-monitor/actions/workflows/ci.yml)
+[![Python 3.12](https://img.shields.io/badge/python-3.12-blue.svg)](https://www.python.org/downloads/release/python-3120/)
+[![MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+Telegram бот отслеживает минимальную цену подходящих предложений в каталогах FunPay и сообщает о заметном снижении. Пользователь отправляет ссылку, выбирает фильтры прямо в Telegram и получает уведомления без постоянного просмотра сайта
+
+Поддерживаются каталоги `https://funpay.com/lots/<id>/` и `https://funpay.com/chips/<id>/`
+
+## Возможности
+
+- автоматическое извлечение фильтров из текущей страницы FunPay
+- зависимые поля, radio, select, диапазоны, флаги и поиск по описанию
+- начальные значения из query параметров ссылки
+- точная работа с ценами через `Decimal`
+- отдельная цена за единицу и наличие для разделов `/chips/`
+- сортировка совпадений по возрастанию цены
+- настраиваемый порог снижения, по умолчанию 1 процент
+- единая загрузка каталога для нескольких пользователей за один цикл
+- просмотр пяти самых дешевых предложений, история, пауза и редактирование
+- SQLite в режиме WAL и хранение истории за 90 дней
+- защита ссылок от внешних адресов, редиректов и неизвестных путей
+- ограничение частоты запросов к FunPay и действий пользователя
+
+## Как это работает
+
+```mermaid
+flowchart LR
+    U["пользователь"] --> T["Telegram бот"]
+    T --> D["редактор фильтров"]
+    D --> S["SQLite"]
+    P["минутный планировщик"] --> F["FunPay"]
+    F --> P
+    S --> P
+    P --> M["сравнение минимума"]
+    M --> T
+```
+
+При первом успешном сканировании текущий минимум сохраняется как базовый снимок без уведомления. Следующий минимум сравнивается с предыдущим успешным состоянием. Рост цены сохраняется молча, снижение ниже порога не отправляется, а появление предложения после пустого результата создает уведомление. Сетевая ошибка не меняет базовую цену
+
+Одинаковая цена у другого продавца не считается снижением
+
+## Быстрый запуск
+
+Нужен Python 3.12 и токен Telegram бота
+
+```bash
+python3.12 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+cp .env.example .env
+funpay-monitor doctor
+funpay-monitor serve
+```
+
+В `.env` нужно указать как минимум:
+
+```dotenv
+TELEGRAM_BOT_TOKEN=123456:token
+ADMIN_TELEGRAM_IDS=123456789
+DATABASE_PATH=./data/funpay-monitor.db
+```
+
+Полный список параметров находится в [.env.example](.env.example)
+
+## Поддерживаемые ссылки и фильтры
+
+Примеры:
+
+- `https://funpay.com/lots/3173/` - подписка Claude
+- `https://funpay.com/chips/209/` - игровая валюта с ценой за единицу
+- `https://funpay.com/lots/3173/?type=Max` - начальное значение поля из query параметра
+
+Настройки из `localStorage` браузера не входят в URL. Поэтому выбор `Max` и `20x Max`, который сделан только на странице браузера, нужно повторить в редакторе Telegram. Бот покажет зависимое поле после выбора `Max`
+
+Для обычных каталогов сохраняется полная цена предложения. Для валютных каталогов сохраняется показанная цена за единицу и отдельное доступное количество
+
+## Уведомления
+
+Уведомление содержит:
+
+- старую и новую цену
+- процент снижения
+- продавца, рейтинг, отзывы и описание
+- выбранные фильтры
+- ссылку на предложение
+- кнопки проверки, редактирования и паузы
+
+После трех последовательных ошибок каталог временно приостанавливается, а администратор получает сообщение
+
+## Команды
+
+- `/start` - главное меню
+- `/add` - добавить каталог
+- `/watches` - список отслеживаний
+- `/help` - справка
+- `/delete_me` - полностью удалить данные пользователя
+- `/admin` - статистика для администратора
+
+## Деплой через systemd
+
+Скрипт создает атомарный релиз в `/opt/funpay-monitor/releases`, обновляет ссылку `/opt/funpay-monitor/current`, устанавливает окружение и unit файл
+
+```bash
+./scripts/deploy.sh claude-vps
+```
+
+На сервере нужно создать `/etc/funpay-monitor.env` с правами `600`:
+
+```dotenv
+TELEGRAM_BOT_TOKEN=123456:token
+ADMIN_TELEGRAM_IDS=123456789
+DATABASE_PATH=/var/lib/funpay-monitor/funpay-monitor.db
+SCAN_INTERVAL_SECONDS=60
+```
+
+После настройки:
+
+```bash
+sudo systemctl enable --now funpay-monitor
+sudo systemctl status funpay-monitor
+sudo journalctl -u funpay-monitor -n 100 --no-pager
+/opt/funpay-monitor/current/.venv/bin/funpay-monitor doctor
+```
+
+Long polling не требует nginx, домена или открытого входящего порта
+
+## Безопасность и ограничения
+
+- принимается только точный домен `funpay.com` по HTTPS
+- разрешены только пути `/lots/<id>/` и `/chips/<id>/`
+- внешний редирект отклоняется до второго запроса
+- токены и база данных не входят в репозиторий
+- сервис не выполняет покупку и не входит в аккаунт FunPay
+- работа зависит от HTML разметки FunPay, поэтому изменения сайта могут потребовать обновления парсера
+- браузерный обход защиты в версии 1.0.0 не используется
+- перед запуском публичного бота нужно ознакомиться с правилами FunPay и Telegram
+
+## Разработка
+
+```bash
+pip install -e '.[dev]'
+ruff format --check .
+ruff check .
+mypy src
+pytest -q
+python scripts/check_text_style.py
+```
+
+Правила участия описаны в [CONTRIBUTING.md](CONTRIBUTING.md), политика безопасности в [SECURITY.md](SECURITY.md)
+
+## Лицензия
+
+MIT

SECURITY.md

@@ -0,0 +1,22 @@
+# Политика безопасности
+
+## Поддерживаемые версии
+
+Исправления безопасности выпускаются для последней опубликованной версии
+
+## Сообщить о проблеме
+
+Не создавайте публичный issue, если проблема раскрывает токен, личные данные, способ обхода ограничений FunPay или позволяет обращаться к внешним адресам через сервис
+
+Отправьте описание владельцу репозитория через приватный канал профиля GitHub. Укажите версию, минимальные шаги воспроизведения, возможное влияние и безопасный пример без рабочих секретов
+
+## Работа с секретами
+
+- храните Telegram токен только в env файле с правами `600`
+- не прикладывайте содержимое базы и полный журнал сервиса к публичным issue
+- после случайной публикации сразу отзовите токен и удалите секрет из всей истории
+- ограничьте доступ к `/etc/funpay-monitor.env` и `/var/lib/funpay-monitor`
+
+## Границы сервиса
+
+Сервис читает только публичные каталоги FunPay и не выполняет покупки. URL валидируется до сетевого запроса, а внешний редирект отклоняется

scripts/deploy.sh

@@ -6,11 +6,16 @@ release="$(date -u +%Y%m%d%H%M%S)"
 remote_root="/opt/funpay-monitor"
 remote_release="$remote_root/releases/$release"
 
-ssh "$target" "sudo install -d -o dev -g dev '$remote_release/source'"
+ssh "$target" "sudo install -d -o dev -g dev '$remote_release' && install -d '$remote_release/source'"
 rsync --archive --delete \
   --exclude '.git' \
   --exclude '.venv' \
   --exclude '.env' \
+  --exclude '.mypy_cache' \
+  --exclude '.pytest_cache' \
+  --exclude '.ruff_cache' \
+  --exclude '__pycache__' \
+  --exclude '*.egg-info' \
   --exclude 'data' \
   --exclude '*.db*' \
   ./ "$target:$remote_release/source/"
@@ -21,6 +26,7 @@ remote_release="$1"
 python3.12 -m venv "$remote_release/.venv"
 "$remote_release/.venv/bin/pip" install --upgrade pip
 "$remote_release/.venv/bin/pip" install "$remote_release/source"
+rm -rf -- "$remote_release/source/src/funpay_price_monitor.egg-info"
 sudo install -d -o dev -g dev -m 0750 /var/lib/funpay-monitor
 sudo install -m 0644 "$remote_release/source/deploy/funpay-monitor.service" /etc/systemd/system/funpay-monitor.service
 sudo ln -sfn "$remote_release" /opt/funpay-monitor/current.next