# Universal File Compress

Высокопроизводительный инструмент на Go для массового сжатия PDF и изображений (JPEG/PNG) с удобным TUI-интерфейсом, гибкой конфигурацией и модульной архитектурой (Clean Architecture). Поддерживает выбор алгоритма сжатия (PDFCPU / UniPDF), параметрическое управление качеством, рекурсивную обработку директорий, параллельное выполнение, расширяемость через дополнительные компрессоры.

---
## Содержание
1. Обзор и ключевые особенности  
2. Быстрый старт  
3. Конфигурация (полный справочник)  
4. Алгоритмы сжатия (PDFCPU vs UniPDF)  
5. Сжатие изображений (JPEG / PNG)  
6. Архитектура и внутреннее устройство  
7. Поток обработки (Pipeline)  
8. Параллельность и производительность  
9. Логирование и мониторинг  
10. Расширяемость (как добавить новый компрессор)  
11. Сценарии использования и рекомендации  
12. Устранение неполадок  
13. План развития / Roadmap  
14. Лицензия (если применимо)  

---
## 1. Обзор и ключевые особенности

| Возможность | Описание |
|-------------|----------|
| Сжатие PDF  | Алгоритмы PDFCPU (скорость) и UniPDF (качество) |
| Сжатие изображений | JPEG (10–50% качество), PNG (адаптивная оптимизация) |
| Рекурсивная обработка | Поиск файлов во всех поддиректориях |
| Сохранение структуры | **Полное сохранение иерархии папок** в целевой директории |
| Параллельность | Несколько воркеров, управляемые через конфигурацию |
| Замена или сохранение | Перезапись оригиналов или вывод в целевую папку |
| Интеллектуальное сжатие | Автоматический выбор оригинала при неэффективном сжатии |
| TUI интерфейс | Настройка, запуск, мониторинг прогресса и логов |
| Логирование | В файл и/или на экран, ротация по размеру |
| Универсальная конфигурация | YAML + динамическая загрузка в рантайме |
| Расширяемость | Чистые интерфейсы для добавления новых компрессоров |
| Обработка ошибок | Повторы (retry), таймауты, агрегирование статистики |

---
## 2. Быстрый старт

### Установка из исходников
```bash
git clone https://github.com/your-username/compress.git
cd compress
go mod tidy
go build -o compress cmd/main.go
./compress   # (Windows: compress.exe)
```

### Минимальный сценарий
1. Поместите файлы в директорию `./pdfs` (или измените путь в `config.yaml`).  
2. Запустите программу.  
3. В TUI выберите «Конфигурация», настройте параметры.  
4. Сохраните и запустите обработку.  
5. Результаты появятся в выбранной целевой директории или заменят оригиналы.

---
## 3. Конфигурация (config.yaml)

```yaml
scanner:
  source_directory: "./pdfs"        # Папка с исходными файлами
  target_directory: "./compressed"  # Если пусто и replace_original=true — замена
  replace_original: false            # true — перезаписывать исходники

compression:
  level: 50                          # Общий уровень (10–90) влияет на стратегию
  algorithm: "pdfcpu"                # pdfcpu | unipdf
  auto_start: false                  # Автозапуск при старте приложения
  unipdf_license_key: ""             # Ключ для UniPDF (опционально)
  
  # Сжатие изображений
  enable_jpeg: true                  # Включить JPEG
  enable_png: true                   # Включить PNG
  jpeg_quality: 30                   # 10–50 (шаг 5)
  png_quality: 25                    # 10–50 (шаг 5)

processing:
  parallel_workers: 2                # Количество воркеров
  timeout_seconds: 30                # Таймаут на файл
  retry_attempts: 3                  # Повторы при падениях

output:
  log_level: "info"                  # debug|info|warning|error
  progress_bar: true
  log_to_file: true
  log_file_name: "compress.log"
  log_max_size_mb: 10
```

### Валидация параметров
| Параметр | Диапазон | Ошибка при нарушении |
|----------|----------|----------------------|
| compression.level | 10–90 | ErrInvalidCompressionLevel |
| jpeg_quality | 10–50 (шаг 5) | ErrInvalidJPEGQuality |
| png_quality | 10–50 (шаг 5) | ErrInvalidPNGQuality |

---
## 4. Алгоритмы сжатия PDF

| Критерий | PDFCPU | UniPDF |
|----------|--------|--------|
| Основной фокус | Скорость | Максимальное сжатие |
| Сжатие изображений | Базовое | Продвинутое (перекодирование) |
| Скорость (относит.) | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ |
| Степень сжатия | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
| Стабильность | Высокая | Высокая |
| Зависимости | Легковесный | Более тяжелая библиотека |

Рекомендации:
- Выберите PDFCPU, если: массовая обработка, преобладает текст, важна скорость.
- Выберите UniPDF, если: критичен размер, много изображений, важна агрессивная оптимизация.

Переключение: `compression.algorithm: "unipdf"`.

---
## 5. Сжатие изображений (JPEG / PNG)

### Поддерживаемые форматы
- JPEG: `.jpg`, `.jpeg`
- PNG: `.png`

### Параметры
| Параметр | Назначение |
|----------|------------|
| enable_jpeg | Включает проход по JPEG файлам |
| enable_png | Включает проход по PNG файлам |
| jpeg_quality | Управляет степенью перекодирования и масштабирования |
| png_quality | Управляет коэффициентом масштабирования и уровнем компрессии |

### Алгоритм JPEG (улучшенный с защитой от увеличения)
1. **Декодирование** исходного JPEG.  
2. **Адаптивное масштабирование**: quality 10→50%, quality 50→90% размера.  
3. **Консервативное качество**: маппинг 10→30, 30→55, 50→75 (вместо агрессивного 20-100).  
4. **Кодирование во временный файл** с проверкой размера.  
5. **Интеллектуальный выбор**:
   - Если результат ≥95% от оригинала → копируется оригинал (без потери качества)
   - Если результат меньше → используется сжатая версия
6. **Гарантия**: выходной файл никогда не будет больше исходного.

### Алгоритм PNG (улучшенный с защитой от увеличения)
1. **Декодирование** исходного PNG.  
2. **Консервативное масштабирование**: quality 10→60%, quality 50→90% размера.  
3. **Адаптивная обработка**: маленькие изображения (<400px) не изменяются в размерах.  
4. **Кодирование во временный файл** с максимальным сжатием (`png.BestCompression`).  
5. **Интеллектуальный выбор**:
   - Если результат ≥95% от оригинала → копируется оригинал
   - Если результат меньше → используется сжатая версия
6. **Гарантия**: выходной файл никогда не будет больше исходного.

**Важно**: PNG — lossless формат. Для уже оптимизированных файлов алгоритм автоматически сохраняет оригинал, предотвращая увеличение размера.

---
## 6. Архитектура

Следует принципам Clean Architecture.

Слои:
- `domain` — сущности, ошибки, интерфейсы (`Сompress`, `FileRepository`, `Logger`).
- `usecase` — сценарии: `ProcessPDFsUseCase`, `CompressImageUseCase`, `ProcessAllFilesUseCase`.
- `infrastructure` — реализации (компрессоры, файловый репозиторий, конфигурация, логирование).
- `presentation/tui` — UI слой, отображение прогресса, ввод настроек.
- `cmd/main.go` — композиция.

Преимущества: тестируемость, независимость от фреймворков, лёгкая замена реализаций.

---
## 7. Поток обработки (Pipeline)
1. Загрузка `config.yaml` через `config.Repository`.
2. Инициализация логирования и TUI.
3. Выбор реализации компрессора PDF.
4. Создание UseCases.
5. Пользователь подтверждает запуск (или auto_start).
6. Сканирование директорий — фильтрация поддерживаемых файлов.
7. Постановка задач в воркеры.
8. Сжатие + повторы при сбоях.
9. Обновление прогресса через callback → TUI.
10. Запись статистики, логов, замена/вывод файлов.

---
## 8. Параллельность и производительность
- Модель: пул воркеров (число — `parallel_workers`).
- Ограничение таймаутом: `timeout_seconds`.
- Повторы: `retry_attempts` (экспоненциальную стратегию можно внедрить дополнительно).
- Потенциальные оптимизации: кэширование размеров, отложенное пересохранение, batch-операции.

---
## 9. Логирование и мониторинг
| Тип | Назначение |
|-----|------------|
| Console/TUI | Интерактивное наблюдение за процессом |
| File logger | История и аудит |
| Уровни | debug, info, warning, error, success |

Ротация — по максимальному размеру (MB).

---
## 10. Расширяемость

### Добавление нового PDF компрессора
1. Создайте файл в `internal/infrastructure/compress/` (например, `myengine_compressor.go`).  
2. Реализуйте интерфейс `PDFCompressor`.  
3. Добавьте значение в конфигурацию (`compression.algorithm`).  
4. Расширьте `main.go` switch.  

### Добавление формата изображений
1. Дополните `IsImageFile` и `GetImageFormat`.  
2. Реализуйте метод в `ImageCompressor`.  
3. Добавьте поля в `AppCompressionConfig`, валидацию, TUI форму.

---
## 11. Сценарии и рекомендации
| Сценарий | Рекомендации |
|----------|--------------|
| Архивирование большого массива офисных PDF | PDFCPU + level 40–60 |
| Максимальное уменьшение для рассылки | UniPDF + level 70–85 |
| Много цветных сканов | UniPDF + включить сжатие JPEG 25–35% |
| Оптимизация сайта (изображения + PDF) | PDFCPU + JPEG/PNG 30% |
| Быстрая предпрод. обработка | PDFCPU + low retries |

---
## 12. Устранение неполадок
| Проблема | Причина | Решение |
|----------|---------|---------|
| UniPDF ошибка лицензии | Нет ключа | Установите `UNIDOC_LICENSE_API_KEY` или в config |
| PNG вырос в размере | Уже оптимален | Повышайте качество или отключите PNG |
| Нет файлов найдено | Неверный путь | Проверьте `scanner.source_directory` |
| Высокая нагрузка CPU | Слишком много воркеров | Уменьшите `parallel_workers` |
| Медленно при больших изображениях | Масштабирование | Увеличьте качество или отключите уменьшение |

---
## 13. Тестирование

### Комплексное тестирование всех алгоритмов

Проект включает единый комплексный тест, который проверяет все основные алгоритмы и компоненты:

```powershell
# Запуск через скрипт (рекомендуется)
cd tests
.\run-tests.ps1

# Или вручную
cd tests
go build -o comprehensive_test.exe comprehensive.go
.\comprehensive_test.exe
```

### Покрытие тестами

Комплексный тест проверяет:

✅ **Валидация конфигурации** (5 тестов)
- Корректность настроек JPEG/PNG качества
- Граничные значения (10-50%)
- Обнаружение невалидных параметров

✅ **Сжатие JPEG** (4 теста)
- Различные уровни качества (10%, 30%, 50%)
- Защита от увеличения размера файла

✅ **Сжатие PNG** (4 теста)
- Различные уровни качества
- Защита от увеличения размера файла

✅ **Сжатие PDF** (1 тест)
- Алгоритм PDFCPU

✅ **Структура папок** (1 тест)
- Сохранение иерархии при обработке

✅ **Вычисления** (3 теста)
- Коэффициент сжатия
- Экономия места

**Результаты:** Автоматический отчёт с детальной статистикой, время выполнения каждого теста, коды возврата для CI/CD.

Подробности: [tests/README.md](tests/README.md)

---
## 14. План развития (Roadmap)
- [ ] Поддержка WebP / AVIF
- [ ] Асинхронное журналирование с буферизацией
- [ ] REST API слой / gRPC
- [ ] Пакетный режим без TUI (`--headless`)
- [ ] Экспорт отчётов (JSON / HTML)
- [ ] Более точные эвристики выбора стратегии сжатия
- [ ] Плагинная система компрессоров
- [x] Комплексное тестирование всех алгоритмов

---
## 15. Лицензия

---
## Приложение A. Пример расширенного запуска
```bash
PDF_CONFIG=./config.yaml ./compress
```

## Приложение B. Метрики качества (пример)
| Показатель | PDFCPU (сред.) | UniPDF (сред.) |
|------------|----------------|----------------|
| Снижение размера | 30–45% | 50–70% |
| Время (100 файлов) | 1× | 2–3× |
| Ошибки повторной попытки | Низко | Низко |