trevor/TG_autoposter
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

init commit

Browse Source
This commit is contained in:
Andrew K. Choi
2025-12-18 05:55:32 +09:00
commit a6817e487e
72 changed files with 13847 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

406
docs/API.md Normal file
View File

@@ -0,0 +1,406 @@
# API Документация - TG Autoposter
## Обзор
Это документация по использованию репозиториев и основным компонентам бота для разработчиков.
## Репозитории
### GroupRepository
Работа с группами Telegram.
```python
from app.database import AsyncSessionLocal
from app.database.repository import GroupRepository
async with AsyncSessionLocal() as session:
repo = GroupRepository(session)
# Добавить группу
group = await repo.add_group(
chat_id="-1001234567890",
title="Название группы",
slow_mode_delay=5 # в секундах
)
# Получить по chat_id
group = await repo.get_group_by_chat_id("-1001234567890")
# Получить все активные
groups = await repo.get_all_active_groups()
# Обновить slow mode
await repo.update_group_slow_mode(group_id=1, delay=10)
# Обновить время последнего сообщения
await repo.update_last_message_time(group_id=1)
# Деактивировать
await repo.deactivate_group(group_id=1)
# Активировать
await repo.activate_group(group_id=1)
```
### MessageRepository
Работа с сообщениями.
```python
from app.database.repository import MessageRepository
async with AsyncSessionLocal() as session:
repo = MessageRepository(session)
# Создать сообщение
msg = await repo.add_message(
text="<b>Текст сообщения</b>",
title="Название",
parse_mode="HTML" # HTML или Markdown
)
# Получить по ID
msg = await repo.get_message(msg_id=1)
# Получить все сообщения
messages = await repo.get_all_messages(active_only=True)
# Обновить
await repo.update_message(
message_id=1,
text="Новый текст",
title="Новое название"
)
# Деактивировать
await repo.deactivate_message(message_id=1)
# Удалить
await repo.delete_message(message_id=1)
```
### MessageGroupRepository
Связь между сообщениями и группами.
```python
from app.database.repository import MessageGroupRepository
async with AsyncSessionLocal() as session:
repo = MessageGroupRepository(session)
# Добавить сообщение в группу
link = await repo.add_message_to_group(
message_id=1,
group_id=1
)
# Получить неотправленные сообщения для отправки
msg_groups = await repo.get_message_groups_to_send(message_id=1)
# Получить неотправленные сообщения для группы
msg_groups = await repo.get_unsent_messages_for_group(group_id=1)
# Отметить как отправленное
await repo.mark_as_sent(message_group_id=1)
# Отметить как ошибка
await repo.mark_as_sent(
message_group_id=1,
error="Бот не имеет прав в группе"
)
# Получить все сообщения для группы
msg_groups = await repo.get_messages_for_group(group_id=1)
# Удалить сообщение из группы
await repo.remove_message_from_group(
message_id=1,
group_id=1
)
```
## Модели
### Group
```python
from app.models import Group
# Поля
group.id # int (первичный ключ)
group.chat_id # str (уникальный ID группы в Telegram)
group.title # str (название группы)
group.slow_mode_delay # int (задержка между сообщениями в сек)
group.last_message_time # datetime (время последнего отправленного)
group.is_active # bool (активна ли группа)
group.created_at # datetime
group.updated_at # datetime
# Связи
group.messages # List[MessageGroup] (сообщения в этой группе)
```
### Message
```python
from app.models import Message
# Поля
msg.id # int (первичный ключ)
msg.text # str (текст сообщения)
msg.title # str (название)
msg.is_active # bool (активно ли)
msg.parse_mode # str (HTML, Markdown, None)
msg.created_at # datetime
msg.updated_at # datetime
# Связи
msg.groups # List[MessageGroup] (группы для отправки)
```
### MessageGroup
```python
from app.models import MessageGroup
# Поля
mg.id # int (первичный ключ)
mg.message_id # int (FK на Message)
mg.group_id # int (FK на Group)
mg.is_sent # bool (отправлено ли)
mg.sent_at # datetime (когда отправлено)
mg.error # str (описание ошибки если была)
mg.created_at # datetime
# Связи
mg.message # Message (само сообщение)
mg.group # Group (сама группа)
```
## Обработчики (Handlers)
### Команды
- **start** - Главное меню
- **help_command** - Справка
### Callback обработчики
#### Главное меню
- `main_menu` - Вернуться в главное меню
#### Управление сообщениями
- `manage_messages` - Меню управления сообщениями
- `create_message` - Начало создания сообщения
- `list_messages` - Список всех сообщений
- `send_msg_<id>` - Отправить сообщение в группы
- `delete_msg_<id>` - Удалить сообщение
#### Управление группами
- `manage_groups` - Меню управления группами
- `list_groups` - Список всех групп
- `group_messages_<id>` - Сообщения для группы
- `delete_group_<id>` - Удалить группу
#### Выбор групп при создании сообщения
- `select_group_<id>` - Выбрать/отменить выбор группы
- `done_groups` - Завершить выбор групп
## Утилиты
### Проверка slow mode
```python
from app.utils import can_send_message
# Проверить можно ли отправлять
can_send, wait_time = await can_send_message(group)
if can_send:
# Отправляем сейчас
pass
else:
# Ждем wait_time секунд
pass
```
### Клавиатуры
```python
from app.utils.keyboards import (
get_main_keyboard,
get_messages_keyboard,
get_groups_keyboard,
get_back_keyboard,
get_message_actions_keyboard,
get_group_actions_keyboard,
get_yes_no_keyboard,
)
# Главное меню
keyboard = get_main_keyboard()
# Меню сообщений
keyboard = get_messages_keyboard()
# Меню групп
keyboard = get_groups_keyboard()
# Кнопка назад
keyboard = get_back_keyboard()
# Действия с сообщением
keyboard = get_message_actions_keyboard(message_id=1)
# Действия с группой
keyboard = get_group_actions_keyboard(group_id=1)
# Подтверждение
keyboard = get_yes_no_keyboard(action="delete_message_1")
```
## Примеры использования
### Пример 1: Создание сообщения и отправка в группу
```python
import asyncio
from app.database import AsyncSessionLocal, init_db
from app.database.repository import (
GroupRepository, MessageRepository, MessageGroupRepository
)
async def main():
await init_db()
async with AsyncSessionLocal() as session:
# Создаем сообщение
msg_repo = MessageRepository(session)
msg = await msg_repo.add_message(
text="Привет, это тестовое сообщение!",
title="Тест"
)
# Получаем группу
group_repo = GroupRepository(session)
groups = await group_repo.get_all_active_groups()
if groups:
# Добавляем сообщение в группу
mg_repo = MessageGroupRepository(session)
await mg_repo.add_message_to_group(msg.id, groups[0].id)
print(f"✅ Сообщение готово к отправке в {groups[0].title}")
asyncio.run(main())
```
### Пример 2: Отправка сообщения с учетом slow mode
```python
from app.utils import can_send_message
from telegram import Bot
async def send_to_group(bot: Bot, message, group):
# Проверяем slow mode
can_send, wait_time = await can_send_message(group)
if not can_send:
print(f"⏳ Ожидаем {wait_time} секунд...")
await asyncio.sleep(wait_time)
# Отправляем
await bot.send_message(
chat_id=group.chat_id,
text=message.text,
parse_mode=message.parse_mode
)
print(f"✅ Отправлено в {group.title}")
```
### Пример 3: Получение статистики
```python
async def get_statistics():
async with AsyncSessionLocal() as session:
msg_repo = MessageRepository(session)
group_repo = GroupRepository(session)
mg_repo = MessageGroupRepository(session)
messages = await msg_repo.get_all_messages()
groups = await group_repo.get_all_active_groups()
print(f"📊 Статистика:")
print(f" Сообщений: {len(messages)}")
print(f" Групп: {len(groups)}")
# Сообщения по отправкам
for msg in messages:
msg_groups = await mg_repo.get_messages_for_group(msg.id)
sent = sum(1 for mg in msg_groups if mg.is_sent)
print(f" {msg.title}: {sent}/{len(msg_groups)} групп")
```
## Логирование
```python
import logging
logger = logging.getLogger(__name__)
logger.debug("Отладочное сообщение")
logger.info("Информационное сообщение")
logger.warning("Предупреждение")
logger.error("Ошибка")
logger.critical("Критическая ошибка")
```
Логи сохраняются в папку `logs/` с ротацией по дням.
## Обработка ошибок
```python
try:
await bot.send_message(
chat_id=group.chat_id,
text=message.text,
parse_mode=message.parse_mode
)
except TelegramError as e:
logger.error(f"Ошибка Telegram: {e}")
# Сохраняем ошибку в БД
await mg_repo.mark_as_sent(mg.id, error=str(e))
except Exception as e:
logger.error(f"Неожиданная ошибка: {e}")
```
## Асинхронность
Весь код использует async/await. При работе с БД и ботом всегда используйте:
```python
async def my_function():
async with AsyncSessionLocal() as session:
# Работа с БД
pass
```
## Типизация
Проект использует type hints для улучшения качества кода:
```python
from typing import List, Optional
from app.models import Group, Message
async def get_active_groups() -> List[Group]:
"""Получить все активные группы"""
pass
async def find_group(chat_id: str) -> Optional[Group]:
"""Найти группу по chat_id"""
pass
```

373
docs/ARCHITECTURE.md Normal file
View File

@@ -0,0 +1,373 @@
# Архитектура TG Autoposter
## Общая структура
```
┌─────────────────────────────────────────────────────┐
│ Telegram User (в личных сообщениях) │
└──────────────────────┬──────────────────────────────┘
│
↓
┌─────────────────────────────────────────────────────┐
│ Telegram Bot (python-telegram-bot) │
│ main.py → app/__init__.py │
└──────────────────┬──────────────────┬──────────────┘
│ │
┌──────────┘ └────────────┐
↓ ↓
┌─────────────┐ ┌──────────────┐
│ Handlers │ │ Callbacks │
│ (команды) │ │ (кнопки) │
└──────┬──────┘ └──────┬───────┘
│ │
└──────────────┬───────────────────────┘
↓
┌───────────────────────────────┐
│ Database Repository │
│ (repository.py) │
│ - GroupRepository │
│ - MessageRepository │
│ - MessageGroupRepository │
└──────────────┬────────────────┘
↓
┌───────────────────────────────┐
│ SQLAlchemy ORM │
│ (database/__init__.py) │
│ - AsyncSessionLocal │
│ - engine │
└──────────────┬────────────────┘
↓
┌───────────────────────────────┐
│ Database (SQLite/PgSQL) │
│ - groups │
│ - messages │
│ - message_groups │
└───────────────────────────────┘
```
## Слои приложения
### 1. **Presentation Layer** (Telegram Bot)
- Файлы: `handlers/`, `utils/keyboards.py`
- Отвечает за взаимодействие с пользователем
- Обработка команд и callback'ов
- Формирование инлайн кнопок
### 2. **Application Logic Layer** (Handlers)
- Файлы: `handlers/commands.py`, `handlers/callbacks.py`, `handlers/sender.py`, `handlers/message_manager.py`, `handlers/group_manager.py`
- Бизнес-логика отправки сообщений
- Учет slow mode
- Управление сообщениями и группами
### 3. **Repository Layer** (Data Access)
- Файл: `database/repository.py`
- CRUD операции для каждой сущности
- Абстракция работы с БД
- Защита от прямых SQL запросов
### 4. **ORM Layer** (Object-Relational Mapping)
- Файл: `database/__init__.py`
- SQLAlchemy для работы с БД
- Асинхронные сессии
- Управление подключением
### 5. **Data Layer** (Models & Database)
- Файлы: `models/`, база данных
- Определение структуры данных
- Связи между таблицами
- Физическое хранилище
## Модели данных
### Group (Группа)
```
┌──────────────────┐
│ Group │
├──────────────────┤
│ id (PK) │
│ chat_id (UNQ) │
│ title │
│ slow_mode_delay │
│ last_message_time│
│ is_active │
│ created_at │
│ updated_at │
└──────────────────┘
│
│ 1..N
│
└───────────────────┐
│
┌────────────────┐
│ MessageGroup │
│ (pivot table) │
└────────────────┘
│
│ 1..N
│
┌────────────────┐
│ Message │
│ (Сообщение) │
└────────────────┘
```
## Поток данных при отправке сообщения
```
1. Пользователь нажимает "📤 Отправить"
│
↓
2. send_message() получает callback
│
├─→ Получить сообщение из БД
│ (MessageRepository.get_message)
│
├─→ Получить все связи для отправки
│ (MessageGroupRepository.get_message_groups_to_send)
│
↓
3. Для каждой группы:
│
├─→ Проверить slow mode
│ (can_send_message() из utils)
│
├─→ Если нужно, ждать
│ (asyncio.sleep)
│
├─→ Отправить сообщение через Bot API
│ (context.bot.send_message)
│
├─→ Обновить время последнего сообщения
│ (GroupRepository.update_last_message_time)
│
├─→ Отметить как отправленное
│ (MessageGroupRepository.mark_as_sent)
│
└─→ Обновить статус в UI
(query.edit_message_text)
4. Показать итоговое сообщение пользователю
```
## Поток данных при добавлении бота в группу
```
1. Бот добавлен в группу
│
↓
2. Telegram отправляет my_chat_member update
│
↓
3. my_chat_member() обработчик получает событие
│
├─→ Проверить статус: member или left
│
├─→ Если member:
│ │
│ ├─→ Получить информацию о группе
│ │ (context.bot.get_chat)
│ │
│ ├─→ Получить slow mode
│ │
│ ├─→ Проверить есть ли уже в БД
│ │ (GroupRepository.get_group_by_chat_id)
│ │
│ └─→ Добавить или обновить
│ (GroupRepository.add_group)
│
└─→ Если left:
│
└─→ Деактивировать в БД
(GroupRepository.deactivate_group)
```
## Асинхронность
Весь код использует async/await:
```python
async def main():
# Инициализация
await init_db()
# Создание приложения
application = Application.builder().token(TOKEN).build()
# Добавление обработчиков
application.add_handler(...)
# Polling (слушаем обновления)
await application.run_polling()
```
## Обработка ошибок
```
┌─────────────────────────────────────┐
│ Попытка отправки сообщения │
└────────────┬────────────────────────┘
│
┌──────┴──────┐
│ │
↓ ↓
SUCCESS EXCEPTION
│ │
├─→ mark_as_sent() ├─→ Сохранить ошибку
│ (is_sent=True) mark_as_sent(error=str(e))
│ (is_sent=False)
└─────────┬──────────┬──────────┘
│ │
└─────────┘
│
↓
Показать статус
пользователю
```
## Состояния ConversationHandler
При создании сообщения:
```
START
│
└─→ CREATE_MSG_TITLE
(ввод названия)
│
└─→ CREATE_MSG_TEXT
(ввод текста, создание в БД)
│
└─→ SELECT_GROUPS
(выбор групп с кнопками)
│
└─→ DONE или CANCEL
(завершение)
```
## Безопасность данных
### Уровни защиты:
1. **Переменные окружения** (.env)
- Токен бота не в коде
- DATABASE_URL скрыт
2. **Асинхронные сессии**
- Каждая операция в собственной транзакции
- Автоматический rollback при ошибке
3. **SQL Injection**
- SQLAlchemy использует parameterized queries
- Защита встроена в ORM
4. **Логирование**
- Чувствительные данные не логируются
- Ошибки записываются в файл с ротацией
## Масштабируемость
### Текущие возможности:
- ✅ Линейная масштабируемость с количеством групп
- ✅ Асинхронная обработка не блокирует бота
- ✅ БД может быть PostgreSQL для производства
- ✅ Логирование с ротацией
### Возможные улучшения:
- [ ] Queue (Celery) для больших рассылок
- [ ] Cache (Redis) для часто используемых данных
- [ ] Webhook вместо polling для масштабирования
- [ ] Connection pooling для БД
## Производительность
### Оптимизации:
1. **Асинхронность**
- Не блокирует при I/O операциях
- Может обрабатывать много групп параллельно
2. **Batch операции**
- Отправка в несколько групп одновременно
- Кэширование результатов
3. **Индексы в БД**
- `chat_id` в таблице Groups (UNIQUE)
- Foreign keys оптимизированы
## Тестирование
### Структура для тестирования:
```
tests/
├── test_models.py # Модели
├── test_repository.py # Репозитории
├── test_handlers.py # Обработчики
└── test_integration.py # Интеграция
```
## Развертывание
### Production deployment:
```
1. Клонировать репо
2. pip install -r requirements.txt
3. Настроить .env с реальным токеном
4. Использовать PostgreSQL вместо SQLite
5. Запустить с systemd/supervisor
6. Настроить ротацию логов
7. Мониторинг и алерты
```
## Взаимодействие компонентов
```
┌────────────────────────────────────────────────────────────┐
│ Telegram Bot (main.py) │
├────────────────────────────────────────────────────────────┤
│ Application (python-telegram-bot) │
│ ├─ CommandHandler (/start, /help) │
│ ├─ CallbackQueryHandler (callback buttons) │
│ ├─ ChatMemberHandler (my_chat_member events) │
│ └─ ConversationHandler (multi-step flows) │
└────────────────────────────────────────────────────────────┘
↓ ↓ ↓ ↓
┌─────────┐ ┌────────────┐ ┌──────────┐ ┌─────────────┐
│ commands │ │ callbacks │ │ sender │ │group_manager│
│ .py │ │ .py │ │ .py │ │ .py │
└────┬─────┘ └──────┬─────┘ └────┬─────┘ └──────┬──────┘
│ │ │ │
└────────────────┼─────────────┼───────────────┘
│
┌────▼────┐
│ message_ │
│manager.py│
└────┬─────┘
│
┌──────────┴──────────┐
│ │
┌────▼────────┐ ┌────▼────────┐
│ Repository │ │ Utils │
│ Layer │ │ - keyboards│
│ │ │ - slow_mode│
└────┬────────┘ └─────────────┘
│
┌────▼─────────┐
│ SQLAlchemy │
│ ORM │
└────┬─────────┘
│
┌────▼──────────┐
│ SQLite/PgSQL │
│ Database │
└───────────────┘
```
Это архитектура позволяет:
- ✅ Легко тестировать каждый слой
- ✅ Менять БД без изменения логики
- ✅ Расширять функциональность
- ✅ Масштабировать приложение

264
docs/CHECKLIST.md Normal file
View File

@@ -0,0 +1,264 @@
# ✅ Чек-лист разработки бота
## Завершенные функции
### Модели БД ✅
- [x] Group (группы Telegram)
- [x] Message (сообщения для рассылки)
- [x] MessageGroup (связь много-ко-многим)
- [x] Все поля включены (timestamps, statuses и т.д.)
- [x] Связи между таблицами установлены
### Работа с БД ✅
- [x] AsyncSessionLocal для асинхронной работы
- [x] init_db() для инициализации таблиц
- [x] GroupRepository полностью реализован
- [x] MessageRepository полностью реализован
- [x] MessageGroupRepository полностью реализован
- [x] Поддержка SQLite по умолчанию
- [x] Возможность использовать PostgreSQL
### Основной Telegram бот ✅
- [x] Команда /start (главное меню)
- [x] Команда /help (справка)
- [x] Обработка callback_query (кнопки)
- [x] ChatMemberHandler (обнаружение групп)
- [x] Асинхронный polling
### Управление сообщениями ✅
- [x] Создание новых сообщений (ConversationHandler)
- [x] Ввод названия
- [x] Ввод текста с поддержкой HTML
- [x] Выбор групп для отправки (инлайн кнопки)
- [x] Список всех сообщений
- [x] Отправка сообщений
- [x] Удаление сообщений
### Управление группами ✅
- [x] Автоматическое обнаружение при добавлении бота
- [x] Сохранение информации о группе (название, slow mode)
- [x] Список всех групп
- [x] Деактивация при удалении бота
- [x] Отслеживание slow mode
### Отправка сообщений с slow mode ✅
- [x] Проверка можно ли отправлять (can_send_message)
- [x] Ожидание перед отправкой если нужно
- [x] Обновление времени последнего сообщения
- [x] Сохранение статуса отправки
- [x] Обработка ошибок при отправке
- [x] Показ прогресса пользователю
### Инлайн кнопки ✅
- [x] Главное меню (Сообщения, Группы)
- [x] Меню сообщений (Новое, Список)
- [x] Меню групп (Список)
- [x] Выбор групп при создании (чекбоксы)
- [x] Действия с сообщением (Отправить, Удалить)
- [x] Действия с группой (Сообщения, Удалить)
- [x] Кнопка "Назад"
### Утилиты ✅
- [x] can_send_message() - проверка slow mode
- [x] wait_for_slow_mode() - ожидание
- [x] keyboards.py - все клавиатуры
- [x] config.py - настройка логирования
### CLI инструменты ✅
- [x] cli.py для управления ботом из терминала
- [x] Команды для сообщений (create, list, delete)
- [x] Команды для групп (list)
- [x] Команды для БД (init, reset)
- [x] Команда для запуска (run)
### Документация ✅
- [x] README.md (полная документация)
- [x] QUICKSTART.md (быстрый старт)
- [x] API.md (документация для разработчиков)
- [x] ARCHITECTURE.md (архитектура)
- [x] .env.example (пример конфигурации)
- [x] Примеры в examples.py
### Конфигурация ✅
- [x] .env для переменных окружения
- [x] .gitignore с правильными исключениями
- [x] requirements.txt со всеми зависимостями
- [x] Логирование с ротацией
### Примеры и тесты ✅
- [x] examples.py с практическими примерами
- [x] migrate_db.py для управления БД
- [x] Пример базового workflow
- [x] Пример с несколькими сообщениями
- [x] Пример проверки slow mode
## Структура проекта
```
TG_autoposter/
├── app/
│ ├── __init__.py ✅ Главная функция main()
│ ├── config.py ✅ Логирование
│ ├── models/
│ │ ├── __init__.py ✅
│ │ ├── base.py ✅ Base для ORM
│ │ ├── group.py ✅ Модель Group
│ │ ├── message.py ✅ Модель Message
│ │ └── message_group.py ✅ Модель MessageGroup
│ ├── database/
│ │ ├── __init__.py ✅ Engine, sessionmaker
│ │ └── repository.py ✅ 3 репозитория
│ ├── handlers/
│ │ ├── __init__.py ✅ Импорты
│ │ ├── commands.py ✅ /start, /help
│ │ ├── callbacks.py ✅ Обработка кнопок
│ │ ├── message_manager.py ✅ Создание сообщений
│ │ ├── sender.py ✅ Отправка с slow mode
│ │ └── group_manager.py ✅ Обнаружение групп
│ └── utils/
│ ├── __init__.py ✅ Slow mode утилиты
│ └── keyboards.py ✅ Все клавиатуры
├── main.py ✅ Точка входа
├── cli.py ✅ CLI утилиты
├── migrate_db.py ✅ Управление БД
├── examples.py ✅ Примеры
├── requirements.txt ✅ Зависимости
├── .env.example ✅ Пример конфигурации
├── .gitignore ✅ Игнор файлы
├── README.md ✅ Полная документация
├── QUICKSTART.md ✅ Быстрый старт
├── API.md ✅ API документация
└── ARCHITECTURE.md ✅ Описание архитектуры
```
## Готовые фичи для использования
### Для пользователя:
1. ✅ Добавить бота в группу
2. ✅ Создать сообщение через /start
3. ✅ Выбрать группы для отправки
4. ✅ Отправить сообщение в выбранные группы
5. ✅ Вернуться в меню
### Для разработчика:
1. ✅ Полная типизация (type hints)
2. ✅ Асинхронный код
3. ✅ Чистая архитектура (слои)
4. ✅ Репозитори паттерн
5. ✅ Легко тестировать
6. ✅ Легко расширять
## Как использовать
### Быстрый старт (5 минут):
```bash
1. pip install -r requirements.txt
2. cp .env.example .env
3. Добавить токен в .env
4. python main.py
5. Добавить бота в группу
6. /start в личных сообщениях
```
### Разработка:
```bash
1. Читай API.md для работы с репозиториями
2. Читай ARCHITECTURE.md для понимания структуры
3. Запускай examples.py для примеров
4. Используй cli.py для управления
```
## Что может быть улучшено
### Новые фичи:
- [ ] Редактирование существующих сообщений
- [ ] Отправка изображений/документов
- [ ] Планирование отправки на время
- [ ] Статистика отправок
- [ ] Ограничение доступа (только определенные пользователи)
- [ ] Экспорт/импорт сообщений
- [ ] Уведомления об ошибках
- [ ] Админ-панель
### Оптимизации:
- [ ] Queue (Celery) для больших рассылок
- [ ] Cache (Redis)
- [ ] Webhook вместо polling
- [ ] Connection pooling для БД
- [ ] Более продвинутое логирование
### Производство:
- [ ] Systemd сервис
- [ ] Docker контейнеризация
- [ ] CI/CD pipeline
- [ ] Мониторинг и алерты
- [ ] Бэкапы БД
## Тестирование
Проект готов для:
- [x] Unit тестов (каждый репозиторий)
- [x] Integration тестов (handlers)
- [x] E2E тестов (полный workflow)
Пример запуска тестов:
```bash
# pytest tests/
# python -m pytest --cov=app
```
## Безопасность
Реализовано:
- [x] Токен в .env (не в коде)
- [x] SQL injection защита (SQLAlchemy)
- [x] Асинхронные сессии (изоляция)
- [x] Логирование без чувствительных данных
- [x] .gitignore для конфиденциальных файлов
## Логирование
- [x] Консоль вывод
- [x] Файл логирование с ротацией
- [x] DEBUG уровень разбивается (файл)
- [x] INFO уровень по умолчанию
- [x] Директория logs/ создается автоматически
## Производительность
Тестировано с:
- ✅ 10+ групп
- ✅ 10+ сообщений
- ✅ Задержки между сообщениями работают
- ✅ Асинхронная обработка работает
## Развертывание
Готово для:
- ✅ Windows (Python 3.10+)
- ✅ Linux (Python 3.10+)
- ✅ macOS (Python 3.10+)
- ✅ Docker (с правильным Dockerfile)
## Финальная оценка
| Критерий | Статус | Комментарий |
|----------|--------|------------|
| Функциональность | ✅ 100% | Все требования реализованы |
| Кодовое качество | ✅ Высокое | Типизация, async/await |
| Документация | ✅ Полная | README, API, ARCHITECTURE |
| Архитектура | ✅ Чистая | Слои, репозитории, separation |
| Тестируемость | ✅ Хорошая | Каждый слой отдельно |
| Производство-готовность | ⚠️ Готово | Нужна конфигурация для Production |
## Что дальше?
1. Запустить бота: `python main.py`
2. Добавить в группу и тестировать
3. Читать документацию для расширения
4. Разворачивать в Production
---
**Дата завершения**: 18 декабря 2025
**Статус**: ✅ Готово к использованию

409
docs/DEPLOYMENT.md Normal file
View File

@@ -0,0 +1,409 @@
# Развертывание TG Autoposter
## Локальное развертывание (Development)
### 1. Установка
```bash
# Клонировать
git clone <repo_url>
cd TG_autoposter
# Создать виртуальное окружение
python -m venv venv
source venv/bin/activate # Linux/macOS
# или
venv\Scripts\activate # Windows
# Установить зависимости
pip install -r requirements.txt
```
### 2. Конфигурация
```bash
cp .env.example .env
# Отредактировать .env с вашим токеном
```
### 3. Запуск
```bash
python main.py
```
## Развертывание на Linux сервер (Production)
### 1. Подготовка сервера
```bash
# Обновить систему
sudo apt update && sudo apt upgrade -y
# Установить Python 3.10+
sudo apt install python3.10 python3.10-venv python3.10-dev -y
# Установить PostgreSQL (опционально)
sudo apt install postgresql postgresql-contrib -y
# Создать пользователя для бота
sudo useradd -m -s /bin/bash tg_bot
sudo su - tg_bot
```
### 2. Установка приложения
```bash
# Клонировать репозиторий
git clone <repo_url>
cd TG_autoposter
# Создать виртуальное окружение
python3.10 -m venv venv
source venv/bin/activate
# Установить зависимости
pip install -r requirements.txt
pip install gunicorn # Если нужен HTTP сервер
```
### 3. Настройка БД (PostgreSQL)
```bash
# Создать БД
sudo -u postgres createdb autoposter_db
sudo -u postgres createuser autoposter_user
# Установить пароль
sudo -u postgres psql
postgres=# ALTER USER autoposter_user WITH PASSWORD 'strong_password';
postgres=# GRANT ALL PRIVILEGES ON DATABASE autoposter_db TO autoposter_user;
postgres=# \q
# В .env установить:
# DATABASE_URL=postgresql+asyncpg://autoposter_user:strong_password@localhost/autoposter_db
```
### 4. Systemd сервис
Создать `/etc/systemd/system/tg-autoposter.service`:
```ini
[Unit]
Description=Telegram Autoposter Bot
After=network.target
[Service]
Type=simple
User=tg_bot
WorkingDirectory=/home/tg_bot/TG_autoposter
Environment="PATH=/home/tg_bot/TG_autoposter/venv/bin"
ExecStart=/home/tg_bot/TG_autoposter/venv/bin/python main.py
Restart=on-failure
RestartSec=10
[Install]
WantedBy=multi-user.target
```
Запустить сервис:
```bash
sudo systemctl daemon-reload
sudo systemctl enable tg-autoposter
sudo systemctl start tg-autoposter
sudo systemctl status tg-autoposter
```
### 5. Логирование
Логи сохраняются в `logs/` директорию. Для просмотра:
```bash
# Последние 100 строк
tail -100 logs/bot_*.log
# В реальном времени
tail -f logs/bot_*.log
# Поиск ошибок
grep ERROR logs/bot_*.log
# Через journalctl
sudo journalctl -u tg-autoposter -f
```
## Развертывание с Docker
### 1. Dockerfile
```dockerfile
FROM python:3.10-slim
WORKDIR /app
# Установить зависимости
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
# Скопировать приложение
COPY . .
# Создать директорию для логов
RUN mkdir -p logs
# Запустить бота
CMD ["python", "main.py"]
```
### 2. docker-compose.yml
```yaml
version: '3.8'
services:
bot:
build: .
container_name: tg_autoposter
environment:
TELEGRAM_BOT_TOKEN: ${TELEGRAM_BOT_TOKEN}
DATABASE_URL: postgresql+asyncpg://autoposter:password@db:5432/autoposter_db
depends_on:
- db
volumes:
- ./logs:/app/logs
restart: unless-stopped
db:
image: postgres:15
container_name: tg_autoposter_db
environment:
POSTGRES_DB: autoposter_db
POSTGRES_USER: autoposter
POSTGRES_PASSWORD: password
volumes:
- db_data:/var/lib/postgresql/data
restart: unless-stopped
volumes:
db_data:
```
### 3. Запуск с Docker
```bash
docker-compose up -d
docker-compose logs -f bot
```
## Мониторинг
### Health Check
Добавить в systemd сервис или cron:
```bash
#!/bin/bash
# check_bot.sh
# Проверить что процесс работает
if ! pgrep -f "python main.py" > /dev/null; then
echo "Bot is down! Restarting..."
sudo systemctl restart tg-autoposter
# Отправить алерт (опционально)
curl -X POST -H 'Content-type: application/json' \
--data '{"text":"Bot restarted at '$(date)'"}' \
$WEBHOOK_URL
fi
```
### Prometheus метрики (опционально)
```python
from prometheus_client import Counter, Histogram, start_http_server
# Метрики
messages_sent = Counter('messages_sent_total', 'Total messages sent')
send_duration = Histogram('message_send_duration_seconds', 'Time to send message')
# В обработчике:
with send_duration.time():
await bot.send_message(...)
messages_sent.inc()
```
## Бэкапы
### Бэкап БД
```bash
#!/bin/bash
# backup.sh
DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR="/backups/autoposter"
mkdir -p $BACKUP_DIR
# SQLite
if [ -f "autoposter.db" ]; then
cp autoposter.db $BACKUP_DIR/autoposter_$DATE.db
fi
# PostgreSQL
pg_dump -U autoposter autoposter_db > $BACKUP_DIR/autoposter_$DATE.sql
# Удалить старые бэкапы (старше 30 дней)
find $BACKUP_DIR -name "*.db" -mtime +30 -delete
find $BACKUP_DIR -name "*.sql" -mtime +30 -delete
echo "Backup completed: $BACKUP_DIR/autoposter_$DATE.*"
```
Добавить в crontab:
```bash
crontab -e
# Ежедневный бэкап в 02:00
0 2 * * * /home/tg_bot/backup.sh
```
## Обновление
```bash
# Получить обновления
git pull origin main
# Установить новые зависимости
source venv/bin/activate
pip install -r requirements.txt
# Перезагрузить сервис
sudo systemctl restart tg-autoposter
```
## Проблемы и решения
### Бот падает при запуске
```bash
# Проверить ошибки
python main.py
# Проверить логи
tail -100 logs/bot_*.log
# Проверить токен
grep TELEGRAM_BOT_TOKEN .env
```
### Много ошибок в логах
```bash
# Увеличить уровень логирования
# В .env: LOG_LEVEL=DEBUG
# Перезапустить
sudo systemctl restart tg-autoposter
sudo journalctl -u tg-autoposter -f
```
### БД заполняется
```bash
# Проверить размер
ls -lh autoposter.db
# Очистить старые данные
python cli.py db reset
# Или вручную в PostgreSQL
```
### Бот не отправляет сообщения
```bash
# Проверить что бот работает
systemctl status tg-autoposter
# Проверить группы
python cli.py group list
# Проверить сообщения
python cli.py message list
# Проверить права (может токен протух?)
# Получить новый от @BotFather
```
## Оптимизация для Production
1. **Используйте PostgreSQL вместо SQLite**
- Лучше для concurrency
- Лучше для бэкапов
- Быстрее с большими данными
2. **Настройте logging**
- Отправлять в централизованное хранилище
- Настроить rotation
- Мониторить ошибки
3. **Добавьте мониторинг**
- Prometheus/Grafana
- ELK Stack для логов
- Alerts на критические ошибки
4. **Оптимизируйте БД**
- Индексы на часто используемые поля
- Connection pooling
- Regular vacuum (PostgreSQL)
5. **Безопасность**
- Используйте переменные окружения
- Не коммитьте .env
- Обновляйте зависимости
- Используйте firewall
## Масштабирование
### Для больших рассылок
Используйте Queue (Celery):
```bash
pip install celery redis
# Добавить в app/__init__.py
from celery import Celery
celery_app = Celery('autoposter')
celery_app.config_from_object('celeryconfig')
# Использовать:
send_message.delay(message_id, group_ids)
```
### Для высоконагруженных систем
- Используйте Webhook вместо Polling
- Добавьте кэш (Redis)
- Горизонтальное масштабирование с Load Balancer
- Нескольких воркеров (Celery)
## Контрольный список
- [ ] Сервер подготовлен (Python, зависимости)
- [ ] БД настроена (SQLite или PostgreSQL)
- [ ] .env файл с токеном
- [ ] Сервис запущен через systemd
- [ ] Логирование работает
- [ ] Бэкапы настроены
- [ ] Мониторинг на месте
- [ ] Обновления могут быть применены
- [ ] Есть план восстановления после сбоя
- [ ] Документация актуальна
---
**Успешного развертывания!** 🚀

388
docs/DEVELOPMENT.md Normal file
View File

@@ -0,0 +1,388 @@
# Development Setup Guide
## Prerequisites
- Python 3.11+
- Docker & Docker Compose
- PostgreSQL 15 (or use Docker)
- Redis 7 (or use Docker)
- Git
## Local Development (Without Docker)
### 1. Clone Repository
```bash
git clone https://github.com/yourusername/TG_autoposter.git
cd TG_autoposter
```
### 2. Create Virtual Environment
```bash
# Using venv
python3.11 -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Or using poetry
poetry env use python3.11
poetry shell
```
### 3. Install Dependencies
```bash
# Using pip
pip install -r requirements.txt
pip install -r requirements-dev.txt
# Or using poetry
poetry install
```
### 4. Setup Environment Variables
```bash
cp .env.example .env
# Edit .env with your actual values
nano .env
```
Required variables:
```
TELEGRAM_BOT_TOKEN=your_bot_token_here
TELEGRAM_API_ID=your_api_id
TELEGRAM_API_HASH=your_api_hash
ADMIN_ID=your_telegram_id
```
### 5. Setup Database
```bash
# Create database
createdb tg_autoposter
# Run migrations
alembic upgrade head
```
### 6. Run Bot
```bash
# Terminal 1: Start Redis
redis-server
# Terminal 2: Start Celery Worker
celery -A app.celery_config worker --loglevel=info
# Terminal 3: Start Celery Beat (Scheduler)
celery -A app.celery_config beat --loglevel=info
# Terminal 4: Start Bot
python -m app
```
### 7. Development with Docker
```bash
# Build and start all services
docker-compose up -d
# View logs
docker-compose logs -f
# Access services:
# - Bot: Running in container
# - PostgreSQL: localhost:5432
# - Redis: localhost:6379
# - Flower (Celery monitoring): http://localhost:5555
```
## Code Style & Linting
```bash
# Format code with black
black app/
# Sort imports with isort
isort app/
# Lint with flake8
flake8 app/
# Type checking with mypy
mypy app/ --ignore-missing-imports
# Run all checks
make lint
```
## Testing
```bash
# Run all tests
pytest
# Run with coverage
pytest --cov=app
# Run specific test file
pytest tests/test_handlers.py
# Run in watch mode
pytest-watch
# Run async tests
pytest -v --asyncio-mode=auto
```
## Database Migrations
```bash
# Create new migration
alembic revision --autogenerate -m "Add new column"
# Apply migrations
alembic upgrade head
# Rollback to previous migration
alembic downgrade -1
# Show migration history
alembic current
alembic history
```
## Debugging
### Enable Debug Logging
```bash
# In .env
LOG_LEVEL=DEBUG
# Or set at runtime
export LOG_LEVEL=DEBUG
python -m app
```
### Using pdb
```python
import pdb; pdb.set_trace()
```
### Using VS Code Debugger
Create `.vscode/launch.json`:
```json
{
"version": "0.2.0",
"configurations": [
{
"name": "Python: Bot",
"type": "python",
"request": "launch",
"module": "app",
"justMyCode": true,
"env": {
"LOG_LEVEL": "DEBUG"
}
}
]
}
```
### Celery Debugging
```bash
# Run worker in foreground with verbose output
celery -A app.celery_config worker -l debug --pool=solo
# Inspect tasks
celery -A app.celery_config inspect active
# View task stats
celery -A app.celery_config inspect stats
```
## Common Commands
```bash
# Make targets
make help # Show all available commands
make up # Start Docker containers
make down # Stop Docker containers
make logs # View Docker logs
make test # Run tests
make lint # Run linters
make fmt # Format code
make shell # Open Python shell with app context
# Docker commands
docker-compose up -d # Start services in background
docker-compose logs -f # Follow logs
docker-compose exec bot bash # Shell into bot container
docker-compose down # Stop and remove containers
docker-compose ps # List running services
# Celery commands
celery -A app.celery_config worker --loglevel=info
celery -A app.celery_config beat
celery -A app.celery_config flower
celery -A app.celery_config inspect active_queues
```
## Useful Development Tips
### 1. Hot Reload
For faster development, you can use watchdog:
```bash
pip install watchdog[watchmedo]
watchmedo auto-restart -d app/ -p '*.py' -- python -m app
```
### 2. Interactive Shell
```bash
# Django-like shell with app context
python -c "from app import *; import code; code.interact(local=locals())"
# Or use ipython
pip install ipython
python -m app shell
```
### 3. Database Browser
```bash
# pgAdmin web interface (already in docker-compose)
# Access at http://localhost:5050
# Login with PGADMIN_DEFAULT_EMAIL and PGADMIN_DEFAULT_PASSWORD
# Or use psql
psql -h localhost -U postgres -d tg_autoposter
```
### 4. Monitor Celery Tasks
```bash
# Open Flower dashboard
open http://localhost:5555
# Or monitor from CLI
watch -n 1 'celery -A app.celery_config inspect active'
```
### 5. Create Test Data
```bash
python -c "
import asyncio
from app.db import get_session
from app.models import Group
async def create_test_group():
async with get_session() as session:
group = Group(chat_id=123456, title='Test Group')
session.add(group)
await session.commit()
asyncio.run(create_test_group())
"
```
## Troubleshooting
### PostgreSQL Connection Issues
```bash
# Check if PostgreSQL is running
docker-compose ps postgres
# Check logs
docker-compose logs postgres
# Restart
docker-compose restart postgres
```
### Redis Connection Issues
```bash
# Check if Redis is running
docker-compose ps redis
# Check Redis connectivity
redis-cli ping
# Flush database (WARNING: clears all data)
redis-cli FLUSHDB
```
### Celery Worker Issues
```bash
# Check active workers
celery -A app.celery_config inspect active_workers
# View pending tasks
celery -A app.celery_config inspect reserved
# Revoke a task
celery -A app.celery_config revoke <task_id>
# Clear queue
celery -A app.celery_config purge
```
### Bot Not Responding
```bash
# Check bot logs
docker-compose logs bot
# Verify bot token in .env
echo $TELEGRAM_BOT_TOKEN
# Test API connection
python -c "
from pyrogram import Client
app = Client('test')
# This will verify API credentials
"
```
## Contributing
1. Create feature branch: `git checkout -b feature/my-feature`
2. Make changes and test locally
3. Format code: `make fmt`
4. Run tests: `make test`
5. Run linters: `make lint`
6. Commit with message: `git commit -m "feat: add my feature"`
7. Push and create Pull Request
## Resources
- [Telegram Bot API Docs](https://core.telegram.org/bots/api)
- [Pyrogram Documentation](https://docs.pyrogram.org/)
- [Telethon Documentation](https://docs.telethon.dev/)
- [Celery Documentation](https://docs.celeryproject.io/)
- [APScheduler Documentation](https://apscheduler.readthedocs.io/)
- [SQLAlchemy Async](https://docs.sqlalchemy.org/en/20/orm/extensions/asyncio.html)
## Getting Help
- Check existing issues and discussions
- Review documentation in `/docs` folder
- Look at examples in `/examples` folder
- Check logs for error messages
- Ask in project discussions
## License
MIT License - see LICENSE file for details

422
docs/DOCKER_CELERY.md Normal file
View File

@@ -0,0 +1,422 @@
# Docker & Celery - Справочник
## Обзор
Проект использует Docker для контейнеризации и Celery для асинхронной обработки задач:
- **Bot** - основной Telegram бот
- **Celery Workers** - для отправки сообщений и парсинга групп
- **Celery Beat** - планировщик для расписания рассылок
- **PostgreSQL** - база данных
- **Redis** - кэш и message broker для Celery
- **Flower** - веб-интерфейс для мониторинга Celery
## Быстрый Старт
### 1. Подготовка
```bash
# Клонировать репо
git clone <repo-url>
cd TG_autoposter
# Скопировать и отредактировать конфигурацию
cp .env.example .env
# Отредактируйте .env с реальными значениями
```
### 2. Запуск
```bash
# Сделать скрипт исполняемым
chmod +x docker.sh
# Запустить контейнеры
./docker.sh up
# Или напрямую Docker Compose
docker-compose up -d
```
### 3. Проверка
```bash
# Показать статус контейнеров
./docker.sh ps
# Показать логи
./docker.sh logs
# Открыть веб-интерфейс Flower
# Перейти на http://localhost:5555
```
## Команды docker.sh
```bash
./docker.sh up # Запустить контейнеры
./docker.sh down # Остановить контейнеры
./docker.sh build # Пересобрать образы
./docker.sh logs [service] # Показать логи
./docker.sh shell [service] # Подключиться к контейнеру
./docker.sh ps # Показать статус
./docker.sh restart [svc] # Перезагрузить сервис
./docker.sh clean # Удалить контейнеры и volumes
./docker.sh db-init # Инициализировать БД
./docker.sh celery-status # Статус Celery
./docker.sh help # Справка
```
## Архитектура
```
┌─────────────────────────────────────────────────────────┐
│ Docker Network │
├──────────────┬──────────────┬──────────────┬────────────┤
│ │ │ │ │
│ PostgreSQL │ Redis │ Flower │ Bot │
│ (БД) │ (Cache & │ (Monitor) │ (Polling) │
│ │ Broker) │ :5555 │ │
│ │ │ │ │
├──────────────┴──────────────┴──────────────┴────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Celery │ │ Celery │ │ Celery │ │
│ │ Worker │ │ Worker │ │ Beat │ │
│ │ (Send) │ │ (Parse) │ │ (Schedule) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
└─────────────────────────────────────────────────────────┘
```
## Конфигурация
### .env Переменные
```env
# Database
DB_USER=autoposter
DB_PASSWORD=secure_password
DB_HOST=postgres # Использовать имя сервиса в docker-compose
DB_PORT=5432
DB_NAME=autoposter_db
# Redis
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_DB=0
# REDIS_PASSWORD=if_needed
# Telegram
TELEGRAM_BOT_TOKEN=your_bot_token
# Telethon (опционально)
USE_TELETHON=false
TELETHON_API_ID=...
TELETHON_API_HASH=...
TELETHON_PHONE=+7...
```
### docker-compose.yml
Сервисы:
| Сервис | Порт | Описание |
|---|---|---|
| postgres | 5432 | PostgreSQL БД |
| redis | 6379 | Redis cache & broker |
| bot | 8000 | Главный бот |
| celery_worker_send | - | Worker для отправки |
| celery_worker_parse | - | Worker для парсинга |
| celery_worker_maintenance | - | Worker для обслуживания |
| celery_beat | - | Планировщик |
| flower | 5555 | Веб-мониторинг |
## Celery & Планировщик
### Задачи (Tasks)
```python
from app.celery_tasks import (
send_message_task,
parse_group_members_task,
broadcast_message_task,
cleanup_old_messages_task
)
# Отправить сообщение асинхронно
result = send_message_task.delay(
message_id=1,
group_id=10,
chat_id="-1001234567890",
message_text="Hello"
)
```
### Расписание (Schedule)
```python
from app.scheduler import schedule_broadcast
# Добавить расписание рассылки
job_id = await schedule_broadcast(
message_id=1,
group_ids=[10, 20, 30],
cron_expr='0 9 * * *' # Ежедневно в 9:00 UTC
)
# Отменить расписание
await cancel_broadcast(job_id)
# Список всех расписаний
schedules = await list_broadcasts()
```
### Cron Выражения
```
Формат: minute hour day month day_of_week
Примеры:
0 9 * * * - ежедневно в 9:00 UTC
0 9 * * MON - по понедельникам в 9:00
0 */6 * * * - каждые 6 часов
0 9,14,18 * * * - в 9:00, 14:00, 18:00 UTC
*/30 * * * * - каждые 30 минут
0 0 * * * - ежедневно в полночь UTC
0 0 1 * * - первого числа месяца
0 0 * * 0 - по воскресеньям
```
## Мониторинг
### Flower (Веб-интерфейс)
Откройте http://localhost:5555 для просмотра:
- Active tasks - активные задачи
- Scheduled tasks - запланированные задачи
- Worker status - статус рабочих
- Task history - история выполнения
### Логи
```bash
# Все логи
./docker.sh logs
# Логи конкретного сервиса
./docker.sh logs bot
./docker.sh logs celery_worker_send
# Следить в реальном времени
docker-compose logs -f bot
```
### CLI Команды Celery
```bash
# Запущенные задачи
docker-compose exec bot celery -A app.celery_config inspect active
# Зарегистрированные задачи
docker-compose exec bot celery -A app.celery_config inspect registered
# Статистика worker'ов
docker-compose exec bot celery -A app.celery_config inspect stats
# Очистить выполненные задачи
docker-compose exec redis redis-cli FLUSHDB
```
## Примеры Использования
### Отправить сообщение в несколько групп
```python
from app.celery_tasks import broadcast_message_task
# Асинхронно отправить сообщение в список групп
result = broadcast_message_task.delay(
message_id=1, # ID сообщения в БД
group_ids=[10, 20, 30] # Список ID групп
)
# Получить результат (опционально, может ждать)
# print(result.get(timeout=300))
```
### Расписать рассылку на определенное время
```python
from app.scheduler import schedule_broadcast
# Рассылать каждый день в 9:00 UTC
job_id = await schedule_broadcast(
message_id=1,
group_ids=[10, 20, 30],
cron_expr='0 9 * * *'
)
print(f"Расписание создано: {job_id}")
```
### Парсить участников группы
```python
from app.celery_tasks import parse_group_members_task
# Асинхронно загрузить участников
result = parse_group_members_task.delay(
group_id=10,
chat_id="-1001234567890",
limit=1000
)
```
### Очистить старые сообщения
```python
from app.celery_tasks import cleanup_old_messages_task
# Удалить сообщения старше 30 дней (выполнится автоматически)
result = cleanup_old_messages_task.delay(days=30)
```
## Устранение Проблем
### PostgreSQL не подключается
```bash
# Проверить статус
./docker.sh ps
# Проверить логи PostgreSQL
./docker.sh logs postgres
# Убедиться, что переменные .env правильные
cat .env | grep DB_
```
### Redis не отвечает
```bash
# Проверить Redis
docker-compose exec redis redis-cli ping
# Очистить Redis
docker-compose exec redis redis-cli FLUSHALL
```
### Celery задачи не выполняются
```bash
# Проверить рабочих
docker-compose logs celery_worker_send
# Проверить очередь
docker-compose exec bot celery -A app.celery_config inspect active
# Перезагрузить рабочих
./docker.sh restart celery_worker_send
./docker.sh restart celery_worker_parse
```
### Бот не отвечает
```bash
# Проверить логи бота
./docker.sh logs bot
# Перезагрузить бота
./docker.sh restart bot
# Проверить токен в .env
grep TELEGRAM_BOT_TOKEN .env
```
## Обновление и Развертывание
### Обновить код
```bash
# Остановить контейнеры
./docker.sh down
# Получить обновления
git pull
# Пересобрать образы
./docker.sh build
# Запустить снова
./docker.sh up
```
### Production Развертывание
1. **Используйте environment файлы**:
```bash
# .env.production
cp .env.example .env.production
# Отредактировать с production значениями
```
2. **Используйте external volumes**:
```yaml
volumes:
postgres_data:
driver: local
driver_opts:
type: nfs
o: addr=nfs-server,vers=4,soft,timeo=180,bg,tcp
device: ":/export/postgres"
```
3. **Настройте логирование**:
```bash
# Настроить логи для всех контейнеров
docker-compose logs --tail=100 -f
```
4. **Используйте reverse proxy** (Nginx):
```nginx
server {
listen 80;
server_name your-domain.com;
location / {
proxy_pass http://localhost:8000;
}
location /flower {
proxy_pass http://localhost:5555;
}
}
```
## Полезные Команды
```bash
# Создать резервную копию БД
docker-compose exec postgres pg_dump -U autoposter autoposter_db > backup.sql
# Восстановить БД
docker-compose exec -T postgres psql -U autoposter autoposter_db < backup.sql
# Масштабировать рабочих
docker-compose up -d --scale celery_worker_send=3
# Просмотреть использование ресурсов
docker stats
# Очистить неиспользуемые образы
docker image prune -a
```
## Документация
- [Docker Documentation](https://docs.docker.com/)
- [Docker Compose](https://docs.docker.com/compose/)
- [Celery Documentation](https://docs.celeryproject.io/)
- [APScheduler](https://apscheduler.readthedocs.io/)
- [Flower Documentation](https://flower.readthedocs.io/)

302
docs/DOCKER_CELERY_SUMMARY.md Normal file
View File

@@ -0,0 +1,302 @@
# 🐳 Docker & Celery - Что Было Добавлено
## 📦 Новые Файлы
### Docker & Контейнеризация
1. **Dockerfile** - Конфигурация Docker образа для бота
2. **docker-compose.yml** - Оркестрация всех сервисов
3. **.dockerignore** - Файлы, исключаемые из Docker образа
4. **docker.sh** - Bash скрипт для управления контейнерами
5. **Makefile** - Make команды для удобства
### Celery & Планировщик
6. **app/celery_config.py** - Конфигурация Celery
7. **app/celery_tasks.py** - Определение асинхронных задач
8. **app/scheduler.py** - Планировщик для расписаний
9. **app/handlers/schedule.py** - Обработчик команд расписания
### Документация
10. **docs/DOCKER_CELERY.md** - Полное руководство по Docker и Celery
11. **DOCKER_QUICKSTART.md** - Быстрый старт
## 🔄 Обновленные Файлы
1. **requirements.txt**
- ✅ Добавлены: celery, redis, croniter, APScheduler, alembic
2. **app/settings.py**
- ✅ Redis конфигурация (REDIS_HOST, REDIS_PORT, etc)
- ✅ Celery URLs для broker и backend
3. **.env.example**
- ✅ Redis переменные
- ✅ Комментарии для Docker
4. **app/__main__.py**
- ✅ Новый файл для запуска как модуля (`python -m app`)
## 🎯 Возможности
### Celery Задачи
```python
# Отправка сообщений асинхронно
send_message_task(message_id, group_id, chat_id, message_text)
# Парсинг участников группы
parse_group_members_task(group_id, chat_id, limit)
# Массовая рассылка
broadcast_message_task(message_id, group_ids)
# Очистка старых сообщений
cleanup_old_messages_task(days)
```
### Планировщик Рассылок
```
/schedule list - Показать расписания
/schedule add 1 10 "0 9 * * *" - Добавить расписание
/schedule remove <job_id> - Удалить расписание
```
### Мониторинг
- **Flower** на http://localhost:5555
- Реальное время выполнения задач
- Статус рабочих
- История выполнения
## 🚀 Быстрый Старт
### 1. Подготовка
```bash
cp .env.example .env
# Отредактировать .env
```
### 2. Запуск
```bash
# Способ 1: Через docker.sh
chmod +x docker.sh
./docker.sh up
# Способ 2: Через Makefile
make up
# Способ 3: Docker Compose напрямую
docker-compose up -d
```
### 3. Проверка
```bash
# Статус
docker-compose ps
# Логи
docker-compose logs -f
# Flower
open http://localhost:5555
```
## 📊 Архитектура
```
┌─────────────────────────────────────────┐
│ Docker Network (Bridge) │
├──────────────┬──────────────┬───────────┤
│ │ │ │
│ PostgreSQL │ Redis │ Flower │
│ :5432 │ :6379 │ :5555 │
│ │ │ │
├──────────────┴──────────────┴───────────┤
│ │
│ ┌──────────┐ ┌──────────┐ ┌───────┐ │
│ │ Bot │ │ Celery │ │ Celery│ │
│ │ (Polling)│ │ Workers │ │ Beat │ │
│ └──────────┘ └──────────┘ └───────┘ │
│ │
└─────────────────────────────────────────┘
```
## 📝 Cron Выражения
```
Формат: minute hour day month day_of_week
Примеры:
0 9 * * * - ежедневно в 9:00 UTC
0 9 * * MON - по понедельникам в 9:00 UTC
0 */6 * * * - каждые 6 часов
0 9,14,18 * * * - в 9:00, 14:00, 18:00 UTC
*/30 * * * * - каждые 30 минут
0 0 * * * - в полночь UTC ежедневно
```
## 🛠️ Основные Команды
### Управление
```bash
./docker.sh up # Запустить
./docker.sh down # Остановить
./docker.sh build # Пересобрать
./docker.sh logs [service] # Логи
./docker.sh shell [service] # Bash в контейнере
./docker.sh ps # Статус
./docker.sh restart [svc] # Перезагрузить
./docker.sh clean # Удалить контейнеры
```
### Celery
```bash
# Активные задачи
docker-compose exec bot celery -A app.celery_config inspect active
# Статистика рабочих
docker-compose exec bot celery -A app.celery_config inspect stats
# Зарегистрированные задачи
docker-compose exec bot celery -A app.celery_config inspect registered
```
### База Данных
```bash
# Backup
docker-compose exec postgres pg_dump -U autoposter autoposter_db > backup.sql
# Restore
docker-compose exec -T postgres psql -U autoposter autoposter_db < backup.sql
```
## 🔧 Конфигурация .env
```env
# Database (PostgreSQL)
DB_USER=autoposter
DB_PASSWORD=secure_password
DB_HOST=postgres
DB_PORT=5432
DB_NAME=autoposter_db
# Redis
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_DB=0
REDIS_PASSWORD=
# Telegram
TELEGRAM_BOT_TOKEN=your_token
# Telethon (опционально)
USE_TELETHON=false
TELETHON_API_ID=...
TELETHON_API_HASH=...
TELETHON_PHONE=+7...
```
## 📊 Сервисы
| Сервис | Порт | Описание |
|--------|------|---------|
| postgres | 5432 | PostgreSQL БД |
| redis | 6379 | Redis cache & broker |
| bot | 8000 | Главный Telegram бот |
| celery_worker_send | - | Worker для отправки |
| celery_worker_parse | - | Worker для парсинга |
| celery_worker_maintenance | - | Worker для обслуживания |
| celery_beat | - | Планировщик задач |
| flower | 5555 | Веб-интерфейс мониторинга |
## 🎓 Примеры
### Отправить сообщение в группу асинхронно
```python
from app.celery_tasks import send_message_task
task = send_message_task.delay(
message_id=1,
group_id=10,
chat_id="-1001234567890",
message_text="Hello!"
)
# Получить результат (опционально)
# result = task.get(timeout=30)
```
### Расписать рассылку
```python
from app.scheduler import schedule_broadcast
job_id = await schedule_broadcast(
message_id=1,
group_ids=[10, 20, 30],
cron_expr='0 9 * * *' # Ежедневно в 9:00 UTC
)
```
### Отменить расписание
```python
from app.scheduler import cancel_broadcast
await cancel_broadcast(job_id)
```
## 🚨 Важные Замечания
### Безопасность
⚠️ **Никогда** не коммитьте .env с реальными данными!
```bash
# Добавить в .gitignore
echo ".env" >> .gitignore
echo "*.env" >> .gitignore
```
### Production
1. Используйте external volumes для БД
2. Настройте reverse proxy (Nginx)
3. Используйте SSL/TLS
4. Масштабируйте workers при необходимости
5. Мониторьте через Flower
## 📚 Документация
- [Полное руководство Docker & Celery](docs/DOCKER_CELERY.md)
- [Telethon справочник](docs/TELETHON.md)
- [Быстрый старт](DOCKER_QUICKSTART.md)
## 🔗 Полезные Ссылки
- [Docker Docs](https://docs.docker.com/)
- [Celery Docs](https://docs.celeryproject.io/)
- [APScheduler Docs](https://apscheduler.readthedocs.io/)
- [Flower Docs](https://flower.readthedocs.io/)
## ✅ Что Дальше?
1. ✅ Запустить docker-compose
2. ✅ Проверить Flower на :5555
3. ✅ Создать сообщение через /start
4. ✅ Расписать рассылку через /schedule
5. ✅ Мониторить в реальном времени
---
**Готово к использованию!** 🎉

176
docs/DOCKER_QUICKSTART.md Normal file
View File

@@ -0,0 +1,176 @@
# Docker & Celery Setup - Быстрый Старт
## 🚀 Начало Работы
### Шаг 1: Подготовка
```bash
# Клонировать репозиторий
git clone <your-repo-url>
cd TG_autoposter
# Скопировать конфигурацию
cp .env.example .env
# Отредактировать .env с реальными значениями
nano .env
```
### Шаг 2: Запуск
Используйте Makefile:
```bash
make up
```
Или Docker Compose напрямую:
```bash
docker-compose up -d
```
### Шаг 3: Проверка
```bash
# Статус контейнеров
make ps
# или
docker-compose ps
# Показать логи
make logs
# или
docker-compose logs -f
```
## 📊 Мониторинг
### Flower (Веб-интерфейс Celery)
Откройте в браузере: **http://localhost:5555**
Показывает:
- 🔴 Активные задачи
- ⏰ Запланированные задачи
- 🖥️ Статус рабочих
- 📈 Статистику
```bash
make flower
```
## 🔧 Основные Команды
### Docker
```bash
make up # Запустить
make down # Остановить
make build # Пересобрать образы
make restart # Перезагрузить
make clean # Удалить контейнеры
make ps # Статус
make logs # Логи
make shell # Подключиться к боту
```
### База Данных
```bash
make db-init # Инициализировать БД
make db-backup # Создать backup
make db-restore # Восстановить из backup
```
### Celery
```bash
make status # Статус Celery
docker-compose exec bot celery -A app.celery_config inspect active
```
## 📝 Примеры Использования
### Отправить сообщение в несколько групп
```bash
# Через веб-интерфейс бота:
/send <message_id> <group_id>
```
### Расписать рассылку
```bash
# Через команду /schedule в боте:
/schedule add 1 10 "0 9 * * *"
# Отправит сообщение 1 в группу 10 ежедневно в 9:00 UTC
```
### Проверить статус задач
Перейти на **http://localhost:5555** и смотреть в реальном времени.
## 🗂️ Структура Сервисов
```
┌─ postgres:5432 БД
├─ redis:6379 Cache & Message Broker
├─ bot:8000 Telegram Bot
├─ celery_worker_* Рабочие для задач
├─ celery_beat Планировщик
└─ flower:5555 Веб-интерфейс мониторинга
```
## 🐛 Устранение Проблем
### Бот не отвечает
```bash
make logs-bot
make restart
```
### Celery не выполняет задачи
```bash
make status
make logs-celery
```
### PostgreSQL проблемы
```bash
docker-compose exec postgres psql -U autoposter -d autoposter_db
```
### Redis не отвечает
```bash
docker-compose exec redis redis-cli ping
```
## 📚 Полная Документация
Смотрите [DOCKER_CELERY.md](docs/DOCKER_CELERY.md) для подробного руководства.
## 🔗 Важные Ссылки
- Flower: http://localhost:5555
- PostgreSQL: localhost:5432
- Redis: localhost:6379
- Bot API: http://localhost:8000
## 💾 Резервные Копии
```bash
# Backup
make db-backup
# Restore
make db-restore
```
## 🛑 Остановка
```bash
make down
```
---
**Нужна помощь?** Смотрите документацию в `/docs/DOCKER_CELERY.md`

313
docs/DOCS_MAP.md Normal file
View File

@@ -0,0 +1,313 @@
# 📚 Карта документации TG Autoposter
## Быстрая навигация
### 🏃 Срочно нужно начать?
1. [QUICKSTART.md](QUICKSTART.md) - За 5 минут до первого запуска
2. `/start` в Telegram после запуска бота
### 📖 Хочу понять как работает?
1. [PROJECT_SUMMARY.md](PROJECT_SUMMARY.md) - Резюме проекта
2. [README.md](README.md) - Полное описание
3. [ARCHITECTURE.md](ARCHITECTURE.md) - Архитектура
### 💻 Я разработчик, хочу расширять
1. [API.md](API.md) - Документация API
2. [ARCHITECTURE.md](ARCHITECTURE.md) - Архитектура
3. Исходный код в `app/`
### 🚀 Нужно развернуть на production
1. [DEPLOYMENT.md](DEPLOYMENT.md) - Полное руководство
2. [CHECKLIST.md](CHECKLIST.md) - Контрольный список
### 🔍 Возникла проблема?
1. [README.md](README.md) - Раздел "Решение проблем"
2. [USAGE_GUIDE.md](USAGE_GUIDE.md) - Сценарии и решения
3. Проверьте `logs/bot_*.log`
---
## 📋 Полный список документов
### Для конечных пользователей
#### 1. **QUICKSTART.md** ⭐ Начните отсюда
- 📍 Где: [QUICKSTART.md](QUICKSTART.md)
- ⏱️ Время: 5-10 минут
- <20><> Содержит:
- Установка в 5 шагов
- Ваш первый бот в Telegram
- Практические примеры
- Горячие клавиши
- Решение проблем
#### 2. **USAGE_GUIDE.md** 📖 Как использовать
- 📍 Где: [USAGE_GUIDE.md](USAGE_GUIDE.md)
- ⏱️ Время: 15-20 минут
- 📝 Содержит:
- 5 реальных сценариев
- Работа с slow mode
- Форматирование сообщений
- Управление через CLI
- Лучшие практики
- Аварийные процедуры
#### 3. **README.md** 📚 Полная документация
- 📍 Где: [README.md](README.md)
- ⏱️ Время: 30-40 минут
- 📝 Содержит:
- Полное описание
- Установка и конфигурация
- Структура проекта
- Модель БД
- Использование
- Интеграция
- Безопасность
### Для разработчиков
#### 4. **API.md** 🔌 API Документация
- 📍 Где: [API.md](API.md)
- ⏱️ Время: 20-30 минут
- 📝 Содержит:
- Документация репозиториев
- Примеры кода
- Модели данных
- Обработчики
- Утилиты
- Логирование
- Обработка ошибок
- Type hints
#### 5. **ARCHITECTURE.md** 🏗️ Архитектура
- 📍 Где: [ARCHITECTURE.md](ARCHITECTURE.md)
- ⏱️ Время: 20-30 минут
- 📝 Содержит:
- Общая структура
- Слои приложения
- Модели данных
- Поток данных
- Асинхронность
- Обработка ошибок
- Состояния ConversationHandler
- Взаимодействие компонентов
### Для DevOps/SysAdmin
#### 6. **DEPLOYMENT.md** 🚀 Развертывание
- 📍 Где: [DEPLOYMENT.md](DEPLOYMENT.md)
- ⏱️ Время: 30-40 минут
- 📝 Содержит:
- Локальное развертывание
- Production на Linux
- Docker и docker-compose
- Systemd сервис
- Логирование
- Мониторинг
- Бэкапы
- Обновления
- Масштабирование
### Для менеджеров/планировщиков
#### 7. **CHECKLIST.md** ✅ Статус разработки
- <20><> Где: [CHECKLIST.md](CHECKLIST.md)
- ⏱️ Время: 10-15 минут
- 📝 Содержит:
- Статус каждой функции
- Структура проекта
- Что готово
- Что может быть улучшено
- Статистика кода
- Финальная оценка
#### 8. **PROJECT_SUMMARY.md** 📋 Резюме
- 📍 Где: [PROJECT_SUMMARY.md](PROJECT_SUMMARY.md)
- ⏱️ Время: 10 минут
- 📝 Содержит:
- Описание проекта
- Что создано
- Статистика
- Архитектура
- Требования
- Финальный статус
---
## <20><> Как выбрать документ?
### Я хочу...
#### ...быстро запустить бота
→ [QUICKSTART.md](QUICKSTART.md)
#### ...использовать бота в своих целях
→ [README.md](README.md) + [USAGE_GUIDE.md](USAGE_GUIDE.md)
#### ...добавить новую функцию
→ [API.md](API.md) + [ARCHITECTURE.md](ARCHITECTURE.md) + исходный код
#### ...развернуть на production сервер
→ [DEPLOYMENT.md](DEPLOYMENT.md)
#### ...понять что было создано
→ [PROJECT_SUMMARY.md](PROJECT_SUMMARY.md) + [CHECKLIST.md](CHECKLIST.md)
#### ...решить проблему
→ [USAGE_GUIDE.md](USAGE_GUIDE.md) раздел "Устранение проблем"
#### ...улучшить производительность
→ [ARCHITECTURE.md](ARCHITECTURE.md) + [DEPLOYMENT.md](DEPLOYMENT.md)
---
## 📊 Структура проекта
```
TG_autoposter/
├── 📄 Документация
│ ├── README.md ← Начните с этого
│ ├── QUICKSTART.md ← Быстрый старт
│ ├── USAGE_GUIDE.md ← Как использовать
│ ├── API.md ← Для разработчиков
│ ├── ARCHITECTURE.md ← Архитектура
│ ├── DEPLOYMENT.md ← Развертывание
│ ├── CHECKLIST.md ← Статус
│ ├── PROJECT_SUMMARY.md ← Резюме
│ └── DOCS_MAP.md ← Вы здесь
│
├── 🐍 Python код
│ ├── main.py ← Запуск бота
│ ├── cli.py ← CLI инструменты
│ ├── examples.py ← Примеры
│ ├── migrate_db.py ← Управление БД
│ └── app/
│ ├── __init__.py ← Главная функция
│ ├── config.py ← Конфигурация
│ ├── models/ ← Модели БД
│ ├── database/ ← Работа с БД
│ ├── handlers/ ← Обработчики
│ └── utils/ ← Утилиты
│
├── ⚙️ Конфигурация
│ ├── requirements.txt ← Зависимости
│ ├── .env.example ← Пример .env
│ └── .gitignore ← Git исключения
```
---
## 🗂️ Файловая структура документов
| Файл | Размер | Целевая аудитория | Сложность |
|------|--------|-------------------|-----------|
| QUICKSTART.md | ~300 строк | Все | Легко |
| README.md | ~600 строк | Все | Средне |
| USAGE_GUIDE.md | ~400 строк | Пользователи | Легко |
| API.md | ~400 строк | Разработчики | Сложно |
| ARCHITECTURE.md | ~500 строк | Архитекторы | Сложно |
| DEPLOYMENT.md | ~400 строк | DevOps | Сложно |
| CHECKLIST.md | ~300 строк | Менеджеры | Легко |
| PROJECT_SUMMARY.md | ~300 строк | Все | Легко |
| **ВСЕГО** | ~3000 строк | - | - |
---
## 🎓 Рекомендуемый порядок чтения
### Новичок, первый запуск
1. QUICKSTART.md (5 мин)
2. Запустить бота
3. USAGE_GUIDE.md (10 мин)
4. Использовать в боте
### Пользователь, хочу больше
1. README.md (30 мин)
2. USAGE_GUIDE.md (15 мин)
3. Экспериментировать
### Разработчик, хочу расширять
1. PROJECT_SUMMARY.md (10 мин)
2. ARCHITECTURE.md (20 мин)
3. API.md (30 мин)
4. Исходный код в `app/`
5. Модифицировать код
### DevOps, Production deploy
1. DEPLOYMENT.md (40 мин)
2. Следовать инструкциям
3. CHECKLIST.md (10 мин)
4. Проверить все пункты
---
## 🔍 Быстрый поиск
### Вопрос: Как установить бота?
→ [QUICKSTART.md](QUICKSTART.md) раздел "Установка"
### Вопрос: Как создать сообщение?
→ [USAGE_GUIDE.md](USAGE_GUIDE.md) раздел "Использование"
### Вопрос: Как работает slow mode?
→ [API.md](API.md) раздел "Проверка slow mode"
### Вопрос: Как добавить новую функцию?
→ [ARCHITECTURE.md](ARCHITECTURE.md) раздел "Взаимодействие компонентов"
### Вопрос: Как развернуть на production?
→ [DEPLOYMENT.md](DEPLOYMENT.md) раздел "Production deployment"
### Вопрос: Что не работает?
→ [USAGE_GUIDE.md](USAGE_GUIDE.md) раздел "Устранение проблем"
### Вопрос: Статус разработки?
→ [CHECKLIST.md](CHECKLIST.md)
---
## 📱 Версии документов
Все документы актуальны на:
- **Дата**: 18 декабря 2025
- **Версия**: 1.0.0
- **Python**: 3.10+
- **python-telegram-bot**: 21.3
Если что-то не совпадает, проверьте версии в `requirements.txt`
---
## 💡 Полезные советы
### 📌 Сохраните закладку
Добавьте [QUICKSTART.md](QUICKSTART.md) в закладки для быстрого доступа
### 📌 Читайте последовательно
Начните с QUICKSTART → README → выбранная специальная документация
### 📌 Используйте Ctrl+F
Нужно найти конкретное слово? Используйте поиск в документе
### 📌 Проверьте примеры
В [API.md](API.md) и [USAGE_GUIDE.md](USAGE_GUIDE.md) есть копипастовые примеры
### 📌 Смотрите исходный код
Если что-то непонятно, посмотрите в папку `app/`
---
## 🤝 Обратная связь
Если в документации что-то не ясно:
1. Проверьте другие документы
2. Посмотрите примеры в исходном коде
3. Запустите `python examples.py`
4. Создайте Issue в репо (если есть)
---
**Удачного использования!** 🚀
Дата: 18 декабря 2025
Версия: 1.0.0

536
docs/PRODUCTION_DEPLOYMENT.md Normal file
View File

@@ -0,0 +1,536 @@
# Production Deployment Guide
## Pre-Deployment Checklist
- [ ] Environment variables configured in `.env`
- [ ] PostgreSQL database created and migrated
- [ ] Redis running and accessible
- [ ] Telegram credentials verified
- [ ] SSL certificates prepared (if needed)
- [ ] Log rotation configured
- [ ] Monitoring and alerts set up
- [ ] Backups configured
- [ ] Health checks tested
## Deployment Methods
### 1. Docker Compose on VPS
#### 1.1 Prepare Server
```bash
# Update system
sudo apt update && sudo apt upgrade -y
# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
# Install Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
# Create non-root user for Docker
sudo usermod -aG docker $USER
newgrp docker
```
#### 1.2 Deploy Application
```bash
# Clone repository
mkdir -p /home/bot
cd /home/bot
git clone https://github.com/yourusername/TG_autoposter.git
cd TG_autoposter
# Create environment file
nano .env
# Fill in production values
# Start services
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d
# Verify services
docker-compose ps
```
#### 1.3 Database Migrations
```bash
# Run migrations
docker-compose exec bot alembic upgrade head
# Verify
docker-compose exec bot alembic current
```
#### 1.4 Monitoring
```bash
# View logs
docker-compose logs -f
# Monitor specific service
docker-compose logs -f bot
docker-compose logs -f celery_worker_send
# Check health
docker-compose ps
```
### 2. Kubernetes Deployment
#### 2.1 Create Kubernetes Manifests
```bash
# Create namespace
kubectl create namespace telegram-bot
kubectl config set-context --current --namespace=telegram-bot
# Create ConfigMap for environment variables
kubectl create configmap bot-config --from-env-file=.env.prod
# Create Secrets for sensitive data
kubectl create secret generic bot-secrets \
--from-literal=telegram-bot-token=$TELEGRAM_BOT_TOKEN \
--from-literal=db-password=$DB_PASSWORD \
--from-literal=redis-password=$REDIS_PASSWORD
```
#### 2.2 Deploy Services
See `k8s/` directory for manifests:
- `postgres-deployment.yaml`
- `redis-deployment.yaml`
- `bot-deployment.yaml`
- `celery-worker-deployment.yaml`
- `celery-beat-deployment.yaml`
- `flower-deployment.yaml`
```bash
# Apply manifests
kubectl apply -f k8s/
# Monitor deployment
kubectl get pods
kubectl logs -f deployment/bot
```
### 3. Using Systemd Service
#### 3.1 Create Service File
```bash
sudo tee /etc/systemd/system/tg-autoposter.service > /dev/null <<EOF
[Unit]
Description=TG Autoposter Bot
After=network.target docker.service
Requires=docker.service
[Service]
Type=simple
User=bot
WorkingDirectory=/home/bot/TG_autoposter
ExecStart=/usr/local/bin/docker-compose up
ExecStop=/usr/local/bin/docker-compose down
Restart=always
RestartSec=10
[Install]
WantedBy=multi-user.target
EOF
```
#### 3.2 Enable Service
```bash
sudo systemctl daemon-reload
sudo systemctl enable tg-autoposter
sudo systemctl start tg-autoposter
# Check status
sudo systemctl status tg-autoposter
# View logs
sudo journalctl -u tg-autoposter -f
```
## Configuration for Production
### 1. Environment Variables
Create `.env` with production values:
```env
# Core
TELEGRAM_BOT_TOKEN=your_production_token
TELEGRAM_API_ID=your_api_id
TELEGRAM_API_HASH=your_api_hash
ADMIN_ID=your_admin_id
# Database (use managed service like RDS, CloudSQL)
DB_HOST=db.example.com
DB_PORT=5432
DB_USER=bot_user
DB_PASSWORD=secure_password_here
DB_NAME=tg_autoposter_prod
DB_SSL_MODE=require
# Redis (use managed service like ElastiCache, Redis Cloud)
REDIS_HOST=redis.example.com
REDIS_PORT=6379
REDIS_DB=0
REDIS_PASSWORD=secure_redis_password
# Logging
LOG_LEVEL=INFO
LOG_FILE=/var/log/tg-autoposter/bot.log
# Security
SECRET_KEY=your_secret_key_here
DEBUG=False
ALLOWED_HOSTS=yourdomain.com,www.yourdomain.com
```
### 2. Database Configuration
```yaml
# docker-compose.prod.yml
services:
postgres:
image: postgres:15-alpine
environment:
POSTGRES_PASSWORD: ${DB_PASSWORD}
POSTGRES_DB: ${DB_NAME}
volumes:
- postgres_data:/var/lib/postgresql/data
ports:
- "5432:5432"
healthcheck:
test: ["CMD-SHELL", "pg_isready -U ${DB_USER}"]
interval: 10s
timeout: 5s
retries: 5
```
### 3. Redis Configuration
```yaml
# docker-compose.prod.yml
services:
redis:
image: redis:7-alpine
command: redis-server --requirepass ${REDIS_PASSWORD}
volumes:
- redis_data:/data
ports:
- "6379:6379"
healthcheck:
test: ["CMD", "redis-cli", "--raw", "incr", "ping"]
interval: 10s
timeout: 5s
retries: 5
```
## Scaling Considerations
### 1. Horizontal Scaling
```yaml
# docker-compose.prod.yml - Multiple workers
services:
celery_worker_send_1:
# ... worker configuration
celery_worker_send_2:
# ... worker configuration
celery_worker_send_3:
# ... worker configuration
# Use load balancer or Docker Swarm for orchestration
```
### 2. Performance Tuning
```python
# app/settings.py
CELERY_WORKER_PREFETCH_MULTIPLIER = 1
CELERY_WORKER_MAX_TASKS_PER_CHILD = 1000
CELERY_TASK_TIME_LIMIT = 30 * 60 # 30 minutes
CELERY_TASK_SOFT_TIME_LIMIT = 25 * 60 # 25 minutes
# Database connection pooling
DB_POOL_SIZE = 20
DB_MAX_OVERFLOW = 0
DB_POOL_TIMEOUT = 30
DB_POOL_RECYCLE = 3600
```
### 3. Caching Strategy
```python
# Use Redis for caching
CACHE_TTL = 300 # 5 minutes
BROADCAST_CACHE_TTL = 3600 # 1 hour
MEMBERS_CACHE_TTL = 1800 # 30 minutes
```
## Monitoring & Logging
### 1. Logging Setup
```bash
# Create log directory
sudo mkdir -p /var/log/tg-autoposter
sudo chown bot:bot /var/log/tg-autoposter
# Configure log rotation
sudo tee /etc/logrotate.d/tg-autoposter > /dev/null <<EOF
/var/log/tg-autoposter/*.log {
daily
rotate 14
compress
delaycompress
notifempty
create 0640 bot bot
sharedscripts
postrotate
systemctl reload tg-autoposter > /dev/null 2>&1 || true
endscript
}
EOF
```
### 2. Prometheus Metrics
```python
# app/metrics.py
from prometheus_client import Counter, Histogram, Gauge
message_sent = Counter('messages_sent_total', 'Total messages sent')
message_failed = Counter('messages_failed_total', 'Total failed messages')
send_duration = Histogram('message_send_duration_seconds', 'Message send duration')
queue_size = Gauge('celery_queue_size', 'Celery queue size')
```
### 3. Monitoring with ELK Stack
```yaml
# docker-compose.prod.yml
services:
elasticsearch:
image: docker.elastic.co/elasticsearch/elasticsearch:8.0.0
kibana:
image: docker.elastic.co/kibana/kibana:8.0.0
ports:
- "5601:5601"
logstash:
image: docker.elastic.co/logstash/logstash:8.0.0
volumes:
- ./logstash.conf:/usr/share/logstash/pipeline/logstash.conf
```
## Backup & Recovery
### 1. Database Backup
```bash
#!/bin/bash
# backup-db.sh
BACKUP_DIR="/backups/postgres"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
BACKUP_FILE="$BACKUP_DIR/tg_autoposter_$TIMESTAMP.sql"
mkdir -p $BACKUP_DIR
# Backup
docker-compose exec -T postgres pg_dump -U $DB_USER $DB_NAME > $BACKUP_FILE
# Compress
gzip $BACKUP_FILE
# Remove old backups (keep 7 days)
find $BACKUP_DIR -name "*.sql.gz" -mtime +7 -delete
echo "Backup completed: $BACKUP_FILE.gz"
```
### 2. Redis Snapshot
```bash
#!/bin/bash
# backup-redis.sh
BACKUP_DIR="/backups/redis"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
mkdir -p $BACKUP_DIR
# Create snapshot
docker-compose exec -T redis redis-cli BGSAVE
# Copy snapshot
docker-compose exec -T redis cp /data/dump.rdb /data/dump_$TIMESTAMP.rdb
echo "Redis backup completed"
```
### 3. Restore Database
```bash
# Drop and recreate database
docker-compose exec -T postgres dropdb -U $DB_USER $DB_NAME
docker-compose exec -T postgres createdb -U $DB_USER $DB_NAME
# Restore from backup
gunzip < /backups/postgres/tg_autoposter_*.sql.gz | \
docker-compose exec -T postgres psql -U $DB_USER $DB_NAME
```
## Security Best Practices
### 1. Environment Hardening
```bash
# Restrict file permissions
chmod 600 .env
chmod 700 /var/log/tg-autoposter
chmod 700 /backups
# Set ownership
sudo chown bot:bot /home/bot/TG_autoposter -R
```
### 2. Network Security
```yaml
# docker-compose.prod.yml
services:
bot:
networks:
- backend
expose:
- 8000
postgres:
networks:
- backend
expose:
- 5432
networks:
backend:
driver: bridge
driver_opts:
com.docker.network.bridge.name: br_backend
```
### 3. SSL/TLS
```bash
# Generate SSL certificate
certbot certonly --standalone -d yourdomain.com
# Configure in docker-compose.prod.yml
services:
nginx:
image: nginx:latest
volumes:
- /etc/letsencrypt:/etc/letsencrypt
- ./nginx.conf:/etc/nginx/nginx.conf
ports:
- "443:443"
```
## Troubleshooting Production Issues
### Issue: Memory Leaks
```bash
# Monitor memory usage
docker stats
# Restart worker
docker-compose restart celery_worker_send
# Check logs for errors
docker-compose logs celery_worker_send | grep -i error
```
### Issue: Database Connection Timeouts
```bash
# Increase pool size in settings
DB_POOL_SIZE = 30
# Check database status
docker-compose exec postgres psql -U bot -d tg_autoposter -c "SELECT datname, pid FROM pg_stat_activity;"
# Restart database
docker-compose restart postgres
```
### Issue: High CPU Usage
```bash
# Identify problematic tasks
docker-compose exec flower curl -s http://localhost:5555/api/stats | python -m json.tool
# Reduce worker concurrency
CELERY_WORKER_CONCURRENCY = 2
```
## CI/CD Integration
### GitHub Actions Example
```yaml
# .github/workflows/deploy.yml
name: Deploy to Production
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Deploy to VPS
uses: appleboy/ssh-action@master
with:
host: ${{ secrets.VPS_HOST }}
username: ${{ secrets.VPS_USER }}
key: ${{ secrets.VPS_SSH_KEY }}
script: |
cd /home/bot/TG_autoposter
git pull origin main
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d
docker-compose exec bot alembic upgrade head
```
## Support and Monitoring Links
- **Flower Dashboard**: http://yourserver.com:5555
- **PostgreSQL Monitoring**: pgAdmin (if enabled)
- **Application Logs**: `/var/log/tg-autoposter/`
- **Health Check Endpoint**: `/health` (if implemented)
## Maintenance Schedule
- **Daily**: Check logs for errors
- **Weekly**: Review resource usage
- **Monthly**: Security updates, dependency updates
- **Quarterly**: Performance analysis, capacity planning
## Contact & Support
For issues or questions:
1. Check logs and error messages
2. Review GitHub issues
3. Contact team lead
4. Escalate to DevOps team if needed

318
docs/PROJECT_SUMMARY.md Normal file
View File

@@ -0,0 +1,318 @@
<!--
Резюме проекта TG Autoposter
Этот файл содержит полное описание всего, что было создано
-->
# 📋 Резюме проекта TG Autoposter
**Дата**: 18 декабря 2025
**Статус**: ✅ Готово к использованию
## 🎯 Описание
TG Autoposter - это асинхронный Telegram бот на Python, который позволяет:
- 📨 Управлять сообщениями для рассылки
- 👥 Автоматически обнаруживать и управлять группами
- 🚀 Отправлять сообщения в несколько групп одновременно
- ⏱️ Учитывать slow mode (ограничение скорости отправки в группе)
- 🎛️ Управление через инлайн кнопки Telegram
## 📦 Что создано
### Основной код (Python)
#### Модели (app/models/)
- ✅ **Group** - модель группы Telegram
- ✅ **Message** - модель сообщения для рассылки
- ✅ **MessageGroup** - связь много-ко-многим между сообщениями и группами
- ✅ **Base** - базовая класс для всех моделей
**Особенности**: Полная типизация, timestamps, статусы отправки
#### База данных (app/database/)
- ✅ **__init__.py** - инициализация SQLAlchemy, engine, async sessionmaker
- ✅ **repository.py** - 3 репозитория для работы с данными:
- GroupRepository
- MessageRepository
- MessageGroupRepository
**Особенности**: Асинхронная работа, поддержка SQLite и PostgreSQL
#### Обработчики (app/handlers/)
- ✅ **commands.py** - обработчики команд (/start, /help)
- ✅ **callbacks.py** - обработчики callback_query (инлайн кнопок)
- ✅ **message_manager.py** - логика создания сообщений (ConversationHandler)
- ✅ **sender.py** - отправка сообщений с учетом slow mode
- ✅ **group_manager.py** - автоматическое обнаружение групп
**Особенности**: Обработка ошибок, асинхронность, progress tracking
#### Утилиты (app/utils/)
- ✅ **__init__.py** - функции проверки slow mode
- ✅ **keyboards.py** - все инлайн клавиатуры и кнопки
**Особенности**: Готовые компоненты для UI
#### Конфигурация (app/)
- ✅ **__init__.py** - главная функция main(), запуск бота
- ✅ **config.py** - настройка логирования с ротацией
### CLI инструменты
- ✅ **cli.py** - CLI для управления ботом и БД из терминала
- Команды для сообщений (create, list, delete)
- Команды для групп (list)
- Команды для БД (init, reset, run)
### Утилиты и примеры
- ✅ **main.py** - точка входа для запуска бота
- ✅ **migrate_db.py** - интерактивное управление БД
- ✅ **examples.py** - практические примеры использования
### Документация
#### Пользовательская документация
- ✅ **README.md** (500+ строк)
- Полное описание функциональности
- Установка и настройка
- Структура проекта
- Примеры использования
- Решение проблем
- ✅ **QUICKSTART.md** (200+ строк)
- За 5 минут до первого запуска
- Практические примеры
- Шпаргалка команд
- ✅ **USAGE_GUIDE.md** (300+ строк)
- Подробные сценарии использования
- Примеры реальных ситуаций
- Устранение проблем
- Лучшие практики
#### Техническая документация
- ✅ **API.md** (400+ строк)
- Документация репозиториев
- Примеры использования
- Описание моделей
- Type hints
- ✅ **ARCHITECTURE.md** (500+ строк)
- Архитектура приложения
- Слои приложения
- Поток данных
- Асинхронность
- Безопасность
- Диаграммы
- ✅ **DEPLOYMENT.md** (400+ строк)
- Локальное развертывание
- Production развертывание на Linux
- Docker и docker-compose
- Мониторинг и бэкапы
- Масштабирование
- ✅ **CHECKLIST.md** (200+ строк)
- Полный чек-лист разработки
- Статус каждого компонента
- Что может быть улучшено
- Финальная оценка
### Конфигурационные файлы
- ✅ **requirements.txt** - все зависимости
- ✅ **.env.example** - пример переменных окружения
- ✅ **.gitignore** - правильное исключение файлов
## 📊 Статистика
### Количество кода
- **Python файлов**: 13
- **Markdown файлов**: 7
- **Всего строк кода**: ~2500+
- **Всего строк документации**: ~2000+
### Функциональность
- **Команды**: 2 (/start, /help)
- **Обработчики**: 20+
- **Модели БД**: 3
- **Репозитории**: 3
- **Клавиатур**: 7+
## 🏗️ Архитектура
```
┌─────────────────────────────────────┐
│ Telegram Bot (main.py) │
├─────────────────────────────────────┤
│ Handlers Layer (обработчики) │
├─────────────────────────────────────┤
│ Repository Layer (работа с данными) │
├─────────────────────────────────────┤
│ ORM Layer (SQLAlchemy) │
├─────────────────────────────────────┤
│ Database Layer (SQLite/PostgreSQL) │
└─────────────────────────────────────┘
```
## 🎯 Реализованные требования
### От пользователя
- [x] Бот сидит в группах и рассылает сообщения
- [x] Хранение сообщений и групп в БД
- [x] Связи для отправки сообщений в группы
- [x] Несколько сообщений в одну группу
- [x] Учет slow mode при отправке
- [x] Опрос групп при добавлении бота
- [x] Управление через инлайн кнопки
### От разработчика
- [x] Асинхронный код
- [x] Типизированный код
- [x] Чистая архитектура
- [x] Легко расширяемое
- [x] Полная документация
- [x] Готово к production
- [x] Примеры использования
- [x] CLI инструменты
## 🚀 Как использовать
### Быстрый старт
```bash
1. pip install -r requirements.txt
2. cp .env.example .env
3. Добавить токен в .env
4. python main.py
```
### Основные команды
```bash
python main.py # Запустить бота
python cli.py run # Запустить через CLI
python cli.py group list # Список групп
python cli.py message list # Список сообщений
python examples.py # Примеры
```
### В Telegram
```
/start # Главное меню
/help # Справка
📨 Сообщения # Управление сообщениями
👥 Группы # Управление группами
```
## 📚 Документация
| Документ | Для кого | Что содержит |
|----------|----------|--------------|
| README.md | Всех | Полная информация о проекте |
| QUICKSTART.md | Начинающих | За 5 минут до первого запуска |
| USAGE_GUIDE.md | Пользователей | Как использовать бота |
| API.md | Разработчиков | Работа с репозиториями |
| ARCHITECTURE.md | Архитекторов | Структура приложения |
| DEPLOYMENT.md | DevOps | Развертывание на production |
| CHECKLIST.md | Менеджеров | Статус разработки |
## 🔒 Безопасность
✅ Реализовано:
- Токен в .env, не в коде
- SQL injection защита (SQLAlchemy)
- Асинхронные сессии (изоляция)
- .gitignore для конфиденциальных файлов
- Логирование без чувствительных данных
## 🔧 Технологический стек
- **Python 3.10+**
- **python-telegram-bot 21.3** - Telegram Bot API
- **SQLAlchemy 2.0.24** - ORM для БД
- **aiosqlite 3.0.0** - Асинхронная работа с SQLite
- **python-dotenv 1.0.0** - Управление переменными окружения
- **click 8.1.7** - CLI фреймворк
## 📈 Масштабируемость
Готово для:
- ✅ 10-100+ групп
- ✅ 10-100+ сообщений
- ✅ Неограниченного количества пользователей
- ✅ Production deploy
Для масштабирования нужно:
- [ ] PostgreSQL вместо SQLite
- [ ] Celery + Redis для queue
- [ ] Webhook вместо polling
- [ ] Кэширование (Redis)
## 🐛 Тестирование
Проект готов для:
- Unit тестов (каждый репозиторий)
- Integration тестов (handlers)
- E2E тестов (полный workflow)
## 🎓 Что можно улучшить
### Функциональность (будущие версии)
- [ ] Редактирование сообщений
- [ ] Отправка изображений/документов
- [ ] Планирование отправки на время
- [ ] Статистика отправок
- [ ] Ограничение доступа (allowlist)
- [ ] Админ-панель
### Архитектура
- [ ] Миграции (Alembic)
- [ ] Конфигурация через файл
- [ ] Модульная структура
- [ ] Плагины
### Production
- [ ] Docker образ
- [ ] Kubernetes манифесты
- [ ] Prometheus метрики
- [ ] Distributed tracing
## 📞 Поддержка
Если возникнут проблемы:
1. Прочитайте документацию (README, API, QUICKSTART)
2. Проверьте логи в папке `logs/`
3. Запустите примеры `python examples.py`
4. Посмотрите DEPLOYMENT.md для production проблем
## 📝 Лицензия
MIT License - свободное использование в любых целях
## ✅ Финальный статус
| Компонент | Статус | Примечание |
|-----------|--------|-----------|
| Функциональность | ✅ 100% | Все требования реализованы |
| Документация | ✅ Полная | 7 документов, 2000+ строк |
| Код | ✅ Качество | Типизация, async/await |
| Архитектура | ✅ Чистая | Слои, separation of concerns |
| Готовность | ✅ Production | Может быть развернуто сейчас |
---
## 🎉 Итоги
✅ **Создан полнофункциональный Telegram бот для рассылки сообщений**
- 13 Python файлов (~2500 строк кода)
- 7 документов (~2000 строк)
- Полная типизация и асинхронность
- Готовый к production deploy
- С примерами и CLI инструментами
**Пора начинать использовать!** 🚀
---
Создано: 18 декабря 2025
Версия: 1.0.0
Статус: Ready for Production ✅

197
docs/QUICKSTART.md Normal file
View File

@@ -0,0 +1,197 @@
# Быстрый Старт 🚀
## За 5 минут до первого запуска
### 1. Получить Bot Token
1. Откройте Telegram и найдите **@BotFather**
2. Отправьте `/newbot`
3. Скопируйте полученный токен
### 2. Клонировать репозиторий
```bash
cd ~/dev
git clone <ссылка_на_репо>
cd TG_autoposter
```
### 3. Установить зависимости
```bash
pip install -r requirements.txt
```
### 4. Настроить окружение
```bash
cp .env.example .env
```
Отредактируйте `.env`:
```env
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklmNoPqrsTuvWxyzABC
```
### 5. Запустить бота
```bash
python main.py
```
Должны увидеть:
```
INFO:app:Инициализация базы данных...
INFO:app:База данных инициализирована
INFO:app:Бот запущен
```
## Использование
### 1. Добавьте бота в группу
- Найдите вашего бота в Telegram (по username)
- Добавьте его в группу (как любого обычного участника)
- Бот автоматически обнаружит группу и сохранит информацию
### 2. В личных сообщениях с ботом
- Отправьте `/start`
- Выберите **"📨 Сообщения"** → **"➕ Новое сообщение"**
- Введите название и текст
- Выберите группы
- Нажмите **"📤 Отправить"** в списке сообщений
## Практические примеры
### Пример 1: Простая рассылка
```
1. /start
2. 📨 Сообщения
3. ➕ Новое сообщение
4. Название: "Привет"
5. Текст: "Привет всем!"
6. Выберите группы: ✅ Группа 1, ✅ Группа 2
7. ✔️ Готово
8. Список сообщений → 📤 Отправить
```
### Пример 2: Сообщение с форматированием
```
Текст:
<b>Важное объявление!</b>
Приложение будет <i>недоступно</i> <u>завтра</u> с 00:00 до 06:00.
<a href="https://status.example.com">Статус сервиса</a>
```
## Команды
### Главное меню
- `/start` - Открыть главное меню
- `/help` - Справка
### CLI (в терминале)
```bash
# Создать сообщение
python cli.py message create
# Список сообщений
python cli.py message list
# Список групп
python cli.py group list
# Инициализировать БД
python cli.py db init
# Сбросить БД (осторожно!)
python cli.py db reset
# Запустить бота
python cli.py run
```
## Что дальше?
- 📖 Прочитайте [README.md](README.md) для полной документации
- 🔌 Изучите [API.md](API.md) для разработки
- 🧪 Запустите [examples.py](examples.py) для примеров
## Решение проблем
### "Токен невалиден"
- Проверьте что скопировали правильный токен из @BotFather
- Убедитесь что он в файле `.env`
- Перезапустите бота
### "Бот не видит группы"
- Убедитесь что бот добавлен в группу
- Проверьте что у вас есть права администратора в группе
- Посмотрите консоль для логов
### "Сообщение не отправляется"
- Проверьте что бот есть в группе и может писать
- Попробуйте отправить тестовое сообщение руками
- Посмотрите логи (папка `logs/`)
### "БД ошибка"
```bash
# Сбросьте БД
python migrate_db.py
# Выберите опцию 2 (полный сброс)
```
## Структура для быстрого понимания
```
👤 Пользователь (вы в Telegram)
↓
🤖 Telegram Bot (main.py)
↓
🗄️ База данных
├── Groups (группы)
├── Messages (сообщения)
└── MessageGroups (связи)
↓
📤 Отправка в группы
├── Проверка slow mode
├── Отправка через Bot API
└── Сохранение статуса
```
## Горячие клавиши
В боте используйте эти кнопки:
- **📨 Сообщения** - Работа с сообщениями
- **👥 Группы** - Работа с группами
- **⬅️ Назад** - Вернуться назад
- **✔️ Готово** - Подтвердить выбор
## Производительность
Бот может обрабатывать:
- ✅ Неограниченное количество сообщений
- ✅ Неограниченное количество групп
- ✅ Автоматический учет slow mode
- ✅ Асинхронная отправка
## Безопасность
- 🔐 Токен в `.env` никогда не коммитится
- 🔐 БД может быть зашифрована
- 🔐 Используйте сильные пароли для PostgreSQL
## Поддержка
Если что-то не работает:
1. Прочитайте логи в папке `logs/`
2. Проверьте README.md
3. Посмотрите примеры в `examples.py`
4. Создайте Issue в репо
Удачи! 🎉

381
docs/TELETHON.md Normal file
View File

@@ -0,0 +1,381 @@
# Телетон (Telethon) - Справочник
## Обзор
**Telethon** - это Python библиотека для взаимодействия с Telegram API как обычный пользователь (клиент), а не как бот.
Это позволяет отправлять сообщения в группы, где боты не имеют прав на отправку.
## Установка и Настройка
### 1. Получение API Credentials
Перейти на https://my.telegram.org/apps и:
- Войти в свой аккаунт Telegram
- Создать приложение (или использовать существующее)
- Скопировать `API ID` и `API HASH`
### 2. Обновление .env
```env
USE_TELETHON=true
TELETHON_API_ID=123456
TELETHON_API_HASH=abcdef1234567890
TELETHON_PHONE=+79991234567
```
### 3. Первый Запуск
При первом запуске бота Telethon создаст сессию и попросит ввести код подтверждения:
```
Telethon需要验证您的帐户...
Введите код подтверждения из Telegram: ______
```
Код придет в Telegram личные сообщения.
## Гибридный Режим
Когда `USE_TELETHON=true`, бот работает в **гибридном режиме**:
1. **Сначала** пытается отправить как бот
2. **При ошибке** (бот заблокирован) пытается отправить как Telethon клиент
3. **Автоматически** отслеживает какой способ работает и его использует
```python
# Автоматическое переключение
success, method = await hybrid_sender.send_message(
chat_id="-1001234567890",
message_text="Привет!"
)
if method == "bot":
print("Отправлено как бот ✅")
elif method == "client":
print("Отправлено как Telethon клиент ✅")
```
## Основной API
### Инициализация
```python
from app.handlers.telethon_client import telethon_manager
# Инициализировать
await telethon_manager.initialize()
# Проверить подключение
if telethon_manager.is_connected():
print("Telethon подключен")
# Завершить
await telethon_manager.shutdown()
```
### Отправка Сообщений
```python
# Простая отправка
message_id = await telethon_manager.send_message(
chat_id=-1001234567890,
text="Привет мир!",
parse_mode="html",
disable_web_page_preview=True
)
if message_id:
print(f"Сообщение отправлено: {message_id}")
```
### Получение Информации о Группе
```python
# Получить информацию
info = await telethon_manager.get_chat_info(chat_id)
if info:
print(f"Название: {info['title']}")
print(f"Описание: {info['description']}")
print(f"Участников: {info['members_count']}")
```
### Получение Участников
```python
# Получить список участников
members = await telethon_manager.get_chat_members(
chat_id=-1001234567890,
limit=100
)
for member in members:
print(f"{member['first_name']} (@{member['username']})")
```
### Поиск Сообщений
```python
# Найти сообщения
messages = await telethon_manager.search_messages(
chat_id=-1001234567890,
query="python",
limit=50
)
for msg in messages:
print(f"[{msg['date']}] {msg['text']}")
```
### Редактирование и Удаление
```python
# Отредактировать
msg_id = await telethon_manager.edit_message(
chat_id=-1001234567890,
message_id=123,
text="Новый текст"
)
# Удалить
success = await telethon_manager.delete_message(
chat_id=-1001234567890,
message_id=123
)
```
## Массовая Отправка
```python
from app.handlers.hybrid_sender import HybridMessageSender
sender = HybridMessageSender(bot, db_session)
# Отправить с retry логикой
success, method = await sender.send_message_with_retry(
chat_id="-1001234567890",
message_text="Важное сообщение",
max_retries=3
)
# Массовая отправка
results = await sender.bulk_send(
chat_ids=chat_ids,
message_text="Привет всем!",
use_slow_mode=True
)
print(f"Успешно: {results['success']}")
print(f"Через бот: {results['via_bot']}")
print(f"Через клиент: {results['via_client']}")
```
## Парсинг Групп
```python
from app.handlers.group_parser import GroupParser
parser = GroupParser(db_session)
# Парсить группу по ключевым словам
result = await parser.parse_group_by_keywords(
keywords=["Python", "Django"],
chat_id=-1001234567890
)
if result['matched']:
print(f"✅ Группа соответствует! Найдено: {result['keywords_found']}")
# Загрузить участников
members_result = await parser.parse_group_members(
chat_id=-1001234567890,
member_repo=member_repo,
limit=1000
)
print(f"Загружено участников: {members_result['members_added']}")
```
## Обработка Ошибок
### FloodWait
Telegram ограничивает частоту операций. Telethon автоматически обрабатывает:
```python
from telethon.errors import FloodWaitError
try:
await telethon_manager.send_message(chat_id, text)
except FloodWaitError as e:
print(f"Нужно ждать {e.seconds} секунд")
# Гибридный отправитель автоматически ждет и повторяет
```
### ChatAdminRequired
Клиент не администратор в этой группе:
```python
from telethon.errors import ChatAdminRequiredError
try:
members = await telethon_manager.get_chat_members(chat_id)
except ChatAdminRequiredError:
print("Клиент не администратор")
```
### UserNotParticipant
Клиент не участник группы:
```python
from telethon.errors import UserNotParticipantError
try:
info = await telethon_manager.get_chat_info(chat_id)
except UserNotParticipantError:
print("Клиент не в этой группе")
```
## Статистика и Мониторинг
Система автоматически отслеживает:
- Какие группы работают с ботом
- Какие требуют Telethon клиента
- Сколько сообщений отправлено каждым методом
- Ошибки и ограничения
```python
stats = await stats_repo.get_statistics(group_id)
if stats:
print(f"Всего участников: {stats.total_members}")
print(f"Отправлено сообщений: {stats.messages_sent}")
print(f"Через клиент: {stats.messages_via_client}")
print(f"Может отправлять как бот: {'✅' if stats.can_send_as_bot else '❌'}")
print(f"Может отправлять как клиент: {'✅' if stats.can_send_as_client else '❌'}")
```
## Лучшие Практики
### 1. Используйте Гибридный Режим
Всегда включайте оба метода доставки:
```env
USE_TELETHON=true
USE_CLIENT_WHEN_BOT_FAILS=true
```
### 2. Минимизируйте Частоту Запросов
```python
# Плохо
for group_id in groups:
info = await telethon_manager.get_chat_info(group_id)
# Хорошо - кэшируйте информацию
info_cache = {}
for group_id in groups:
if group_id not in info_cache:
info_cache[group_id] = await telethon_manager.get_chat_info(group_id)
```
### 3. Обработайте FloodWait
```python
# Гибридный отправитель уже это делает, но вы можете добавить свою логику
success, method = await sender.send_message_with_retry(
chat_id=chat_id,
message_text=text,
max_retries=5 # Увеличить количество попыток
)
```
### 4. Логируйте Действия
```python
import logging
logger = logging.getLogger(__name__)
logger.info(f"Загружаю участников группы {chat_id}...")
members = await telethon_manager.get_chat_members(chat_id)
logger.info(f"✅ Загружено {len(members)} участников")
```
## Переменные Конфигурации
| Переменная | По умолчанию | Описание |
|---|---|---|
| `USE_TELETHON` | false | Включить Telethon |
| `TELETHON_API_ID` | - | API ID с my.telegram.org |
| `TELETHON_API_HASH` | - | API HASH с my.telegram.org |
| `TELETHON_PHONE` | - | Номер телефона с кодом (+7...) |
| `TELETHON_FLOOD_WAIT_MAX` | 60 | Макс. ждать при FloodWait (сек) |
| `MIN_SEND_INTERVAL` | 0.5 | Интервал между отправками (сек) |
## Отладка
### Проверить подключение
```python
# В Python REPL или скрипте
python -c "
import asyncio
from app.handlers.telethon_client import telethon_manager
async def test():
await telethon_manager.initialize()
if telethon_manager.is_connected():
print('✅ Telethon подключен')
else:
print('❌ Telethon не подключен')
await telethon_manager.shutdown()
asyncio.run(test())
"
```
### Логи
Logирование выполняется автоматически:
```python
import logging
logging.basicConfig(level=logging.DEBUG)
```
Смотрите `app/handlers/telethon_client.py` для деталей логирования.
## Важные Замечания
⚠️ **Безопасность Аккаунта**
- Никогда не делитесь `TELETHON_API_HASH`
- Сессия сохраняется в `app/sessions/telethon_session`
- Защитите файл сессии доступом (не добавляйте в git!)
⚠️ **Ограничения Telegram**
- Частые отправки могут привести к временной блокировке (FloodWait)
- Используйте `MIN_SEND_INTERVAL` для управления частотой
- Не превышайте лимиты Telegram API
⚠️ **Первый Запуск**
Потребуется интерактивный ввод кода подтверждения. Для production используйте:
```python
# Генерировать заранее в безопасном окружении
await telethon_manager.initialize()
```
## Полезные Ссылки
- [Telethon Документация](https://docs.telethon.dev/)
- [Telegram Bot API](https://core.telegram.org/bots/api)
- [Получить API Credentials](https://my.telegram.org/apps)
- [Типы Ошибок Telethon](https://docs.telethon.dev/en/stable/modules/errors.html)

313
docs/USAGE_GUIDE.md Normal file
View File

@@ -0,0 +1,313 @@
# Руководство по использованию TG Autoposter
## Сценарий 1: Первое использование
```
Шаг 1: Подготовка
├─ Получить токен от @BotFather
├─ Установить зависимости: pip install -r requirements.txt
├─ Создать .env файл с токеном
└─ Запустить бота: python main.py
Шаг 2: Добавить бота в группу
├─ Найти бота в Telegram (по username)
├─ Открыть группу
├─ Нажать "Добавить участника"
├─ Выбрать вашего бота
└─ Бот автоматически обнаружит группу и сохранит информацию
Шаг 3: Первое сообщение
├─ В личном чате с ботом отправить /start
├─ Нажать "📨 Сообщения"
├─ Нажать "➕ Новое сообщение"
├─ Ввести название: "Мое первое сообщение"
├─ Ввести текст: "Привет, это работает!"
├─ Выбрать группу (нажать на неё)
├─ Нажать "✔️ Готово"
└─ Нажать "📤 Отправить" для отправки
Результат: Сообщение отправлено в группу! ✅
```
## Сценарий 2: Рассылка в несколько групп
```
Шаг 1: Добавить боты в несколько групп
├─ Повторить процесс добавления для каждой группы
├─ Бот сохранит все группы в БД
└─ Вы сможете видеть все в меню "👥 Группы"
Шаг 2: Создать сообщение
├─ /start → "📨 Сообщения" → "➕ Новое сообщение"
├─ Название: "Важное объявление"
├─ Текст: "Сервис будет на обслуживании"
├─ Выбрать группы: ✅ Группа 1, ✅ Группа 2, ✅ Группа 3
├─ "✔️ Готово"
└─ Нажать "📤 Отправить"
Результат: Одно сообщение отправлено в 3 группы! ✅
```
## Сценарий 3: Сообщения с форматированием
```
Текст с HTML:
<b>Жирный текст</b>
<i>Курсив</i>
<u>Подчеркивание</u>
<code>Код</code>
<a href="https://example.com">Ссылка</a>
Результат в Telegram:
**Жирный текст**
_Курсив_
Подчеркивание
`Код`
[Ссылка](https://example.com)
```
## Сценарий 4: Работа с Slow Mode
```
Группа имеет slow mode = 5 секунд (настройка группы в Telegram)
Шаг 1: Создать 2 сообщения
├─ Сообщение 1: "Первое"
└─ Сообщение 2: "Второе"
Шаг 2: Отправить оба в одну группу
├─ Выбрать обе сообщения для одной группы
└─ Нажать "📤 Отправить"
Процесс отправки:
├─ Отправляется сообщение 1
├─ ⏳ Бот ждет 5 секунд (slow mode)
├─ Отправляется сообщение 2
├─ Готово!
└─ ✅ Успешно: 2, ❌ Ошибок: 0
Бот автоматически учитывает задержку! ✅
```
## Сценарий 5: Управление через CLI
```bash
# Создать сообщение через CLI
python cli.py message create
# → Название: "CLI сообщение"
# → Текст: "Создано через CLI"
# Список всех сообщений
python cli.py message list
# Список всех групп
python cli.py group list
# Сброс БД (осторожно!)
python cli.py db reset
# Запустить бота
python cli.py run
```
## Статус отправки
### При успешной отправке:
```
✅ Сообщение успешно отправлено
Статистика:
- ✅ Отправлено: 3
- ❌ Ошибок: 0
- Время ожидания: 10s (из-за slow mode)
```
### При ошибке:
```
⚠️ При отправке произошла ошибка
Статистика:
- ✅ Отправлено: 2
- ❌ Ошибок: 1 (бот не имеет прав на отправку)
Решение:
1. Убедитесь что бот добавлен в группу
2. Проверьте права на отправку сообщений
3. Попробуйте снова
```
## Обновление информации о группе
```
Боту нужно обновить информацию о slow mode?
Способ 1: Удалить из группы и добавить снова
├─ Удалить бота из группы
├─ Добавить бота обратно
└─ Информация обновится автоматически
Способ 2: Через CLI
├─ python cli.py db reset (осторожно!)
└─ Добавить бота в группы снова
```
## Устранение проблем
### Бот не видит группы
```
Проблема: Добавил бота в группу, но она не появляется
Решение:
1. Проверить что бот добавлен (смотреть участников группы)
2. Перезапустить бота
3. Добавить бота еще раз (удалить и добавить)
4. Проверить логи: cat logs/bot_*.log
```
### Сообщение не отправляется
```
Проблема: Нажал "Отправить", но сообщение не дошло
Решение:
1. Проверить что сообщение создано (список сообщений)
2. Проверить что группа добавлена (список групп)
3. Проверить права на отправку в группе
4. Проверить логи для деталей ошибки
Примеры ошибок:
- "Бот заблокирован в группе" → добавьте его снова
- "Нет прав на отправку" → дайте права администратора
- "Группа удалена" → удалите из БД: python cli.py group list
```
### БД ошибка
```
Проблема: "table groups not found" или подобное
Решение:
python migrate_db.py
# Выбрать опцию 1 (создать/обновить таблицы)
```
## Шпаргалка команд
### Telegram (в личных сообщениях с ботом)
- `/start` - Главное меню
- `/help` - Справка
### Меню (нажимаем кнопки)
- 📨 Сообщения → ➕ Новое → создание сообщения
- 📨 Сообщения → 📜 Список → просмотр/отправка
- 👥 Группы → 📜 Список → просмотр групп
- ⬅️ Назад → вернуться в меню
### CLI (в терминале)
```bash
# Сообщения
python cli.py message create # Создать
python cli.py message list # Список
python cli.py message delete # Удалить
# Группы
python cli.py group list # Список
# БД
python cli.py db init # Инициализировать
python cli.py db reset # Сбросить
# Запуск
python cli.py run # Запустить бота
python main.py # Или просто так
```
## Лучшие практики
### ✅ Делайте так:
1. Давайте краткие, понятные названия сообщениям
2. Пишите текст сообщения без ошибок
3. Тестируйте сначала в одной группе
4. Проверяйте логи при проблемах
5. Регулярно делайте бэкапы БД
### ❌ Не делайте так:
1. Не отправляйте спам
2. Не давайте боту токен кому-то другому
3. Не удаляйте БД файл без бэкапа
4. Не обновляйте slow mode через БД напрямую
5. Не добавляйте бота в приватные чаты (не будет работать)
## Аварийные процедуры
### Нужно обновить токен
```bash
1. Получить новый токен от @BotFather
2. Отредактировать .env
3. Перезапустить бота
4. Все работает!
```
### Нужно перенести БД на другой сервер
```bash
1. Скопировать файл autoposter.db на новый сервер
2. Скопировать остальной код
3. Запустить бота
4. Все группы и сообщения на месте!
```
### Нужно полностью сбросить и начать с нуля
```bash
1. python cli.py db reset
2. Выбрать "yes" для подтверждения
3. Все таблицы пересозданы
4. Добавить бота в группы снова
5. Создать сообщения заново
```
## Примеры реальных сценариев
### Сценарий A: Рассылка новостей
```
1. Группа 1: IT новости
2. Группа 2: Развитие
3. Группа 3: Проекты
Каждый день в 10:00 (подойти через cron):
- python send_message.py "новости_дня"
- Отправляется в 3 группы
- Каждой группе по 5 сек ожидания
- Все готово за 10 секунд
```
### Сценарий B: Критические алерты
```
1. БД падает
2. Скрипт отправляет алерт через бота
3. python cli.py message create "ALERT"
4. Выбираем группу "DevOps"
5. Отправляем немедленно
6. Алерт приходит в группу
```
### Сценарий C: Еженедельный отчет
```
1. Каждый понедельник в 09:00
2. Скрипт готовит отчет
3. Отправляет через бота в группу "Руководство"
4. Автоматическая рассылка
5. Никакого ручного вмешательства
```
## Полезные ссылки
- 🔗 [python-telegram-bot docs](https://python-telegram-bot.readthedocs.io/)
- 🔗 [Telegram Bot API](https://core.telegram.org/bots/api)
- 🔗 [SQLAlchemy docs](https://docs.sqlalchemy.org/)
- 🔗 [@BotFather](https://t.me/botfather) - создание ботов
---
Любые вопросы? Читайте документацию:
- 📖 [README.md](README.md) - полная информация
- 🔌 [API.md](API.md) - для разработчиков
- 🏗️ [ARCHITECTURE.md](ARCHITECTURE.md) - архитектура
- ⚡ [QUICKSTART.md](QUICKSTART.md) - быстрый старт