Добавление автомута

2025-10-12 16:00:02 +03:00
parent 643ad9feda
commit f6b888c6d3
9 changed files with 894 additions and 8 deletions
--- a/README.md
+++ b/README.md
@@ -40,4 +40,169 @@ python src/main.py
 - Проверит наличие обновлений в git-репозитории
 - Загрузит изменения (`git pull`)
 - Перезапустит службу бота (`systemctl restart LGBot.service`)
- Покажет статус работы бота
+- Покажет статус работы бота
+
+---
+
+## Система автоматического мьюта
+
+Бот автоматически отслеживает использование нецензурной лексики и применяет прогрессирующие наказания.
+
+### Как работает
+
+1. **Обнаружение нарушений:**
+   - Каждое текстовое сообщение проверяется на наличие бранных слов
+   - Проверяются только группы и супергруппы (не личные сообщения)
+   - Команды (начинающиеся с `/`) не проверяются
+
+2. **При обнаружении мата:**
+   - Сообщение удаляется автоматически
+   - Нарушение фиксируется в базе данных
+   - Пользователь получает мут соответствующего уровня
+   - Уведомление отправляется в чат и админ-чат
+
+3. **Прогрессирующие наказания:**
+
+| № нарушения | Длительность мута | № нарушения | Длительность мута |
+|-------------|-------------------|-------------|-------------------|
+| 1           | 5 минут           | 9           | 1 день            |
+| 2           | 15 минут          | 10          | 2 дня             |
+| 3           | 30 минут          | 11          | 3 дня             |
+| 4           | 1 час             | 12          | 5 дней            |
+| 5           | 2 часа            | 13          | 7 дней            |
+| 8           | 12 часов          | 16+         | **НАВСЕГДА**      |
+
+4. **Накопительный эффект:**
+   - Нарушения учитываются за последние **30 дней**
+   - Старые нарушения автоматически удаляются из базы
+   - Администраторы **освобождены** от автоматических мутов
+
+### Управление списком бранных слов
+
+⚠️ **Все команды доступны только администраторам чата**
+
+#### Основные команды
+
+```bash
+# Показать справку
+/badwords help
+
+# Показать список бранных слов (первые 50)
+/badwords list
+
+# Статистика
+/badwords count
+
+# Добавить слово в список
+/badwords add <слово>
+
+# Удалить слово из списка
+/badwords remove <слово>
+```
+
+#### Исключения
+
+Исключения — слова, содержащие бранные корни, но не являющиеся матом (например: "республика", "документ"):
+
+```bash
+# Показать исключения
+/badwords exceptions
+
+# Добавить исключение
+/badwords add_exception <слово>
+
+# Удалить исключение
+/badwords remove_exception <слово>
+```
+
+#### Служебные команды
+
+```bash
+# Перезагрузить списки из файла
+/badwords reload
+```
+
+### Рекомендации
+
+1. **Используйте корни слов**, а не полные формы:
+   - ✅ Правильно: `ебал` (поймает все формы)
+   - ❌ Неправильно: `ебала` (пропустит другие формы)
+
+2. **Избегайте коротких корней** (могут давать ложные срабатывания)
+
+3. **Тестируйте после добавления** нового слова
+
+### Хранение данных
+
+Все списки хранятся в файле `src/data/bad_words.json`:
+
+```json
+{
+  "bad_words": ["слово1", "слово2", ...],
+  "exceptions": ["исключение1", "исключение2", ...]
+}
+```
+
+Изменения через команды применяются **немедленно**, перезапуск бота не требуется.
+
+### Логирование
+
+Все действия записываются в:
+- **bot.log** - файл логов
+- **Админ-чат** - уведомления о мутах
+
+Примеры логов:
+```
+[INFO] Пользователь 123456789 получил автоматический мут на 5 минут за нецензурную лексику (нарушение #1)
+[INFO] Нарушение пользователя 123456789 зафиксировано в чате -100123456789
+[INFO] Администратор 987654321 добавил бранное слово: спам
+```
+
+### База данных
+
+Таблица `violations` хранит все нарушения:
+- `id` - уникальный идентификатор
+- `user_id` - ID пользователя
+- `chat_id` - ID чата
+- `violation_date` - время нарушения (unix timestamp)
+- `violation_type` - тип нарушения ('bad_language')
+
+### Настройка системы
+
+#### Изменение уровней мутов
+
+Откройте `src/modules/auto_mute.py` и измените массив `MUTE_LEVELS`:
+
+```python
+MUTE_LEVELS = [
+    300,        # 1. 5 минут
+    900,        # 2. 15 минут
+    # ... добавьте или измените уровни
+    None,       # Перманентный мут
+]
+```
+
+#### Изменение периода накопления
+
+Измените `VIOLATIONS_PERIOD` в `src/modules/auto_mute.py`:
+
+```python
+VIOLATIONS_PERIOD = 2592000  # 30 дней в секундах
+```
+
+### Требования
+
+- Python 3.7+
+- pyTelegramBotAPI (telebot)
+- SQLite3
+- Права бота в чате:
+  - Удаление сообщений
+  - Ограничение пользователей
+
+### Устранение проблем
+
+При возникновении проблем проверьте:
+1. Логи бота в файле `bot.log`
+2. Права бота в чате (удаление сообщений, ограничение пользователей)
+3. Корректность настроек в `.env`
+4. Наличие файла `src/data/bad_words.json`