# VNDB Telegram Bot Полнофункциональный Telegram бот для работы с базой данных [VNDB](https://vndb.org/) (Visual Novel Database). ## Возможности Бот поддерживает **все методы** VNDB API v2: ### Поиск и запросы - **Визуальные новеллы** - полный поиск по названию, языку, платформе, тегам, рейтингу и дате выпуска - **Персонажи** - поиск по имени, полу, роли, чертам характера - **Релизы** - поиск по названию, платформе, типу, дате выпуска - **Сотрудники** - поиск сценаристов, художников, композиторов и других - **Продюсеры** - поиск издателей и разработчиков - **Теги** - просмотр популярных тегов и категорий - **Черты характера** - список черт персонажей - **Цитаты** - получение случайных цитат из ВН ### Изображения - **Обложки ВН** - автоматическая отправка обложек при поиске визуальных новелл - **Аватары персонажей** - картинки персонажей при поиске - **Картинки релизов** - изображения для каждого релиза - **Подробный просмотр** - команды `/vn_detail`, `/char_detail`, `/release_detail` для полной информации с высоким качеством изображений ### Управление списками (требует токена) - Добавление ВН в личный список - Обновление статуса просмотра - Добавление заметок и оценок - Управление меткамиме ### Информация - Статистика базы данных - Информация о схеме API - Информация об авторизации ## Установка ### Требования - Python 3.8+ - pip ### Шаг 1: Клонирование репозитория ```bash git clone cd vntgbot ``` ### Шаг 2: Установка зависимостей ```bash pip install -r requirements.txt ``` ### Шаг 3: Настройка переменных окружения Создайте файл `.env` в корневой папке проекта: ```env # Обязательно TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here # Опционально (для функций авторизации) VNDB_TOKEN=your_vndb_api_token_here ``` #### Получение токена Telegram Bot 1. Напишите боту [@BotFather](https://t.me/botfather) в Telegram 2. Используйте команду `/newbot` 3. Следуйте инструкциям и получите токен #### Получение VNDB API токена 1. Создайте аккаунт на [VNDB.org](https://vndb.org) 2. Перейдите на https://vndb.org/u/tokens 3. Создайте новый токен 4. Скопируйте его в переменную `VNDB_TOKEN` ### Шаг 4: Запуск бота ```bash python bot.py ``` ## Использование ### Команды #### Поиск - `/search <название>` - Поиск визуальных новелл - `/char <имя>` - Поиск персонажей - `/release <название>` - Поиск релизов - `/staff <имя>` - Поиск сотрудников - `/producer <название>` - Поиск продюсеров #### Информация - `/tag` - Список популярных тегов - `/trait` - Список черт характера - `/quote [число]` - Случайные цитаты (макс. 5) - `/stats` - Статистика базы данных - `/schema` - Информация о схеме API - `/authinfo` - Информация об авторизации (если токен установлен) #### Просмотр с картинками - `/vn_detail ` - Полная информация о ВН с обложкой (_Пример: /vn_detail v17_) - `/char_detail ` - Информация о персонаже с аватаром (_Пример: /char_detail c1_) - `/release_detail ` - Информация о релизе с картинкой (_Пример: /release_detail r1_) #### Справка - `/start` - Приветствие и основная информация - `/help` - Подробная справка по всем командам ### Примеры использования ``` /search Steins Gate /char Okabe Rintaro /release Windows /staff Yoko Taro /producer Key /quote 3 /vn_detail v17 /char_detail c25 /release_detail r1 ``` ## Структура проекта ``` vntgbot/ ├── bot.py # Основной файл бота с обработчиками команд ├── vndb_client.py # VNDB API клиент ├── requirements.txt # Зависимости Python ├── .env # Переменные окружения (не отслеживается в git) ├── .gitignore # Файлы для игнорирования └── README.md # Этот файл ``` ## API Endpoints Бот поддерживает следующие endpoint'ы VNDB API: ### Простые запросы - `GET /schema` - Информация о схеме API - `GET /stats` - Статистика базы данных - `GET /user` - Информация о пользователе - `GET /authinfo` - Информация об авторизации ### Запросы к базе данных - `POST /vn` - Запрос визуальных новелл - `POST /release` - Запрос релизов - `POST /character` - Запрос персонажей - `POST /staff` - Запрос сотрудников - `POST /producer` - Запрос продюсеров - `POST /tag` - Запрос тегов - `POST /trait` - Запрос черт характера - `POST /quote` - Запрос цитат ### Управление списками - `POST /ulist` - Запрос списка ВН пользователя - `POST /rlist` - Запрос списка релизов пользователя - `PATCH /ulist/` - Обновление записи в списке ВН - `PATCH /rlist/` - Обновление записи в списке релизов - `DELETE /ulist/` - Удаление из списка ВН - `DELETE /rlist/` - Удаление из списка релизов - `GET /ulist_labels` - Получение меток списка ## Фильтры и опции ### Поддерживаемые параметры запросов: - **filters** - Условия фильтрации - **fields** - Выбираемые поля - **sort** - Сортировка (id, title, released, rating, votecount) - **reverse** - Обратный порядок сортировки - **results** - Количество результатов (макс. 100) - **page** - Номер страницы для пагинации - **count** - Включить общее количество результатов - **user** - ID пользователя для фильтров специфичных для пользователя ## Ограничения API VNDB API имеет следующие ограничения: - **200 запросов** за 5 минут - **1 секунда** общего времени выполнения в минуту - **3 секунды** максимального времени для одного запроса Бот учитывает эти ограничения и использует асинхронные запросы для оптимальной производительности. ## Обработка ошибок Бот обрабатывает следующие типы ошибок: - Сетевые ошибки (HTTP, timeout) - Ошибки парсинга JSON - Ошибки авторизации (401) - Ошибки валидации данных Все ошибки логируются и сообщаются пользователю в удобном формате. ## Расширение функционала Для добавления новых команд: 1. Добавьте метод в класс `BotHandlers` 2. Зарегистрируйте обработчик в функции `main()` 3. (Опционально) Расширьте `VndbClient` новыми методами API Пример: ```python @staticmethod async def my_command(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None: """Description""" try: # Your code here pass except Exception as e: logger.error(f"Error: {e}") await update.message.reply_text(f"❌ Error: {str(e)}") # In main(): application.add_handler(CommandHandler("mycommand", BotHandlers.my_command)) ``` ## Логирование Бот использует встроенный модуль `logging` для отслеживания операций. Логи выводятся в консоль с уровнем INFO. Для изменения уровня логирования отредактируйте `bot.py`: ```python logging.basicConfig( format="%(asctime)s - %(name)s - %(levelname)s - %(message)s", level=logging.DEBUG # Измените на DEBUG для более подробных логов ) ``` ## Документация VNDB API Полная документация VNDB API доступна по адресу: https://api.vndb.org/kana ## Лицензирование Данные, полученные через VNDB API, подлежат [Data License VNDB](https://vndb.org/d17#4). ## Благодарности - [VNDB](https://vndb.org/) за отличную базу данных и API - [python-telegram-bot](https://github.com/python-telegram-bot/python-telegram-bot) за удобную библиотеку ## Поддержка Если у вас есть вопросы или проблемы: 1. Проверьте файл логов 2. Убедитесь, что токены установлены правильно 3. Проверьте интернет соединение и статус API VNDB ## Автор Создано для удобного доступа к VNDB из Telegram.