docs

README.md

@@ -1,47 +1,119 @@
-# Квотер
+# Quoter 🚀
 
-Управляет квотами на загрузку файлов и их размещением в S3-хранилище. Поддерживает создание миниатюр для изображений и управляет квотами на использование дискового пространства для каждого пользователя с использованием Redis.
+[![Rust](https://img.shields.io/badge/Rust-1.70+-orange.svg)](https://www.rust-lang.org/)
+[![Actix Web](https://img.shields.io/badge/Actix%20Web-4.0+-blue.svg)](https://actix.rs/)
+[![Redis](https://img.shields.io/badge/Redis-6.0+-red.svg)](https://redis.io/)
+[![S3 Compatible](https://img.shields.io/badge/S3%20Compatible-Storj%20%7C%20AWS-green.svg)](https://aws.amazon.com/s3/)
+[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-## Основные функции
+> Микросервис для управления файлами с поддержкой квот, миниатюр и интеграции с S3 хранилищами
 
- - Миниатюры: Автоматическое создание миниатюр для изображений.
- - S3/STORJ интеграция: Загрузка файлов в через `aws-sdk-s3` и возврат публичных URL-адресов.
- - Управление квотами: Ограничение объема загружаемых данных для каждого пользователя с использованием Redis.
- - Отслеживание файлов: Хранение информации о загруженных файлах в Redis для управления квотами.
- - CORS поддержка: Встроенная поддержка кросс-доменных запросов на уровне приложения для безопасного взаимодействия с веб-интерфейсами.
+Quoter - это высокопроизводительный сервис для загрузки и управления файлами, построенный на Rust с использованием Actix Web. Поддерживает автоматическое создание миниатюр, управление квотами пользователей и интеграцию с различными S3-совместимыми хранилищами. 
 
-### Как это работает
+## 📖 Документация
 
-1. **Аутентификация**:
-   - Клиент отправляет файл на сервер с заголовком `Authorization`, содержащим токен. Сервер проверяет наличие и валидность токена, определяя пользователя.
+Подробная документация доступна в папке [`docs/`](./docs/):
 
-2. **Загрузка файлов**:
-   - Сервер обрабатывает все загружаемые файлы. Если файл является изображением, создается его миниатюра. И миниатюра, и оригинальное изображение загружаются в S3. Для остальных файлов выполняется простая загрузка в S3 без создания миниатюр.
+### Основные разделы
+- [📚 Оглавление](./docs/README.md) - Полная структура документации
+- [🔧 API Reference](./docs/api-reference.md) - Документация API
+- [⚙️ Конфигурация](./docs/configuration.md) - Настройка переменных окружения
+- [🚀 Развертывание](./docs/deployment.md) - Инструкции по развертыванию
+- [📊 Мониторинг](./docs/monitoring.md) - Логирование и мониторинг
 
-3. **Создание миниатюр**:
-   - Для всех загружаемых изображений сервер автоматически создает миниатюры размером 320x320 пикселей. Миниатюры сохраняются как отдельные файлы в том же S3 bucket, что и оригинальные изображения.
+### Технические детали
+- [🏗️ Архитектура](./docs/architecture.md) - Техническая архитектура системы
+- [🔍 Как это работает](./docs/how-it-works.md) - Подробное описание процессов
+- [💻 Разработка](./docs/development.md) - Настройка среды разработки
+- [🤝 Contributing](./docs/contributing.md) - Руководство для контрибьюторов
 
-4. **Определение MIME-типа и расширения файла**:
-   - MIME-тип и расширение файла определяются автоматически на основе имени файла и его содержимого с использованием библиотеки `mime_guess`.
+## ✨ Основные возможности
 
-5. **Загрузка файлов в S3**:
-   - Все файлы, включая миниатюры и оригиналы изображений, загружаются в указанный S3 bucket. Сформированные URL-адреса файлов возвращаются клиенту.
+- 🔐 **Аутентификация** через JWT токены
+- 📁 **Загрузка файлов** в S3/Storj с автоматическим определением MIME-типов
+- 🖼️ **Автоматические миниатюры** для изображений (10, 40, 110, 300, 600, 800, 1400px)
+- 💾 **Управление квотами** пользователей (5 ГБ по умолчанию)
+- 🎨 **Оверлеи для shout** с автоматическим наложением текста
+- 🔄 **CORS поддержка** для веб-приложений
+- ⚡ **Высокая производительность** благодаря асинхронной архитектуре
+- 📊 **Мониторинг и логирование** всех операций
 
-6. **Управление квотами**:
-   - Для каждого пользователя устанавливается квота на загрузку данных, которая составляет 1 ГБ в неделю. Перед загрузкой каждого нового файла проверяется, не превысит ли его размер текущую квоту пользователя. Если квота будет превышена, загрузка файла будет отклонена. После успешной загрузки файл и его размер регистрируются в Redis, и квота пользователя обновляется.
+## 🏗️ Архитектура
 
-7. **Сохранение информации о загруженных файлах в Redis**:
-   - Имя каждого загруженного файла сохраняется в Redis для отслеживания загруженных пользователем файлов. Это позволяет учитывать квоты и управлять пространством, занимаемым файлами.
+Quoter построен на современном стеке технологий:
 
-8. **Оверлей для shout**:
-   - При загрузке файла, если он является изображением, и в запросе присутствует параметр `s=<shout_id>`, то к файлу будет добавлен оверлей с данными shout.
+- **Backend**: Rust + Actix Web
+- **База данных**: Redis для квот и кэширования
+- **Хранилище**: S3-совместимые сервисы (Storj, AWS S3)
+- **Аутентификация**: JWT токены через GraphQL API
+- **Обработка изображений**: image-rs + imageproc
 
-## Использование
+## 📋 Требования
 
-Нужно задать следующие переменные среды:
+- **Rust**: 1.70 или выше
+- **Redis**: 6.0 или выше
+- **S3 совместимое хранилище**: Storj, AWS S3 или другое
+- **API ядра**: для аутентификации и получения данных shout
 
-- `REDIS_URL`: URL для подключения к Redis. Используется для управления квотами и хранения информации о загружаемых файлах.
-- `CDN_DOMAIN`: Домен CDN для генерации публичных URL-адресов загруженных файлов.
-- `AUTH_URL`: URL для подключения к сервису аутентификации.
-- `CORE_URL`: URL для подключения к сервису core.
-- `STORJ_ACCESS_KEY`, `STORJ_SECRET_KEY`, `AWS_ACCESS_KEY`, `AWS_SECRET_KEY`
+## 🔧 Использование
+
+### Переменные окружения
+
+Подробная информация о настройке переменных окружения доступна в [документации по конфигурации](./docs/configuration.md).
+
+### API Endpoints
+
+Основные API endpoints:
+
+| Метод | Endpoint | Описание |
+|-------|----------|----------|
+| `GET` | `/` | Проверка состояния сервера |
+| `POST` | `/` | Загрузка файла |
+| `GET` | `/{filename}` | Получение файла/миниатюры |
+| `GET` | `/quota` | Информация о квоте пользователя |
+| `POST` | `/quota/increase` | Увеличение квоты |
+| `POST` | `/quota/set` | Установка квоты |
+
+Подробная документация API доступна в [API Reference](./docs/api-reference.md).
+
+### Примеры использования
+
+#### Загрузка файла
+```bash
+curl -X POST http://localhost:8080/ \
+  -H "Authorization: Bearer your-token" \
+  -F "file=@image.jpg"
+```
+
+#### Получение миниатюры
+```bash
+curl http://localhost:8080/image_300.jpg
+```
+
+#### Увеличение квоты
+```bash
+curl -X POST http://localhost:8080/quota/increase \
+  -H "Authorization: Bearer your-token" \
+  -H "Content-Type: application/json" \
+  -d '{"user_id": "user123", "additional_bytes": 1073741824}'
+```
+
+## 🧪 Разработка
+
+```bash
+cargo build # сборка
+cargo test # запуск тестов
+cargo clippy # Проверка кода
+cargo fmt # Форматирование
+RUST_LOG=debug cargo run # подробные логи
+```
+
+### Метрики
+
+Основные метрики для мониторинга:
+
+- Количество загруженных файлов
+- Использование квот пользователями
+- Время ответа API
+- Ошибки аутентификации
+- Ошибки загрузки в S3