compress/README.md

Universal File Compressor

Высокопроизводительный инструмент на 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. Быстрый старт

Установка из исходников

git clone https://github.com/your-username/compressor.git
cd compressor
go mod tidy
go build -o compressor cmd/main.go
./compressor   # (Windows: compressor.exe)

Минимальный сценарий

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

---

3. Конфигурация (config.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: "compressor.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 — сущности, ошибки, интерфейсы (PDFCompressor, 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/compressors/ (например, 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. Тестирование

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

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

# Запуск через скрипт (рекомендуется)
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

---

14. План развития (Roadmap)

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

---

15. Лицензия

(Добавьте информацию о лицензии проекта при необходимости.)

---

Приложение A. Пример расширенного запуска

PDF_CONFIG=./config.yaml ./pdf-compressor

Приложение B. Метрики качества (пример)

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