# Yandex.Music Downloader Bot

[![Build Status](https://drone.mrixs.me/api/badges/Mrixs/yamusic-bot/status.svg?branch=dev)](https://drone.mrixs.me/Mrixs/yamusic-bot?branch=dev) [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

Удобный и быстрый Telegram-бот для получения аудиофайлов из сервиса Yandex.Music. Работает в inline-режиме, позволяя отправлять музыку в любой чат. Поддерживает поиск, а также ссылки на треки, альбомы и исполнителей.

## 🚀 Основные возможности

*   **Inline-режим:** Используйте бота в любом чате, просто упомянув его `@username`.
*   **Поддержка ссылок:** Распознает и обрабатывает ссылки на треки, альбомы и страницы исполнителей.
*   **Поиск:** Если введенный текст не является ссылкой, бот выполнит поиск треков по этому тексту.
*   **Метаданные:** Автоматически встраивает в аудиофайлы ID3-теги (название, исполнитель, альбом, год) и обложку.
*   **Кэширование:** Мгновенная отправка уже обработанных треков благодаря системе кэширования на базе SQLite и приватного Telegram-канала.
*   **Администрирование:** Предоставляет набор команд для администраторов для мониторинга и управления ботом.

## ⚙️ Конфигурация

Бот настраивается с помощью переменных окружения.

| Переменная                | Описание                                               | Пример                        | Обязательно |
| ------------------------- | ------------------------------------------------------ | ----------------------------- | ----------- |
| `TELEGRAM_BOT_TOKEN`      | Токен, полученный от @BotFather.                       | `12345:ABC-DEF`               | **Да**      |
| `TELEGRAM_ADMIN_IDS`      | Список Telegram ID администраторов через запятую.    | `1234567,9876543`             | **Да**      |
| `TELEGRAM_CACHE_CHAT_ID`  | ID приватного канала/чата для хранения файлов.         | `-100123456789`               | **Да**      |
| `YANDEX_MUSIC_TOKEN`      | OAuth-токен для доступа к Yandex.Music API.            | `y0_...`                      | **Да**      |
| `DATABASE_PATH`           | Путь к файлу базы данных SQLite.                       | `/data/bot.db`                | Нет (`/data/bot.db`) |
| `LOG_LEVEL`               | Уровень логирования (`debug`, `info`, `warn`, `error`). | `info`                        | Нет (`info`)  |
| `PROCESSOR_WORKERS`       | Количество воркеров для обработки треков.              | `4`                           | Нет (`4`)     |
| `YANDEX_API_RATE_LIMIT`   | Запросов в секунду к Yandex API.                       | `5`                           | Нет (`5`)     |

## ▶️ Запуск

### С помощью Docker 🐳

Рекомендуемый способ запуска. Убедитесь, что у вас установлен Docker.

1.  Создайте директорию для хранения базы данных: `mkdir -p ./data`
2.  Запустите контейнер:

    ```bash
    docker run -d --name yamusic-bot \
      -v $(pwd)/data:/data \
      -e TELEGRAM_BOT_TOKEN="ВАШ_ТОКЕН" \
      -e TELEGRAM_ADMIN_IDS="ВАШ_ID,ID_ДРУГА" \
      -e TELEGRAM_CACHE_CHAT_ID="-100..." \
      -e YANDEX_MUSIC_TOKEN="y0_..." \
      --restart always \
      gitea.mrixs.me/mrixs/yamusic-bot:dev
    ```
    *Примечание: Используйте тег `:latest` для стабильной версии из ветки `master` или `:dev` для последней сборки из ветки `dev`.*

### С помощью Docker Compose

1.  Создайте файл `docker-compose.yml`:
    ```yaml
    version: '3.8'
    services:
      bot:
        image: gitea.mrixs.me/mrixs/yamusic-bot:dev
        container_name: yamusic-bot
        restart: always
        volumes:
          - ./data:/data
        environment:
          - TELEGRAM_BOT_TOKEN=
          - TELEGRAM_ADMIN_IDS=
          - TELEGRAM_CACHE_CHAT_ID=
          - YANDEX_MUSIC_TOKEN=
          - LOG_LEVEL=info
    ```
2.  Заполните переменные окружения в файле или создайте рядом `.env` файл.
3.  Запустите: `docker-compose up -d`

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

### Для пользователей
Начните вводить в любом чате `@bot_username`, а затем вставьте ссылку или напишите поисковый запрос.

-   **Ссылка на трек:** `@bot_username https://music.yandex.ru/album/123/track/456`
-   **Ссылка на альбом:** `@bot_username https://music.yandex.ru/album/123`
-   **Поиск:** `@bot_username Rammstein - Sonne`

### Для администраторов
Отправьте команду в личные сообщения боту.

-   `/help` — Показать список команд.
-   `/stats` — Показать статистику работы бота.
-   `/find <yandex_track_id>` — Найти трек в кэше по ID.
-   `/warm <URL>` — "Прогреть" кэш для альбома или исполнителя.

## 🗺️ План разработки (Dev Roadmap)

| Статус | Задача                                                               | Комментарий                                                              |
| :----: | -------------------------------------------------------------------- | ------------------------------------------------------------------------ |
|   ✅   | Базовый CI/CD пайплайн (lint, test)                                  | Настроен в `.drone.yml`.                                                 |
|   ✅   | Основная логика обработки URL (трек, альбом, артист)                 | Реализовано в `internal/bot/handler.go`.                                 |
|   ✅   | Система кэширования (SQLite + Telegram)                              | Реализовано в `internal/storage` и `internal/processor`.                 |
|   ✅   | Базовая структура проекта и конфигурация                             | Вся структура соответствует ТЗ.                                          |
|   ✅   | Административные команды `/help`, `/stats`, `/find`                  | Основной функционал реализован в `internal/admin/handler.go`.            |
|   ✅   | Публикация Docker-образов в CI/CD                                    | Шаги `build-and-publish-*` активны в `.drone.yml` для `master` и `dev`.    |
|   ⏳   | Расширение тестового покрытия                                        | Есть тесты для `storage`, но нужны для `processor`, `bot`, `admin`.       |
|   ⏳   | Финализация документации                                             | Этот `README.md` является частью задачи.                                 |
|   ❌   | Реализация логики команды `/warm`                                    | Существует только заглушка, фоновая обработка не реализована.             |
|   ❌   | Ограничение частоты запросов (Rate Limiting) к Yandex API            | Требуется внедрение `rate.Limiter`.                                      |
|   ❌   | Поддержка текстового поиска и коротких URL                           | Задача из нового ТЗ, требуется реализация в `handler` и `yamusic client`. |

## 📄 Лицензия

Проект распространяется под лицензией MIT. См. файл `LICENSE` для получения дополнительной информации.