Implement CLI commands for batch extraction and PDF generation

- Added command-line interface using Click for `batch_extractor.py` to handle extraction from ZIP and PDF files. - Enhanced `save_to_excel` function to create parent directories for output files. - Updated `build_pdf.py` to include a CLI for generating PDF labels from Excel data. - Improved README.md with detailed usage instructions for the new CLI commands. - Added `click` to requirements.txt for command-line functionality.
2026-02-21 13:20:08 +03:00
parent 3f8e6935a8
commit 6850f3672e
5 changed files with 170 additions and 55 deletions
--- a/README.md
+++ b/README.md
@@ -1,14 +1,16 @@
 # LabelExtractor (Честный ЗНАК / CRPT)

-Утилита для автоматизированного извлечения кодов маркировки (DataMatrix) и массовой генерации готовых к печати PDF-этикеток (формат 58x40 мм) на основе данных из Excel-шаблона. Решение оптимизировано для работы с системой «Честный ЗНАК» и создания этикеток для термопринтеров.
+Комплексное решение для работы с кодами маркировки «Честный ЗНАК». Состоит из двух мощных утилит:
+1. **Batch Extractor:** Автоматически вытаскивает коды из выгрузок ЧЗ (PDF или ZIP-архивы) и собирает их в удобную Excel-таблицу.
+2. **PDF Builder:** Генерирует промышленные макеты этикеток (58x40 мм) для термопринтеров, объединяя извлеченные коды и описания товаров.

-## Ключевые возможности
+## 🌟 Главная фича: Утилита массового извлечения кодов (`batch_extractor.py`)

-*   **Распознавание DataMatrix:** Точное чтение кодов из изображений с помощью `zxing-cpp` с сохранением непечатаемых спецсимволов GS1 (включая FNC1 / ASCII 29) посредством кодирования в Base64.
-*   **Интеграция с Excel:** Парсинг атрибутов товара (GTIN, EAN, Описание, Артикул, Цвет, Размер, Организация) из Excel-шаблонов с использованием `pandas`. Чтение строго по позициям колонок обеспечивает защиту от изменения заголовков.
-*   **PDF Генерация:** Автоматическая сборка промышленных макетов этикеток (включая логотипы EAC, Честный ЗНАК, штрихкоды Code128 и DataMatrix) с помощью `reportlab`.
-*   **Умное форматирование текста:** Автоматический перенос строк (Word Wrap), адаптивное уменьшение размера шрифта и умное усечение текста многоточием (при выходе за границы AABB).
-*   **Портативность:** Использование встроенной версии Ghostscript (`gswin32c`) для рендеринга EPS и штрихкодов без необходимости сложной системной настройки.
+Вам больше не нужно вручную копировать коды или пытаться достать их из картинок. В проекте есть специальная утилита, которая сама "прочитает" исходные файлы от Честного ЗНАКа и создаст готовый Excel-файл (со списком текстовых значений кодов и их Base64-представлением, сохраняющим скрытые спецсимволы GS1/FNC1).
+
+Утилита поддерживает два формата исходников:
+*   **Многостраничные PDF-файлы** (где на каждой странице расположена этикетка).
+*   **ZIP-архивы**, внутри которых лежат векторные `EPS` файлы.

 ## Требования и установка

@@ -19,38 +21,58 @@ pip install -r requirements.txt
 ```

 **Зависимости:**
-*   `pillow` — работа с изображениями.
-*   `zxing-cpp` — быстрое и надежное чтение штрихкодов.
-*   `reportlab` — генерация векторных PDF-файлов.
-*   `pandas` & `openpyxl` — чтение и обработка Excel-таблиц.
-*   `treepoem` — генерация штрихкодов (Code128, DataMatrix).
+*   `pillow`, `zxing-cpp` — чтение штрихкодов из изображений.
+*   `reportlab`, `treepoem` — генерация векторных PDF-файлов и штрихкодов.
+*   `pandas`, `openpyxl` — чтение и создание Excel-таблиц.
+*   `click` — создание удобного интерфейса командной строки.

-*Примечание: Убедитесь, что архив `Ghostscript.zip` распакован в папку `Ghostscript` в корне проекта для корректной работы `treepoem` и обработки EPS-файлов.*
+*Примечание: Убедитесь, что архив `Ghostscript.zip` распакован в папку `Ghostscript` в корне проекта.*

-## Структура проекта
+## 📋 Порядок работы (Как получить готовые этикетки)

-*   `build_pdf.py` — Главный модуль и оркестратор бизнес-логики. Считывает базу данных Excel, группирует входные коды по GTIN, рендерит штрихкоды и генерирует готовые PDF-документы.
-*   `read_image.py` — Утилита для извлечения байтов DataMatrix из картинок и перевода их в безопасный Base64 формат.
-*   `render_eps.py` — Скрипт-конвертер EPS изображений в PNG с использованием портативного Ghostscript.
-*   `Resources/` — Папка с графическими ассетами (логотипы) и исходным файлом `ШАблон для загрузки этикеток.xlsx`.
-*   `data/` — Рабочая директория (содержит входные коды, картинки и генерируемые PDF в папке `output_pdfs`).
+Процесс разделен на три простых шага в терминале:

-## Использование
+### ШАГ 1: Извлечение кодов в Excel (Создание списка КМ)

-1.  Подготовьте описания ваших товаров в файле `Resources/ШАблон для загрузки этикеток.xlsx`.
-2.  Подготовьте список КМ (кодов маркировки), предварительно закодировав сырые байты DataMatrix в формат Base64. (Для получения Base64 из изображений можно использовать скрипт `read_image.py`).
-3.  Запустите процесс генерации PDF:
+Возьмите файл, который вы скачали из системы «Честный ЗНАК», и натравите на него утилиту-экстрактор.

+**Если у вас ZIP-архив с этикетками:**
 ```bash
-python build_pdf.py
+python batch_extractor.py from-zip "C:\путь\к\архиву\ЧЗ.zip" "извлеченные_коды.xlsx"
 ```

-Готовые многостраничные PDF-файлы (сгруппированные по GTIN) будут сохранены в директории `data/output_pdfs/`.
+**Если у вас многостраничный PDF-файл:**
+```bash
+python batch_extractor.py from-pdf "C:\путь\к\файлу\ЧЗ.pdf" "извлеченные_коды.xlsx"
+```

-## Архитектура решения
+*Результат:* Рядом появится файл `извлеченные_коды.xlsx`. В нем две колонки: текстовый код и его Base64 (именно он нужен для точной печати).

-Код разбит на несколько логических слоев:
-1.  **Domain Layer:** Описание структур данных (`LabelData`).
-2.  **Data & Asset Layer:** Функции генерации и трансформации изображений и штрихкодов (`render_code128`, `create_datamatrix_in_memory`). Изображения генерируются без сглаживания (`NEAREST`) для идеальной печати на термопринтерах.
-3.  **Presentation Layer:** Низкоуровневая отрисовка PDF-холста через `reportlab`, позиционирование блоков и алгоритмы подгонки текста (`draw_label_page`, `place_text`).
-4.  **Business Logic Layer:** Оркестрация батчевой обработки данных (`process_batch`). Чтение тяжелых файлов происходит один раз для экономии ресурсов I/O диска.
+### ШАГ 2: Подготовка описания товаров
+
+Откройте шаблон `Resources/ШАблон для загрузки этикеток.xlsx`. Внесите данные о товарах строго по порядку колонок (слева направо). Программа читает именно номера столбцов, а не их заголовки:
+1.  **GTIN** (14 цифр)
+2.  **EAN** (13 цифр)
+3.  **Описание** (название товара, до 200 символов, длинный текст автоматически перенесется или обрежется)
+4.  **Артикул**
+5.  **Цвет**
+6.  **Размер**
+7.  **Организация**
+
+### ШАГ 3: Генерация этикеток для печати (`build_pdf.py`)
+
+Теперь скрестим наши коды из Шага 1 и описания из Шага 2. Запустите генератор, указав три пути: файл с кодами, файл-шаблон с описаниями и папку для сохранения готовых этикеток.
+
+```bash
+python build_pdf.py "извлеченные_коды.xlsx" "Resources/ШАблон для загрузки этикеток.xlsx" "готовые_этикетки/"
+```
+
+*Результат:* В папке `готовые_этикетки/` программа создаст аккуратные PDF-файлы (по одному на каждый GTIN). Формат 58х40 мм, все штрихкоды и шрифты оптимизированы для термопринтеров без размытия. Можно смело отправлять на печать!
+
+## Внутренняя структура проекта
+
+*   `batch_extractor.py` — CLI утилита для извлечения кодов в Excel.
+*   `build_pdf.py` — Главный оркестратор. Группирует коды и генерирует макеты этикеток.
+*   `read_image.py` — Низкоуровневый движок чтения DataMatrix через `zxing-cpp`.
+*   `render_eps.py` — Вспомогательный модуль для работы с EPS.
+*   `Resources/` — Папка с графикой (логотипы EAC, ЧЗ) и Excel-шаблоном.