257 lines
10 KiB
Markdown
257 lines
10 KiB
Markdown
# 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 <repo_url>
|
||
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 <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
|
||
|
||
Пример:
|
||
|
||
```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.
|