Bulk Print v3.5.4

Bulk Print — профессиональный инструмент для автоматической печати PDF этикеток одежды на принтеры Zebra с расширенной валидацией штрихкодов, отслеживанием напечатанных файлов через SQLite базу данных, интеграцией с MCDM для автоматического перемещения файлов и REST API для внешних приложений.

Polyglot архитектура: Python 3.13+ (основное приложение, UI, оркестрация) + Go 1.21+ сервисы (опциональная высокопроизводительная валидация + REST API сервер).

Два режима работы:

• UI Mode (bulk_print.exe) — интерактивная CLI печать
• API Mode (bulk_print.exe --api) — headless REST API для внешних приложений

---

✨ Ключевые возможности

• 🖨️ Автоматическая печать PDF файлов через Foxit PDF Reader на принтеры Zebra
• <EFBFBD> REST API режим — интеграция с внешними приложениями (Go HTTP + Python gRPC)
• <EFBFBD>📊 Валидация штрихкодов: EAN13, Code128, DataMatrix с конфигурируемыми паттернами
• 📏 Умная обработка размеров: L-XL, L(42), 42A, 122-128 и другие форматы одежды
• 💾 Отслеживание печати: SQLite база данных в режиме WAL с историей всех операций
• ⚡ Фоновое дублирование: асинхронная подготовка PDF файлов для ускорения печати
• 🎛️ Управление принтером Zebra: команды ~JA (мягкая) и ~JR (жёсткая остановка)
• 🔄 Интеграция с MCDM: передача только фактически напечатанных файлов через параметр -f
• 🎨 Интерактивный UI: пошаговая печать, фильтрация файлов, индексация папок

---

🚀 Быстрый старт

Установка

1. Скачайте последний релиз из Releases
2. Распакуйте архив Bulk_Print_Windows_vX.X.X.zip
3. Запустите Bulk_Print.exe

Первоначальная настройка

1. Создайте свой zebra_settings.conf — скопируйте zebra_settings.conf.example и заполните локальные значения (см. Конфигурация).

   • Путь к Foxit PDF Reader (если отличается от стандартного)
   • Путь к MCDM.exe (если используете автоперемещение файлов)
   • Регулярное выражение для поиска файлов (по умолчанию: .*@altinbike.*\.pdf)
   • Папка для поиска (по умолчанию: Downloads)

2. При первом запуске программа автоматически:

   • Найдёт принтер Zebra в системе (по ключевым словам: Zebra, ZDesigner)
   • Создаст базу данных printed_files.db с индексами
   • Проиндексирует указанную папку

3. Требования к системе:

   • Windows (полная функциональность), macOS/Linux (ограниченная поддержка)
   • Принтер Zebra, подключённый и настроенный в Windows
   • Foxit PDF Reader (бесплатная версия)

---

🔌 API режим (External API)

Новое в версии 3.2.0+: Bulk Print поддерживает запуск в headless API режиме для интеграции с внешними приложениями.

Быстрый старт API

# Запуск в API режиме
bulk_print.exe --api

# С кастомным портом
bulk_print.exe --api --port 9000

Сервер выводит в stdout когда готов:

READY:8321

Архитектура API

External App → HTTP REST (8321) → Go API Server → gRPC (50053) → Python Backend

• Go HTTP Server (порт 8321): Высокопроизводительный REST API
• Python gRPC Backend (порт 50053): Бизнес-логика, JobManager, PrintManager
• State Machine: Управление заданиями и паузами между файлами

Основные эндпоинты

# Health check
GET /health

# Создать задание печати
POST /api/v1/jobs
{
  "files": ["C:\\path\\to\\file1.pdf", "C:\\path\\to\\file2.pdf"],
  "copies": 2
}

# Получить статус задания
GET /api/v1/jobs/{job_id}

# Подтвердить печать файла (аналог Enter)
POST /api/v1/jobs/{job_id}/continue

# Пропустить файл
POST /api/v1/jobs/{job_id}/skip

# Отменить задание
DELETE /api/v1/jobs/{job_id}

# Завершить сервер
POST /api/v1/shutdown

Пример использования (Python)

import requests

API_BASE = "http://127.0.0.1:8321/api/v1"

# Создать задание
resp = requests.post(f"{API_BASE}/jobs", json={
    "files": [r"C:\Labels\label1.pdf", r"C:\Labels\label2.pdf"],
    "copies": 2
})
job_id = resp.json()["job_id"]

# Цикл подтверждения
while True:
    status = requests.get(f"{API_BASE}/jobs/{job_id}").json()

    if status["status"] == "completed":
        print("Все файлы напечатаны!")
        break

    if status["status"] == "awaiting_confirmation":
        # Подтвердить печать
        requests.post(f"{API_BASE}/jobs/{job_id}/continue")

    time.sleep(0.5)

Подробная документация API

• docs/EXTERNAL_API.md — Полная документация REST API с примерами на Python, PowerShell, C#
• docs/API_IMPLEMENTATION_PLAN.md — Архитектура и технические детали

Конфигурация API

[API]
api_enabled = true
api_http_port = 8321
api_grpc_port = 50053
api_host = 127.0.0.1
api_idle_timeout_sec = 300
api_log_file = api.log
api_printer_name =

Безопасность: API доступен только с localhost (127.0.0.1), без авторизации (локальная интеграция).

---

🎮 Интерфейс программы (UI режим)

Главное меню

При запуске отображается список найденных PDF файлов с информацией:

• Имя файла
• EAN13 штрихкод
• Code128 артикул
• Размер
• Статус (напечатан/ошибки)

Доступные команды:

• [Enter] — Начать пошаговую печать файлов
• [1] — Мягкая остановка печати (~JA) — отмена текущей задачи (4-5 сек)
• [2] — Жёсткая остановка печати (~JR) — отмена с перезапуском принтера (4-5 сек)
• [3] — Повторить поиск файлов
• [4] — Скрыть/показать напечатанные файлы
• [5] — Скрыть/показать файлы с ошибками валидации
• [6] — Отметить все файлы как напечатанные и запустить MCDM
• [7] — Запустить индексацию произвольной папки
• [Esc] — Выход из программы

Пошаговая печать

После нажатия Enter программа переходит в режим пошаговой печати:

1. Файлы без ошибок — печатаются сразу при нажатии Enter

2. Файлы с ошибками валидации — показывается предупреждение:

   • Нажмите Enter для печати несмотря на ошибки
   • Нажмите любую клавишу для пропуска файла

3. После печати каждого файла:

   • Отображается информация о следующем файле в очереди
   • Нажмите Enter для печати следующего
   • Нажмите [1] или [2] для остановки принтера
   • Нажмите [3] для возврата в главное меню
   • Нажмите [Esc] для выхода

4. После печати всех файлов:

   • Отображается итоговая сводка
   • Автоматический запуск MCDM (если настроен) с передачей списка напечатанных файлов

---

🧩 Функциональность

Валидация PDF файлов

Программа проверяет наличие и корректность следующих полей:

Обязательные штрихкоды

• EAN13 (13 цифр): \b(\d{13})\b

  • Пример: 4603727123456
  • Используется как основной идентификатор продукта

• Code128 (артикул, 8-9 символов): ^[A-Z][A-Z0-9]{7,8}$

  • Примеры: SL033L121, M4619092
  • Начинается с заглавной буквы, далее буквы или цифры
  • Обработка перевернутых штрихкодов (автоматическое определение)

• DataMatrix (GTIN + метаданные): 01\d{12,}

  • Формат: начало с 01, минимум 12 цифр
  • Обязательные паттерны из config_files/datamatrix_patterns.txt:
    • Окончания: 512, 4010 и другие (формат: ending:512)
    • Начала после префикса: 215, 0104 и другие (формат: beginning:0104)
  • Пример: 010460372712345621SL033L121\x1d4010Россия\x1d512Хлопок 95%

Размер одежды

Поддерживаются различные форматы размеров из config_files/allowed_sizes.txt:

• Стандартные: XS, S, M, L, XL, XXL, XXXL
• Комбинированные: L-XL, L XL, LXL, M-L
• С скобками: L(42), M(44), S(40)
• Числовые: 42, 44, 46, 48, 50, 52, 54, 56, 58, 60
• С суффиксами: 42A, 48B, 50C
• Детские: 122-128, 134-140, 146-152, 158-164
• Старый формат (артикул + размер): LO0001ML 146-152
• Новый формат (цифровой): 000-000

Бренд

• Поиск по ключевым словам из config_files/brand_keywords.txt
• Регистронезависимый поиск
• Примеры: ALTIN, ALTINBIKE, ALTINFIT, COCOLUX, Beach Peach

Иконки и изображения

• Валидация через src/pdf/image_validator.py
• Проверка наличия и корректности изображений в PDF
• Определение типа изображения (JPEG, PNG и т.д.)

Управление принтером Zebra

Мягкая остановка (~JA)

• Отменяет только текущую задачу печати
• Время выполнения: 4-5 секунд
• Принтер готов к новым заданиям
• Использовать при: ошибке в файле, случайной печати

Жёсткая остановка (~JR)

• Отменяет все задания и перезапускает принтер
• Время выполнения: 4-5 секунд
• Сброс всех буферов и очередей
• Использовать при:
  • Зависании принтера
  • Мигании красным индикатором
  • Физической кнопке паузы (нажата на принтере)
  • Открытой крышке принтера
  • Закончившейся бумаге

Автопоиск принтера

• Поиск по ключевым словам из конфига (по умолчанию: Zebra, ZDesigner)
• Нечёткий поиск с учётом подстрок
• Кэширование найденного принтера в конфиге
• При не найденном принтере — вывод списка доступных

Фоновое дублирование PDF

Новая функция в версии 2.11.0+ для ускорения печати (см. docs/BACKGROUND_DUPLICATION.md):

• Асинхронная подготовка: PDF файлы дублируются в фоновом потоке
• Кэширование: продублированные файлы готовы к мгновенной печати
• Статусная система: ready, in_progress, error
• Thread-safe операции: блокировки для конкурентного доступа
• Автоочистка: автоматическое удаление временных файлов
• Singleton pattern: глобальный доступ через get_duplicator()

Интеграция с MCDM

MCDM (Master Collection Data Manager) — внешняя программа для перемещения напечатанных файлов.

Умная передача файлов

Программа передаёт в MCDM только фактически напечатанные файлы:

# ✅ ПРАВИЛЬНО - печать успешна
MCDM.exe -i -f "file1.pdf,file2.pdf,file3.pdf"

# ❌ Если файлы НЕ печатались - MCDM НЕ запускается

Настройка в zebra_settings.conf

[MCDM]
path = C:\Users\Altin\Apps\MCDM\MCDM.exe
args = -i

Когда запускается MCDM

• После печати всех файлов в пошаговом режиме
• При выборе пункта меню [6] "Отметить все как напечатанные"
• Только если есть список напечатанных файлов

Предотвращение множественного запуска

• Флаг mcdm_launched отслеживает статус запуска
• MCDM запускается строго один раз за сессию печати
• Возможность повторного запуска при ошибках

---

⚙️ Конфигурация

Все настройки находятся в файле zebra_settings.conf. Скопируйте zebra_settings.conf.example в zebra_settings.conf и заполните значения перед запуском. Подробнее см. config_help.md.

Основные параметры

[Settings]
# Путь к Foxit PDF Reader (Windows)
foxit_path = C:\Program Files (x86)\Foxit Software\Foxit PDF Reader\FoxitPDFReader.exe

# Регулярное выражение для поиска файлов
file_pattern = .*@altinbike.*\.pdf

# Папка для поиска (по умолчанию: Downloads)
input_folder = C:\Users\YourName\Downloads

# Максимальное количество файлов за один цикл
max_files_to_print = 10

# Количество копий (дублирование страниц)
default_copies = 2

# Имя принтера (определяется автоматически, если пусто)
printer_name =

# Ключевые слова для поиска принтера
search_keywords = Zebra,ZDesigner

# Ограничение по времени создания файлов (в минутах)
search_minutes = 30

# Включить ограничение по времени
scan_time_limit_enabled = true

# Тестовый режим (без реальной печати)
test_print_mode = false

MCDM конфигурация

[MCDM]
# Путь к программе MCDM.exe
path = C:\Users\Altin\Apps\MCDM\MCDM.exe

# Стандартные аргументы
args = -i

Конфигурационные файлы валидации

Папка config_files/ содержит файлы с валидационными данными (UTF-8 encoding):

allowed_sizes.txt

Список допустимых размеров одежды (один размер на строку):

XS
S
M
L
XL
XXL
L-XL
L(42)
42A
122-128
...

brand_keywords.txt

Ключевые слова брендов для валидации (одно слово на строку):

ALTIN
ALTINBIKE
ALTINFIT
COCOLUX
Beach Peach
...

datamatrix_patterns.txt

Обязательные паттерны для валидации DataMatrix кодов:

# Обязательные окончания
ending:512
ending:4010

# Обязательные начала после префикса '01'
beginning:215
beginning:0104

Важно: При изменении конфигурационных файлов необходимо перезапустить программу для применения изменений.

---

📊 Примеры использования

Типичный рабочий процесс

1. Запустите программу — Bulk_Print.exe или python run.py
2. Просмотрите найденные файлы — список отображается с информацией о штрихкодах
3. Отфильтруйте при необходимости:
   • Нажмите [4] чтобы скрыть напечатанные файлы
   • Нажмите [5] чтобы скрыть файлы с ошибками
4. Начните печать — нажмите Enter
5. Подтвердите каждый файл — нажимайте Enter для печати следующего
6. Дождитесь завершения — MCDM запустится автоматически

Работа с файлами с ошибками

Если файл имеет ошибки валидации:

⚠️ ВНИМАНИЕ! У файла обнаружены следующие ошибки:
• Отсутствует EAN13 штрихкод
• Размер не найден или некорректен

Нажмите Enter для печати несмотря на ошибки
или любую другую клавишу для пропуска файла

Рекомендация: исправьте PDF файл перед печатью, чтобы избежать проблем с этикетками.

Экстренная остановка принтера

Если принтер завис или печатает не тот файл:

1. Вернитесь в программу
2. Нажмите [2] для жёсткой остановки (~JR)
3. Дождитесь завершения (4-5 сек)
4. Принтер готов к новым заданиям

Массовая отметка файлов

Если нужно отметить все файлы как напечатанные без печати:

1. Нажмите [6] в главном меню
2. Подтвердите действие
3. MCDM запустится с полным списком файлов

Индексация новой папки

Для быстрой обработки файлов из другой папки:

1. Нажмите [7] в главном меню
2. Укажите путь к папке
3. Файлы будут проиндексированы и добавлены в базу данных
4. Используйте пункт [6] для отметки как напечатанных

---

📁 База данных

Программа использует SQLite базу данных printed_files.db для отслеживания:

• Напечатанные файлы с временем печати
• Файлы с ошибками валидации
• История обработки файлов
• Статистика печати

Особенности

• WAL режим (Write-Ahead Logging) для одновременных чтений
• Индексы для быстрого поиска по имени файла и времени
• Retry логика при блокировках базы данных
• Автоматическая миграция при обновлениях схемы

Очистка базы данных

Для сброса истории печати:

1. Закройте программу
2. Удалите файл printed_files.db
3. При следующем запуске база создастся заново

---

📝 Логирование

Все события записываются в файл app.log:

• Запуск и завершение программы
• Поиск и обработка файлов
• Операции печати
• Ошибки и предупреждения
• Запуск MCDM

Настройки логирования

• Максимальный размер файла: 1MB
• Количество бэкапов: 3 файла
• Автоматическая ротация: при превышении размера
• Формат: YYYY-MM-DD HH:MM:SS [LEVEL] - message

---

🔧 Устранение неполадок

Принтер не найден

Проблема: Программа не может найти принтер Zebra

Решение:

1. Убедитесь что принтер включён и подключён
2. Проверьте что принтер отображается в Windows (Параметры → Устройства → Принтеры)
3. Проверьте search_keywords в zebra_settings.conf
4. Укажите имя принтера вручную в параметре printer_name

Файлы не печатаются

Проблема: Файлы найдены, но печать не происходит

Решение:

1. Проверьте что Foxit PDF Reader установлен
2. Проверьте путь foxit_path в конфиге
3. Проверьте что принтер настроен по умолчанию
4. Посмотрите логи в app.log для деталей ошибки

MCDM не запускается

Проблема: MCDM не запускается после печати

Решение:

1. Проверьте путь path в секции [MCDM] конфига
2. Убедитесь что MCDM.exe существует по указанному пути
3. Проверьте что хотя бы один файл был напечатан (иначе MCDM не запустится)
4. Посмотрите логи для команды MCDM

Ошибки валидации PDF

Проблема: Файлы помечаются с ошибками валидации

Решение:

1. Проверьте что PDF содержит все обязательные штрихкоды
2. Убедитесь что размер присутствует в config_files/allowed_sizes.txt
3. Проверьте что бренд есть в config_files/brand_keywords.txt
4. Для DataMatrix проверьте паттерны в config_files/datamatrix_patterns.txt
5. Используйте опцию печати несмотря на ошибки (Enter при предупреждении)

Программа зависает

Проблема: Программа не реагирует на нажатия клавиш

Решение:

1. Подождите завершения текущей операции (поиск файлов, валидация)
2. Закройте программу через диспетчер задач
3. Проверьте app.log для диагностики
4. Перезапустите программу

---

🤝 Поддержка и участие

Нашли ошибку?

1. Проверьте существующие Issues
2. Создайте новый Issue с подробным описанием:
   • Версия программы
   • Операционная система
   • Шаги для воспроизведения
   • Логи из app.log
   • Скриншоты (если применимо)

Хотите внести вклад?

Ознакомьтесь с CONTRIBUTING.md для получения инструкций по разработке.

Документация для пользователей

• CHANGELOG.md — История изменений
• config_help.md — Подробная справка по конфигурации

Для разработчиков

Вся техническая документация находится в CONTRIBUTING.md

---

📄 Лицензия

MIT License. См. файл LICENSE для подробностей.

---

🙏 Благодарности

• pdfplumber — Извлечение данных из PDF
• pypdf — Манипуляция PDF файлами
• colorama — Цветной вывод в консоль
• pywin32 — Интеграция с Windows API

---

Версия документа: 3.5.4 | Дата обновления: 2026-01-14