# Boty VK - Подробная документация ## Введение Данный документ содержит полное и детальное описание реализации бота для ВКонтакте. Проект разработан для автоматизации публикации новостей в группу ВКонтакте с возможностью планирования, управления черновиками и интеграции с существующей инфраструктурой. ## Возможности VK API VK API предоставляет богатый набор возможностей для работы с группами и публикациями. Основные функции, которые можно использовать: ### Публикация контента - **Публикация записей на стене группы** - возможность размещать текстовые сообщения - **Добавление изображений** - загрузка и публикация фотографий - **Добавление видео** - публикация видеозаписей - **Добавление документов** - публикация файлов - **Форматирование текста** - поддержка переносов строк и разметки - **Планирование публикаций** - возможность запланировать публикацию на будущее - **Работа с опросами** - создание голосований - **Публикация с геолокацией** - добавление местоположения к записи ### Управление группой - **Получение статистики** - доступ к аналитике группы - **Управление подписчиками** - получение списка участников - **Работа с диалогами и сообщениями** - обработка личных сообщений - **Обработка событий через callback-сервер** - получение уведомлений о событиях - **Управление правами доступа** - настройка прав администраторов ### Преимущества использования VK API - **Официальный API** - поддерживается разработчиками ВКонтакте - **Хорошая документация** - подробная документация с примерами - **Поддержка всех типов медиа** - работа с изображениями, видео, документами - **Возможность планирования** - автоматизация публикаций - **Интеграция с другими сервисами VK** - работа с Mini Apps, Market и другими сервисами - **Безопасность** - использование токенов доступа с ограниченными правами ## Технологический стек Проект реализован на Python с использованием современных библиотек и подходов: ### Основные зависимости - **Python 3.8+** - основной язык программирования - **vk_api** - официальный SDK для работы с VK API - **requests** - библиотека для выполнения HTTP-запросов - **python-dotenv** - управление конфигурационными переменными - **schedule** - планирование задач - **tqdm** - индикаторы выполнения (опционально) ### Почему Python? - **Простота и читаемость кода** - легкость поддержки и модификации - **Богатая экосистема** - множество готовых библиотек - **Кроссплатформенность** - работает на всех основных ОС - **Быстрая разработка** - быстрое прототипирование и реализация - **Поддержка асинхронности** - возможность расширения с использованием asyncio ## Структура проекта ### Общая структура ``` bot_vk/ ├── src/ # Исходный код приложения │ ├── __init__.py # Инициализация пакета │ ├── config.py # Конфигурация приложения │ ├── vk_client.py # Клиент для работы с VK API │ ├── post_manager.py # Менеджер публикаций │ └── scheduler.py # Планировщик задач ├── templates/ # Шаблоны для публикаций │ └── news_template.html # HTML-шаблон для новостей ├── media/ # Медиафайлы │ └── posts/ # Черновики публикаций ├── logs/ # Файлы логов ├── .env.example # Пример файла конфигурации ├── requirements.txt # Зависимости ├── main.py # Точка входа ├── README.md # Краткая документация └── DETAILED.md # Подробная документация ``` ### Назначение папок #### `src/` Основная директория с исходным кодом приложения. Содержит все модули и классы, реализующие функциональность бота. #### `templates/` Шаблоны для формирования контента публикаций. Позволяют стандартизировать оформление новостей и упростить их создание. #### `media/` Хранилище медиафайлов: - `posts/` - черновики публикаций в формате JSON - Другие поддиректории могут быть добавлены для изображений, видео и документов #### `logs/` Файлы логов приложения: - `vk_client.log` - логи работы с VK API - `post_manager.log` - логи менеджера публикаций - `scheduler.log` - логи планировщика - `main.log` - основной лог приложения ## Подробное описание компонентов ### `config.py` - Конфигурация приложения Модуль содержит классы для управления конфигурацией приложения: #### `VKConfig` Конфигурация для работы с VK API: - `TOKEN` - токен доступа к API группы - `GROUP_ID` - ID группы (с минусом) - `OWNER_ID` - ID владельца стены (обычно совпадает с GROUP_ID) - `API_VERSION` - версия VK API - `API_URL` - базовый URL API #### `AppConfig` Конфигурация приложения: - `DEBUG` - режим отладки - `LOG_DIR` - путь к директории логов - `MEDIA_DIR` - путь к медиафайлам - `TEMPLATES_DIR` - путь к шаблонам #### `PostConfig` Конфигурация публикаций: - `MAX_RETRIES` - максимальное количество попыток публикации - `RETRY_DELAY` - задержка между попытками - `FROM_GROUP` - публиковать от имени группы - `SIGNED` - подписывать записи - `CLOSE_COMMENTS` - закрывать комментарии - `COPY_RIGHT` - разрешать копирование #### `SchedulerConfig` Конфигурация планировщика: - `CHECK_INTERVAL` - интервал проверки расписания (в минутах) - `MAX_POSTS_PER_CHECK` - максимальное количество публикаций за одну проверку ### `vk_client.py` - Клиент VK API Основной класс для работы с VK API. Реализует все необходимые методы для взаимодействия с API. #### Основные методы ##### `_make_request(method, params)` Унифицированный метод для выполнения запросов к VK API с поддержкой: - Повторных попыток при ошибках - Обработки специфичных ошибок VK - Экспоненциальной задержки при превышении лимитов - Логирования запросов и ответов ##### `get_group_info()` Получение информации о группе: - Название - Описание - Количество участников - Ссылки - Активность ##### `get_wall_posts(count=10)` Получение записей со стены группы. Позволяет получить последние публикации для анализа или модификации. ##### `upload_photo_to_wall(photo_path)` Загрузка фотографии для публикации на стене. Реализует полный цикл: 1. Получение сервера для загрузки 2. Загрузка файла на сервер 3. Сохранение фотографии в VK ##### `publish_post(**kwargs)` Публикация записи на стене. Поддерживает все параметры метода wall.post API VK: - `message` - текст записи - `attachments` - вложения (фото, видео, документы) - `from_group` - публиковать от имени группы - `signed` - подписывать запись - `publish_date` - дата публикации (для планирования) - `lat`, `long` - географические координаты - `place_id` - ID места ##### `schedule_post(**kwargs)` Планирование публикации. Аналогичен `publish_post`, но с обязательным параметром `publish_date`. ##### `get_scheduled_posts()` Получение списка запланированных публикаций для мониторинга и управления. ##### `edit_post(post_id, **kwargs)` Редактирование существующей публикации. Позволяет обновлять текст, вложения и другие параметры. ##### `delete_post(post_id)` Удаление публикации. Используется для отмены запланированных публикаций. ##### `get_comments(post_id, count=100)` Получение комментариев к публикации для мониторинга обратной связи. ##### `add_comment(post_id, message, **kwargs)` Добавление комментария к публикации от имени группы. ##### `get_likes(post_id)` Получение списка лайков публикации для аналитики. ##### `add_like(post_id)` Добавление лайка публикации. ##### `remove_like(post_id)` Удаление лайка с публикации. ### `post_manager.py` - Менеджер публикаций Класс для управления созданием, публикацией и хранением публикаций. #### Основные методы ##### `create_post(title, content, images=None, videos=None, hashtags=None, website=None, contacts=None, **kwargs)` Создание публикации с автоматическим формированием текста: - Объединение заголовка и содержания - Добавление хэштегов - Добавление ссылки на сайт - Добавление контактной информации - Загрузка изображений и видео - Сохранение черновика ##### `publish_post(post_data)` Публикация готовой записи на стене группы с обработкой ошибок и логированием результата. ##### `publish_post_from_draft(post_id)` Публикация из сохраненного черновика. Позволяет возобновить работу с ранее подготовленной публикацией. ##### `schedule_post(title, content, publish_date, images=None, videos=None, hashtags=None, website=None, contacts=None, **kwargs)` Планирование публикации на указанную дату и время. Реализует полный цикл: 1. Создание публикации 2. Добавление даты публикации 3. Планирование через VK API 4. Сохранение информации в черновик ##### `get_scheduled_posts()` Получение списка запланированных публикаций с фильтрацией и сортировкой. ##### `cancel_scheduled_post(post_id)` Отмена запланированной публикации. Используется для корректировки расписания. ##### `update_post(post_id, title=None, content=None, images=None, videos=None, **kwargs)` Обновление существующей публикации с поддержкой изменения текста и вложений. ### `scheduler.py` - Планировщик задач Класс для автоматического выполнения задач по расписанию. #### Основные методы ##### `_setup_schedule()` Настройка расписания выполнения задач: - Проверка запланированных публикаций каждые N минут - Ежедневная очистка старых черновиков в 02:00 ##### `_check_scheduled_posts()` Основной метод проверки расписания. Выполняет: - Получение списка запланированных публикаций - Сортировку по дате - Проверку, наступило ли время публикации - Публикацию готовых записей ##### `_should_publish(post)` Проверка, нужно ли публиковать запись (наступило ли время публикации). ##### `_publish_scheduled_post(post)` Публикация запланированной записи. Реализует: - Отмену запланированной публикации - Создание немедленной публикации - Логирование результата ##### `_cleanup_old_drafts()` Очистка старых черновиков (старше 30 дней) для экономии места. ##### `start()` и `stop()` Методы для запуска и остановки планировщика в отдельном потоке. ## Работа с конфигурацией ### `.env.example` - Пример конфигурации Файл содержит все необходимые переменные окружения: ```env # Токен группы VK (обязательно) VK_TOKEN=your_vk_group_token_here # ID группы VK (с минусом) VK_GROUP_ID=-123456789 # ID владельца стены (обычно совпадает с VK_GROUP_ID) VK_OWNER_ID=-123456789 # Версия API VK VK_API_VERSION=5.131 # Режим отладки DEBUG=True # Пути LOG_DIR=logs MEDIA_DIR=media TEMPLATES_DIR=templates # Настройки публикаций POST_FROM_GROUP=1 POST_SIGNED=0 POST_CLOSE_COMMENTS=0 POST_COPY_RIGHT=0 # Настройки планировщика SCHEDULER_CHECK_INTERVAL=5 SCHEDULER_MAX_POSTS=5 ``` ### Безопасность конфигурации - Файл `.env` не должен коммититься в репозиторий - Токен должен храниться только в `.env` файле - Рекомендуется использовать отдельный токен с минимально необходимыми правами - Токен следует периодически обновлять ## Установка и настройка ### 1. Установка зависимостей ```bash # Создаем виртуальное окружение python -m venv venv # Активируем виртуальное окружение # Linux/Mac: source venv/bin/activate # Windows: venv\Scripts\activate # Устанавливаем зависимости pip install -r requirements.txt ``` ### 2. Настройка конфигурации ```bash # Копируем пример конфигурации cp .env.example .env # Редактируем .env файл notepad .env # или любой другой редактор ``` ### 3. Получение токена группы 1. Перейдите в настройки группы ВКонтакте 2. Перейдите в раздел "Работа с API" 3. Нажмите "Создать токен" 4. Выберите права доступа: - Управление группой - Доступ в сообщения 5. Скопируйте токен и вставьте в .env файл ### 4. Запуск приложения ```bash # Запуск основного скрипта python main.py ``` ## Примеры использования ### Пример 1: Простая публикация ```python from src.post_manager import PostManager # Создаем менеджер публикаций pm = PostManager() # Публикуем новость result = pm.create_post( title="Плановые отключения воды", content="Сообщаем о предстоящих плановых отключениях...", hashtags=["#водоканал", "#отключения", "#Ангарск"], website="https://vodokanal-angarsk.ru", contacts="📞 Телефон: +7 (3954) 55-12-01" ) if result['success']: publish_result = pm.publish_post(result['data']) if publish_result['success']: print(f"Публикация успешна: {publish_result['post_id']}") ``` ### Пример 2: Планирование публикации ```python from datetime import datetime, timedelta # Планируем публикацию на завтра в 10:00 publish_date = datetime.now() + timedelta(days=1) publish_date = publish_date.replace(hour=10, minute=0, second=0, microsecond=0) result = pm.schedule_post( title="Напоминание: Отключения воды", content="Напоминаем о завтрашних отключениях воды...", publish_date=publish_date, hashtags=["#водоканал", "#отключения", "#Ангарск"], website="https://vodokanal-angarsk.ru", contacts="📞 Телефон: +7 (3954) 55-12-01" ) if result['success']: print(f"Публикация запланирована на {publish_date}") ``` ### Пример 3: Работа с изображениями ```python # Публикация с изображением result = pm.create_post( title="Новость с изображением", content="Описание новости...", images=["media/news_image.jpg"], hashtags=["#водоканал", "#новости"], website="https://vodokanal-angarsk.ru" ) if result['success']: publish_result = pm.publish_post(result['data']) ``` ## Обработка ошибок ### Основные типы ошибок VK API | Код | Описание | Решение | |-----|----------|---------| | 6 | Too many requests per second | Внедрена экспоненциальная задержка | | 9 | Flood control | Остановка выполнения, анализ причин | | 14 | Captcha needed | Требуется ручное решение CAPTCHA | | 15 | Access denied | Проверка прав токена | | 100 | One of the parameters specified was missing or invalid | Проверка параметров запроса | | 113 | Invalid user id | Проверка ID пользователя/группы | ### Стратегия повторных попыток Для временных ошибок (например, превышение лимита запросов) реализована стратегия экспоненциальной задержки: - Первая попытка: 1 секунда - Вторая попытка: 2 секунды - Третья попытка: 4 секунды Это позволяет эффективно обрабатывать временные сбои без перегрузки API. ## Логирование ### Формат логов Все логи используют единый формат: ``` YYYY-MM-DD HH:MM:SS - module_name - LEVEL - message ``` ### Уровни логирования - **DEBUG** - подробная информация для отладки (включается при DEBUG=True) - **INFO** - информационные сообщения о ходе выполнения - **WARNING** - предупреждения о потенциальных проблемах - **ERROR** - ошибки, которые не привели к остановке приложения - **CRITICAL** - критические ошибки, приводящие к остановке приложения ### Структура логов Каждый модуль имеет свой файл логов: - `vk_client.log` - логи работы с API - `post_manager.log` - логи менеджера публикаций - `scheduler.log` - логи планировщика - `main.log` - основной лог приложения ## Безопасность ### Хранение токена - Токен хранится только в `.env` файле - `.env` файл добавлен в `.gitignore` - Токен не должен отображаться в логах - Рекомендуется использовать переменные окружения на сервере ### Права токена - Используйте токен с минимально необходимыми правами - Для публикации новостей достаточно прав "Управление группой" - Не используйте токен с правами администратора приложения ### Защита от DDoS - Реализована экспоненциальная задержка при ошибках - Ограничение количества запросов в секунду - Кэширование некоторых данных (например, информации о группе) ## Ограничения VK API ### Ограничения запросов - Максимум 3 запроса в секунду - Ограничение на количество публикаций в день - Ограничение на размер текста (16384 символа) - Ограничение на количество вложений (10) ### Требования к контенту - Запрещен спам и реклама - Запрещен контент, нарушающий законодательство - Требуется модерация некоторых типов контента - Запрещено массовое добавление пользователей ## Интеграция с существующей системой ### Возможные точки интеграции #### С базой данных - Использование существующей базы данных `bot_lk` для получения информации об отключениях - Автоматическая публикация уведомлений из таблицы `notifications_sent` - Синхронизация пользователей между Telegram и VK #### С текущими ботами - Использование общих шаблонов сообщений - Единая система управления уведомлениями - Централизованное хранение конфигурации #### С веб-интерфейсом - Добавление панели управления для VK в административный интерфейс - Единый интерфейс для публикации новостей во все каналы - Общая статистика по всем платформам ## Расширение функциональности ### Возможные улучшения #### Callback-сервер Реализация callback-сервера для получения событий в реальном времени: - Новые подписчики - Комментарии к публикациям - Лайки и репосты - Сообщения от пользователей #### Аналитика Добавление аналитики публикаций: - Статистика просмотров - Анализ вовлеченности - Эффективность разных типов контента - Время публикации с наибольшей вовлеченностью #### Медиабиблиотека Создание медиабиблиотеки: - Централизованное хранение изображений - Автоматическое создание превью - Оптимизация размера изображений - Поддержка различных форматов #### Шаблоны публикаций Расширение системы шаблонов: - Разные шаблоны для разных типов новостей - Переменные в шаблонах - Условная логика в шаблонах - Поддержка многоязычности #### API для других сервисов Создание API для интеграции с другими системами: - REST API для публикации новостей - Веб-хуки для автоматической публикации - SDK для других языков программирования ## Заключение Разработанный бот для ВКонтакте предоставляет полный набор инструментов для автоматизации публикации новостей в группу. Проект реализован с учетом лучших практик разработки, безопасности и масштабируемости. Ключевые преимущества решения: - **Готовность к использованию** - полная реализация всех необходимых функций - **Масштабируемость** - архитектура позволяет легко добавлять новые функции - **Безопасность** - соблюдение лучших практик хранения конфигурации - **Документация** - полная документация для быстрого старта - **Поддержка** - подробные примеры использования и обработка ошибок Проект готов к развертыванию и интеграции с существующей инфраструктурой.