193 lines
10 KiB
Markdown
193 lines
10 KiB
Markdown
# Go-библиотека и утилита для ККТ "Штрих-М" (shtrih-kkt)
|
||
|
||
[](https://opensource.org/licenses/MIT)
|
||
|
||
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-тестирования.
|
||
|
||
Это обеспечивает слабую связанность и позволяет тестировать логику приложений, использующих библиотеку, в изолированной среде.
|
||
|
||
## Начало работы
|
||
|
||
### Требования
|
||
|
||
1. **Go:** Версия 1.18 или выше.
|
||
2. **ОС:** Windows (x86 или x64).
|
||
3. **32-битный (x86) тулчейн Go:** Даже на 64-битной системе для компиляции требуется 32-битный набор инструментов.
|
||
4. **Драйвер "Штрих-М":** На целевой машине должен быть установлен и зарегистрирован официальный драйвер от "Штрих-М" (например, `DrvFR_4.15_882.exe`).
|
||
|
||
### Использование библиотеки в вашем проекте
|
||
|
||
1. **Добавьте библиотеку в ваш проект:**
|
||
```bash
|
||
go get github.com/your-username/shtrih-kkt/pkg/shtrih
|
||
```
|
||
|
||
2. **Пример использования:**
|
||
```go
|
||
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` (генерируется автоматически):
|
||
```json
|
||
{
|
||
"shtrih": [
|
||
{
|
||
"type_connect": 0,
|
||
"com_port": "COM1",
|
||
"com_baudrate": "115200"
|
||
},
|
||
{
|
||
"type_connect": 6,
|
||
"ip": "192.168.137.111",
|
||
"ip_port": "7778"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
* `service.json` (создается вручную для настройки логов):
|
||
```json
|
||
{
|
||
"service": {
|
||
"log_level": "info",
|
||
"log_days": 7
|
||
}
|
||
}
|
||
```
|
||
|
||
## Сборка проекта
|
||
|
||
**Важно:** Сборка должна производиться для архитектуры `386`.
|
||
|
||
Откройте терминал в корневой папке проекта.
|
||
|
||
**Для PowerShell:**
|
||
```powershell
|
||
$env:GOARCH="386"; $env:GOOS="windows"; go build -o shtrih-scanner.exe
|
||
```
|
||
|
||
**Для CMD:**
|
||
```cmd
|
||
set GOARCH=386
|
||
set GOOS=windows
|
||
go build -o shtrih-scanner.exe
|
||
```
|
||
|
||
**Сборка без консольного окна (для фоновой работы):**
|
||
```powershell
|
||
$env:GOARCH="386"; $env:GOOS="windows"; go build -ldflags="-H=windowsgui" -o shtrih-scanner.exe
|
||
```
|
||
|
||
## Тестирование
|
||
|
||
Для запуска unit-тестов, использующих `mockDriver`, выполните команду в корне проекта:
|
||
```bash
|
||
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` для получения дополнительной информации. |