# Boty VK - Документация

## Обзор

Проект предназначен для интеграции с VK API для публикации новостей в группу ВКонтакте. Реализован на Python с использованием официального SDK vk_api.

## Возможности VK API

VK API предоставляет широкие возможности для работы с группами:

### Публикация контента
- Публикация записей на стене группы
- Добавление изображений, видео, документов
- Поддержка форматирования текста
- Планирование публикаций
- Работа с опросами

### Управление группой
- Получение статистики
- Управление подписчиками
- Работа с диалогами и сообщениями
- Обработка событий (callback-сервер)

### Преимущества
- Официальный API с хорошей документацией
- Поддержка всех типов медиа
- Возможность планирования публикаций
- Интеграция с другими сервисами VK

## Реализация

### Технологический стек
- Python 3.8+ - основной язык
- vk_api - официальный SDK для VK
- requests - HTTP-запросы
- python-dotenv - управление конфигурацией
- schedule - планирование задач

### Структура проекта

```
bot_vk/
├── src/
│   ├── __init__.py
│   ├── config.py
│   ├── vk_client.py
│   ├── post_manager.py
│   └── scheduler.py
├── templates/
│   └── news_template.html
├── media/
│   └── .gitkeep
├── logs/
│   └── .gitkeep
├── .env.example
├── requirements.txt
├── README.md
└── main.py
```

### Основные компоненты

#### `vk_client.py`
Класс для работы с VK API:
- Авторизация через токен
- Отправка запросов к API
- Обработка ошибок
- Работа с медиафайлами

#### `post_manager.py`
Менеджер публикаций:
- Формирование текста новости
- Добавление вложений
- Публикация на стене
- Планирование публикаций

#### `scheduler.py`
Планировщик задач:
- Расписание публикаций
- Проверка готовых к публикации новостей
- Отправка уведомлений о публикации

#### `config.py`
Конфигурация приложения:
- Токен группы
- ID группы
- Параметры подключения
- Настройки логирования

## Установка и настройка

1. Установите зависимости:
```bash
pip install -r requirements.txt
```

2. Настройте переменные окружения:
```bash
cp .env.example .env
```

3. Получите токен группы:
- Перейдите в настройки группы
- Раздел "Работа с API"
- Создайте токен с правами "Управление группой" и "Доступ в сообщения"

4. Запустите приложение:
```bash
python main.py
```

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

### Публикация новости
```python
from src.post_manager import PostManager

pm = PostManager()

post_data = {
    'owner_id': -123456789,  # ID группы (с минусом)
    'message': 'Заголовок новости\n\nТекст новости',
    'attachments': 'photo123456789_123456789',  # ID медиа
    'from_group': 1,  # Публиковать от имени группы
    'signed': 0,  # Не подписывать запись
    'close_comments': 0  # Не закрывать комментарии
}

pm.publish_post(post_data)
```

### Планирование публикации
```python
pm.schedule_post(post_data, publish_date='2023-12-01 15:00')
```

## Безопасность
- Храните токен в .env файле, не коммитьте в репозиторий
- Ограничьте права токена только необходимыми функциями
- Регулярно обновляйте токен
- Используйте HTTPS для всех запросов

## Ограничения VK API
- Ограничение на количество запросов (3 запроса в секунду)
- Ограничение на размер текста (16384 символа)
- Ограничение на количество вложений (10)
- Требуется модерация некоторых типов контента

## Альтернативы
- Использование callback-сервера для получения событий
- Интеграция с VK Mini Apps
- Работа с сообществами через Long Poll API

## Примечание
Проект готов к реализации. Для начала работы необходимо получить токен группы и настроить конфигурацию.