Files

2025-08-21 10:42:56 +03:00

10 KiB

Raw Blame History

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

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

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

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

Надежная обертка над COM-драйвером: Предоставляет безопасный и удобный Go-интерфейс для драйвера "Штрих-М".
Комплексный сбор данных: Агрегирует полную информацию о ККТ, включая регистрационные данные, статус ФН, версии ПО, лицензии и атрибуты торговли.
Умный автопоиск устройств:
- COM-порты: Автоматически сканирует все системные COM-порты на двух самых распространенных скоростях (115200 и 4800), предотвращая зависания на "портах-призраках".
- TCP/IP (RNDIS): Параллельно сканирует стандартные для 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-тестирования.

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

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

Требования

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

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

Добавьте библиотеку в ваш проект:
```
go get github.com/your-username/shtrih-kkt/pkg/shtrih
```

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

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`

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

Режим автопоиска (первый запуск):
- Просто запустите shtrih-scanner.exe.
- Программа выполнит полный поиск устройств.
- В папке /date будут созданы JSON-файлы с данными для каждой найденной ККТ.
- Будет создан или перезаписан файл connect.json с параметрами найденных устройств.
Стационарный режим (последующие запуски):
- Убедитесь, что рядом с 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 для получения дополнительной информации.

10 KiB Raw Blame History Unescape Escape