quoter/docs/development.md

# Разработка

## Настройка среды разработки

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

- **Rust**: 1.70 или выше
- **Redis**: 6.0 или выше (локально или Docker)
- **Git**: для работы с репозиторием
- **IDE**: VS Code, IntelliJ IDEA или другой редактор с поддержкой Rust

### Установка Rust

```bash
# Установка Rust через rustup
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Перезагрузка shell
source ~/.bashrc

# Проверка установки
rustc --version
cargo --version
```

### Клонирование репозитория

```bash
git clone https://github.com/your-org/quoter.git
cd quoter
```

### Установка зависимостей

```bash
# Сборка проекта
cargo build

# Установка дополнительных инструментов
cargo install cargo-watch  # для автоматической пересборки
cargo install cargo-audit  # для проверки безопасности
cargo install cargo-tarpaulin  # для покрытия кода тестами
```

## Структура проекта

```
quoter/
├── src/
│   ├── main.rs              # Точка входа приложения
│   ├── app_state.rs         # Состояние приложения и подключения
│   ├── auth.rs              # Аутентификация и авторизация
│   ├── core.rs              # Интеграция с API ядра
│   ├── lookup.rs            # Поиск и определение MIME-типов
│   ├── overlay.rs           # Генерация оверлеев для изображений
│   ├── s3_utils.rs          # Утилиты для работы с S3
│   ├── thumbnail.rs         # Создание миниатюр
│   └── handlers/            # HTTP обработчики
│       ├── mod.rs           # Модуль обработчиков
│       ├── upload.rs        # Загрузка файлов
│       ├── proxy.rs         # Получение файлов
│       ├── quota.rs         # Управление квотами
│       └── serve_file.rs    # Обслуживание файлов
├── docs/                    # Документация
├── tests/                   # Интеграционные тесты
├── Cargo.toml              # Зависимости и конфигурация
├── Cargo.lock              # Фиксированные версии зависимостей
├── Dockerfile              # Docker образ
└── README.md               # Основная документация
```

## Локальная разработка

### Настройка переменных окружения

Создайте файл `.env` в корне проекта:

```bash
# Redis (локально или Docker)
REDIS_URL=redis://localhost:6379

# Core API (замените на ваш endpoint)
CORE_URL=https://api.example.com/graphql

# Storj S3 (тестовые ключи)
STORJ_ACCESS_KEY=your-test-key
STORJ_SECRET_KEY=your-test-secret
STORJ_BUCKET_NAME=test-bucket

# AWS S3 (тестовые ключи)
AWS_ACCESS_KEY=your-test-aws-key
AWS_SECRET_KEY=your-test-aws-secret

# Server
PORT=8080
RUST_LOG=debug
```

### Запуск Redis

#### Локально
```bash
# Ubuntu/Debian
sudo apt-get install redis-server
sudo systemctl start redis-server

# macOS
brew install redis
brew services start redis

# Проверка
redis-cli ping
```

#### Docker
```bash
docker run -d \
  --name redis-dev \
  -p 6379:6379 \
  redis:7-alpine
```

### Запуск приложения

```bash
# Обычный запуск
cargo run

# С автоматической пересборкой
cargo watch -x run

# В режиме отладки
RUST_LOG=debug cargo run

# С профилированием
cargo run --release
```

### Проверка работоспособности

```bash
# Проверка сервера
curl http://localhost:8080/

# Проверка загрузки файла (требует токен)
curl -X POST http://localhost:8080/ \
  -H "Authorization: Bearer your-token" \
  -F "file=@test-image.jpg"
```

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

### Unit тесты

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

# Запуск тестов с выводом
cargo test -- --nocapture

# Запуск конкретного теста
cargo test test_upload_file

# Запуск тестов в параллельном режиме
cargo test -- --test-threads=4
```

### Интеграционные тесты

Создайте файл `tests/integration_test.rs`:

```rust
use actix_web::{test, web, App};
use quoter::app_state::AppState;

#[actix_web::test]
async fn test_upload_endpoint() {
    let app_state = AppState::new().await;
    let app = test::init_service(
        App::new()
            .app_data(web::Data::new(app_state))
            .route("/", web::post().to(upload_handler))
    ).await;

    let req = test::TestRequest::post()
        .uri("/")
        .insert_header(("Authorization", "Bearer test-token"))
        .set_form(("file", "test-data"))
        .to_request();

    let resp = test::call_service(&app, req).await;
    assert!(resp.status().is_success());
}
```

### Тестирование производительности

```bash
# Бенчмарки (если настроены)
cargo bench

# Профилирование с flamegraph
cargo install flamegraph
cargo flamegraph --bin quoter
```

## Отладка

### Логирование

```rust
use log::{debug, info, warn, error};

// В коде
debug!("Processing file: {}", filename);
info!("File uploaded successfully");
warn!("Author quota is getting low: {} bytes", quota);
error!("Failed to upload file: {}", e);
```

### Отладка с GDB

```bash
# Компиляция с отладочной информацией
cargo build

# Запуск с GDB
gdb target/debug/quoter

# В GDB
(gdb) break main
(gdb) run
(gdb) continue
```

### Отладка с LLDB (macOS)

```bash
lldb target/debug/quoter
(lldb) breakpoint set --name main
(lldb) run
```

## Проверка кода

### Clippy

```bash
# Проверка стиля кода
cargo clippy

# Проверка с дополнительными предупреждениями
cargo clippy -- -D warnings

# Автоматическое исправление
cargo clippy --fix
```

### Форматирование

```bash
# Форматирование кода
cargo fmt

# Проверка форматирования
cargo fmt -- --check
```

### Проверка безопасности

```bash
# Аудит зависимостей
cargo audit

# Проверка уязвимостей
cargo audit --deny warnings
```

## Покрытие кода

### Tarpaulin

```bash
# Установка
cargo install cargo-tarpaulin

# Запуск
cargo tarpaulin

# С HTML отчетом
cargo tarpaulin --out Html
```

### grcov

```bash
# Установка
cargo install grcov

# Настройка переменных
export CARGO_INCREMENTAL=0
export RUSTFLAGS="-Zprofile -Ccodegen-units=1 -Cinline-threshold=0 -Clink-dead-code -Coverflow-checks=off -Cpanic=abort -Zpanic_abort_tests"
export RUSTDOCFLAGS="-Zprofile -Ccodegen-units=1 -Cinline-threshold=0 -Clink-dead-code -Coverflow-checks=off -Cpanic=abort -Zpanic_abort_tests"

# Запуск тестов
cargo test

# Генерация отчета
grcov . -s . --binary-path ./target/debug/ -t html --branch --ignore-not-existing -o ./coverage/
```

## Git workflow

### Создание feature branch

```bash
# Создание новой ветки
git checkout -b feature/new-feature

# Внесение изменений
# ...

# Коммит изменений
git add .
git commit -m "feat: add new feature"

# Push в репозиторий
git push origin feature/new-feature
```

### Commit conventions

Используйте [Conventional Commits](https://www.conventionalcommits.org/):

- `feat:` - новая функциональность
- `fix:` - исправление багов
- `docs:` - изменения в документации
- `style:` - форматирование кода
- `refactor:` - рефакторинг кода
- `test:` - добавление тестов
- `chore:` - обновление зависимостей, конфигурации

### Pull Request

1. Создайте Pull Request в GitHub/GitLab
2. Добавьте описание изменений
3. Укажите связанные issues
4. Дождитесь code review
5. Исправьте замечания если есть
6. Получите approval и merge

## Полезные команды

### Cargo

```bash
# Обновление зависимостей
cargo update

# Очистка сборки
cargo clean

# Проверка зависимостей
cargo tree

# Документация
cargo doc --open

# Проверка типов без компиляции
cargo check
```

### Отладка

```bash
# Просмотр логов в реальном времени
tail -f logs/quoter.log

# Мониторинг ресурсов
htop
iotop

# Сетевые соединения
netstat -tulpn | grep 8080
```

### Docker

```bash
# Сборка для разработки
docker build -t quoter:dev .

# Запуск с volume для hot reload
docker run -v $(pwd):/app -p 8080:8080 quoter:dev

# Просмотр логов контейнера
docker logs -f quoter-container
```

## Рекомендации

### Производительность

1. Используйте `cargo build --release` для production
2. Настройте профилирование для критических участков
3. Мониторьте использование памяти и CPU
4. Оптимизируйте размер изображений

### Безопасность

1. Регулярно обновляйте зависимости
2. Используйте `cargo audit` для проверки уязвимостей
3. Не храните секреты в коде
4. Валидируйте все входные данные

### Качество кода

1. Пишите тесты для новой функциональности
2. Используйте `cargo clippy` для проверки стиля
3. Документируйте публичные API
4. Следуйте принципам SOLID