quoter/README.md

# Quoter 🚀

[![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/)
[![Tests](https://img.shields.io/badge/Tests-36%20Passing-brightgreen.svg)](https://dev.discours.io/discours.io/quoter)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

> Микросервис для управления файлами с поддержкой квот, миниатюр и интеграции с S3 хранилищами

Quoter - это высокопроизводительный сервис для загрузки и управления файлами, построенный на Rust с использованием Actix Web. Поддерживает автоматическое создание миниатюр, управление квотами пользователей и интеграцию с различными S3-совместимыми хранилищами. 

## 📖 Документация

Подробная документация доступна в папке [`docs/`](./docs/):

### Основные разделы
- [📚 Оглавление](./docs/README.md) - Полная структура документации
- [🔧 API Reference](./docs/api-reference.md) - Документация API
- [⚙️ Конфигурация](./docs/configuration.md) - Настройка переменных окружения
- [🚀 Развертывание](./docs/deployment.md) - Инструкции по развертыванию
- [📊 Мониторинг](./docs/monitoring.md) - Логирование и мониторинг

### Технические детали
- [🏗️ Архитектура](./docs/architecture.md) - Техническая архитектура системы
- [🔍 Как это работает](./docs/how-it-works.md) - Подробное описание процессов
- [🧪 Тестирование](./docs/testing.md) - Полное покрытие тестами (36 тестов)
- [💻 Разработка](./docs/development.md) - Настройка среды разработки
- [🤝 Contributing](./docs/contributing.md) - Руководство для контрибьюторов

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

- 🔐 **Аутентификация** через JWT токены
- 📁 **Загрузка файлов** в S3/Storj с автоматическим определением MIME-типов
- 🖼️ **Автоматические миниатюры** для изображений (10, 40, 110, 300, 600, 800, 1400px)
- 💾 **Управление квотами** пользователей (5 ГБ по умолчанию)
- 🎨 **Оверлеи для shout** с автоматическим наложением текста
- 🔄 **CORS поддержка** для веб-приложений
- ⚡ **Высокая производительность** благодаря асинхронной архитектуре
- 📊 **Мониторинг и логирование** всех операций

## 🏗️ Архитектура

Quoter построен на современном стеке технологий:

- **Backend**: Rust + Actix Web
- **База данных**: Redis для квот и кэширования
- **Хранилище**: S3-совместимые сервисы (Storj, AWS S3)
- **Аутентификация**: JWT токены через GraphQL API
- **Обработка изображений**: image-rs + imageproc

## 🧪 Тестирование

### Запуск тестов
```bash
# Все тесты
cargo test

# Конкретный тест
cargo test test_health_check

# Тесты с покрытием
./scripts/test-coverage.sh
```

### Статистика тестов
- **basic_test.rs:** 23 теста (основная функциональность)
- **handler_tests.rs:** 13 тестов (HTTP endpoints)
- **Общее покрытие:** 100% основных компонентов
- **Статус:** Все тесты проходят успешно

## 📋 Требования

- **Rust**: 1.70 или выше
- **Redis**: 6.0 или выше
- **S3 совместимое хранилище**: Storj, AWS S3 или другое
- **API ядра**: для аутентификации и получения данных shout

## 🚀 CI/CD и автоматизация

### Статус конвейера
- ✅ **Тесты:** 36/36 проходят успешно
- ✅ **Компиляция:** без ошибок
- ✅ **Покрытие:** 100% основных компонентов
- 🚀 **Деплой:** автоматический при успешном прохождении тестов

### Автоматизация
- Автоматический запуск тестов при каждом коммите
- Проверка качества кода и покрытия
- Автоматический деплой в продакшн
- Полностью автоматизированный конвейер "тесты → деплой"

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

### Переменные окружения

Подробная информация о настройке переменных окружения доступна в [документации по конфигурации](./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