shtrihscanner/README.md

Go-библиотека и утилита для ККТ "Штрих-М" (shtrih-kkt)

Go-библиотека и консольная утилита для взаимодействия с фискальными регистраторами (ККТ) "Штрих-М" через официальный 32-битный COM-драйвер. Проект разработан с фокусом на безопасный сбор данных в режиме "только чтение" и предоставляет гибкие режимы работы для различных сценариев использования.

Важнейшее ограничение: Приложения, использующие эту библиотеку, должны быть скомпилированы для 32-битной архитектуры (GOARCH=386) из-за зависимости от 32-битного COM-драйвера.

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

• Надежная обертка над COM-драйвером: Предоставляет безопасный и удобный Go-интерфейс для драйвера "Штрих-М".
• Комплексный сбор данных: Агрегирует полную информацию о ККТ, включая регистрационные данные, статус ФН, версии ПО, лицензии и атрибуты торговли.
• Умный автопоиск устройств:
  • COM-порты: Автоматически сканирует все системные COM-порты на двух самых распространенных скоростях (115200 и 4800), предотвращая зависания на "портах-призраках".
  • TCP/IP (RNDIS): Cканирует стандартные для RNDIS-устройств IP-подсети (192.168.137.0/24, 192.168.138.0/24).
• Два режима работы утилиты:
  1. Режим автопоиска: При первом запуске или отсутствии конфигурации выполняет полный поиск устройств, собирает с них данные и сохраняет найденные конфигурации в connect.json для последующих быстрых запусков.
  2. Стационарный режим: При наличии файла connect.json использует заданные в нем параметры для быстрого опроса конкретных ККТ, пропуская этап сканирования.
• Управление данными:
  • Сохраняет информацию о каждом ККТ в отдельный JSON-файл (/date/{ЗН_ККТ}.json).
  • "Обогащает" данные ККТ информацией о рабочей станции (hostname, TeamViewer ID и т.д.), заимствуя ее из существующих JSON-файлов в папке /date.
  • Автоматически обновляет временные метки (current_time, v_time) в существующих файлах при повторных опросах.
• Файловое логирование с ротацией: В стационарном режиме ведет подробный лог в папке /logs, настройки которого (срок хранения) задаются в файле service.json.
• Тестируемость: Включает в себя mockDriver для написания unit-тестов без необходимости подключения реального оборудования.

Архитектура

Библиотека построена на простом интерфейсе Driver, что позволяет легко подменять реализации:

• comDriver: Основная реализация для работы с реальным COM-драйвером.
• mockDriver: Имитационная реализация для unit-тестирования.

Это обеспечивает слабую связанность и позволяет тестировать логику приложений, использующих библиотеку, в изолированной среде.

Начало работы

Требования

1. Go: Версия 1.23 или выше.
2. Windows: Поддержка Windows 7 и выше.
3. 32-битный (x86) тулчейн Go: Даже на 64-битной системе для компиляции требуется 32-битный набор инструментов.
4. Драйвер "Штрих-М": На целевой машине должен быть установлен и зарегистрирован официальный драйвер от "Штрих-М" (например, DrvFR_4.15_882.exe).

Использование библиотеки в вашем проекте

1. Добавьте библиотеку в ваш проект:

   go get github.com/your-username/shtrih-kkt/pkg/shtrih
   

2. Пример использования:

   package main
   
   import (
       "fmt"
       "log"
       "shtrih-kkt/pkg/shtrih"
   )
   
   func main() {
       // Конфигурация для подключения по COM-порту
       config := shtrih.Config{
           ConnectionType: 0,
           ComName:        "COM3",
           ComNumber:      3,
           BaudRate:       6, // Индекс для 115200
           Password:       30,
       }
   
       // Создаем новый драйвер
       driver := shtrih.New(config)
   
       // Подключаемся
       if err := driver.Connect(); err != nil {
           log.Fatalf("Ошибка подключения: %v", err)
       }
       // Гарантируем отключение в конце
       defer driver.Disconnect()
   
       // Получаем информацию
       info, err := driver.GetFiscalInfo()
       if err != nil {
           log.Fatalf("Ошибка получения информации: %v", err)
       }
   
       fmt.Printf("Успешно получены данные для ККТ модели: %s\n", info.ModelName)
       fmt.Printf("Серийный номер: %s\n", info.SerialNumber)
   }
   

Использование готовой утилиты shtrih-scanner.exe

Утилита предназначена для запуска "рядом" с другими служебными файлами.

1. Режим автопоиска (первый запуск):

   • Просто запустите shtrih-scanner.exe.
   • Программа выполнит полный поиск устройств.
   • В папке /date будут созданы JSON-файлы с данными для каждой найденной ККТ.
   • Будет создан или перезаписан файл connect.json с параметрами найденных устройств.

2. Стационарный режим (последующие запуски):

   • Убедитесь, что рядом с shtrih-scanner.exe лежит connect.json.
   • Для настройки логирования создайте файл service.json.
   • Запустите shtrih-scanner.exe.
   • Программа быстро опросит устройства из connect.json и обновит временные метки в файлах в папке /date.

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

• connect.json (генерируется автоматически):

  {
      "shtrih": [
          {
              "type_connect": 0,
              "com_port": "COM1",
              "com_baudrate": "115200"
          },
          {
              "type_connect": 6,
              "ip": "192.168.137.111",
              "ip_port": "7778"
          }
      ]
  }
  

• service.json (создается вручную для настройки логов):

  {
      "service": {
          "log_level": "info",
          "log_days": 7
      }
  }
  

Сборка проекта

Важно: Сборка должна производиться для архитектуры 386.

Откройте терминал в корневой папке проекта.

Для PowerShell:

$env:GOARCH="386"; $env:GOOS="windows"; go build -o shtrih-scanner.exe

Для CMD:

set GOARCH=386
set GOOS=windows
go build -o shtrih-scanner.exe

Сборка без консольного окна (для фоновой работы):

$env:GOARCH="386"; $env:GOOS="windows"; go build -ldflags="-H=windowsgui" -o shtrih-scanner.exe

Тестирование

Для запуска unit-тестов, использующих mockDriver, выполните команду в корне проекта:

go test ./...

Структура проекта

shtrih-kkt/
├── go.mod                  # Файл модуля Go
├── main.go                 # Исходный код утилиты shtrih-scanner.exe
├── README.md               # Этот файл
└── pkg/
    └── shtrih/
        ├── driver.go       # Основная логика библиотеки и реализация comDriver
        ├── mock_driver.go  # Реализация mockDriver для тестов
        └── driver_test.go  # Unit-тесты для библиотеки

---
# Файлы, создаваемые во время работы:
shtrih-scanner.exe
connect.json
service.json
date/
│   └── 0012345678901234.json
logs/
    └── shtrih-scanner.log

Лицензия

Этот проект распространяется под лицензией MIT. См. файл LICENSE для получения дополнительной информации.