VNDB Telegram Bot

Полнофункциональный Telegram бот для работы с базой данных VNDB (Visual Novel Database).

Возможности

Бот поддерживает все методы VNDB API v2:

Поиск и запросы

• Визуальные новеллы - полный поиск по названию, языку, платформе, тегам, рейтингу и дате выпуска
• Персонажи - поиск по имени, полу, роли, чертам характера
• Релизы - поиск по названию, платформе, типу, дате выпуска
• Сотрудники - поиск сценаристов, художников, композиторов и других
• Продюсеры - поиск издателей и разработчиков
• Теги - просмотр популярных тегов и категорий
• Черты характера - список черт персонажей
• Цитаты - получение случайных цитат из ВН

Изображения

• Обложки ВН - автоматическая отправка обложек при поиске визуальных новелл
• Аватары персонажей - картинки персонажей при поиске
• Картинки релизов - изображения для каждого релиза
• Подробный просмотр - команды /vn_detail, /char_detail, /release_detail для полной информации с высоким качеством изображений

Управление списками (требует токена)

• Добавление ВН в личный список
• Обновление статуса просмотра
• Добавление заметок и оценок
• Управление меткамиме

Информация

• Статистика базы данных
• Информация о схеме API
• Информация об авторизации

Установка

Требования

• Python 3.8+
• pip

Шаг 1: Клонирование репозитория

git clone <repo_url>
cd vntgbot

Шаг 2: Установка зависимостей

pip install -r requirements.txt

Шаг 3: Настройка переменных окружения

Создайте файл .env в корневой папке проекта:

# Обязательно
TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here

# Опционально (для функций авторизации)
VNDB_TOKEN=your_vndb_api_token_here

Получение токена Telegram Bot

1. Напишите боту @BotFather в Telegram
2. Используйте команду /newbot
3. Следуйте инструкциям и получите токен

Получение VNDB API токена

1. Создайте аккаунт на VNDB.org
2. Перейдите на https://vndb.org/u/tokens
3. Создайте новый токен
4. Скопируйте его в переменную VNDB_TOKEN

Шаг 4: Запуск бота

python bot.py

Использование

Команды

Поиск

• /search <название> - Поиск визуальных новелл
• /char <имя> - Поиск персонажей
• /release <название> - Поиск релизов
• /staff <имя> - Поиск сотрудников
• /producer <название> - Поиск продюсеров

Информация

• /tag - Список популярных тегов
• /trait - Список черт характера
• /quote [число] - Случайные цитаты (макс. 5)
• /stats - Статистика базы данных
• /schema - Информация о схеме API
• /authinfo - Информация об авторизации (если токен установлен)

Просмотр с картинками

• /vn_detail <ID> - Полная информация о ВН с обложкой (Пример: /vn_detail v17)
• /char_detail <ID> - Информация о персонаже с аватаром (Пример: /char_detail c1)
• /release_detail <ID> - Информация о релизе с картинкой (Пример: /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/<id> - Обновление записи в списке ВН
• PATCH /rlist/<id> - Обновление записи в списке релизов
• DELETE /ulist/<id> - Удаление из списка ВН
• DELETE /rlist/<id> - Удаление из списка релизов
• 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

Пример:

@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:

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.

Благодарности

• VNDB за отличную базу данных и API
• python-telegram-bot за удобную библиотеку

Поддержка

Если у вас есть вопросы или проблемы:

1. Проверьте файл логов
2. Убедитесь, что токены установлены правильно
3. Проверьте интернет соединение и статус API VNDB

Автор

Создано для удобного доступа к VNDB из Telegram.