diff --git a/.gitignore b/.gitignore index 0e362af..1de044f 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,4 @@ *.exe -*.json \ No newline at end of file +*.json +*.log +*.zip \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..65f4029 --- /dev/null +++ b/README.md @@ -0,0 +1,193 @@ +# Go-библиотека и утилита для ККТ "Штрих-М" (shtrih-kkt) + +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](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` для получения дополнительной информации. \ No newline at end of file