fofanov.dmitry/compress
1
0
Fork 0
Code Pull Requests Releases Activity

Достижение: Добавлены скрипты и документация для релиза PDF Compressor.

Browse Source 
- Добавлен release-body.md для подробных заметок о релизе на русском языке.
- Реализован release-gitea.ps1 для автоматизированного релиза Gitea с помощью PowerShell.
- Создан release-gitea.sh для автоматизированного релиза Gitea с помощью Bash.
- Добавлен release.sh для сборки и маркировки релизов с поддержкой нескольких платформ.
- Улучшен пользовательский интерфейс благодаря информативному логированию и обработке ошибок.
- Добавлена ​​поддержка переменных окружения и управления конфигурацией.
- Добавлена ​​функция создания архивов и загрузки ресурсов в Gitea.
This commit is contained in:
Dmitriy Fofanov
2025-11-05 09:33:12 +03:00
parent f328d67080
commit ec65cfd05a
43 changed files with 5792 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

309
README.md
View File

@@ -1,3 +1,308 @@
# compress
# Universal File Compressor
Высокопроизводительный инструмент на Go для массового сжатия PDF и изображений (JPEG/PNG) с удобным TUI-интерфейсом, гибкой конфигурацией и модульной архитектурой (Clean Architecture). Поддерживает выбор алгоритма сжатия (PDFCPU / UniPDF), параметрическое управление качеством, рекурсивную обработку директорий, параллельное выполнение, расширяемость через дополнительные компрессоры.
Высокопроизводительный инструмент на 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/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)
```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. Тестирование
### Комплексное тестирование всех алгоритмов
Проект включает единый комплексный тест, который проверяет все основные алгоритмы и компоненты:
```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 ./pdf-compressor
```
## Приложение B. Метрики качества (пример)
| Показатель | PDFCPU (сред.) | UniPDF (сред.) |
|------------|----------------|----------------|
| Снижение размера | 30–45% | 50–70% |
| Время (100 файлов) | 1× | 2–3× |
| Ошибки повторной попытки | Низко | Низко |