file manager

docs/file_manager_agent.md

@@ -0,0 +1,61 @@
+# Агент файлового менеджера для Synology Power Control Bot
+
+## Описание
+
+Агент файлового менеджера предоставляет удобный интерфейс для просмотра, управления и манипулирования файловой системой Synology NAS через Telegram бота. Агент разработан с использованием модульной архитектуры и предоставляет интуитивно понятный интерфейс с кнопками и диалоговыми окнами.
+
+## Функциональность
+
+- **Просмотр содержимого директорий** - навигация по файловой системе NAS
+- **Загрузка и скачивание файлов** - передача файлов между NAS и устройством пользователя
+- **Управление файлами** - переименование, удаление, получение информации о файлах
+- **Создание папок** - создание новых директорий на NAS
+- **Пагинация** - удобная навигация при большом количестве файлов
+
+## Использование
+
+Для начала работы с файловым менеджером отправьте команду `/files` боту. После этого вы увидите список доступных общих папок на вашем NAS. Используйте интерактивные кнопки для навигации и выполнения различных действий с файлами.
+
+### Основные команды
+
+- `/files` - запуск файлового менеджера
+- `/files [path]` - открытие файлового менеджера с указанным путем
+
+### Интерфейс и навигация
+
+Интерфейс файлового менеджера состоит из:
+- Информации о текущей директории (путь, количество файлов и папок)
+- Списка папок и файлов с кнопками для взаимодействия
+- Кнопок навигации (Вверх, Вперед, Назад)
+- Кнопок действий (Загрузить файл, Создать папку)
+
+## Структура кода
+
+Агент файлового менеджера состоит из следующих основных компонентов:
+
+- **FileManagerAgent** - основной класс агента, реализующий логику файлового менеджера
+- **SynologyAPI** - класс для взаимодействия с API Synology NAS
+- **filestation.py** - модуль, расширяющий SynologyAPI методами для работы с файлами
+
+## Интеграция
+
+Агент файлового менеджера можно легко интегрировать в любого Telegram бота с помощью функции `create_file_manager_handler()`, которая возвращает готовый `ConversationHandler` для регистрации в диспетчере бота.
+
+```python
+from src.api.synology import SynologyAPI
+from src.agents.file_manager_agent import create_file_manager_handler
+from src.api.filestation import add_file_manager_methods_to_synology_api
+
+# Создание экземпляра API
+synology_api = SynologyAPI()
+
+# Создание обработчика
+file_manager_handler = create_file_manager_handler(synology_api)
+
+# Регистрация обработчика в приложении бота
+application.add_handler(file_manager_handler)
+```
+
+## Безопасность
+
+Агент файлового менеджера использует декоратор `@admin_required` для обеспечения доступа только авторизованным пользователям. Это защищает файловую систему NAS от несанкционированного доступа.