docs

docs/development.md

@@ -0,0 +1,422 @@
+# Разработка
+
+## Настройка среды разработки
+
+### Требования
+
+- **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!("User 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