First commit

2026-05-01 15:13:02 +03:00
parent c2fcedf608
commit b983126e6e
18 changed files with 7142 additions and 147 deletions
--- a/README.md
+++ b/README.md
@@ -1,2 +1,256 @@
-# ayako
+# 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.