Add LICENSE, update README.md, .drone.yml

2025-06-23 21:30:30 +03:00
parent 2507a1531e
commit e13557059c
3 changed files with 155 additions and 23 deletions
--- a/README.md
+++ b/README.md
@@ -1,17 +1,109 @@
 # Yandex.Music Downloader Bot

-[![Build Status](https://drone.mrixs.me/api/badges/Mrixs/yamusic-bot/status.svg)](https://drone.mrixs.me/Mrixs/yamusic-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 по ссылке.
+Удобный и быстрый 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` для получения дополнительной информации.