PrimoGuardBot/README.md

# 🛡️ PrimoGuard Bot

**Умный бот-модератор для Telegram** с системой фильтрации спама, банвордов и защитой от флуда.

[
[
[

***

## 📑 Содержание

- [Возможности](#-возможности)
- [Быстрый старт](#-быстрый-старт)
- [Конфигурация](#-конфигурация)
- [Команды](#-команды)
- [Система фильтрации](#-система-фильтрации)
- [Middleware](#️-middleware)
- [Примеры использования](#-примеры-использования)
- [Troubleshooting](#-troubleshooting)
- [FAQ](#-faq)

***

## 🎯 Возможности

### Основные функции

✅ **Многоуровневая система фильтрации:**
- 🔤 **Substring** — фильтрация по подстрокам (например: `хуй`)
- 📖 **Lemma** — фильтрация по лемматизации (например: `пидорас` → `пидор`, `пидорасом`, `пидораса`)
- 🧩 **Part** — фильтрация по частям слов без спецсимволов (например: `@Astrixkeepbot` → заблокирует `astrix` и `bot`)

✅ **Временные правила:**
- ⏰ Банворды с истечением срока действия
- 🔄 Автоматическая очистка истёкших правил

✅ **Режимы модерации:**
- 🔇 **Silence Mode** — удаление всех сообщений (режим тишины)
- ⚔️ **Conflict Mode** — блокировка конфликтных слов (для предотвращения споров)
- ✅ **Whitelist** — исключения для разрешённых слов

✅ **Умный антиспам:**
- 🤖 Адаптивные лимиты (текст, пересылки, медиа, callback)
- 🧠 Детекция спам-паттернов (идентичные сообщения, спам кнопок)
- ⭐ Система репутации пользователей (0.5x - 2.0x к лимитам)
- 🚫 Прогрессивные блокировки (1 мин → 2 мин → 5 мин → 15 мин → 1 час)

✅ **Статистика и аналитика:**
- 📊 Топ-10 самых частых срабатываний
- 👥 Статистика по пользователям
- 📈 Общее количество удалённых сообщений

✅ **Администрирование:**
- 👨‍💼 Многоуровневая система администраторов
- 🔔 Уведомления админов о спаме
- 🎛️ Удобное управление через команды и callback-кнопки

***

## 🚀 Быстрый старт

### 1. Клонируйте репозиторий

```bash
git clone https://github.com/yourusername/primo_guard_bot.git
cd primo_guard_bot
```

### 2. Создайте файл `.env`

```bash
cp .env.example .env
nano .env
```

**Минимальная конфигурация:**

```env
# === BOT SETTINGS ===
BOT_TOKEN=YOUR_BOT_TOKEN_FROM_BOTFATHER

# === ADMIN IDS ===
OWNER_ID=[123456789,987654321]
ADMIN_CHAT_ID=-1001234567890

# === WEBHOOK (если используете) ===
WEBHOOK=true
WEBHOOK_URL=https://yourdomain.com/webhook
SECRET_TOKEN=your_random_secret_32_chars_here

# === SERVER ===
WEBAPP_HOST=0.0.0.0
WEBAPP_PORT=3131
```

### 3. Запустите через Docker Compose

```bash
docker compose up -d
```

### 4. Проверьте логи

```bash
docker compose logs -f
```

### 5. Добавьте бота в группу

1. Добавьте бота в вашу группу
2. Выдайте права администратора (удаление сообщений)
3. Отправьте `/start` в группе

***

## ⚙️ Конфигурация

### Полный `.env` файл

```env
# ═══════════════════════════════════════════════════════════════════════════
#                         🤖 BOT TOKEN
# ═══════════════════════════════════════════════════════════════════════════

# [ОБЯЗАТЕЛЬНО] Токен бота от @BotFather
BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz

# ═══════════════════════════════════════════════════════════════════════════
#                         👤 АДМИНИСТРАТОРЫ И ID
# ═══════════════════════════════════════════════════════════════════════════

# [ОБЯЗАТЕЛЬНО] ID владельцев бота (список через запятую)
OWNER_ID=[123456789,987654321]

# [ОБЯЗАТЕЛЬНО] ID чата для уведомлений админов
ADMIN_CHAT_ID=-1001234567890

# Дополнительные админы (необязательно)
ADMIN_ID=[111111111,222222222]

# ═══════════════════════════════════════════════════════════════════════════
#                         ⚙️ ОСНОВНЫЕ НАСТРОЙКИ БОТА
# ═══════════════════════════════════════════════════════════════════════════

# Имя бота
BOT_NAME=PrimoGuard Bot

# Описание бота (до 512 символов)
BOT_DESCRIPTION=Бот-модератор для защиты чата от спама и нецензурных слов

# Короткое описание (до 120 символов)
BOT_SHORT_DESCRIPTION=Тех.поддержка: @yourusername

# Автоматически обновлять настройки бота при запуске
BOT_EDIT=false

# ═══════════════════════════════════════════════════════════════════════════
#                         🌐 WEBHOOK SETTINGS
# ═══════════════════════════════════════════════════════════════════════════

# Использовать webhook вместо long polling
# false = long polling (для локальной разработки)
# true = webhook (для продакшена, требует HTTPS)
WEBHOOK=true

# URL вебхука (обязателен если WEBHOOK=true)
WEBHOOK_URL=https://yourdomain.com/webhook

# Секретный токен для вебхука (генерируется автоматически если не указан)
SECRET_TOKEN=vK8mP2nQ7xR4wJ9sL6fY3tB5hN0cV1zA

# Хост для сервера (обычно 0.0.0.0)
WEBAPP_HOST=0.0.0.0

# Порт для сервера
WEBAPP_PORT=3131

# Уровень логов (debug, info, warning, error, critical)
LOG_LEVEL=info

# Включить access log
ACCES_LOG=false

# ═══════════════════════════════════════════════════════════════════════════
#                         📊 DATABASE
# ═══════════════════════════════════════════════════════════════════════════

# Путь к базе данных SQLite
DATABASE_PATH=banwords.db

# ═══════════════════════════════════════════════════════════════════════════
#                         🔧 ДОПОЛНИТЕЛЬНЫЕ НАСТРОЙКИ
# ═══════════════════════════════════════════════════════════════════════════

# Префикс команд
PREFIX=/

# Таймаут между сообщениями (антиспам, секунды)
TIMEOUT=3
```

### Docker Compose

Ваш `docker-compose.yml` уже настроен оптимально:

```yaml
services:
  primoguard:
    image: whyverum/primo_guard_bot:latest
    container_name: primoguard-bot
    restart: unless-stopped
    
    env_file:
      - .env
    
    volumes:
      - ./banwords.db:/app/banwords.db
      - ./Logs:/app/Logs
    
    deploy:
      resources:
        limits:
          cpus: '1.0'
          memory: 512M
        reservations:
          cpus: '0.25'
          memory: 128M
    
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"
    
    stop_grace_period: 30s
    
    networks:
      - proxy

networks:
  proxy:
    external: true
```

***

## 📝 Команды

### Основные команды

| Команда | Описание | Доступ |
|---------|----------|--------|
| `/start` | Запуск бота и главное меню | Все |
| `/help` | Помощь по командам | Все |
| `/stats` | Статистика модерации | Админы |
| `/id` | Информация о вашем аккаунте | Все |
| `/chatid` | ID текущего чата | Все |

### Управление банвордами (постоянные)

| Команда | Пример | Описание |
|---------|--------|----------|
| `/addword` | `/addword хуй` | Добавить подстроку |
| `/addlemma` | `/addlemma пидорас` | Добавить лемму |
| `/addpart` | `/addpart astrix` | Добавить часть слова |
| `/remword` | `/remword хуй` | Удалить подстроку |
| `/remlemma` | `/remlemma пидорас` | Удалить лемму |
| `/rempart` | `/rempart astrix` | Удалить часть |

### Временные банворды

| Команда | Пример | Описание |
|---------|--------|----------|
| `/addtempword` | `/addtempword спам 24h` | Добавить временную подстроку (24 часа) |
| `/addtemplemma` | `/addtemplemma флудить 12h` | Добавить временную лемму (12 часов) |
| `/remtempword` | `/remtempword спам` | Удалить временную подстроку |

**Форматы времени:** `1h`, `24h`, `7d`, `30d`

### Исключения (whitelist)

| Команда | Пример | Описание |
|---------|--------|----------|
| `/addexcept` | `/addexcept психология` | Добавить в whitelist |
| `/remexcept` | `/remexcept психология` | Удалить из whitelist |

### Конфликтные слова

| Команда | Пример | Описание |
|---------|--------|----------|
| `/addconflictword` | `/addconflictword политика` | Добавить конфликтное слово |
| `/stopconflict` | `/stopconflict` | Включить режим антиконфликта |
| `/unstopconflict` | `/unstopconflict` | Выключить режим |
| `/conflictstatus` | `/conflictstatus` | Проверить статус режима |

### Режим тишины

| Команда | Описание |
|---------|----------|
| `/silence 30m` | Включить тишину на 30 минут |
| `/unsilence` | Выключить режим тишины |
| `/silencestatus` | Проверить статус |
| `/extend_silence 1h` | Продлить тишину на 1 час |

### Администрирование

| Команда | Пример | Описание |
|---------|--------|----------|
| `/addadmin` | `/addadmin @username` | Добавить администратора |
| `/remadmin` | `/remadmin @username` | Удалить администратора |
| `/listadmins` | `/listadmins` | Список администраторов |
| `/checkadmin` | `/checkadmin @username` | Проверить статус |

### Статистика

| Команда | Описание |
|---------|----------|
| `/userstats` | Статистика по пользователю |
| `/resetstats confirm` | Сбросить всю статистику |

### Просмотр правил

| Команда | Описание |
|---------|----------|
| `/listwords` | Список всех подстрок |
| `/listlemmas` | Список всех лемм |
| `/listparts` | Список всех частей |
| `/listexcept` | Список исключений |
| `/listconflict` | Список конфликтных слов |

### Утилиты

| Команда | Описание |
|---------|----------|
| `/emoji текст` | Извлечь все эмодзи из текста |
| `/ping` | Проверить отклик бота |
| `/checkwebhook` | Проверить статус webhook (админы) |

***

## 🔍 Система фильтрации

### 1. Substring (Подстроки)

**Как работает:** Простой поиск подстроки в тексте.

```
Правило: "хуй"
✅ Заблокирует: "хуй", "хуйня", "похуй", "нахуй"
❌ Не заблокирует: "психология" (хотя содержит "хуй", но это безобидное слово)
```

**Когда использовать:** Для коротких и однозначных матов.

### 2. Lemma (Лемматизация)

**Как работает:** Приводит слова к нормальной форме и сравнивает.

```
Правило: "пидорас" (лемма: "пидор")
✅ Заблокирует: "пидорас", "пидораса", "пидорасом", "пидорасы"
❌ Не заблокирует: "пидор123" (не является словом)
```

**Когда использовать:** Для блокировки всех форм слова.

### 3. Part (Части слов)

**Как работает:** Удаляет ВСЕ спецсимволы и ищет часть.

```
Правило: "astrix"
✅ Заблокирует: "@Astrixkeepbot", "astrix.bot", "a-s-t-r-i-x"
❌ Не заблокирует: "astronomy" (не содержит точную последовательность)
```

**Когда использовать:** Для блокировки упоминаний ботов/каналов со спецсимволами.

### 4. Whitelist (Исключения)

**Как работает:** Проверяется ПЕРВЫМ, до всех фильтров.

```
Whitelist: "психология"
✅ Пропустит: "я изучаю психологию"
✅ Пропустит: "психолог"
```

**Когда использовать:** Для безобидных слов, содержащих мат.

### 5. Временные правила

**Как работает:** Автоматически удаляются после истечения срока.

```
Команда: /addtempword флуд 24h
Результат: Слово "флуд" будет блокироваться 24 часа
```

**Когда использовать:** Для временных мер (события, рейды).

***

## 🛡️ Middleware

### 1. BanWordsMiddleware (Основная защита)

**Приоритет:** Высокий  
**Применяется к:** Все текстовые сообщения

**Функции:**
- Проверка на substring, lemma, part
- Проверка временных банвордов
- Проверка whitelist
- Режим тишины
- Режим антиконфликта

**Pipeline проверки:**
```
1. Пропуск админов
2. Проверка whitelist → ПРОПУСТИТЬ
3. Silence Mode → УДАЛИТЬ
4. Conflict Mode + конфликтные слова → УДАЛИТЬ
5. Substring → УДАЛИТЬ
6. Part → УДАЛИТЬ
7. Lemma → УДАЛИТЬ
8. Временные банворды → УДАЛИТЬ
9. ✅ Пропустить сообщение
```

***

### 2. AntiSpamMiddleware (Умный антиспам)

**Приоритет:** Средний  
**Применяется к:** Все сообщения и callback

**Функции:**
- ⚡ Адаптивные лимиты по типам сообщений
- 🧠 Детекция спам-паттернов
- ⭐ Система репутации (0.5x - 2.0x)
- 🚫 Прогрессивные блокировки

**Лимиты по умолчанию:**

| Тип | Лимит | Окно | Описание |
|-----|-------|------|----------|
| 📝 Текст | 8 сообщений | 10 сек | Обычные текстовые сообщения |
| ↗️ Пересылки | 20 сообщений | 10 сек | Можно массово пересылать! |
| 🔘 Callback | 10 нажатий | 10 сек | Нажатия на кнопки |
| 📷 Медиа | 10 файлов | 10 сек | Фото, видео, документы |
| ⚡ Команды | ∞ | - | Не ограничены |

**Умная детекция:**
- ❌ 5 одинаковых текстов подряд → немедленная блокировка
- ❌ 8 нажатий одной кнопки → блокировка
- ❌ 7+ медиа подряд → предупреждение

**Система репутации:**
```
Новый пользователь: 1.0x (стандартные лимиты)
Хорошее поведение: до 2.0x (лимиты удваиваются!)
Плохое поведение: до 0.5x (лимиты снижаются вдвое)
```

**Прогрессивные блокировки:**
```
1 предупреждение → 2 мин блокировка
2 предупреждения → 4 мин
3 предупреждения → 8 мин
4 предупреждения → 16 мин
5+ предупреждений → 1 час (максимум)
```

***

### 3. LoggingMiddleware (Логирование)

**Приоритет:** Низкий  
**Применяется к:** Все события

**Функции:**
- 📝 Логирование всех команд
- 📊 Логирование всех событий
- 🔍 Детальная информация для отладки

***

### 4. ErrorHandlingMiddleware (Обработка ошибок)

**Приоритет:** Последний  
**Применяется к:** Все события

**Функции:**
- ❌ Перехват всех исключений
- 📧 Уведомления админов об ошибках
- 🔄 Graceful recovery

***

### 5. TimingMiddleware (Замер времени)

**Приоритет:** Первый  
**Применяется к:** Все события

**Функции:**
- ⏱️ Замер времени выполнения
- 📊 Профилирование производительности

***

## 💡 Примеры использования

### Сценарий 1: Настройка для чата с матами

```bash
# 1. Добавляем основные маты
/addword хуй
/addword блять
/addlemma пидорас
/addlemma ебать

# 2. Добавляем исключения
/addexcept психология
/addexcept архитектура

# 3. Проверяем правила
/listwords
```

### Сценарий 2: Блокировка упоминаний ботов

```bash
# 1. Добавляем части названий ботов
/addpart astrix
/addpart keepbot
/addpart spambot

# 2. Проверяем
# ✅ Заблокируется: "@Astrixkeepbot", "astrix_bot"
```

### Сценарий 3: Временная блокировка темы

```bash
# Событие: выборы, запрещаем политику на 3 дня
/addtempword политика 3d
/addtempword выборы 3d
/addtemplemma голосовать 3d

# Через 3 дня слова автоматически разблокируются
```

### Сценарий 4: Режим тишины во время рейда

```bash
# 1. Включаем тишину на 1 час
/silence 1h

# Все сообщения от не-админов удаляются

# 2. Если рейд продолжается, продлеваем
/extend_silence 30m

# 3. Отключаем вручную
/unsilence
```

### Сценарий 5: Антиконфликтный режим

```bash
# 1. Добавляем конфликтные темы
/addconflictword политика
/addconflictword религия
/addconflictlemma спорить

# 2. Включаем режим
/stopconflict

# Теперь сообщения с этими словами удаляются

# 3. Выключаем после события
/unstopconflict
```

***

## 🔧 Troubleshooting

### Бот не отвечает в группе

**Решение:**
```bash
# 1. Проверьте права администратора
# Бот ДОЛЖЕН иметь право "Удаление сообщений"

# 2. Проверьте webhook
docker exec primoguard-bot python -c "
from configs import settings
import requests
url = f'https://api.telegram.org/bot{settings.BOT_TOKEN}/getWebhookInfo'
print(requests.get(url).json())
"

# 3. Проверьте логи
docker compose logs -f

# 4. Перезапустите
docker compose restart
```

### Ошибка 401 Unauthorized (Webhook)

**Причина:** Несовпадение SECRET_TOKEN

**Решение:**
```bash
# 1. Удалите webhook
curl "https://api.telegram.org/botYOUR_TOKEN/deleteWebhook?drop_pending_updates=true"

# 2. Проверьте .env файл
cat .env | grep SECRET_TOKEN

# 3. Перезапустите
docker compose down
docker compose up -d
```

### База данных заблокирована (database is locked)

**Решение:**
```bash
# 1. Остановите все контейнеры
docker compose down

# 2. Проверьте права
sudo chown -R $USER:$USER banwords.db

# 3. Запустите
docker compose up -d
```

### Бот не удаляет сообщения

**Проверьте:**
1. ✅ Бот — администратор группы
2. ✅ Есть право "Удаление сообщений"
3. ✅ Правила банвордов добавлены (`/listwords`)
4. ✅ Пользователь не в списке админов (`/listadmins`)

***

## ❓ FAQ

### Как узнать свой ID?

Отправьте `/id` боту или используйте @userinfobot

### Как узнать ID группы?

1. Добавьте бота в группу
2. Отправьте `/chatid` в группе

### Можно ли использовать без webhook?

Да! Установите в `.env`:
```env
WEBHOOK=false
```

### Как добавить несколько админов?

```env
OWNER_ID=[123456789,987654321,555666777]
ADMIN_ID=[111222333,444555666]
```

### Сколько правил можно добавить?

Ограничений нет, но рекомендуется до 1000 слов для оптимальной производительности.

### Работает ли на русском и английском?

Да! Поддерживаются все языки с Unicode.

### Как сделать backup базы данных?

```bash
# Создайте backup
cp banwords.db banwords_backup_$(date +%Y%m%d).db

# Или через Docker
docker cp primoguard-bot:/app/banwords.db ./backup/
```

### Как обновить бота?

```bash
# 1. Остановите
docker compose down

# 2. Обновите образ
docker pull whyverum/primo_guard_bot:latest

# 3. Запустите
docker compose up -d
```

### Влияет ли на производительность группы?

Нет! Бот обрабатывает сообщения за ~10-50мс. Для пользователей задержка незаметна.

***

## 📊 Мониторинг

### Просмотр логов

```bash
# Все логи
docker compose logs -f

# Только ошибки
docker compose logs -f | grep ERROR

# Последние 100 строк
docker compose logs --tail=100

# Логи за сегодня
docker compose logs --since $(date +%Y-%m-%d)
```

### Статистика Docker

```bash
# Использование ресурсов
docker stats primoguard-bot

# Информация о контейнере
docker inspect primoguard-bot

# Размер логов
docker logs primoguard-bot 2>&1 | wc -l
```

## 📄 Лицензия

MIT License - см. [LICENSE](LICENSE)

***

## 🙏 Благодарности

- [aiogram](https://github.com/aiogram/aiogram) - асинхронный фреймворк для Telegram Bot API
- [pymorphy2](https://github.com/pymorphy2/pymorphy2) - морфологический анализатор для русского языка
- [SQLAlchemy](https://www.sqlalchemy.org/) - ORM для работы с базой данных

***

**⭐ Если бот помог вам, поставьте звезду на GitHub!**